Your first service¶
This walkthrough connects one service to a running server and sends it a command. It links the existing quickstarts for the code instead of repeating them: the Kotlin and Rust pages are the reference for handlers and buses.
Before you start¶
- Docker, for the server.
- A JVM with Gradle, or a Rust toolchain, depending on the service you write.
- A Kafka broker or a RabbitMQ Streams cluster for events, and MongoDB or PostgreSQL/MySQL for the message store. The quickstarts assume Kafka and MongoDB; substitute the stores you run. A service that only answers commands and queries needs neither store.
1. Start the server¶
docker run --rm -p 7000:7000 -p 7001:7001 \
-e SNODRA_SERVER_OTLP_ENDPOINT= \
snodra/snodra-server:0.5.0
Open http://localhost:7001/ui/. The topology is empty until a service registers. If the port is taken on macOS, see the quick start for the AirPlay note.
2. Create the service¶
Follow the Kotlin quick start through the dependency and
the handler. The starter discovers @CommandHandler, @QueryHandler and @EventHandler
methods and registers their types on connect.
Set the service name and the server address in application.yml:
snodra:
messaging:
service-name: orders
hub:
address: static://localhost:7000
Follow the Rust quick start through the builder and the
handler. A closure passed to .command(...), .query(...) or .event(...) is the handler; the
builder opens the hub stream and registers the types.
export SNODRA_SERVICE_NAME=orders
export SNODRA_SERVER_ADDRESS=static://localhost:7000
3. Declare one command and one event¶
Both quickstarts show the message types. Keep the naming rules in mind: a wire type is
<service-prefix>.<ClassName>, commands are imperative, events are past tense. The type name is the
routing key — the server matches a request to a handler by it.
See the messaging model for naming, the Kafka/RabbitMQ layout and the outbox, and Commands for what a handler may assume.
4. Send the command¶
Start the service, wait for it to register, and send through the library's command bus, or from
another service with the same client. The topology should now list the service, its instance and
the command type. A request with no live handler fails immediately with NO_HANDLER; it is not
queued.
5. Watch what happened¶
- Topology shows instances, handled types and queue depth.
- Processors shows each event processor, its lag and its dead letters.
- Events searches the event store for the event your handler published.
See Dashboard, Event processors and Event browser. If the event never appears, check the outbox and the event store's settings in Add-ons.
6. Where to go next¶
| Goal | Page |
|---|---|
| Add authentication | Authentication |
| Choose the stores | Add-ons |
| Add a saga | Sagas, then Rust sagas |
| Test the service | Testing |
| Run it in a container | Containers |
| Tune queues and deadlines | Tuning |