Architecture, protocol contracts, and integration requirements for GraphQL subscriptions and live data through the Cosmo router
This page outlines how live data reaches a browser through the Cosmo router. It
is for frontend engineers consuming live data and backend engineers adding event
sources to the graph.
Architecture: EDFS over NATS
Live data uses event-driven federation (EDFS, Cosmo Streams) over NATS. The
router does not terminate arbitrary third-party WebSockets or raw message
protocols into the graph.
The service defines the Subscription, and the Mutation that creates the
subscription event, in its base schema. Its event subgraph (<name>-edfs) is
published as described in
Registry and schema workflow.
When something happens, the service POSTs the event (for example
yourStuffUpdated(id:)) to its local router.
The router publishes the event through NATS to fan it out to the other
routers. The router handles fan-out and authorization.
A client holds one WebSocket subscription to a router and receives the event
as a GraphQL payload.
Open question: whether services should publish to NATS directly instead of
POSTing to the router. POSTing to the router is the current setup, not a final
decision.
Protocol and authentication contract
Subprotocols
The router supports graphql-transport-ws (the modern standard protocol used by
Apollo Client's GraphQLWsLink) and legacy graphql-ws. Axon 911 clients
standardize on graphql-transport-ws.
Authentication
Browsers cannot attach custom HTTP headers (such as Authorization) to the
initial HTTP Upgrade request during a WebSocket handshake. Consequently, client
authentication credentials must be sent inside the connection_init payload
immediately after the socket opens:For which tokens the router accepts, see
Authentication.Security requirements:
Never include credentials or tokens in WebSocket URL query parameters.
Never pass tokens in GraphQL operation variables or payloads.
Ensure authentication payloads are redacted from application logs.
Registry composition does not validate delivery.
A successful schema check or composition in Cosmo Studio confirms only that
the GraphQL schema is syntactically and structurally valid. It provides no
guarantee that connectivity, subprotocol negotiation, or event delivery works
at runtime.
Publish order and router version.
See Watch out for the EDFS publish order and
the minimum router version.
Integration workflow for new live data sources
Evaluate query snapshotting vs. subscription:
Determine whether real-time streaming is strictly necessary. If update
intervals of several seconds are acceptable, implement a snapshot query with
an updatedAt timestamp or version cursor, allowing clients to poll.
Pair subscriptions with snapshot queries:
Every subscription feature must have a corresponding query to retrieve the
initial state. Clients fetch the baseline state on mount and subsequently
apply subscription events as deltas.
Verify resilience and tenant isolation:
Validate the integration with automated tests that confirm:
Successful reconnect behavior after the connection drops.
Message delivery ordering and deduplication.
Strict tenant isolation: events for Tenant A cannot be delivered to
Tenant B.
Frontend client implementation guidelines
When consuming subscriptions in frontend applications:
Use typed hooks: Use useSubscription alongside useQuery from
@apollo/client, matching the patterns described in the
GraphQL operations guide.
Reconciliation pattern:
Execute a query to seed initial component state.
Open the subscription to receive incremental deltas or invalidation signals.
If the subscription disconnects and reconnects, re-execute the snapshot
query to reconcile state that may have changed during the disconnected
window.
Reconnect: Treat WebSocket disconnections as normal operational events and
reconnect with exponential backoff and randomized jitter.
Fail gracefully: If a subscription fails or is terminated, retain and
display the last known valid state with an appropriate freshness indicator
rather than unmounting UI components or crashing the view.