Typed websocket rpc boundary validation

When to Apply

• You serve WebSocket RPC with multiple method handlers (requests + typed pushes)
• You want decode failures to produce structured diagnostics with path/reason
• You need to prevent invalid payloads from reaching business logic
• Client/server contracts can drift; early validation catches breakages

Steps

1. Define contracts as schema unions in a shared package (e.g., @t3tools/contracts/src/rpc.ts)
2. Define RPC method shapes, request/response schemas, and push channel schemas
3. At server startup, create RPC server with schema-based encoding/decoding
4. On client, create transport that wraps outbound requests and inbound pushes with schema parsing
5. Decode failures at transport boundary immediately return WsDecodeDiagnostic with code, reason, and path
6. Never cast payloads; always parse through schema
7. For pushes, validate and cache per channel; allow clients to opt into replayLatest

Example

// Server: define schemas
const ServerWelcomeSchema = Schema.Struct({ type: Schema.Literal('server.welcome'), state: ThreadStateSchema })
const RpcGroup = Schema.Union([ MethodASchema, MethodBSchema ])

// Server: validate inbound
const request = yield* Schema.decode(RpcGroup)(payload)  // throws or returns typed request

// Client: encode/decode via transport
const wsTransport = new WsTransport({
  url: 'ws://server',
  schemas: { 'server.welcome': ServerWelcomeSchema, ... }
})
wsTransport.on('server.welcome', (data) => { /* data is typed */ })

Counter / Caveats

• Schema validation adds latency; use for contract boundaries, not hot loops
• Caching latest push per channel can grow memory; cap channel subscriptions
• If schema is too strict, valid legacy clients may disconnect; plan versioning strategy
• Decode path info helps debugging but reveals schema structure to clients