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

  1. POST /v1/queues/{queue}/claims with wait_seconds (up to 20). A 204 means nothing arrived in time: claim again, without sleeping.
  2. Run the handler with the message's body and headers.
  3. While it runs, call POST /v1/messages/{id}/extend with the receipt every third of the lease, if the job can take longer than the lease.
  4. On success, POST /v1/messages/{id}/ack with the receipt.
  5. On an exception, POST /v1/messages/{id}/fail with the receipt and {"error": {"type": ..., "message": ...}}. Add "permanent": true only when the input itself is unusable. The answer says what the server did; log it, do not act on it.
  6. 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-After seconds 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.