Technical reference

NuvexaMQ 0.1.1 is a single-node durable message broker. One append-only log stores each message. A stream, a queue, and an exchange binding are three ways to write or read that log.

The wire protocol is NuvexaMQ's own length-prefixed TCP protocol. It is not AMQP, MQTT, or Kafka. RabbitMQ is the model for virtual hosts, users, permissions, exchanges, queues, bindings, and policies. The bytes on the socket are different.

This version does not fail over to another machine. An acknowledged publish is on disk. Segment headers and commit.json store an epoch and a committed offset so a later follower can use the same files. The epoch on this node is 1.

The process opens four listeners. A package install and the desktop app both use these defaults.

GET /health returns {"status":"ok"}. GET /metrics returns Prometheus text.

The data port binds to 0.0.0.0 unless ListenAddress is changed. The banner prints tcp://127.0.0.1:5761 for a wildcard bind. With CertificatePath set, that banner is tls:// and the same frames are wrapped in TLS. Without a certificate, HTTPS on 5764 still starts with a generated certificate, and browsers warn until you replace it.

guest / guest is the seeded management user. That account is accepted only from localhost. A 401 body is JSON { "error", "reason" } and does not include a WWW-Authenticate header.

The package installs the broker and the desktop app, puts nuvexamq on PATH, and starts the broker on boot. CI keeps the packages as workflow artifacts for 14 days. The tag v<Version> publishes them on the GitHub Release for that version. CI does not push them to NuGet.

The desktop window uses a different data directory: the user application-data folder NuvexaMQ/data. On macOS that is ~/Library/Application Support/NuvexaMQ/data. Starting the desktop while the system service already owns 5761–5764 fails with "Address already in use". The window then shows In use, and Stop unloads the system service (macOS asks for an administrator password because that service runs as root and restarts if it is only killed). Open admin portal opens http://127.0.0.1:5763/.

nuvexamq reads appsettings.json next to the binary, section NuvexaMQ, then applies flags.

Other settings exist only in appsettings.json:

A publish acknowledgement means the record was inside an fsync. FlushIntervalMs 0 fsyncs every batch. The index file is not fsynced on the hot path. A crash can redeliver the last few milliseconds of acknowledgements because cursor writes are coalesced.

Verbose lines are a unix timestamp, then New connection from, New client connected, Received PUBLISH, and Client ... disconnected. Passwords and message bodies are not printed.

Command-line client, used by the same nuvexamq binary:

nuvexamq stream add --name orders --filter orders.>
nuvexamq pub --subject orders.created --body hello --key order-18
nuvexamq consume --stream orders --durable billing --count 1
nuvexamq path install

path install adds the published binary to PATH. It refuses a bin/Debug or bin/Release folder.

Streams, consumers, and exchange bindings are the objects stored on this node.

A stream is a named, partitioned log. EnsureStream creates it or, when the layout matches, updates retention.

Subject filters are dot-separated. * is one token. > is the remainder and must be the last token, and the subject must have at least one token there. orders.> matches orders.created and orders.created.eu. orders.* matches orders.created only.

The partition is FNV-1a(key) % count. An empty key round-robins. The same key always lands on the same partition.

$dlq is the broker dead-letter stream for messages that exhaust MaxDeliver. It cannot be deleted.

A consumer is a named cursor on one stream.

If the consumer name already exists, EnsureConsumer returns success and ignores the new start, filter, and ephemeral flag. Create the durable name once with the settings you want. Release an ephemeral name before creating it again.

A fetched message is not delivered again until nack, or until the ack wait expires. Nack of an unknown offset succeeds. Nack marks the delivery so the next fetch can return it with a higher delivery count.

Two durable consumers with different names on the same stream are fan-out: each receives the message. Two connections that use the same durable name compete: one of them receives each delivery.

If retention deletes a segment the cursor still points at, fetch sets the offset-reset flag and reports the first offset still on disk. Reset the consumer to continue.

Every virtual host has these built-in exchanges. They cannot be deleted.

Declaring the same name and type again is a no-op. Declaring a different type is a conflict. Custom exchange types are direct, fanout, topic, and headers.

A queue is a stream whose filter is >. On virtual host / the log is named $queue. plus the queue name. On another virtual host it is $queue. plus the virtual host, a dot, and the queue name. Queue options:

A policy is a regular expression over queue names on one virtual host. The highest priority match wins. A later policy of equal priority replaces the earlier one. A null TTL, null max length, or empty dead-letter field on the policy keeps the queue's own value. The pattern match times out after 50 ms and then does not apply.

Permissions are three regular expressions per user and virtual host: configure, write, and read. .* allows every name. The resource name must match the pattern. A match that times out or a broken pattern denies the operation.

User tags administrator and management may call the management API. Other users can use the data port when their password and permissions allow it. Passwords are stored as a hash. The seeded user is created only when topology.json is missing, so later changes to --management-password do not reset an existing guest.

Resource names follow the same character rules as stream names. Virtual host / is special and cannot be deleted.

{dataDir}/topology.json
{dataDir}/streams/{stream}/stream.json
{dataDir}/streams/{stream}/p{n}/segment-{baseOffset}.log
{dataDir}/streams/{stream}/p{n}/segment-{baseOffset}.idx
{dataDir}/streams/{stream}/p{n}/consumer-{name}.json
{dataDir}/streams/{stream}/p{n}/commit.json

Log records are little-endian and carry a CRC-32 over the bytes after the checksum. On open, a torn tail is truncated. A missing index is rebuilt from the log. commit.json stores the epoch and the last fsynced offset.

Desktop logs, when logging is enabled, are hourly files {logsDir}/{yyyy-MM-dd}/log-HHmm.log. The desktop console keeps the latest 2000 lines.

Every multi-byte integer is little-endian. A frame is:

The maximum frame is 32 MiB. A string is a uint16 byte count plus UTF-8 bytes. A blob is an int32 byte count plus bytes. An absent retention limit is int64 -1.

The first frame on a connection must be Hello. The server handles one request at a time on each connection.

A delivery inside FetchOk is: uint16 partition, int64 offset, int64 timestamp unix ms, int32 delivery count, subject, key blob, uint16 header count, headers, payload blob.

Start bytes: 0 first, 1 tail, 2 offset.

Error codes:

Public routes, with no login, are GET /, GET /icon.png, and POST /api/login. Everything else needs the cookie or Basic authentication. The cookie is HttpOnly, SameSite=Strict, path /, and lasts 8 hours.

POST /api/login body is { "username", "password" }. Success sets the cookie and returns { "username", "localhostOnly" }.

Failures use { "error", "reason" } with 400, 401, 404, 409, or 413.

Clustering, federation, and the shovel plugin are not implemented. The data port is not AMQP. One request is handled at a time on each connection. The index is not fsynced on the publish path. Auto-delete is stored on the queue and is not applied when the last consumer leaves.