Reference
Commands print JSON when the result is data. Human sentences, such as
the line from relay doctor, are omitted when you pass --quiet.
Commands
relay
├── serve
├── daemon
│ ├── start
│ ├── stop
│ ├── restart
│ └── status
├── publish
├── enqueue
├── subscribe
├── topic
│ ├── list
│ ├── show
│ └── history
├── queue
│ ├── create
│ ├── list
│ ├── show
│ ├── stats
│ ├── inspect
│ ├── retry
│ └── purge
├── subscription
│ ├── list
│ ├── show
│ ├── create
│ ├── reset
│ └── delete
├── worker
│ └── consume
├── history
├── storage
│ ├── stats
│ ├── check
│ └── backup
├── config
│ ├── validate
│ ├── show
│ └── path
├── doctor
├── status
└── tui
Global options are --config, --socket, --quiet, --verbose,
--timeout, --dry-run, --version, and --help.
relay config show masks a configured token as ***. relay config
path prints the user configuration file. LUPAXA_RELAY_CONFIG,
LUPAXA_RELAY_DATA, and LUPAXA_RELAY_SOCKET override those default
locations.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | The command finished |
| 1 | The broker rejected the request, or a check failed |
| 2 | The command line or the configuration is invalid |
| 3 | The client could not reach a broker |
| 4 | Another broker already holds this database |
An unknown flag returns 2 and does not print a traceback.
Names
A destination is 1 to 128 characters. Segments are separated by periods.
Each segment starts with a letter, digit, or underscore, and then may
include hyphens. Names are case-sensitive. _relay and _relay. are
reserved. A pattern uses the same segments, plus * for one segment and
** only as the last segment. A pattern is not a valid topic or queue
name.
Configuration
Files are merged in this order: built-in defaults, the user file, the
--config file, then --socket. Unknown keys are rejected. This is a
valid file:
version: 1
server:
socket: ./r.sock
tcp:
enabled: false
host: 127.0.0.1
port: 8765
max_connections: 100
storage:
path: ./relay.sqlite3
durability: full
retention:
events:
max_age_days: 14
max_messages: 100000
completed_jobs:
max_age_days: 7
dead_letters:
max_age_days: 30
messaging:
max_payload_kb: 256
max_headers_kb: 16
consumers:
default_prefetch: 1
max_prefetch: 100
queues:
- name: image.resize
max_attempts: 5
visibility_timeout_seconds: 60
max_depth: 1000
retry:
strategy: exponential
initial_delay_seconds: 5
multiplier: 2
max_delay_seconds: 300
dead_letter_queue: image.resize.failed
- name: image.resize.failed
max_attempts: 1
bindings:
- id: deployment-events
topic: build.completed
queue: image.resize
logging:
level: info
format: text
security:
allow_remote: false
server.socket and storage.path may be auto. durability is full
or normal. Retry strategies are immediate, fixed, linear, and
exponential. A strategy other than immediate needs
initial_delay_seconds greater than zero. max_attempts may be null
for no limit. A queue cannot name itself as its dead-letter queue, and
the dead-letter queue must be defined. Binding topics are exact names.
Duplicate binding ids and duplicate topic-and-queue pairs are rejected.
security.allow_remote: true is a configuration error. TCP, when
enabled, must bind to 127.0.0.1, ::1, or localhost. An optional
token is compared in constant time and is never logged.
default_prefetch cannot be greater than max_prefetch.
Status
relay status prints message count, connection count, and uptime. The
protocol snapshot also includes job counts, storage size, a quick-check
flag, per-queue depths, topics, subscriptions, and lifetime counters:
| Counter | What it Counts |
|---|---|
published_events |
Events committed |
enqueued_jobs |
Jobs inserted, including bound copies |
delivered_messages |
Deliveries handed to a consumer |
acknowledged_deliveries |
Acknowledgements committed |
negative_acknowledgements |
Failed attempts, including expired leases |
retries |
Attempts scheduled for later |
dead_lettered_jobs |
Moves into a dead-letter state |
Depths describe what is stored now. The counters survive a restart because they are updated in the same transaction as the change they describe.
Python Client
from pathlib import Path
from lupaxa.relay.client import RelayClient
with RelayClient(socket=Path("r.sock")) as client:
result = client.publish("build.completed", {"version": "1.2.0"})
print(result.message_id, result.sequence)
RelayClient also speaks loopback TCP when you pass host and port
instead of a socket. The same process offers AsyncRelayClient for
async code. Both use the public protocol. They do not open the
database.
What is Stored
The database is SQLite in WAL mode. durability: full uses synchronous
FULL. A publish, an enqueue, a lease, an acknowledgement, a retry, and
a dead-letter move each commit before the client is told they succeeded.
Retention deletes old events and old completed or dead jobs. It does not
delete a pending, leased, or retrying job. A durable subscriber is told
when retention removes events it had not yet consumed.
Killing the process can leave a publish that the client never saw. Send the same idempotency key to learn whether it committed. The database stays readable. A later open recovers the committed rows.