Integrating an existing service¶
A service does not need a Snodra library to join the system. The server speaks plain gRPC over the
snodra.hub.v1 package, and a client in any language can open the stream, register its types and
answer requests. This page is the integration checklist; the exact messages are in
Protocol.
What the service must implement¶
- Connect. Open
Hub.Connect, a bidirectional stream, once per instance. - Register. Send
Registerfirst, withservice_name,instance_id, thecommandsandqueries(andshared_queries) it handles,initial_permitsand optionallycredentials. Wait forRegisterAckbefore relying on routing. - Serve. Read
ServerMessage.request, decode the payload, run the handler and sendClientMessage.replywith the samerequest_id. A handler error goes inReply.error, not in a dropped stream. - Heartbeat. Send
Heartbeaton the interval from the ack and echo the server's heartbeats. - Flow control. Grant permits as handlers complete; do not expect more concurrent requests than the permits you offered.
- Reconnect. On a stream end, reconnect with backoff and register again. Requests in flight when the stream breaks have an unknown outcome.
The contract you share¶
- Type names are global. The wire name (
orders.PlaceOrder) is the routing key and must match the owner's*-apimodule or documented contract. A typo creates a second, unrelated type. - Payloads are opaque bytes to the server. They are JSON documents in the Snodra libraries; agree on the JSON shape with the other services. The server never decodes or logs them.
- One terminal message per request id. A
Replyor anError, never both. For multi-part modes,ReplyParts and oneReplyEnd. - Deadlines are the server's. It applies the request's
timeout_ms, the type override or the default, and answersTIMEOUTwhen it passes. - Credentials. A static token, a JWT or a client certificate can authenticate the stream; the ACL then decides which types the service may handle and send.
What you can skip¶
Events, the outbox, sagas, processors and testing kits are library features, not protocol requirements. A service that only serves commands and queries needs the hub client alone. A service that publishes events needs an event store and a message store, or it can call the owning service.
Verifying it¶
The conformance runner checks a client library against the contract, including the handshake, flow control, failover and credentials. For a one-off integration, start with a single hub, no authentication and one command type, then add TLS and access control; see the quick start and Lifecycle.