spoolersh/memspoold repository overview

⁠Spooler local evaluation image

Spooler is a message queue with a small surface: send bytes over HTTP, receive them under a lease, ack. In the hosted service, a 201 means the message was written and fsynced before the response.

spoolersh/memspoold is that server on your machine: the same HTTP API with ephemeral in-memory storage. It needs no account and issues no API key. Nothing persists — every message is lost when the container exits. It is an evaluation build, licensed for development, testing, and evaluation only — not for production use; see License⁠.

⁠Run it

docker run --rm -p 127.0.0.1:8080:8080 spoolersh/memspoold

The API is at http://localhost:8080/v1. The port is bound to loopback on purpose: this server holds one implicit account and any bearer token identifies it, so anything that can reach the port can use it. The header is still required — a request without one fails 401.

export SPOOLER_API=http://localhost:8080/v1
export SPOOLER_KEY=local

Create a queue:

curl -X PUT "$SPOOLER_API/spools/default/queues/test" \
  -H "Authorization: Bearer $SPOOLER_KEY"

Returns 201. Send a message — the body is the message, bytes in, bytes out, no envelope:

curl -si -X POST "$SPOOLER_API/spools/default/queues/test/send" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  --data-binary 'hello, world'

HTTP/1.1 201 Created

{"duplicate":false,"id":"1-1"}

Receive it. Receiving does not delete the message, it leases it: while the lease is live no other receiver gets the message, and if you never settle it the lease times out and the message is redelivered.

curl -si -X POST "$SPOOLER_API/spools/default/queues/test/recv?wait=20s" \
  -H "Authorization: Bearer $SPOOLER_KEY"

HTTP/1.1 200 OK
Spooler-Lease: AYUBAQIBAwEEAQUC8XICs5rCQ8xd_87g
Spooler-Lease-Expires-At: 2026-08-19T16:46:59.850770793Z
Spooler-Message-Id: 1-1
Spooler-Retry-Count: 0

hello, world

Ack it by presenting the lease back:

curl -X POST "$SPOOLER_API/spools/default/ack" \
  -H "Authorization: Bearer $SPOOLER_KEY" \
  -H "Content-Type: application/json" \
  --data '{"lease": "<the Spooler-Lease header value>"}'

Returns 204. That is the whole loop: send, receive, ack. Nack, lease renewal, failure queues and deduplication are in the quickstart⁠ and the API reference⁠.

⁠What is in the image

• The Spooler server with ephemeral in-memory storage. Not a mock and not a reimplementation — but a 201 here means the send completed, not that the message survives anything.
• The same HTTP API. Every operation in the reference is available, with the same request shapes and response formats; the environment-specific statuses that never occur here are listed below.
• One static binary on FROM scratch: no shell, no package manager, no operating system, about 14 MB. It runs as uid 65534 and makes no outbound connections; the image ships no CA certificates.
• linux/amd64 and linux/arm64.
• One port, 8080. No volumes and no environment variables.
• A HEALTHCHECK, so a runner that waits for the container to become healthy will not race the first request.
• A proprietary licence: free for development, testing and evaluation, not for production or redistribution. See License⁠.

⁠What differs from the hosted service

• Nothing persists. A restarted container starts empty.
• One spool. Only default exists; any other name fails 404, as it would in production.
• Limits are not plan limits. Fixed limits apply here, printed at startup, and stored data is bounded by its memory budget. Production limits are per plan — see limits⁠.
• Rate limiting is off. 429 never occurs.
• Every key authenticates. 401 occurs only for a missing or non-bearer Authorization header, and 402 never occurs.
• The spool is always available. 503 never occurs, and no primary changes, so no lease is dropped by a failover.

A client that has run only against this image has not exercised its handling of 402, 429, 503, or a 401 for a rejected key. Those responses are in errors⁠. The full list of divergences is on Running locally⁠.

⁠In continuous integration

Run one container per test run and let it go: there is no state to reset beforehand and nothing to clean up after. Wait for the health check before the first request.

⁠Tags

⁠Documentation

• Running locally⁠ — what this image is and where it differs from production
• Quickstart⁠ — send, receive, ack
• API reference⁠ — every operation
• Delivery⁠ — what a delivery guarantees, and what it does not
• console.spooler.sh⁠ — the hosted service and API keys

Report a problem: github.com/spoolersh/docs/issues⁠

⁠License

Proprietary. The image is free to use for developing, testing and evaluating Spooler, including in automated test environments. Mirroring it into your own registry and building your own test images on top of it are allowed. It may not be run in production or as a substitute for the Spooler service, and may not otherwise be redistributed or modified. It is provided as is, without warranty.

The full text is at docs.spooler.sh/memspoold-license.txt⁠ and at /LICENSE in the image. There is no shell in the image, so read the embedded copy with docker cp:

docker create --name spooler-license spoolersh/memspoold
docker cp spooler-license:/LICENSE ./LICENSE
docker rm spooler-license