Internals

Queen is one stateless Rust binary (crate queen, binary queen) and one PostgreSQL database. The binary holds no durable state. Every offset, cursor, lease and segment lives in PostgreSQL, and every in-memory structure in the broker is a cache or a scheduler over it. That single fact is the key to reading this section: when an in-memory structure is stale, wrong, or lost to a restart, the outcome is extra work, not lost or misdelivered messages. Each page below states its own version of that argument, because each structure earns its place only by having one. The one deliberate exception is the ephemeral queue class, whose contents live in broker memory by contract: only the declared configuration is a PostgreSQL row, its hot verbs take neither an admission slot nor a pooled connection, and losing its contents on a restart is that class’s documented trade, not a defect. Everything else in this section is state PostgreSQL owns.

Read the concept pages first if you want to know what Queen promises. This section explains how it keeps those promises, and where it pays for them.

The request path

An HTTP request crosses the same five layers regardless of what it does.

1. The axum router in server/src/main.rs. Eighty-four method-and-path pairs on one flat Router, plus a fallback that serves the dashboard SPA compiled into the binary with rust_embed from server/webapp/dist. There is no runtime static-directory override. There is no TLS listener and no CORS layer: the broker speaks plaintext HTTP on PORT (6632) and expects a proxy in front of it.
2. Middleware. JWT validation (off by default) resolves an access level and an authenticated sub; tenant resolution reads x-queen-tenant when QUEEN_TENANCY_HEADER=1, otherwise stamps the fixed default tenant. Both run before any handler and both are transparent when disabled.
3. An admission slot. Every write transaction passes through one process-wide arbiter that sizes itself from PostgreSQL’s commit-flush pipeline, with four lanes (push, pop, ack, maint) sharing the budget. See Flow control.
4. A pooled connection. One deadpool-postgres pool, DB_POOL_SIZE connections (default 160), shared by handlers and background jobs. Hot statements go through prepare_cached, so a steady-state call re-uses a prepared statement on that connection.
5. One stored-procedure call. Almost every route is a single SELECT queen.<sp>(...) whose JSON result the handler forwards, sometimes verbatim. The decision procedures (who gets which message, whether a push is a duplicate, what an ack commits) live in SQL, under row locks, not in Rust.

A pop that has to wait is the one exception worth knowing: it releases both the permit and the connection before it parks, and re-acquires them on wake. A parked long-poll costs the broker a timer and nothing else.

What lives in memory

Nothing in this table is durable. Every entry is followed by what its being wrong costs.

The two things that decide what data exists (the deduplication verdict and the consumer cursor) are not in this table. They are in PostgreSQL, computed under a row lock, on every call.

The storage side

Storage is the “log engine”: four tables created by 001_log_schema.sql (log_partitions, log_segments, log_txns, log_consumers) plus queen.log_dlq from the ack file, all hanging off queen.queues, which is both a queue’s identity and its configuration (log_partitions.queue_id references it directly, ON DELETE CASCADE). A partition is an ordered lane; a message’s position is a single monotone BIGINT offset; a segment is one row holding many messages packed together and zstd-compressed. The storage model has the row-by-row detail.

Two further tables hang off nothing at all. queen.kv and queen.log_timers are created at every boot like the rest, and stay empty unless an operator switches their surfaces on. Neither names a partition, deliberately, which is what keeps them out of the per-partition maintenance scan; see KV internals and timer internals. The ephemeral class keeps two more (queen.ephemeral_queues, queen.ephemeral_quota): declared configuration and quota rows only, never message contents.

All of that DDL is include_str!-embedded in the binary and re-applied idempotently at every boot, under an advisory lock and with no migrations, because the deployment model is always-virgin; the schema catalogue has the apply order and its rules.

Background jobs

Several loops run alongside the HTTP server. Each is spawned before axum::serve, each swallows its own errors so a transient database failure cannot kill it. The cluster-singleton loops schedule through one durable claim row each in queen.maintenance_leases, so their cadence is the configured value whatever the replica count; the advisory locks stay inside those cycles as belt against old-image pods.

The metrics collector is deliberately un-gated: every replica records its own rows, keyed by hostname and worker id, and the dashboard aggregates across them.

The sweeper is un-gated for a stronger reason, and it is the opposite of retention’s. Any ownership scheme orphans the work of a broker that dies, and an orphaned timer never fires, which is the worst failure this component can have. So every replica drains in parallel and the sharing mechanism is FOR UPDATE ... SKIP LOCKED rather than an election. It is spawned on every replica, because the two surfaces it serves are on every replica; QUEEN_SWEEPER=false is the only thing that stops it.

The mesh

With QUEEN_MESH_PEERS set, replicas form a full mesh over framed TCP. It carries wakes for parked pops when a push commits on another replica, hot-list pending marks, maintenance-mode flips, queue-config cache invalidation, and the admin fan-out for ephemeral queues (whose data verbs travel broker-to-broker over plain HTTP instead, to the owner the HELLO handshake advertised). Nothing it carries is authoritative: PostgreSQL is re-read every QUEEN_CACHE_REFRESH_INTERVAL_MS and a parked pop re-polls on its own backoff, so a dropped frame costs latency only. It also has a security boundary you must enforce yourself: see The mesh.

Working on Queen

The four pages under Contributing are the same tier pointed at the repository rather than at the running system. They are the answer to “where does this claim come from”: the workspace and the build order, the suites each page names in its verifiedBy frontmatter, the generators that derive this site’s fact tables from server/, and what a release actually publishes.

Where to go next