Environment variables

The broker has no configuration file and no command-line flags. Every knob is an environment variable, read once by config::load() during boot, before the HTTP listener binds. There is no reload: changing a variable means restarting the process. The one argument the binary accepts is the subcommand migrate, which exists only to report that offline migration was retired and exit non-zero.

One boolean parser

Every boolean in the broker goes through the same parser, so =on, =1 and =true mean the same thing everywhere. The accepted spellings are true/false, 1/0, yes/no, on/off, case-insensitive, surrounding whitespace trimmed.

Three outcomes, and only three:

• Recognised value: used.
• Unset, or present but empty or whitespace-only: the documented default. JWT_ENABLED= in a Compose file means “leave it alone”, not false.
• Anything else: a fatal boot error. The process logs FATAL: JWT_ENABLED="maybe" is not a boolean (expected true/false, 1/0, yes/no, on/off) and exits 1.

That last rule exists because the alternative failed in both directions: a strict parser with a silent fallback turned JWT_ENABLED=1 into a broker running with authentication off and nothing in the log. Booleans read outside config.rs (QUEEN_LOG_JSON, QUEEN_APPLY_SCHEMA, QUEEN_V2_BUNDLE_LOG) are validated eagerly at the same moment, so every boolean mistake in a deployment surfaces on the same boot with the same message.

Several numeric knobs are also clamped after parsing. Interval and size knobs are floored at 1, and STATS_INTERVAL_MS, RETAINED_BYTES_INTERVAL_MS and METRICS_FLUSH_MS are floored at 1000 ms: a value below the floor is raised without comment.

One clamp does comment, because the value it protects is a correctness invariant rather than a sanity floor. QUEEN_HOTLIST_RESEED_WINDOW_MS is held to at least one QUEEN_HOTLIST_RESEED_MS plus that interval’s de-phasing offset, which is the longest gap two consecutive passes of one ring can leave; below it there is a band of writes no pass ever covers. It is also held below a one-week ceiling. Either way the broker logs a boot warning naming the variable, the value you set and the value in force.

The effective configuration is printed at boot

After the JWT configuration is validated, the broker emits one boot block per subsystem (config: server, postgres, auth, sync, engine, flow, jobs, file_buffer, security, logging) carrying the values it actually resolved. A misspelled variable, a defaulted knob, or a value that came from a legacy alias is visible there instead of having to be inferred from behaviour. Read that block first when a setting appears not to have taken effect.

Secrets are masked, never printed: JWT_SECRET, PG_PASSWORD, QUEEN_ENCRYPTION_KEY and QUEEN_SYNC_SECRET render as <unset> or <set:32 chars>. That is enough to tell “I forgot to mount the secret” from “I mounted the wrong one” without putting key material into a log shipper.

What kills the boot

The broker prefers to die at startup over serving in a state you did not ask for. All five of these exit 1:

• an unparseable boolean, as above;
• JWT_ENABLED=true with no usable key material for the configured algorithm, or an algorithm outside HS256, HS384, HS512, RS256, RS384, RS512, EdDSA, auto;
• QUEEN_TENANCY_HEADER=1 with no QUEEN_KV_TRUSTED_PROXY=1;
• a schema apply failure (unless QUEEN_APPLY_SCHEMA=0);
• failure to bind $PORT on $QUEEN_BIND_ADDR, including a QUEEN_BIND_ADDR that carries a port of its own instead of a bare host or IP.

The third is a safety interlock rather than a validation, and it is keyed on the tenancy mode alone. The tenant header is opaque and validated against nothing, so the trust boundary is the network in front of the broker. That is tolerable for queues, where an ack still has an ownership gate on an id the caller cannot guess, and it is not tolerable for key/value state, which has no opaque id at all: the only gate is the tenant in the WHERE clause, and the tenant comes from the header. Setting QUEEN_KV_TRUSTED_PROXY=1 is the operator asserting that a proxy supplies that header and strips the client’s. An interlock that defaulted to permissive would be no interlock.

The unsafe thing there is not the key/value surface, it is an opaque tenant identity that nothing validates; the KV only made it visible, by being the first surface addressable purely by name. So the requirement is unconditional: there is no flag that switches the KV off to make an unvalidated tenant header safe, and there should not be one, because a fleet where the engine is missing on some cells is worse than a boot that names the variable to set. An operator who has to take the KV down on a running cell wants the runtime kill switch instead, which is a different instrument for a different problem. See KV and timers.

One important omission from that list: a malformed QUEEN_ENCRYPTION_KEY (not 64 hex characters, or not hex) logs a single warning and disables encryption. Queues flagged encryptionEnabled then store plaintext and the pushes succeed. Grep the boot config: security block for encryption_key=<set:64 chars> before trusting at-rest encryption.

Which variables actually matter

Most of the table below is measured engine tuning that should be left alone. In practice a deployment sets variables from these groups only.

Two conventions in that list are worth stating explicitly.

LOG_LEVEL accepts the full EnvFilter syntax, not just a bare level: info,queen::pop=debug works. RUST_LOG takes precedence over it, and an unparseable filter falls back to info.

PG_DATABASE resolves through a non-empty chain (PG_DATABASE, then the legacy PG_DB, then postgres), so an explicitly empty value falls through. Every other string variable keeps a present-but-empty value verbatim, which is how JWT_SKIP_PATHS="" can be used to clear the default skip list.

