protocol reference

Validate JSON messages, invite links and input at a trust boundary. Import from @controller-plus/sdk/protocol, the package root, or /sdk/src/protocol.mjs. See Wire protocol v1 for the full connection sequence and wire for binary codecs.

Constants and errors

Frame validation

parseFrame(raw: string | ArrayBuffer | ArrayBufferView): object decodes UTF-8, checks byte length, parses JSON and requires a non-array object, string type, and v === 1. Returns the parsed object, retaining other fields. It does not validate a specific message type.

validateHello(frame): frame requires type: 'hello' and role host, player or spectator. Normal joins require string room and token, each 1–256 characters. This checks shape, not whether credentials are authentic. It does not replace parseFrame's version check.

validateEvent(frame): frame requires event name [a-z][a-z0-9_.-]{0,47} and a non-array object payload. Missing payload is set to {}. It mutates and returns the frame. It does not validate game rules, the frame's type, or its envelope version.

Input validation

applyInput(previous, frame): ControlState returns new arrays, using prior values (or neutral) for absent fields. It requires an integer seq from 0 to 2,147,483,647 but does not decide whether it is newer; the host owns ordering.

Absent motion retains a clone of prior motion. Present motion replaces it with only recognized vectors; {} clears the old vectors. Unknown input fields are ignored. This is JSON delta behavior; every binary input frame is a full state.

Join URLs and manifests

joinURL(origin, room, token, { path = '/ws', page = '/join' } = {}): string creates an HTTP(S) URL with v, room, token in its fragment and a path field only for nondefault paths. path must match ^/(?!/)[A-Za-z0-9_/-]{1,127}$. The builder validates the scheme/path, but not the room/token syntax: use actual credentials from your host.

parseJoinURL(value): { v: 1, origin, endpoint, room, token } requires HTTP(S), no username/password, URL length ≤2048, room [A-Z0-9]{4,12}, token [A-Za-z0-9_-]{20,128}, and v=1. Duplicate v, room, token, path, tlsPort or pin is rejected. The returned ws/wss endpoint uses the same origin and validated path. Pin/TLS fields are not applied by this JavaScript parser; native pinned desktop pairing has its own implementation.

manifest(game, origin, room): ConnectionManifest returns version 1, session ID, game { id, name }, one developer-or-local WebSocket route at /ws with scope developer, priority 0 and codec json-v1. Policy is { allowOurRelay: false, desktopControl: false }. Required capability is input.touch; optional capabilities are input.gamepad, sensor.gyroscope, sensor.accelerometer. controls is copied from game; privateView defaults to 'none'. This helper has no custom path option.

App versions

Errors

This module emits no events and performs no network requests. Authentication/authorization and rate limits belong to the host.

Validate a handshake and input

import { joinURL, parseJoinURL, parseFrame, validateHello, validateEvent, applyInput,
  manifest, parseVersion, compareVersions, validateRequires, updateNeeded
} from '@controller-plus/sdk/protocol';
const url = joinURL('https://game.example', 'ABC123', 'example_player_token_123456');
const address = parseJoinURL(url);
const hello = validateHello(parseFrame(JSON.stringify({
  v: 1, type: 'hello', role: 'player', room: address.room, token: address.token, name: 'Ana',
})));
const input = applyInput(null, { seq: 0, axes: [1, 0, 0, 0] });
console.log(hello.name, input.axes, validateEvent({ event: 'vote', payload: { target: 'p2' } }));
console.log(manifest({ id: 'quiz', name: 'Quiz', controls: {} }, address.origin, address.room));
const requires = validateRequires({ controller: '1.0.0' });
console.log(parseVersion('1.0.0'), compareVersions('1.0.0', '0.9.0'));
console.log(updateNeeded({ platform: 'ios', version: '0.9.0' }, requires)); // 1.0.0