Configuration
durable-server is configured entirely by flags; there is no config file. durable-server --help
is the same list in the binary. Defaults shown are what the flag carries.
The required two, and the directory that matters
Section titled “The required two, and the directory that matters”| Flag | Default | What it sets |
|---|---|---|
--journal <dir> |
data/journal |
the append-only journal — the runner’s only state. Local disk, one writer ever; see deployment |
--listen <addr> |
127.0.0.1:58300 |
bind address. Loopback is the default; bind wider only behind a real key and a proxy plan |
--handler name=URL |
— | repeatable: the allowlist a step may name. Unregistered names are refused at submit (409 unregistered_handler) |
Plus the environment: DURABLE_API_KEY (required at startup, ≥ 32 chars) and DURABLE_READ_KEY
(optional, ≥ 32 chars, must differ). Authentication covers what each opens.
Engine bounds
Section titled “Engine bounds”| Flag | Default | Bound |
|---|---|---|
--step-timeout-ms |
20000 |
per-attempt deadline on a handler call (the domain caps it at 30 s) |
--reply-timeout-ms |
10000 |
how long an API call waits on the engine before 503 timeout — a stuck disk must not hang every request |
--max-live-runs |
100000 |
non-terminal runs admitted; past it, submits are 503 at_capacity |
--max-index-bytes |
~512 MiB | approximate bytes of retained runs in memory; same refusal. Sized for a 2 GB host |
--max-in-flight |
32 |
handler calls (attempts + probes) concurrently in flight |
--max-dispatch-per-tick |
64 |
dispatches per 50 ms scheduler tick — the first-step dispatch rate is at most ~1280/s |
HTTP edge
Section titled “HTTP edge”| Flag | Default | Bound |
|---|---|---|
--max-connections |
512 |
connections served at once; extras wait in the accept queue. Keep below ulimit -n minus 64 |
--header-timeout-ms |
10000 |
a request head must arrive within this |
--body-deadline-ms |
30000 |
a request body must finish within this (408 otherwise) |
--write-stall-ms |
10000 |
a response write that stalls this long drops the connection |
--max-connection-secs |
600 |
a keep-alive connection’s maximum age |
--max-requests-per-connection |
100 |
the Nth answer carries Connection: close |
--drain-timeout-secs |
30 |
SIGTERM/SIGINT: finish in-flight requests, then let the engine make its decisions durable, before exiting |
Storage and maintenance
Section titled “Storage and maintenance”| Flag | Default | Bound |
|---|---|---|
--reserve-bytes |
67108864 (64 MiB) |
free space that must stay on the journal filesystem; below it submits are 503 no_space, /ready is false, compaction and backup refuse what won’t fit |
--backup-root <dir> |
— | enables POST /admin/backup; without it, 403 backups_disabled |
--compact-every-secs |
0 |
automatic compaction period; 0 means only on request (POST /admin/compact) |
--max-snapshot-bytes |
2147483648 (2 GiB) |
a compaction whose snapshot would exceed this is refused 409 snapshot_over_budget |
--journal-format |
— | print the highest journal record version this binary can read, then exit — the deploy kit’s format guard compares it to the journal’s before an upgrade or rollback |
Per-client limits
Section titled “Per-client limits”One address shouldn’t be able to hold every connection or spend every request: these flags bound
per-client pressure at the edge. All on by default — 0 disables any of them.
| Flag | Default | Bound |
|---|---|---|
--rate-limit-per-addr |
100 per second |
requests one client address may start; a token bucket with a one-second burst, the address table itself bounded. Over it, 429 rate_limited with Retry-After |
--rate-limit-v6-prefix |
64 |
prefix bits an IPv6 client is keyed by — a /64 holds 2⁶⁴ addresses, so keying the full address would let one client mint unlimited buckets |
--max-conns-per-addr |
64 |
connections one untrusted address may hold at once; past it the socket is closed at accept |
--max-conns-per-proxy |
4096 |
connections one peer inside the trusted ranges may hold — a proxy’s edge legitimately carries many real clients at once (the global --max-connections still bounds everything) |
--trusted-proxy <CIDR> |
— | repeatable: the proxy ranges the server believes. A client’s address comes from CF-Connecting-IP only when the peer is inside a trusted range — anyone can set that header, so it is believed from no one else |
Inside a /48 the per-address IPv6 buckets also share a /48 aggregate at 10× the rate, so a
host hopping addresses inside its own prefix stays one client and a whole /48 can’t hide a flood;
IPv4-mapped IPv6 addresses count as IPv4. 429 rate_limited is retryable — back off by
Retry-After, resubmit with the same op_key.
A second instance with a low rate shows the shape — five requests a second per address, a ten- request burst, then the honest refusal:
./target/release/durable-server --journal journal-limits --listen 127.0.0.1:58301 \ --rate-limit-per-addr 5 --trusted-proxy 10.0.0.0/8 >limits-server.log 2>&1 &LIMITED=$!for _ in $(seq 1 100); do curl -sf http://127.0.0.1:58301/health >/dev/null && break; sleep 0.1; donefor i in $(seq 1 10); do curl -s -o /dev/null -w '%{http_code} ' -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobsdone; echocurl -si -H "Authorization: Bearer $DURABLE_API_KEY" http://127.0.0.1:58301/jobs | sed -n '1p;/retry-after/Ip;/rate_limited/p'kill $LIMITED 2>/dev/null; wait $LIMITED 2>/dev/null || true; rm -rf journal-limits limits-server.log200 200 200 200 429 429 429 429 429 429HTTP/1.1 429 Too Many Requestsretry-after: 1{"error":"rate limited","code":"rate_limited"}The UI and the loophole
Section titled “The UI and the loophole”| Flag | Default | Bound |
|---|---|---|
--ui-dir <dir> |
— | serve the built Inspector assets at /inspector |
--open-reads |
off | serve GET /jobs* without a key — loopback listen only (refused at startup otherwise), and never behind a proxy; authentication explains why |
A production-shaped start
Section titled “A production-shaped start”DURABLE_API_KEY="$(openssl rand -hex 32)" \DURABLE_READ_KEY="$(openssl rand -hex 32)" \durable-server --journal /var/lib/durable/journal --listen 127.0.0.1:58300 \ --handler invoices=http://127.0.0.1:58320/invoices \ --handler reports=http://127.0.0.1:58321/reports \ --backup-root /var/lib/durable/backups --compact-every-secs 3600The loopback listen is deliberate: TLS terminates at the proxy in front, and the read surface still wants the keys. Security is the checklist this start assumes.