leanqueue 0.2.0__tar.gz

leanqueue-0.2.0/.cargo/config.toml

@@ -0,0 +1,4 @@
+# Align loop starts to 32 bytes on x86_64 so a short hot loop (CRC, frame scan) never
+# straddles a 64-byte line by luck of the build (same setting as LeanText/LeanVec).
+[target.'cfg(target_arch = "x86_64")']
+rustflags = ["-C", "llvm-args=-align-loops=32"]

leanqueue-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    # A hang must fail the job with a traceback, not hold a runner for 6 hours. The
+    # thread timeout method (the only one on Windows) exits pytest, so failures are
+    # printed as they happen (--instafail), not only in the final summary.
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python-version: '3.8'
+          - os: ubuntu-latest
+            python-version: '3.13'
+          - os: macos-latest
+            python-version: '3.12'
+          - os: windows-latest
+            python-version: '3.12'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Rust unit tests
+        shell: bash
+        run: cargo test --release
+      - name: Build and install the wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip maturin
+          maturin build --release --out dist
+          python -m pip install dist/*.whl pytest pytest-timeout pytest-instafail psutil
+      - name: Install the server stacks (3.9+; the stubs need protobuf 7)
+        if: matrix.python-version != '3.8'
+        shell: bash
+        run: python -m pip install "fastapi>=0.110" "uvicorn[standard]>=0.29" httpx "pydantic>=2.8" "grpcio>=1.82.1" "protobuf>=7.35,<8"
+      - name: Python suite against the installed wheel (outside the checkout)
+        shell: bash
+        env:
+          LEANQUEUE_COMPAT_INSTALL: ${{ matrix.os == 'ubuntu-latest' && '1' || '0' }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/run" && cd "$RUNNER_TEMP/run"
+          python -m pytest "$GITHUB_WORKSPACE/tests" -v --tb=short -p no:cacheprovider \
+            --durations=15 --timeout=600 --timeout-method=thread -o faulthandler_timeout=300 \
+            --instafail

leanqueue-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,206 @@
+name: Release
+
+# Tags `v*` build, test and publish. A manual run builds and tests every platform wheel
+# but never publishes.
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  # Nothing is built for other platforms, and nothing is published, until this passes.
+  # It builds the extension the way a user gets it (a wheel), installs THAT wheel into a
+  # clean environment and runs the Rust tests plus the whole Python suite against it
+  # from outside the source tree, so a wheel missing leanqueuedb.py or the server
+  # package, or a native module that does not match the facade, fails here.
+  test:
+    name: Test (Rust + Python against an installed wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Rust unit tests
+        run: cargo test --release
+
+      - name: Build the wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          args: --release --out dist
+          sccache: 'true'
+          manylinux: auto
+
+      - name: Install the wheel (with server extras) and the test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          WHEEL="$(ls dist/*.whl)"
+          python -m pip install "${WHEEL}[server,grpc]"
+          python -m pip install pytest "psutil>=5.9" httpx "grpcio-tools==1.82.1"
+
+      - name: Verify the checked-in gRPC stubs match the proto and the pinned toolchain
+        run: |
+          python scripts/gen_grpc.py
+          git diff --exit-code -- leanqueue_server/leanqueue_pb2.py leanqueue_server/leanqueue_pb2_grpc.py
+
+      - name: Import the installed wheel from outside the checkout
+        run: |
+          cd /tmp
+          python -c "
+          import leanqueue, leanqueuedb, sys, tempfile
+          assert 'leanqueue_server' not in sys.modules
+          print(leanqueuedb.__file__, leanqueue.__version__)
+          with tempfile.TemporaryDirectory() as d:
+              q = leanqueuedb.Queue(d)
+              q.put(b'hello')
+              m = q.get(); assert m.body == b'hello'; m.ack()
+              q.close()
+          print('wheel round trip ok')
+          "
+
+      - name: Exercise the packaged REST + gRPC servers from outside the checkout
+        run: |
+          cd /tmp
+          leanqueue-serve --help >/dev/null
+          leanqueue-grpc --help >/dev/null
+          python "$GITHUB_WORKSPACE/scripts/server_smoke.py"
+
+      - name: Run the full Python suite against the installed wheel
+        env:
+          # test_compat_published.py installs leanqueue 0.1.0 into a throwaway venv and
+          # checks old-writes/new-reads, new-writes/old-reads and mixed processes.
+          LEANQUEUE_COMPAT_INSTALL: '1'
+        run: |
+          mkdir -p /tmp/run && cd /tmp/run
+          timeout --signal=INT --kill-after=30s 20m python -m pytest "$GITHUB_WORKSPACE/tests" \
+            -vv -x --tb=short -o faulthandler_timeout=120 -p no:cacheprovider
+
+  linux:
+    needs: [test]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [x86_64, x86, aarch64, armv7]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+          manylinux: auto
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.target }}
+          path: dist
+
+  windows:
+    needs: [test]
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        target: [x64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          architecture: ${{ matrix.target }}
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+      - name: Smoke-test the Windows wheel
+        shell: bash
+        run: |
+          python -m pip install dist/*.whl
+          cd "$RUNNER_TEMP"
+          python -c "
+          import leanqueuedb, tempfile, os
+          d = tempfile.mkdtemp()
+          q = leanqueuedb.Queue(d); q.put_many([b'a', b'b']); q.close()
+          q = leanqueuedb.Queue(d); m = q.get(); assert m.body == b'a'; m.ack()
+          q.compact(); assert q.available() == 1; assert q.verify_integrity()['ok']; q.close()
+          print('windows wheel ok')
+          "
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-windows-${{ matrix.target }}
+          path: dist
+
+  macos:
+    needs: [test]
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        target: [x86_64, aarch64]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          sccache: 'true'
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-macos-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-sdist
+          path: dist
+
+  pypi-publish:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    name: Publish to PyPI
+    needs: [test, linux, windows, macos, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/leanqueue
+    # Publishing uses the token below, not OIDC trusted publishing.
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Publish to PyPI
+        uses: PyO3/maturin-action@v1
+        env:
+          MATURIN_PYPI_TOKEN: ${{ secrets.PYPIV2 }}
+        with:
+          command: upload
+          args: --non-interactive --skip-existing dist/*

leanqueue-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+*__pycache__*
+target/
+dist/
+*.tar.gz
+*.log
+*_q/
+*_queue/
+.pytest_cache/
+*.so
+*.pyd

leanqueue-0.2.0/AGENTS.md

@@ -0,0 +1,37 @@
+# Agent Directives: State & Memory Management
+
+## 1. Initialization & Core Operating Principle
+**Initialization Protocol:** On your very first interaction within any workspace, check the root directory for the existence of `HISTORY.md` and `REPO.md`. If either file is missing, you must create and initialize them immediately before executing any other commands or tasks.
+
+**Core Principle:** You are responsible for maintaining the repository's internal memory. You will not write these files for human consumption. You will encode all information using a Sparse Priming Representation (SPR) methodology to optimize for future LLM context ingestion.
+
+### SPR Encoding Rules:
+* **Maximize Density:** Distill all features, decisions, and chronological events into succinct statements, conceptual associations, and technical assertions.
+* **Minimize Tokens:** Capture the absolute maximum amount of conceptual meaning with the absolute minimum number of words. 
+* **Target Latent Space:** Use precise technical vocabulary, metaphors, or architectural analogies that efficiently prime an LLM's internal state. Avoid conversational filler. Use complete sentences.
+
+---
+
+## 2. HISTORY.md (Temporal State & Dynamic Compression)
+**Objective:** Maintain a strict, chronological ledger of repository modifications while rigorously actively managing the token footprint.
+
+**Instructions:**
+* **Event Logging:** Append a new entry upon the completion of any task, refactor, or architectural shift. Encode the delta (code state shifts, resolved edge cases, logic pathways) strictly using SPR. Do not use standard git-style commit messages.
+* **Temporal Compression (The "Roll-up"):** To prevent linear context bloat, you must actively compress older history. 
+    * Monitor the depth of the history log. If the file grows too long (e.g., exceeding 20-30 distinct entries), initiate a compression cycle.
+    * Condense the oldest 80% of the entries into a single, ultra-dense SPR macro-summary under a `# Legacy Epoch` header. 
+    * Retain the most recent 20% of entries in their distinct chronological format for immediate context.
+    * Apply this fractal compression continuously as the repository ages, rolling older epochs into denser concepts while keeping recent context highly granular.
+
+---
+
+## 3. REPO.md (Macro State)
+**Objective:** Maintain a live, highly compressed snapshot of the repository's architecture and purpose.
+
+**Instructions:**
+* Continuously update `REPO.md` to reflect the current macro-state of the project.
+* Whenever a new feature is added, an architectural decision is made, or the project boundaries shift, rewrite the relevant sections using SPR encoding.
+* Ensure the file always contains these three conceptual clusters:
+    * **Features:** Active capabilities, I/O boundaries, and core operational loops.
+    * **Decisions:** Technical trade-offs, architecture selections, hardware/environment optimizations, and accepted constraints.
+    * **Scopes:** Project boundaries, target use cases, and explicit anti-goals (what the system is specifically designed *not* to do).

leanqueue-0.2.0/CLIENT.md

@@ -0,0 +1,234 @@
+# LeanQueue servers: client guide
+
+LeanQueue is an embedded library first. The REST and gRPC servers expose the same
+queues to programs that cannot import it (other languages, other hosts). Both ship in
+the wheel; their dependencies are extras:
+
+```bash
+pip install "leanqueue[server]"   # REST:  leanqueue-serve
+pip install "leanqueue[grpc]"     # gRPC:  leanqueue-grpc
+```
+
+Both servers are backed by one `leanqueuedb.Broker` rooted at the data directory. Each
+queue is a subdirectory, the same layout the library uses, so a server and local
+processes can share a data directory (all of them coordinate through the queue's file
+lock). REST, gRPC and the library return the same results for the same operations:
+the test suite checks this.
+
+## Running
+
+```bash
+leanqueue-serve --data-dir /var/lib/queues                # REST on 127.0.0.1:8004
+leanqueue-grpc  --data-dir /var/lib/queues                # gRPC on 127.0.0.1:50054
+```
+
+The flags set the environment variables listed below. SIGINT and SIGTERM shut a
+server down gracefully: in-flight requests finish, open gRPC consume streams return
+their unacked messages to the queue, and every queue is fsynced and closed.
+
+## Concepts
+
+* **Declare before use.** `PUT /queues/{name}` (REST) or `DeclareQueue` (gRPC) creates
+  a queue. Any other operation on an undeclared queue returns 404 / `NOT_FOUND`. A
+  mistyped name therefore cannot create a queue that nobody consumes.
+* **Queue names** have 1 to 255 characters from `A-Z a-z 0-9 - _ .`. The names `.` and
+  `..` are not allowed. Other names return 400 / `INVALID_ARGUMENT`.
+* **Leases.** A get leases messages for `lease_ms` milliseconds. The default is the
+  queue's lease (30 s, or `LEANQUEUE_DEFAULT_LEASE_MS`). Settle each message with ack
+  (done), nack (requeue it, or drop it), or extend (renew the lease). If a lease
+  expires, the message is delivered again and its `deliveries` count goes up. Delivery
+  is at-least-once.
+* **Sequence ids** (`seq`) identify messages for ack, nack, extend and states.
+
+## REST API
+
+All bodies are JSON. Replies are JSON. Unknown body fields and unknown query parameters
+are rejected with 422. Numbers must be JSON integers: `true`, `"5"` or `1.5` where an
+integer is expected is also a 422.
+
+| Method + path | Body | Reply |
+|---|---|---|
+| `GET /health` | | `{"ready", "version", "limits"}` (never needs a token) |
+| `GET /queues[?stats=true]` | | `{"queues": [names]}` (+ `"stats": {name: stats}`) |
+| `PUT /queues/{q}` | | `{"queue", "created": bool}` |
+| `DELETE /queues/{q}` | | `{"deleted": true}` (404 if absent) |
+| `GET /queues/{q}/stats` | | the `Queue.stats()` dict |
+| `POST /queues/{q}/publish` | one of `{"body": str}`, `{"body_b64": str}`, `{"json": any}` | `{"seq"}` |
+| `POST /queues/{q}/publish_batch` | `{"messages": [<same shape>, ...]}` | `{"seqs": [...]}` |
+| `POST /queues/{q}/get` | `{"max_messages": 1, "lease_ms": null, "wait_ms": 0, "encoding": "base64"}` | `{"messages": [...]}` |
+| `POST /queues/{q}/ack` | `{"seqs": [...]}` | `{"acked": n}` |
+| `POST /queues/{q}/nack` | `{"seqs": [...], "requeue": true}` | `{"nacked": n}` |
+| `POST /queues/{q}/extend` | `{"seqs": [...], "lease_ms": null}` | `{"extended": n}` |
+| `POST /queues/{q}/states` | `{"seqs": [...]}` | `{"states": [null or {"state", "deliveries", "lease_until_ms"}]}` |
+| `POST /queues/{q}/purge` | | `{"purged": true}` |
+
+Message bodies:
+
+* Publish: `body` is stored as UTF-8 text, `body_b64` as the decoded bytes, and `json`
+  as the compact JSON encoding of the value.
+* Get: each message is `{"seq", "deliveries", "enqueued_at_ms", ...}` plus the body.
+  With `"encoding": "base64"` (the default) the body is in `body_b64`. With `"text"` it
+  is in `body`, and with `"json"` it is the parsed value in `json`. If a body is not
+  valid in the requested encoding, it falls back to `body_b64`.
+
+`wait_ms` > 0 turns a get on an empty queue into a long poll. The server checks the
+queue every `LEANQUEUE_POLL_MS` (20 ms) until a message arrives or the wait ends.
+Waiting does not block the server. If the client disconnects after messages were
+leased, those leases expire and the messages are delivered again.
+
+`publish_batch`, a get of several messages, and the ack, nack and extend calls each
+use one write and one fsync.
+
+```bash
+curl -X PUT  localhost:8004/queues/jobs
+curl -X POST localhost:8004/queues/jobs/publish -H 'content-type: application/json' \
+     -d '{"json": {"task": "resize", "id": 42}}'
+curl -X POST localhost:8004/queues/jobs/get -H 'content-type: application/json' \
+     -d '{"max_messages": 10, "wait_ms": 5000, "encoding": "json"}'
+curl -X POST localhost:8004/queues/jobs/ack -H 'content-type: application/json' \
+     -d '{"seqs": [0]}'
+```
+
+```python
+from leanqueue_server.client import LeanQueueRestClient
+
+with LeanQueueRestClient("http://127.0.0.1:8004", token=None) as r:
+    r.declare("jobs")
+    r.publish("jobs", b"payload")
+    for m in r.get("jobs", max_messages=10, wait_ms=1000):
+        handle(m["body"])                      # bytes
+        r.ack("jobs", [m["seq"]])
+```
+
+## gRPC API
+
+The service `leanqueue.LeanQueue` is defined in `leanqueue_server/leanqueue.proto`.
+Bodies are `bytes` and stats are a JSON string.
+
+| RPC | Request | Reply |
+|---|---|---|
+| `Health` | | `ready, version, limits_json` (never needs a token) |
+| `ListQueues` | | `queues` |
+| `DeclareQueue` / `DeleteQueue` | `queue` | `created` / `deleted` |
+| `Stats` | `queue` | `stats_json` |
+| `Publish` | `queue, body` | `seq` |
+| `PublishBatch` | `queue, bodies` | `seqs` |
+| `Get` | `queue, max_messages, lease_ms?, wait_ms` | `messages` (`Delivery`) |
+| `Ack` | `queue, seqs` | `count` |
+| `Nack` | `queue, seqs, drop` (`drop=false` requeues) | `count` |
+| `Extend` | `queue, seqs, lease_ms?` | `count` |
+| `States` | `queue, seqs` | `states` (`exists, in_flight, deliveries, lease_until_ms`) |
+| `Purge` | `queue` | |
+| `Consume` (server stream) | `queue, prefetch, lease_ms?, idle_timeout_ms` | stream of `Delivery` |
+
+`Consume` pushes messages as they become available. At most `prefetch` delivered
+messages can be unsettled at a time. Settle them with `Ack`, `Nack` or `Extend` on the
+same or another channel. A message also stops counting against the window when its
+lease expires.
+
+When the stream ends, the server requeues the messages that are still leased to it.
+This happens on a client cancel, a deadline, `idle_timeout_ms` with nothing to deliver,
+or a server shutdown. It is the same behaviour as a RabbitMQ consumer whose channel
+closes.
+
+Each open stream holds one server worker thread, so the number of open streams is
+limited (see `LEANQUEUE_GRPC_MAX_STREAMS`).
+
+```python
+from leanqueue_server.client import LeanQueueClient
+
+with LeanQueueClient("127.0.0.1:50054", token=None) as c:
+    c.declare("jobs")
+    c.publish_batch("jobs", [b"a", b"b"])
+    for d in c.consume("jobs", prefetch=10):       # dicts: seq, deliveries, enqueued_at_ms, body
+        handle(d["body"])
+        c.ack("jobs", [d["seq"]])
+```
+
+Clients in other languages can generate stubs from `leanqueue.proto`. To regenerate the
+Python stubs after a proto change, run `python scripts/gen_grpc.py` (needs
+`grpcio-tools==1.82.1`).
+
+## Authentication and TLS
+
+* Both servers bind `127.0.0.1` by default.
+* REST on any other address needs `LEANQUEUE_API_TOKEN`, or
+  `LEANQUEUE_ALLOW_INSECURE=1` to declare the network trusted. Otherwise the server
+  does not start.
+* gRPC on any other address needs TLS (`LEANQUEUE_GRPC_TLS_CERT` and
+  `LEANQUEUE_GRPC_TLS_KEY`, PEM files) **and** `LEANQUEUE_API_TOKEN`, or
+  `LEANQUEUE_ALLOW_INSECURE=1`.
+* When a token is set, every request except health must carry
+  `Authorization: Bearer <token>`. For gRPC, send it as the `authorization` metadata
+  entry. This applies to unary calls and streams. A missing or wrong token returns
+  401 / `UNAUTHENTICATED`. Tokens are compared in constant time.
+* The token is read only from the environment, never from a flag, so it does not appear
+  in `ps`.
+
+## Limits
+
+Static caps can be changed with environment variables. A request over a cap is refused
+before it reaches the queue.
+
+| Env var | Default | Applies to |
+|---|---|---|
+| `LEANQUEUE_MAX_REQUEST_BYTES` | 128 MiB | Whole REST body (413), and the gRPC max message size |
+| `LEANQUEUE_MAX_BODY_BYTES` | 512 MiB − 21 | One message body (enforced by the queue core, 400; it can only be lowered) |
+| `LEANQUEUE_MAX_BATCH` | 10 000 | Messages per publish batch (429) |
+| `LEANQUEUE_MAX_PREFETCH` | 1 000 | `max_messages` per get and `prefetch` per consume (429). Also limited by memory, see below |
+| `LEANQUEUE_MAX_WAIT_MS` | 30 000 | Long-poll `wait_ms` (429) |
+| `LEANQUEUE_MAX_SEQS` | 100 000 | Sequence ids per ack, nack, extend or states call (429) |
+| `LEANQUEUE_MEM_FRACTION` | 0.5 | Share of available RAM used for the memory-aware caps |
+| `LEANQUEUE_PER_RESULT_BYTES` | 4096 | Assumed memory per delivered message, for the memory-aware get cap |
+| `LEANQUEUE_MIN_GET` | 16 | The memory-aware get cap never goes below this (unless memory is truly short) |
+| `LEANQUEUE_BODY_MEM_FRACTION` | = MEM_FRACTION | Memory budget shared by REST bodies that are being parsed |
+| `LEANQUEUE_MEM_REFRESH_SECS` | 1.0 | How often the memory probe runs |
+
+Memory-aware caps:
+
+* Available memory is the smaller of `MemAvailable` and the container's cgroup v1 or v2
+  allowance.
+* The number of messages per get is limited by that memory, divided among the workers.
+* The bodies in one get reply are limited to a byte budget, also derived from that
+  memory. A get stops early when the budget is used up. It always returns at least
+  one message, and it can go over the budget by at most one chunk of 64 messages.
+
+REST body admission:
+
+* A request body is admitted before it is parsed. A declared `Content-Length` over the
+  cap gets 413.
+* A body that does not fit the current memory budget gets 429 with `Retry-After`.
+* Chunked bodies are measured as they arrive. Bodies with `Transfer-Encoding` are not
+  trusted to match their `Content-Length`.
+
+## Server settings
+
+| Env var | Default | |
+|---|---|---|
+| `LEANQUEUE_DATA_DIR` | `./leanqueue_data` | Broker root (`--data-dir`) |
+| `HOST` / `PORT` | `127.0.0.1` / `8004` | REST bind address (`--host`, `--port`) |
+| `GRPC_HOST` / `GRPC_PORT` | `127.0.0.1` / `50054` | gRPC bind address |
+| `LEANQUEUE_THREADS` | min(64, 2×CPUs) | REST worker threads |
+| `LEANQUEUE_GRPC_WORKERS` | min(64, 2×CPUs) | gRPC worker threads |
+| `LEANQUEUE_GRPC_MAX_STREAMS` | workers / 2 | Open `Consume` streams (`RESOURCE_EXHAUSTED` past it) |
+| `LEANQUEUE_GRPC_MAX_CONCURRENT_RPCS` | unset (unbounded) | Opt-in limit on running plus queued RPCs |
+| `LEANQUEUE_POLL_MS` | 20 | Poll interval of long-poll gets and consume streams |
+| `LEANQUEUE_SYNC_INTERVAL_MS` | 0 | Queue durability: 0 fsyncs each write; N fsyncs in the background within N ms (`--sync-interval-ms`) |
+| `LEANQUEUE_DEFAULT_LEASE_MS` | 30 000 | Default lease of the queues |
+| `LEANQUEUE_AUTO_COMPACT_BYTES` | 64 MiB | Auto-compaction threshold of the queues |
+| `LEANQUEUE_API_TOKEN`, `LEANQUEUE_ALLOW_INSECURE`, `LEANQUEUE_GRPC_TLS_CERT`, `LEANQUEUE_GRPC_TLS_KEY` | unset | See Authentication |
+
+gRPC connections send keepalive pings (every 60 s, 20 s timeout). This cancels the
+streams of a client that vanished without closing its connection.
+
+## Errors
+
+| Kind | HTTP | gRPC | Typical cause | Retry? |
+|---|---|---|---|---|
+| not found | 404 | `NOT_FOUND` | Queue not declared, or deleted | No |
+| invalid | 400 (422 for a malformed body or query) | `INVALID_ARGUMENT` | Bad queue name, bad base64, negative seq, body over `LEANQUEUE_MAX_BODY_BYTES` | No |
+| over capacity | 413 (body too large), 429 | `RESOURCE_EXHAUSTED` | A cap above, the memory budget, or too many streams | Yes (429 has `Retry-After: 1`) |
+| unavailable | 503 | `UNAVAILABLE` | Process-lock timeout (busy peer), I/O error such as ENOSPC, queue closed under the request | Yes (`Retry-After: 1`) |
+| internal | 500 | `INTERNAL` | `CorruptionError`, `UnsupportedFormatError`, `DurabilityError`: an operator must look at the queue (see docs/RECOVERY.md) | No |
+
+Error details are limited to 512 characters and never repeat request data back.