QA
/QA - Query Acknowledgement
The query acknowledgement packet is used to inform a search client that a target hub has received its query and is processing it. It also provides information for the search client's hub cache, expanding knowledge of the network and ensuring hubs are not searched more than once in a given query.
Sending
Send a query acknowledgement packet only when operating in hub mode, and only when the query was not received from a hub via a TCP link. Acknowledgements should only be sent after verifying the query key authentication.
Receiving
When a query acknowledgement is received, update the local hub cache as necessary:
- Hubs which have been searched should not be sent this query again
- New suggested hubs should be added and refreshed
- Any "back-off" time should be recorded and honoured.
Payload
A GUID identifying the query being acknowledged.
Children
This packet has several child packet types defined at the current time:
- /QA/TS - Timestamp
- /QA/D - "Done" or Completed Hub
- /QA/S - "Search" or New Hub
- /QA/RA - Retry After
- /QA/FR - From Address
/QA/TS - Timestamp
The /QA/TS child provides a timestamp representing the current universal time at the sending node. This can be used as a reference when considering other timestamps in the packet, allowing them to be adjusted to eliminate differences between the time setting on the local and remote node.
Sending
This child is optional but recommended.
Payload
A 32-bit integer representing the current UNIX time, or time(NULL).
Children
This packet has no known children at the current time.
/QA/D - Done Hub
References a hub which has now been queried, and should not be queried again.
Sending
Send a /QA/D child for the local hub and each neighbouring hub, whether or not the hub has actually forwarded the query. If a hub has not forwarded the query, it was still effectively searched as the QHT indicated it could not field a matching object.
Receiving
Upon receiving a /QA/D child, add the hub to the cache, freshen its timestamp and mark it as queried in this search. Do not query this node again for several minutes.
Payload
A network/node address followed by a 16-bit leaf count.
Children
This packet has no known children at the current time.
/QA/S - Search Hub
References a hub which was not searched in this operation, but could be searched later if it has not already been touched.
Sending
Send a /QA/S child for every unique hub in the local hub cluster which is not a direct neighbour. Optionally select some recent cached hubs and send /QA/S children for them also, to make up at least 10 in total.
Receiving
Upon receiving a /QA/S child, add the hub to the cache and/or freshen its timestamp.
Payload
A network/node address, optionally followed by a 32-bit last-seen timestamp. This makes detecting the address family slightly harder, but the compactness is worthwhile. Timestamps are omitted for hubs in the local hub cluster, which should make up the majority.
Children
This packet has no known children at the current time.
/QA/RA - Retry After
Advises the search client that the hub does not wish to be contacted again for a specified period of time. Queries earlier than this time may result in a longer-term ban.
Sending
Send this child, with or without executing the search if the hub's resources are becoming saturated. It provides an indirect means of flow control.
Receiving
Upon receiving a /QA/RA child, record the retry after interval and do not send any requests to the hub until the period has expired.
Payload
A 16 bit or 32 bit integer specifying the delay in seconds until the hub may be contacted again.
Children
This packet has no known children at the current time.
/QA/FR - From Address
This child is used when a query acknowledgement is forwarded from a proxy hub to a firewalled leaf node. It advises the leaf of the original sender.
Sending
When a hub receives a /QA packet for a search originated by one of its leaves, it should forward the /QA to the appropriate leaf after adding a /QA/FR child with the remote hub's network address.
Receiving
If this child is present and the /QA packet was received via TCP from a local hub, the node address within should be used as the remote hub's node address. This information is often reflected in the first /QA/D child, however this is not always present.
Payload
A network address which may omit the port number.
Children
This packet has no known children at the current time.