REQUEST

← Back to Home - To Transport

The REQUEST packet is used to get one or more values in a range from a bucket and to subscribe to bucket updates (in the selected range).

Request

Request request bytemap

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

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

The REQUEST packet accepts one flag:

#6: Also subscribe to this bucket or the selected range in this bucket

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 that is requested.
Slot index end (optional): a 2-byte integer (uint-16) that indicates the ‘to’ index of the slot in the bucket that will requested. If omitted, all values from the start index are requested.

If both indexes are omitted, the entire bucket will be requested.

Response

REQUEST response bytemap

Figure B: REQUEST response byte-map

The response packet contains an array of n times the following data (where n equals the amount of requested slots) alongside a status code:

Index: a 2-byte integer (uint-16) that indicates the slot in the bucket at which the following data is stored (because data can be sent out-of-order by the server, or at an unknown point in time when it is a subscribe)
Length: a dynamically sized integer that indicates the length of the following data.
Content: The binary content that is in the bucket slot, can be at least 0 bytes and at most the max slot size a server supports.

You might encounter the following error codes:

3 (invalid permissions): This bucket does not have the correct permissions to be read
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

Request process

Figure C: REQUEST process flow

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

The client sends a REQUEST packet to the server
If the bucket exists but the user does not have write permission, return error code 3.
If the subscribe flag is set, subscribe user to bucket (optionally with range), see SUBSCRIBE.
If the flag is not set but a range is provided, select the slots from the database within the range.
If the range is not provided, get all slots from the database
Create the response and send it to the user.

Note: If the user has subscribed and an update is pushed to the bucket, the server will send another response to the REQUEST request if this request asked to subscribe. This packet looks the same as a REQUEST response.

← Back to Home - To Transport - Prev: WIPE packet - Next: SUBSCRIBE packet →