C++ client

One header, queen_client.hpp, namespace queen. Everything is inline, so there is nothing to link. It has no separately published package version: the header is the version at the repository tag or commit you check out.

#include "queen_client.hpp"

queen::QueenClient client("http://localhost:6632");

Build requirements

The relative include means the header expects to sit next to the repository’s server/ directory, or to be compiled with that directory on the include path (-I../server/include -I../server/vendor, as the shipped Makefile does).

Configuration

struct Retry429Options {
    int max_attempts = 0;   // 0 = kind-based default
    int base_millis  = 0;   // 0 = 500
    int cap_millis   = 0;   // 0 = 30000
};

struct ClientConfig {
    std::vector<std::string> urls;
    int timeout_millis = 30000;
    int retry_attempts = 3;
    int retry_delay_millis = 1000;
    std::string load_balancing_strategy = "round-robin";
    bool enable_failover = true;
    std::string bearer_token;
    Retry429Options retry_429;
};

Retry429Options covers HTTP 429 only, separately from retry_attempts, and a zero field means “use the kind-based default”; the defaults, the Retry-After contract and the jitter are in What the clients do with a 429.

QueenClient

QueenClient(const std::string& url);
QueenClient(const std::vector<std::string>& urls, const ClientConfig& config = ClientConfig());

ack

message is a message object, a transaction-id string, or a JSON array of either. status is bool only: true → completed, false → failed. context accepts a group key and an error key.

partitionId is required on every message object; without it the call throws std::runtime_error("Message must have partitionId property"). A leaseId is forwarded when present. One message posts to /api/v1/ack; an array posts to /api/v1/ack/batch.

Return shape:

renew

Accepts a lease-id string, a message object, or an array of either. Lease ids are deduplicated in insertion order: with multi-partition pop one extend call renews every claimed partition, so passing the whole message array issues one HTTP call. Returns an array of {leaseId, success, newExpiresAt} for an array input, or the single element for a scalar input.

QueueBuilder

client.queue(name). Configuration methods return QueueBuilder&; terminal methods are push(), pop(), consume(), create(), del(), dlq() and flush_buffer().

Addressing

Queue lifecycle

QueueConfig’s snake_case fields (lease_time, retry_limit, delayed_processing, window_buffer, retention_seconds, completed_retention_seconds, encryption_enabled) map onto the camelCase wire options via to_json(), with the values listed under Queue option defaults.

create() always sends the complete set, so calling it without config() applies the struct’s defaults, including leaseTime: 300, whereas a queue created implicitly by a first push gets a 60-second lease. to_json() emits a fixed key set, so options outside that struct cannot be set through config(); post to /api/v1/configure yourself when you need one. Since 1.6.0 that route merges, so a hand-written partial body edits what it names and leaves the rest alone, and "mode": "replace" is how you ask for the old reset-everything-else behaviour. This client sends no mode and a complete set either way, so its own create() behaves as it always has.

Producing

Each item may carry data, payload, or be the payload itself. The client mints a UUIDv7 transactionId when the item has none, and sends traceId only when it is a valid UUID. The broker’s push path stores no trace id, so the value is dropped and the message pops back with traceId: null; it is honoured only on the transaction path. A direct push returns the broker’s per-item array; a buffered push returns {"buffered": true, "count": n} without sending.

client.queue("orders")
      .partition("customer-42")
      .push({{{"data", {{"orderId", 8891}}}}});

Consuming

pop()

json pop() returns the messages array, or an empty array. Route selection: queue plus non-Default partition uses /api/v1/pop/queue/:queue/partition/:partition; queue alone uses /api/v1/pop/queue/:queue; namespace or task alone uses /api/v1/pop. None of the three throws.

pop_result()

PopResult pop_result() returns {messages, autopilot}. It is the same call as pop() and returns the messages plus the broker’s account of how it sized the claim: partitions, batch, and an optional wait_millis pacing hint the consume loop honours in place of its own delay between empty polls. autopilot.present is false when the pop did not engage autopilot, when the broker is older than 1.2, or when the answer was a bodiless 204, which has no body to carry an echo. See pop autopilot.

consume()

void consume(std::function<void(const json&)> handler,
             std::atomic<bool>* stop_signal = nullptr);

Blocks until every worker stops. The handler receives one message in each() mode and the whole messages array otherwise. Workers stop when *stop_signal becomes true, when is_shutdown_requested() is set by close(), on the limit, or on the idle timeout.

std::atomic<bool> stop{false};
client.queue("orders").group("workers").batch(10).each()
      .consume([](const queen::json& msg) { /* … */ }, &stop);

Worker loop behaviour:

• A handler exception with auto_ack on nacks the message and the worker continues.
• A 429 that escapes the HTTP layer’s own retry sleeps for Retry-After (or 1 s) and continues.
• A timeout while waiting, or a connection failure, retries after a short sleep.
• A 403 stops that worker and is re-thrown to the caller of consume() once every worker has finished. Workers run inside packaged_tasks that are only waited on, so the exception is captured and re-thrown rather than discarded.
• Any other HttpError or exception is re-thrown from the worker.

Buffering

flush_buffer(deadline_millis = -1) flushes this builder’s queue/partition buffer; throws with no queue name. get_buffer_stats() on the client returns the aggregate. Buffers are keyed on "<queue>/<partition>", so builders addressing the same pair share one, and a buffer flushes at message_count messages or time_millis after its first message.

