Queue

Implements an asynchronous request queue.

Queue Status Life Cycle

Queue Status Lifecycle

Status Code Description

Status	Code	Description
PENDING	0	Request has been received in the upload queue but not yet sent to satellite.
SENT	1	Request has been sent to satellite and is pending execution. These requests can no longer be deleted.
READY	2	Response has been downloaded from the satellite, passed a health check and is ready to be read by the user.
DELETED	5	The request has been deleted.
ARCHIVED	6	When a request has been deleted after it has been sent.
LOST	8	The request was uploaded but it did not return in the next window.
ERROR	9	There was an error with the request.

Requests can be deleted to allow for some housekeeping.

Protocol

The API is non-blocking but asynchronous. The endpoints that request work to be performed on a satellite are delayed. Therefore, it is necessary to establish a protocol that structures the artifacts relevant to query the status of each request. Further, as there are non-controllable factors that can affect response time, it is only an estimate.

Request Response

When a request is performed, information about the status of the request is appended. This can then be used to query the /queue endpoints.

request_uuid	A unique request identifier that can be used for querying its status
request_name	The name of the request endpoint i.e. PRIVATE_KEY
request_verb	The HTTP verb used: POST, GET, DELETE
request_status	The status code and the name of the status.
created_at	The timestamp of when the request was created.
response_eta*	The timestamp of when a response is expected.
satellite_id*	The servicing satellite name identifier.

Populated once the request status changes to SENT.

{
  “request”: {
    “request_uuid”: “<request_uuid>”,
    “request_name”: “<endpoint_name>”,
    “request_verb”: “<endpoint_verb>”,
    “request_status”: {
      “status_code”: <status_code_int>,
      “status_name”: “<status_name_string>”
    },
    “created_at” : “<ts_with_tz>”
    “response_eta”: “<ts_with_tz>”,
    “satellite_id”: “<sat_id_string>”,
  }
} 

Once the request changes status to READY, we can see that the response object will be populated in the request queue.

payload_size	Size of the payload in KiB
received_at	Timestamp of the received request
payload	The requested payload
signature	The signature for verification
is_verified	Boolean: indicates whether the response signature has been verified successfully

{
  “request”: { … }, 
  “response”: {
    “payload_size”: “<kib_int>”,
    “received_at”: “<ts_with_tz>”,
    “payload”: {},
    “signature”: “<signature_string>”,
    “is_verified”: <is_verified_boolean>”
  }
} 

The responses can be veriefed against the corresponding satellite public signing key found here.

See the queue requests documentation here.