QA

Root Packets
CRAWLA - CRAWLR
HAW - LNI
KHL - KHLA - KHLR
PI - PO - PUSH
QKA - QKR
Q2 - QA - QH2 - QHT
UPROC - UPROD

/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.