The buffer is bounded and lossless under errors. At max_size waiting messages (default 4 * message_count), further adds block on the flusher instead of growing the heap. A batch whose POST fails goes back to the front of the buffer, in order, and is retried every retry_delay_millis until it lands or the client closes; it is never dropped. A broker outage therefore shows up as blocked producers and a full buffer, not as silent loss.

A flush with no deadline retries a failing batch until it lands. Pass deadline_millis >= 0 to flush_buffer or flush_all_buffers to bound that: when it expires, a BufferFlushError reports how many messages are still buffered (still buffered, not dropped) via unflushed_count() and in what(). close() flushes under a 30 s deadline, prints what could not be sent, and only then discards; a buffered push after close() throws instead of being accepted by a client that will lose it.

Dead-letter queue

dlq(const std::string& consumer_group = "") returns a DLQBuilder; throws with no queue name.

Read-only, and this client has no admin surface, so replay means reading the row and pushing the payload again, or calling one of the broker’s own replay routes yourself: POST /api/v1/messages/{partitionId}/{transactionId}/retry by address, or POST /api/v1/dlq/{id}/replay by dead-letter row id, which is the one that can name a different destination. Both move the record rather than copying it, so re-pushing the payload by hand is the only one of the three that leaves the dead-letter row behind.

TransactionBuilder

client.transaction(). Pushes and acks in one PostgreSQL transaction, all-or-nothing.

A transaction is atomic, not exactly-once end to end; see the limit.

HttpClient

There is no Admin class in the C++ client. Management and observability routes are reached through the shared HttpClient from get_http_client():

auto http = client.get_http_client();
queen::json overview = http->get("/api/v1/resources/overview");

All four return json, with nullptr for an empty body or a 204 (a 204 carries no body at all), and throw HttpError on any status >= 400. request_timeout_millis of 0 uses the client default. Pass RetryKind::Pop for a long-poll request so a 429 backs off indefinitely instead of using the bounded budget.

The complete route list is in the route table.

HttpError

Derives from std::runtime_error, with what() set to the broker’s error string, so existing catch (const std::exception&) sites keep working.

A transport failure with no response at all surfaces as a plain std::runtime_error, not an HttpError.

LoadBalancer

Constructed automatically when the two-argument QueenClient gets more than one URL; throws std::invalid_argument on an empty vector. get_next_url(session_key = "") returns a sticky URL for "session" and a round-robin URL otherwise. get_all_urls(), get_strategy() and reset() are also public.

util helpers

Not in this client

There is no streaming SDK for C++ and no Admin facade. The Stream builder, windows, gates and the /streams/v1/* runtime exist in the JavaScript, Python, Go and Rust clients.

Same surface, other languages

Parity here is a claim about the surface, not about shared code: each client is written natively in its own idiom. These sixteen rows are that surface, read out of clients/ on this tree. Six of them are full parity across all six clients; the other ten are where a client stops.

The ten divergent rows, with their conditions:

• Key/value. The seven operations are get, getMany, getPrefix, put, putIfAbsent, delete and incr. C++ wraps five of them: getMany and getPrefix have no method, and both remain reachable through POST /api/v1/kv on the shared HttpClient. getPrefix inside a transaction is refused by the broker in every client, which is its rule and not a client’s gap.
• Timers. C++ has schedule and cancel only; peek and list are reads and stay on GET /api/v1/timers/{queue}[/{timerKey}]. There is no reschedule operation anywhere, because schedule is the upsert and status reports which happened; Python, Go, Rust and PHP still spell a reschedule alias over it, JavaScript and C++ do not.
• once. JavaScript (kv.once, transaction().once) and Python (kv.once, transaction().once) fold putIfAbsent plus required into the question people actually ask, “did I win?”. The other four write the putIfAbsent themselves, which is the same wire and one line longer.
• kv on a streams operator context. No client has it, so it is not a row. Inside a stream the state primitive is state_ops, which commits with the sink and the ack in the cycle’s own transaction; a key/value write from an operator would not, and that atomicity is the thing the stream already gives you for free.
• Admin facade. C++ has no Admin class. Every management and observability route is still reachable, through the shared HttpClient returned by get_http_client().
• affinity. The C++ LoadBalancer implements round-robin and "session" only, and load_balancing_strategy = "affinity" falls through to round-robin silently. The strategy matters because it keeps one consumer’s pops on one backend, which is what keeps two clients from contending on the same partition claim.
• Streams. The Stream builder, the four window kinds, gates and the /streams/v1/* runtime are in the JavaScript, Python, Go and Rust clients. PHP and C++ have none of it.
• Lease renewal. In C++, renew_lease() sets a flag the consumer loop does not act on: the worker carries an unimplemented placeholder where the timer would go. Call client.renew(message) yourself before the lease expires.
• Per-message trace. Where it exists it is attached by the consume loop, so a message returned by a manual pop() never carries it. Rust records a trace through Admin::record_trace instead of hanging a method off the message. C++ cannot hang one off a JSON object at all, and its trace hook is an explicit no-op.
• Host override. JavaScript (hostHeader) and Rust (host_header) advertise a request authority, and a TLS SNI, independent of the address the socket dials. That is what addresses a named tenant cluster behind a shared proxy endpoint. The other four clients send the dialled address.
• pop failures. Go, Rust and PHP surface a 4xx, an exhausted 429 budget, a terminal 403 or a network fault to the caller, so an empty result means an empty queue. JavaScript, Python and C++ log the failure and return an empty result, which does not distinguish an empty queue from revoked credentials.

The cpp suite in the test matrix runs test_retry429, which needs no broker, then test_client against a live one, on the single, ha and tenanted topologies. That suite plus its 14 proxy-contract assertions is green on this tree.