gpresd Protocol

The protocol used to communicate between gstat and gpresd is designed to allow for both flexibility and future expansion. Any suggestions on improvements are welcome.

Overview

Queries are sent from clients to gpresd on the category @<domain>/presence/. The queries must be signed by the requesting user and must be encrypted for the ID domain@<domain>. If the messages are not correctly signed and encrypted, they will be ignored. This is to prevent DoS attacks on both the server and third parties via the server. The query must contain the fragments id/class, id/time, and id/instance to allow gpresd to sufficiently identify the client and user making the request.

Within the query, requests are submitted in the form of fragments, with each fragment being a request. The name of the fragment identifies the type of request, and the value of the fragment contains the necessary data. As many requests can be submitted within one message as are needed.

The reply sent by the server will be sent to the requested category, if indicated in the query, or otherwise to the category @<user domain>/user/<user name>/gstat/. It will be signed by the ID domain@<domain>, and encrypted for the user that signed the query.

Results for the query will be returned as fragments. Each request will result in any number, including zero, of fragments being returned. The name of the fragment will identify the type of data, and the value of the fragment will be the actual result. For some types of requests, more than one type of reply fragment may be returned.

Encapsulated messages

Some types of requests, particularly those requesting the status of a user, will result in fragments of type frag_group being returned which contain a previously-stored message from another user. For these results, the fragment will contain a group of all the fragments originally contained within the archived message, plus two extra fragments. The added fragment named archived/signer will contain the name of the ID that originally signed the message, and the added fragment named archived/category will contain the category list that the message was originally sent to.

Request fragments

id/request (type: frag_number)

If present in a request, this fragment will be added to the reply to allow the client to identify the results.

request/category (type: frag_text)

The reply to this request will be sent to the category specified in this fragment.

query/presence (type: frag_text)

Requests that all current presence messages received from the user specified be returned to the client. The user is specified as their notice category: @<user domain>/notice/<user>/. The last-seen presence messages from each known client run by that user are returned in the reply as encapsulated messages in fragments named reply/presence. If the user does not have any clients running, the last-seen presence message is returned as an encapsulated message in a fragment named reply/last.

query/last (type: frag_text)

Requests that the last-seen presence message from the user specified be returned to the client. The user is specified as above. The last-seen presence message from the user is returned as an encapsulated message in a fragment named reply/last.