Graphorin API reference v0.7.0
Graphorin API reference / @graphorin/protocol / server-message
server-message
ServerMessage - discriminated union of every frame a Graphorin server may push to a client. Three families share the channel:
- RPC responses (
{ jsonrpc, id, result | error }) - correlate with a previously-issued client request. - Typed push events (
{ kind: 'event', subject, type, payload, eventId }) - the streaming-first data plane; consumers ignore unknowntypestrings per the agent-event extensibility convention. - Asynchronous server frames (
{ kind: 'lifecycle' | 'error' | 'pong' | 'subscribed' | 'unsubscribed' | 'replay-marker' })- server-initiated messages that do not correlate with a single client RPC id.
Versioning contract (W-109, honest edition): the frame ENVELOPE - the set of kinds, the fields of the control frames, and the v: '1' literal - is validated strictly (.strict(), literal v) on BOTH server and client, and evolves only in lockstep with both sides shipping together: there is NO negotiation, and a frame with v: '2' is rejected outright. That is the deployment model of the 0.x line. The additive extension points are deliberate and inside the envelope: the type string + payload: z.unknown() of event frames (consumers ignore unknown types per the agent-event convention), result: z.unknown() of RPC responses, and the capabilities record of the initialize result (which today the shipped client does not consume). If additive envelope evolution is ever promised publicly, that is a separate negotiation feature - do not loosen .strict() for it piecemeal.
Type Aliases
| Type Alias | Description |
|---|---|
| ServerErrorFrame | - |
| ServerEventFrame | Convenience type aliases for callers that want to reference an individual variant without z.infer<typeof X>. |
| ServerLifecycleFrame | - |
| ServerMessage | Inferred TypeScript union for the ServerMessage discriminator. |
| ServerPongFrame | - |
| ServerReplayMarkerFrame | - |
| ServerRpcFailure | - |
| ServerRpcSuccess | - |
| ServerSubscribedFrame | - |
| ServerUnsubscribedFrame | - |
Variables
| Variable | Description |
|---|---|
| RPC_ERROR_CODES | Stable JSON-RPC error code catalogue used by the server when surfacing routine failures (per JSON-RPC 2.0 § 5.1 + Graphorin extensions). Application-level errors use codes in the implementation-defined range (-32000 … -32099). |
| ServerMessageSchema | Zod schema for every legal server → client frame. Validation runs twice in the server pipeline: first when a route handler enqueues the frame onto the dispatcher's send queue (so a malformed frame never escapes the process), then again on the client side to defend against protocol drift. |
Functions
| Function | Description |
|---|---|
| isErrorFrame | - |
| isEventFrame | Type guard helpers, one per discriminator. The narrow over the ServerMessage union without forcing consumers to memorize the exact field names. |
| isLifecycleFrame | - |
| isPongFrame | - |
| isReplayMarkerFrame | - |
| isRpcFailure | - |
| isRpcSuccess | - |
| isSubscribedFrame | - |
| isUnsubscribedFrame | - |