Examples
These three directories are in samples/. Each one has a relay.yml
and a short Python script. Start the broker from the sample directory
before you run the script. The script changes to its own directory, so
python samples/hello/publish.py from the repository root still uses
that sample's socket.
Stop the broker with Ctrl-C when you are finished. Delete relay.sqlite3
in the sample directory when you want an empty database. A second
relay serve on the same file exits 4 while the first one is running.
Hello
samples/hello publishes build.completed and then reads that topic
back.
"""Publish one event to the hello sample broker."""
from __future__ import annotations
import json
import os
from pathlib import Path
from lupaxa.relay.client import RelayClient
from lupaxa.relay.config import load_config
def main() -> None:
root = Path(__file__).resolve().parent
os.chdir(root)
config = load_config(root / "relay.yml", user_path=None)
socket = config.socket_path()
if socket is None:
raise SystemExit("This sample uses a Unix socket.")
with RelayClient(socket=socket) as client:
result = client.publish("build.completed", {"version": "1.2.0"})
stored = client.history("build.completed", limit=1)
print(
json.dumps(
{
"message_id": result.message_id,
"sequence": result.sequence,
"stored": len(stored),
}
)
)
if __name__ == "__main__":
main()
From another terminal, still in samples/hello:
python publish.py
relay --config relay.yml history --topic build.completed
relay --config relay.yml doctor
publish.py prints JSON. stored is 1 when the event just written is
the latest event on that topic. relay doctor should report a
compatible schema, a restrictive socket, and a listening broker.
The same publish without the script:
relay --config relay.yml publish build.completed \
--json '{"version":"1.2.0"}' \
--idempotency-key hello
relay --config relay.yml publish build.completed \
--json '{"version":"1.2.0"}' \
--idempotency-key hello
The second command prints the same message_id as the first.
Queue
samples/queue defines image.resize and its dead-letter queue.
version: 1
server:
socket: ./r.sock
storage:
path: ./relay.sqlite3
queues:
- name: image.resize
max_attempts: 3
visibility_timeout_seconds: 30
dead_letter_queue: image.resize.failed
- name: image.resize.failed
max_attempts: 1
"""Take one job from image.resize, print it, and acknowledge it."""
from __future__ import annotations
import json
import os
from pathlib import Path
from lupaxa.relay.client import RelayClient
from lupaxa.relay.config import load_config
def main() -> None:
root = Path(__file__).resolve().parent
os.chdir(root)
config = load_config(root / "relay.yml", user_path=None)
socket = config.socket_path()
if socket is None:
raise SystemExit("This sample uses a Unix socket.")
with RelayClient(socket=socket) as client:
for job in client.consume("image.resize", prefetch=1):
print(json.dumps({"message_id": job.message_id, "data": job.data}))
job.ack()
return
if __name__ == "__main__":
main()
From another terminal:
cd samples/queue
relay --config relay.yml enqueue image.resize --json '{"image":"a.jpg"}'
python worker.py
relay --config relay.yml queue stats image.resize
worker.py prints the job and acknowledges it, then exits. The stats
show the job as completed. It is no longer pending. relay queue inspect
image.resize prints the same job, including its payload and state.
Subscribe
samples/subscribe keeps a durable subscription named auditor and
copies build.completed onto deployment.jobs.
version: 1
server:
socket: ./r.sock
storage:
path: ./relay.sqlite3
queues:
- name: deployment.jobs
max_attempts: 3
bindings:
- id: deployment-events
topic: build.completed
queue: deployment.jobs
"""Read one matching event for the auditor subscription, then acknowledge it."""
from __future__ import annotations
import json
import os
from pathlib import Path
from lupaxa.relay.client import Delivery, RelayClient
from lupaxa.relay.config import load_config
def main() -> None:
root = Path(__file__).resolve().parent
os.chdir(root)
config = load_config(root / "relay.yml", user_path=None)
socket = config.socket_path()
if socket is None:
raise SystemExit("This sample uses a Unix socket.")
with RelayClient(socket=socket) as client:
for item in client.subscribe("build.*", durable="auditor", start="earliest"):
if not isinstance(item, Delivery):
continue
print(
json.dumps(
{
"message_id": item.message_id,
"destination": item.destination,
"data": item.data,
}
)
)
item.ack()
return
if __name__ == "__main__":
main()
Publish first, then listen. listen.py starts at the earliest stored
event, prints one match, acknowledges it, and exits:
cd samples/subscribe
relay --config relay.yml publish build.completed --json '{"version":"1.2.0"}'
python listen.py
relay --config relay.yml queue inspect deployment.jobs
relay --config relay.yml subscription show auditor
Inspect shows a job whose payload is the event payload and whose id is
not the event id. The event is still returned by relay history --topic
build.completed. The subscription cursor has moved past the event you
acknowledged.
Run python listen.py before the publish when you want to watch the
event arrive. It waits until one matching event is stored. Publish again
with --idempotency-key demo and the same payload. Relay returns the
original event and does not append another job.