docs
Native API
One listener (default :8080) serves three surfaces from the same router:
SQS (covered in SQS compatibility), gRPC, and an
HTTP/JSON mirror of the same calls. Native surfaces authenticate with
bearer API keys; the SQS surface authenticates with SigV4. The two
credential sets are separate and never derived from each other.
Authentication
Every gRPC and HTTP/JSON request carries a bearer key:
Authorization: Bearer <key>Keys are 32 bytes in base64 and each is scoped to a namespace; see configuration for how they are provisioned. A key scoped to a different namespace is indistinguishable from one that was never configured.
gRPC
The service is okuri.api.v1.QueueService:
| rpc | purpose |
|---|---|
SendMessage |
append a message, with optional delay and dedup id |
ReceiveMessage |
lease up to a batch of messages, with optional long poll |
AckMessage |
complete a delivery |
NackMessage |
return a message early, with optional backoff |
ChangeMessageVisibility |
extend or shorten an outstanding lease |
RedriveQueue |
move dead letters back to the parent queue |
PurgeQueue |
drop everything sent before now |
GetQueueStats |
queue depth and related counters |
The proto files live in the
okuri-proto crate.
HTTP/JSON
The same calls as plain HTTP:
| route | purpose |
|---|---|
POST /v1/queues/{queue}/messages |
send |
POST /v1/queues/{queue}/messages:receive |
receive |
POST /v1/messages:ack |
ack |
POST /v1/messages:nack |
nack |
POST /v1/messages:extend |
change visibility |
POST /v1/queues/{queue}:redrive |
redrive the queue’s dead letters |
POST /v1/queues/{queue}:purge |
purge |
GET /v1/queues/{queue}/stats |
stats |
Receipt handles
A receive hands back one receipt handle per message. The handle is opaque,
signed with the fleet-wide receipt_handle_key, and bound to the node’s
namespace. Because every node carries the same key, a handle issued by
whichever node served the receive is honored by whichever node the load
balancer sends the ack to, so sticky routing is not required.
Handles are what ack, nack, and visibility changes take. Do not parse or store them beyond the lease’s lifetime.
Queue management
The native API deliberately defines no queue-creation RPC today: create
queues through the SQS surface’s CreateQueue, or through the Rust
library when embedding okuri. okuri queue admin CLI commands are planned
for 0.1.0.
Queue names everywhere are non-empty, at most 64 bytes, [a-z0-9_-] only,
and the -dlq suffix is reserved for each queue’s dead-letter companion.