Skip to content

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.

version: 1
server:
  socket: ./r.sock
storage:
  path: ./relay.sqlite3
"""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()
cd samples/hello
relay --config relay.yml serve

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()
cd samples/queue
relay --config relay.yml serve

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()
cd samples/subscribe
relay --config relay.yml serve

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.