REDWEBAPI guide

ProtocolClient

Documentation for Redweb 0.13.2. Install that exact version when following these examples.

Dependency-free helper from redweb/client for opt-in versioned routes. It builds, sends, and validates stable envelopes from the same checked-in schema used by server constants and TypeScript declarations.

Explain it like I’m five

ProtocolClient is a phrasebook shared with the browser. It puts outgoing messages into Redweb’s expected envelope and checks incoming envelopes before your code trusts them.

When should I use it?

Use it for opt-in versioned routes when browser clients should share protocol constants, parsing, sequencing, and error handling with the server.

Follow the example

This API pattern illustrates the named surface; it may require application-owned classes, credentials, or assets. Start from a complete recipe for a runnable application.

js
const { ProtocolClient, ERROR_CODES } = require('redweb/client')

const socket = new WebSocket('wss://game.example/match?redwebVersion=1')
const client = new ProtocolClient(socket, '1')
client.send('move', { x: 4, y: 2 }, { sequence: 17 })
  1. The client connects to the versioned route and creates a ProtocolClient for that version.
  2. send builds a stable typed envelope containing payload and optional sequence metadata.
  3. parse validates server messages so application code can respond to known errors such as rate limiting.

Methods and members

constructor(socket, version)

Wraps any socket-like object with send(data) and selects the envelope version.

envelope(type, payload, metadata?)

Builds a stable versioned event with optional requestId and sequence.

send(type, payload, metadata?)

Serializes and sends one versioned event through the wrapped socket.

parse(value)

Parses and validates a protocol event or error envelope.

What should I watch for?

Protocol validation is not domain validation. Continue checking payload shape, authorization, and game rules on the authoritative server.