Compatibility¶
snodra.hub.v1 is the protocol package. This page states what it guarantees, so you can decide what
may be rolled independently and what must move together.
One version, no negotiation¶
The server and the client libraries ship as one release train. Register carries client_version for
diagnostics, not for capability negotiation: the server has no branches for older clients, and a
server and a client of different builds are not supported. Every session has every feature — flow
control, query modes, status reports, credential refresh, processor control.
The package name is the boundary. A change that is not compatible belongs in a new package, and a server and its clients must be on the same side of it.
What the package guarantees¶
| Guarantee | Meaning |
|---|---|
| One stream per instance | Hub.Connect, first message Register, answered by RegisterAck |
| One terminal message per request | A Reply or an Error; for multi-part modes, ReplyParts and one ReplyEnd |
| Stable error codes | NO_HANDLER, TIMEOUT, HANDLER_DISCONNECTED, INVALID_REQUEST, RESOURCE_EXHAUSTED, CANCELLED, UNAUTHENTICATED, PERMISSION_DENIED |
| Opaque payloads | The server never decodes, logs or persists a payload; bytes are forwarded unchanged |
| Type-based routing | One exclusive owner per command/query type, or a shared type with several owners |
| Deadlines | The request's timeout_ms, a per-type override, or the default; a late reply is dropped |
| Flow control | A request is forwarded only while the target instance has a permit |
| Reconnect | A stream end is recoverable; in-flight requests fail with a defined code |
| Reserved names | snodra.events.* types, the snodra.hub.v1.Hub health name, the snodra://service/<name> SAN |
What it does not guarantee¶
- Mixed builds. There is no compatibility window inside a protocol package.
- Exactly-once delivery. At-least-once plus processed-event markers; see Consistency.
- Payload schema. JSON is the convention, and the owning service's
*-apimodule or documented contract defines the shape. The server does not validate it. - Global ordering. Order is per key within an event store.
- Durability of a command. A command that times out may or may not have run.
- Broker resources. The libraries do not create topics, super streams, collections or tables.
Data compatibility¶
Within snodra.hub.v1, the stored data keeps its shape:
- Event store: the record's key, headers and value; the topic
snodra.eventsand its.dltcompanion; consumer groups<service>.<processor>. - MongoDB: collections
outbox,processed_events,dead_letters,processor_control,external_calls,sagas,saga_dispatch,deadlines,saga_failures, with explicit fields and no_class. - SQL: schema version
1; the tables aresnodra_*, with explicit columns, indexes and values.
A Kotlin and a Rust instance can share one event store and one message store. That is a supported layout, not a compatibility accident: the two libraries are tested against the same record and document contracts.