SUBSCRIBE

← Back to Home - To Transport

The SUBSCRIBE packet is used to subscribe the user to updates from a bucket or from a range of slots in a bucket. It returns the data asynchronous and potentially partial, so after the SUBSCRIBE response other responses can be expected in the future. These are REQUEST responses.

Request

Subscribe request bytemap

Figure A: SUBSCRIBE request byte-map (header and body)

The SUBSCRIBE request (see Figure A) includes a header. This header contains one field: the bucket id which indicates the bucket to subscribe to.

The SUBSCRIBE packet accepts no extra flags.

The body can contain the following fields:

Slot index start (optional): a 2-byte integer (uint-16) that indicates the ‘from’ index of the slot in the bucket to subscribe to
Slot index end (optional): a 2-byte integer (uint-16) that indicates the ‘to’ index of the slot in the bucket to subscribe to. If omitted, the user will be subscribed from the slot index start until the end of the bucket

If both indexes are omitted, the user will be subscribed to all slots/to the entire bucket.

Response

Subscribe response bytemap

Figure B: SUBSCRIBE response byte-map

The SUBSCRIBE request does not return any data directly. However, when an update occurs, a REQUEST response is sent to the user.

You might encounter the following error codes:

3 (invalid permissions): This bucket does not have the correct permissions to be read (so we can’t subscribe either)
4 (authentication failed): Authentication for this bucket failed (bucket key missing or invalid).
21 (bucket does not exist): The requested bucket is not found

Process and flow

Subscribe process

Figure C: SUBSCRIBE process flow

The SUBSCRIBE process (see Figure C) goes as follows:

The client sends a SUBSCRIBE packet to the server
The server checks if the user has read permissions. If not, error code 3 is sent.
If a range is provided, the user is subscribed to only that slot range
If no range is provided, the user is subscribed to the entire bucket (all slots)
When an update is pushed to the bucket (a slot is added or modified, or wiped) a REQUEST is sent with the update data. This response is sent after the response of step 5.

← Back to Home - To Transport - Prev: REQUEST packet - Next: UNSUBSCRIBE packet →