ProtocolClient

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

Low-level envelope helper from redweb/client. It wraps a socket you own; it does not connect, reconnect or correlate pending requests. For those features use redweb-client; server TSX pages generate their client integration automatically.

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 when you already own the connection and only need versioned envelopes. Use redweb-client for connection lifecycle and requests, or typed handlers bound to server TSX for generated UI transport.

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.

import { ProtocolClient } from 'redweb/client'

const socket = new WebSocket('wss://game.example/match?redwebVersion=1')
const client = new ProtocolClient(socket, '1')

socket.addEventListener('open', () => {
  client.send('move', { x: 4, y: 2 }, { sequence: 17 })
})

socket.addEventListener('message', event => {
  try {
    const message = client.parse(event)
    console.log(message)
  } catch (error) {
    console.error('Invalid server envelope', error)
  }
})

1. Create a WebSocket and its envelope helper, then wait for open before sending.
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?

Bundle this import for browser use; it is not a native script URL. Envelope validation is not payload validation or authorization, and this helper does not replay messages after disconnect.