Send messages¶
Give a project a topic and a queue on NATS, each with a Secret that says where to reach it, made by the nats Nereid. The Mandate picks the Nereid, so the code asks for an engine, never for a server.
A topic carries each message to everyone who listens, on the subject topics.<name>. A queue keeps each message until one worker takes it, in the JetStream stream queue-<name> on queues.<name>. To put a coding agent in the team's room, see Join the team's room.
Before you start¶
- A cluster from Prepare the cluster, with the tenancy tree its profile seeds: the owner of each topic and queue, here the project
triton, must exist in it.
Steps¶
1. Apply the messaging reef¶
nereus reef apply brings the two kinds.
nereus reef apply messaging
✓ core/reefs/messaging 0.1.0 created (messaging.getnereus.dev/v1alpha1: queues, topics)
Next steps:
nereus messaging --help
nereus nereid apply <nereid> --reef messaging
2. Apply the nats Nereid and its Mandate¶
nereus nereid apply nats runs NATS next to the Nereid in its Pod, with JetStream on the claim nats-data.
nereus nereid apply nats \
--reef messaging
✓ core/nereids/nats created, Ready, pinned to sha256:<digest>: see 'nereus messaging --help'
Next steps:
nereus mandate create messaging-nats --reef messaging --nereid nats --match engine=nats --param jetstream=true
The Mandate takes every request of engine nats; jetstream=true is what queues need. A second Mandate with the same match is refused.
nereus mandate create messaging-nats \
--reef messaging \
--nereid nats \
--match engine=nats \
--param jetstream=true
✓ core/mandates/messaging-nats created (reef: messaging, nereid: nats, match: engine=nats)
3. Create a topic¶
nereus messaging topic create names the owner and the engine. An owner missing from the tree is refused before anything is written.
nereus messaging topic create orders \
--owner project/triton \
--engine nats
✓ messaging/topics/orders created (mandate: messaging-nats, nereid: nats)
Next steps:
nereus messaging topic get orders
4. Create a queue¶
nereus messaging queue create takes the same flags.
nereus messaging queue create builds \
--owner project/triton \
--engine nats
✓ messaging/queues/builds created (mandate: messaging-nats, nereid: nats)
Next steps:
nereus messaging queue get builds
5. Create one from a file¶
A dry run writes the YAML that nereus messaging queue apply takes. --deletion-policy delete drops the stream and its messages with the queue; retain, the default, keeps them.
nereus messaging queue create scratch \
--owner project/triton \
--engine nats \
--deletion-policy delete \
--dry-run \
--output yaml > scratch.yaml
nereus messaging queue apply \
--from-file scratch.yaml
✓ messaging/queues/scratch created
Next steps:
nereus messaging queue list
A topic works the same way, with nereus messaging topic apply.
Check it worked¶
nereus messaging topic list and nereus messaging queue list show each one Ready, with the Mandate and the Nereid that took it. nereus messaging queue get names the Secret that says where to reach it: builds-queue in nereus-system, with the keys host, port, uri, subject and stream.
Clean up¶
nereus messaging queue delete follows the queue's deletion policy.
nereus messaging queue delete builds
✓ messaging/queues/builds deleted (deletionPolicy: retain, its messages are kept)
Next steps:
nereus messaging queue list
nereus messaging queue delete scratch
✓ messaging/queues/scratch deleted (deletionPolicy: delete)
Next steps:
nereus messaging queue list
nereus messaging topic delete orders
✓ messaging/topics/orders deleted (deletionPolicy: retain, its messages are kept)
Next steps:
nereus messaging topic list
Next¶
- Join the team's room: a coding agent's session on the same NATS.
Learn more¶
- The messaging reef: topics, queues and sessions, every command.
- Reef, Nereid and Mandate: why the Mandate, not the code, picks NATS.