Topology¶
What the hub knows about its services, types and instances, and how fresh that picture is.
Topology view¶
The hub can show who is connected right now: every service with its live instances, which command and query types each instance handles, who owns each type, and how many requests are in flight (as handler and as sender). It never contains payloads or headers. The same snapshot is served three ways:
grpcurl -plaintext -import-path proto -proto hub.proto localhost:7000 snodra.hub.v1.Hub/Topology # gRPC, same port as Connect
curl localhost:7001/api/v1/topology # HTTP JSON (the dashboard API)
snodra-server --topology [--json] # CLI inside the container
docker exec snodra-server /app/snodra-server --topology
docker exec snodra-server /app/snodra-server --topology --json
GET /api/v1/topologyis served onSNODRA_SERVER_HTTP_LISTEN(camelCase fields,kindasCOMMANDorQUERY) with the rest of the dashboard API. Besides the dashboard paths (/,/ui,/ui/...,/api/v1/...) every path is 404, and withSNODRA_SERVER_DASHBOARD_ENABLED=falseevery path is: the gRPC call and the CLI remain. the HTTP endpoint is a second port (7001), because the gRPC port speaks only HTTP/2 gRPC. An emptySNODRA_SERVER_HTTP_LISTENdisables it.snodra-server --topologyprints a table (--jsonprints the JSON). It probes127.0.0.1on the port ofSNODRA_SERVER_LISTEN(or--address host:port|https://host:port) with a 3 s timeout, over TLS as--tls-ca <pem>, anhttps://address or the environment's TLS setting say, withSNODRA_SERVER_DASHBOARD_TOKENfrom its environment when the hub has one. Exit codes: 0 success, 1 failure (hub unreachable or timeout), 2 usage error (unknown or conflicting flags; usage goes to stderr). With nothing connected it printsno services connectedand a totals line.- Without
SNODRA_SERVER_DASHBOARD_TOKENthe topology has no authentication, like the rest of the port-7000 surface, except that withSNODRA_SERVER_AUTH_MODE=enforcethe gRPC call needs an ACL token; with the token, the gRPC call andGET /api/v1/topologyneed it (see Security). - The hub has no gRPC server reflection, hence the
-protoflags. grpcurl's proto-JSON prints int64 as strings and omits default values, so its output differs textually fromcurl :7001/api/v1/topology.
Snapshot fields¶
Top level:
| Field | Type | Meaning |
|---|---|---|
hubId |
string | SNODRA_SERVER_ID |
hubStartedAtMs |
int64 | hub start, epoch milliseconds |
nowMs |
int64 | snapshot time, epoch milliseconds |
heartbeatTimeoutMs |
int64 | the configured SNODRA_SERVER_HEARTBEAT_TIMEOUT, in ms |
services |
list | one entry per service with at least one live session |
types |
list | one entry per owned type, including orphaned ones |
totals |
object | services, instances, commandTypes, queryTypes, inFlight, queued (all counts; inFlight includes queued requests) |
services[]: serviceName (string) and instances[]:
| Field | Type | Meaning |
|---|---|---|
instanceId |
string | instance id from Register |
connectedSinceMs |
int64 | when the session started, epoch ms |
lastHeartbeatAgeMs |
int64 | time since the last heartbeat, ms |
stale |
bool | lastHeartbeatAgeMs > a third of the eviction threshold (see below) |
inFlightAsHandler |
uint32 | requests currently being handled by this instance |
inFlightAsSender |
uint32 | requests this instance sent that have no terminal message yet |
commandTypes |
list of string | command types this instance registered |
queryTypes |
list of string | query types this instance registered (shared ones included) |
sharedQueryTypes |
list of string | the query types it registered as shared (Register.shared_query_types) |
clientVersion |
string | Register.client_version, for example snodra-messaging/0.1.0; empty when the client sent none |
permitsAvailable |
uint32 | permits left: requests the hub may still forward before the next Permits |
queued |
uint32 | requests waiting in the hub's queue for this instance |
loadFactor |
uint32 | Register.load_factor as applied (0 reads as 100) |
tags |
map | Register.tags |
connectedHubIds |
list of string | InstanceStatus.connected_hub_ids as last reported: the hubs the instance holds a stream to; empty when never reported |
statusAgeMs |
int64 | time since that report, ms; -1 when never reported |
processors |
list | InstanceStatus.processors of that report, as kept (see Event processors): name, groupId, topic, state, partitions[] (partition, position, committed, highWatermark, lag), processedTotal, failedTotal, deadLetters, lastError, lastErrorAtMs, eventTypes, deadLetterMode; [] when never reported |
types[]:
| Field | Type | Meaning |
|---|---|---|
type |
string | the command or query type name |
kind |
string | COMMAND or QUERY |
ownerServices |
list of string | every owning service, sorted (one for an exclusive type) |
shared |
bool | a shared query type: many services may own it |
liveInstances |
uint32 | live instances of the owner (of all owners) that registered it |
orphaned |
bool | the owner has no live instance (ownership is held during the grace period) |
orphanedForMs |
int64 | how long it has been orphaned, ms; 0 when not orphaned |
totals.inFlight counts requests in the router, so it can differ from the per-instance sums when
a sender or handler is already gone. A scatter-gather counts once in inFlight and in its
sender's inFlightAsSender, and once per target in each handler's inFlightAsHandler.
Consistency¶
A snapshot is three sequential reads (sessions, then registry, then router), each under its own lock and never nested. It is not a single atomic cut: a request or a disconnect can land between reads. Sessions are the base set: an instance appears only if it has a live session, and its types and in-flight counts are attached by instance id (empty or zero when absent).
Staleness¶
an instance is stale when its last heartbeat is older than a third of the
eviction threshold (SNODRA_SERVER_HEARTBEAT_TIMEOUT).
It is still connected and still receives requests; the flag is an early warning before the hub
evicts it at the full timeout. A brief stale: true right before a heartbeat arrives is normal.
Orphaned types¶
when the last instance of a service leaves, its types stay in types with
orphaned: true and a growing orphanedForMs until SNODRA_SERVER_OWNER_GRACE expires and the
sweep removes them. Requests for an orphaned type fail with NO_HANDLER.
Register rejections¶
two additions to the registry rules.
- A type listed under both
command_typesandquery_typesin oneRegisteris rejected withINVALID_ARGUMENT. - Registering a type under a different kind than its current owner uses (for example a query
type that the owner holds as a command) is rejected with
ALREADY_EXISTS. A type's kind cannot change while it is owned; change it only after every instance of the owner has left and the owner grace sweep has removed the type. - Shared query types (
Register.shared_query_types, ADR 0017): a type registered exclusive by one registrant and shared by another (even of the same service) fails the laterRegisterwithALREADY_EXISTS; a type listed as shared and as a command or exclusive query in oneRegisterisINVALID_ARGUMENT. Like a kind, the flag changes only once the type is gone.