Writing a client
A LessorMQ client is small on purpose: it claims, runs a handler, and reports. All policy lives on the server. If your language has no official library yet, the examples for Python, TypeScript and Go are complete workers in about sixty lines each, written against the plain HTTP API.
The loop
POST /v1/queues/{queue}/claimswithwait_seconds(up to 20). A 204 means nothing arrived in time: claim again, without sleeping.- Run the handler with the message's
bodyandheaders. - While it runs, call
POST /v1/messages/{id}/extendwith the receipt every third of the lease, if the job can take longer than the lease. - On success,
POST /v1/messages/{id}/ackwith the receipt. - On an exception,
POST /v1/messages/{id}/failwith the receipt and{"error": {"type": ..., "message": ...}}. Add"permanent": trueonly when the input itself is unusable. The answer says what the server did; log it, do not act on it. - On
409 lease_lost, drop the message: it is someone else's now.
The rules
A conforming client:
- sends the API key as
Authorization: Bearer <key>on every request; - never decides on its own to retry, delay or drop a message;
- retries network errors and 5xx answers of claim, extend, ack, fail and release with
the same receipt, and of publish only with a
dedup_key(generate one per publish to make that always safe); - waits
Retry-Afterseconds on 429; - ignores fields it does not know: the API only ever adds them.
The full set, with the reasons, is in the protocol; every request and answer is in the API reference.
Proving it
The server repository has a conformance suite: scenarios written as data (YAML) that
run against a real server in docker. A library passes them through a small adapter that
maps the six protocol calls onto its own API, and turns its results and errors back into
status codes. The PHP library's adapter is the model:
clients/php/tests/Conformance/ClientAdapter.php.
LESSORMQ_ADAPTER=path/to/your/adapter.php conformance/run.sh
For a library in another language, port the runner (a few hundred lines) and keep the scenarios as they are. Every official library passes the suite before it is released.