Every accelerator has an off switch

The broker-side fast paths are all optional, and none of them is load-bearing for correctness. Each one has a kill switch that reverts to the path the broker used before that optimisation existed, so an accelerator you do not trust can be turned off in a deployment without giving up a guarantee. What you give up is throughput, and the table says how much of what.

Pop autopilot is the one entry with three positions rather than two, and the third is the reason to reach for it. shadow computes the decision, reports it and does not apply it, so a deployment can read what the controller would have chosen for a week before letting it choose. off removes the controller outright, including its in-memory lane state and its logs. Both positions answer an opted-in request with today’s defaults and no autopilot object in the response, which is exactly what a broker older than 1.2 does, so a client needs no capability check either way.

Six constants tune the law rather than switch it. QUEEN_POP_AUTOPILOT_BATCH (100) is the batch handed to a consumer that delegated that dimension, and only to such a consumer: a client that sends its own batch is never touched by it. QUEEN_POP_AUTOPILOT_TARGET_AGE_MS (25) is the ready-age the width loop steers to. QUEEN_POP_AUTOPILOT_DWELL_MS (500) and QUEEN_POP_AUTOPILOT_DWELL_POPS (16) bound how often one (tenant, queue, group) may change its width in either direction, which is what stops the loop limit-cycling. QUEEN_POP_AUTOPILOT_MAX_LANES (50000) bounds the in-memory state on a cell with very many queues; past it the controller stops creating lanes and those lanes degrade to today’s defaults rather than a live one being evicted. QUEEN_POP_AUTOPILOT_BURST_CAP (0, disabled) lets a delegated width jump for one request to what is ready at that instant, capped, without the feedback loop losing ownership of the steady width.

Two of these are validated at boot rather than corrected. A QUEEN_POP_AUTOPILOT that is not a mode, and a QUEEN_POP_AUTOPILOT_BATCH outside its range, both kill the boot naming the value. Resolving a typo to the default silently is how a fleet ends up running on a number nobody chose.

One accelerator is absent from that table because it has no switch: push fusion has no enable flag. Cross-request push fusion is always on, and QUEEN_V2_FUSION_SHARDS (8), QUEEN_V2_FUSION_FRAMES (500) and QUEEN_V2_FUSION_HOLD_MS (3 ms) shape it rather than disable it.

The boot block prints the resolved state of most of these, so a deployment that thinks it turned one off can confirm it without inferring from throughput: config: engine carries hotlist, dedup_cache, ack_registry, ack_fusion and the reseed intervals, config: jobs carries retention_parallelism and partition_cleanup, and config: flow carries all seven pop_autopilot knobs next to the pop and admission ones. QUEEN_POP_FUSION is the exception: it prints nothing at boot in either state and has no counter of its own, so the deployment’s own environment is the only record of whether it is on.

Pop autopilot also says what it is doing while it runs, on its own autopilot log target. A rate-limited info line carries the mode, the width and batch it last chose, and running counts of requests, adjustments and live lanes, each line reporting how many it suppressed. A warn line fires once per lane, re-armed daily, when a client’s explicit width and the controller’s choice diverge widely: that one is diagnostic only, and it says so, because an explicit value is never overridden.

The variables

Defaults below are the ones the code applies, extracted from config.rs at build time. Where a variable has an alias, both names read the same setting and the newer name wins.

A handful of rows carry a derivation rather than a literal, because that is what the code applies. QUEEN_ADMISSION_INIT and QUEEN_ADMISSION_MIN come from the pool size; QUEEN_HOTLIST_RESEED_WINDOW_MS is rewritten before load() returns; QUEEN_KV_POOL_SIZE is DB_POOL_SIZE / 10 clamped to 4..32; QUEEN_KV_REQUIRE_GRANT takes the value of QUEEN_TENANCY_HEADER; and QUEEN_TIMERS_MAX_PAYLOAD_BYTES is the smaller of its own literal and the plan’s message payload ceiling, since a timer becomes a message and an independent ceiling would be a way around the plan’s. The extractor reads the call site, which for these is an expression rather than a number, so each of them is stated here with its derivation instead of published as whatever the expression happened to look like.

The broker is configured entirely through environment variables: 170 of them, listed below with the defaults the code actually applies. Booleans go through one strict parser: an unparseable value is a fatal boot error, while unset and empty both fall back to the default.

Two columns record what a variable falls back to. Also read as is an older name for the same setting: either name configures the same thing, and the row’s name wins when both are set. Default inherited from is a different knob whose value this one starts at when it is unset: setting that knob moves this variable and everything else that inherits from it, while setting this variable moves only this one.

Server

PostgreSQL

Authentication

Multi-broker mesh

Consume and long-poll

Storage engine

Admission and flow control

Background jobs

Durability spool

Security

Key/value state, timers and the sweeper

Logging

Other

Experiment-only

These exist to run experiments against the storage engine. The source marks them as such, they are not part of any compatibility promise, and a deployment should not set them.

Read but inert

The broker still parses these and still prints them in its boot configuration block, so they look live in a log. They change nothing.

Node identity

One variable does not appear in the table because it is not read through the same helper: QUEEN_SERVER_ID names this instance in mesh heartbeats and peer stats. Unset, the broker uses HOSTNAME; with neither, it generates queen-<8 hex>. The value is cosmetic (nothing routes on it), but it is what makes a peer list readable in the config: sync boot block.

Related pages