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.

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. Sixty 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. A concurrency permit. Push and pop each pass through their own adaptive limiter, a Vegas-style controller that sizes itself from observed PostgreSQL round-trip times. 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.

server/sql/schema.sql and 23 files under server/sql/procedures/ (001–023) are embedded in the binary with include_str! and applied at every boot, in lexical order, under session advisory lock 778120010. Every statement is idempotent, so re-apply is a no-op. QUEEN_APPLY_SCHEMA=0 skips the whole step so a privileged role can pre-apply the DDL and the broker can then run as a low-privilege user.

The boot apply only creates: nothing is dropped, migrated or folded at boot, because the deployment model is always-virgin. A deployment starts from an empty database, each table and function is defined exactly once by exactly one file, and there is no upgrade path: pointing this build at a database written by an earlier schema generation is unsupported. Lexical order is still load-bearing where SQL function bodies resolve tables at creation time: the table files (001, 002) come first, the engine procedures next, the management plane after, and the partition-counter trigger attachment (020_log_partition_counters) after both the table it attaches to and the functions it binds.

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, and each that mutates shared state elects a leader with an advisory lock so replicas never double-work.

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 mesh

With QUEEN_MESH_PEERS set, replicas form a full mesh over framed TCP. It carries three things: a wake for a parked pop when a push commits on another replica, maintenance-mode flips, and queue-config cache invalidation. 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.

Where to go next