@vgai/p2p-colyseus 0.5.2 → 0.5.3

package/src/index.ts

@@ -1,5 +1,59 @@
-export type { P2PAccessTokenClaims } from './access-token';
-export { createP2PAccessToken, verifyP2PAccessToken } from './access-token';
+export {
+  $changes,
+  $childType,
+  $decoder,
+  $deleteByIndex,
+  $encoder,
+  $filter,
+  $getByIndex,
+  $refId,
+  $track,
+  ArraySchema,
+  Callbacks as SchemaCallbacks,
+  ChangeTree,
+  CollectionSchema,
+  Decoder,
+  decode,
+  decodeKeyValueOperation,
+  decodeSchemaOperation,
+  defineCustomTypes,
+  defineTypes,
+  deprecated,
+  dumpChanges,
+  Encoder,
+  encode,
+  encodeArray,
+  encodeKeyValueOperation,
+  encodeSchemaOperation,
+  entity,
+  getDecoderStateCallbacks,
+  getRawChangesCallback,
+  MapSchema,
+  Metadata,
+  OPERATION,
+  Reflection,
+  ReflectionField,
+  ReflectionType,
+  registerType,
+  Schema,
+  SetSchema,
+  StateCallbackStrategy,
+  StateView,
+  schema,
+  TypeContext,
+  type,
+  view,
+} from '@colyseus/schema';
+export type { P2PAccessTokenClaims, RelayGrantClaims } from './access-token';
+export {
+  createP2PAccessToken,
+  deriveRelayGrantKey,
+  mintRelayGrant,
+  mintRelayToken,
+  readP2PAccessToken,
+  readRelayGrant,
+  verifyP2PAccessToken,
+} from './access-token';
 export { Callbacks } from './callbacks';
 export type { PacketChannel, PacketChannelMode } from './channels';
 export {
@@ -19,7 +73,6 @@ export {
 export { SignalingRelayCoordinator } from './cloudflare/coordinator';
 export type { RelayLimits } from './cloudflare/limits';
 export { DEFAULT_RELAY_LIMITS } from './cloudflare/limits';
-export { applyStatePatch, clone, createStatePatch, encodeSnapshot } from './codec';
 export type {
   NetDiagnostics,
   RelayProofDiagnostics,
@@ -139,58 +192,12 @@ export {
   WebSocketClient,
   WebSocketTransport,
 } from './platform';
-export type { Envelope, Snapshot, StatePatch, StatePatchOperation } from './protocol';
+export type { Envelope } from './protocol';
 export { isEnvelope, P2P_CLOSE_CODES } from './protocol';
 export { CloudflareRelayPacketChannel } from './relay';
 export type { CompatClient } from './room';
 export { Room } from './room';
 export type { RoomClass } from './runtime';
 export { UniversalRoomRuntime } from './runtime';
-export {
-  $changes,
-  $childType,
-  $decoder,
-  $deleteByIndex,
-  $encoder,
-  $filter,
-  $getByIndex,
-  $refId,
-  $track,
-  ArraySchema,
-  Callbacks as SchemaCallbacks,
-  ChangeTree,
-  CollectionSchema,
-  Decoder,
-  decode,
-  decodeKeyValueOperation,
-  decodeSchemaOperation,
-  defineCustomTypes,
-  defineTypes,
-  deprecated,
-  dumpChanges,
-  Encoder,
-  encode,
-  encodeArray,
-  encodeKeyValueOperation,
-  encodeSchemaOperation,
-  entity,
-  getDecoderStateCallbacks,
-  getRawChangesCallback,
-  MapSchema,
-  Metadata,
-  OPERATION,
-  Reflection,
-  ReflectionField,
-  ReflectionType,
-  registerType,
-  Schema,
-  SetSchema,
-  StateCallbackStrategy,
-  StateView,
-  schema,
-  TypeContext,
-  type,
-  view,
-} from './schema';
 export { createWebRTCDataChannelPacketChannel, WebRTCDataChannelPacketChannel } from './webrtc';
 export { createWebSocketPacketChannel, WebSocketPacketChannel } from './websocket';

package/src/protocol.ts

@@ -1,16 +1,13 @@
-export interface Snapshot {
-  readonly type: 'snapshot';
-  readonly state: unknown;
-}
-
-export interface StatePatch {
-  readonly type: 'patch';
-  readonly operations: readonly StatePatchOperation[];
-}
-
-export type StatePatchOperation =
-  | { readonly op: 'set'; readonly path: readonly string[]; readonly value: unknown }
-  | { readonly op: 'delete'; readonly path: readonly string[] };
+/**
+ * The JSON `Envelope` wire protocol shared by every P2P transport.
+ *
+ * Authoritative state is encoded with the REAL `@colyseus/schema` `Encoder`
+ * (see `runtime.ts`) and decoded with the real `Decoder` (`client.ts`). The
+ * encoder's `Uint8Array` output rides as a base64 STRING on the envelope
+ * (`join-ok.state`, `state-snapshot.state`, `state-patch.patch`), so the whole
+ * envelope survives `JSON.stringify` on any transport unchanged. See
+ * `wire-bytes.ts`.
+ */
 
 export type Envelope =
   | {
@@ -23,13 +20,24 @@ export type Envelope =
       readonly kind: 'join-ok';
       readonly requestId: string;
       readonly sessionId: string;
-      readonly snapshot: Snapshot;
+      /** base64-encoded full-state bytes from `Encoder.encodeAll`/`encodeAllView`. */
+      readonly state: string;
       readonly clock: number;
     }
   | { readonly kind: 'join-error'; readonly requestId: string; readonly message: string }
   | { readonly kind: 'message'; readonly type: string; readonly payload?: unknown }
-  | { readonly kind: 'state-patch'; readonly patch: StatePatch; readonly clock: number }
-  | { readonly kind: 'state-snapshot'; readonly snapshot: Snapshot; readonly clock: number }
+  | {
+      readonly kind: 'state-patch';
+      /** base64-encoded delta bytes from `Encoder.encode`/`encodeView`. */
+      readonly patch: string;
+      readonly clock: number;
+    }
+  | {
+      readonly kind: 'state-snapshot';
+      /** base64-encoded full-state bytes (resync). */
+      readonly state: string;
+      readonly clock: number;
+    }
   | { readonly kind: 'state-resync'; readonly clock: number }
   | { readonly kind: 'leave'; readonly code?: number; readonly reason?: string }
   | { readonly kind: 'ping'; readonly t: number }

package/src/room-registry.ts

@@ -0,0 +1,22 @@
+import type { RoomClass } from './runtime';
+
+/**
+ * The locally-registered room classes, keyed by room name. This is the source
+ * the CLIENT decoder is built from (brief decision: no Reflection handshake —
+ * the client derives its `@colyseus/schema` state class from the same room
+ * class the host holds). Both the loopback client path and the host runtime
+ * register here, so a co-located client always resolves the decoder root.
+ */
+const rooms = new Map<string, RoomClass>();
+
+export function registerLoopbackRoom(roomName: string, roomClass: RoomClass): void {
+  rooms.set(roomName, roomClass);
+}
+
+export function getRegisteredRoom(roomName: string): RoomClass | undefined {
+  return rooms.get(roomName);
+}
+
+export function registeredRoomNames(): string[] {
+  return [...rooms.keys()];
+}

package/src/room.ts

@@ -1,4 +1,4 @@
-import { encodeSnapshotState } from './schema';
+import type { StateView } from '@colyseus/schema';
 
 export interface CompatClient {
   readonly id: string;
@@ -7,6 +7,13 @@ export interface CompatClient {
   userData?: unknown;
   auth?: unknown;
   reconnectionToken: string;
+  /**
+   * Per-client visibility filter for `@view()`-gated state — identical to real
+   * Colyseus. A game sets `client.view = new StateView()` in `onJoin` and adds
+   * the refs this client may see; the host runtime encodes each viewed client
+   * separately so gated fields never reach a client whose view excludes them.
+   */
+  view?: StateView;
   ref: {
     on(event: string, handler: (...args: unknown[]) => void): void;
     off(event: string, handler: (...args: unknown[]) => void): void;
@@ -251,10 +258,6 @@ export abstract class Room<State = unknown> {
     this.runtime?.broadcastState();
   }
 
-  _snapshot(): unknown {
-    return encodeSnapshotState(this.state);
-  }
-
   _disposeRuntime(): void {
     for (const timer of this.simulationTimers) clearInterval(timer);
     for (const timer of this.timeoutTimers) clearTimeout(timer);

package/src/runtime.ts

@@ -1,14 +1,19 @@
+import { Encoder, Schema, type StateView } from '@colyseus/schema';
 import type { PacketChannel } from './channels';
-import { clone, createStatePatch, encodeSnapshot } from './codec';
-import type { Envelope, Snapshot } from './protocol';
+import type { Envelope } from './protocol';
 import { P2P_CLOSE_CODES } from './protocol';
 import type { BroadcastOptions, CompatClient, Room } from './room';
+import { registerLoopbackRoom } from './room-registry';
+import { bytesToBase64 } from './wire-bytes';
 
 export type RoomClass<T extends Room = Room> = new () => T;
 
+const EMPTY_BYTES = new Uint8Array(0);
+
 interface RuntimeClient extends CompatClient {
   readonly channel: PacketChannel;
-  lastState: unknown;
+  /** Per-client monotonic patch sequence — the client resyncs on a gap. */
+  clock: number;
 }
 
 interface PendingReconnection {
@@ -19,15 +24,29 @@ interface PendingReconnection {
 
 export class UniversalRoomRuntime<T extends Room = Room> {
   readonly room: T;
-  private clock = 0;
   private readonly clients = new Map<string, RuntimeClient>();
   private readonly reconnections = new Map<string, PendingReconnection>();
+  /**
+   * The REAL `@colyseus/schema` encoder bound to `room.state`. Created lazily
+   * (after `onCreate`, so field-initialized or `setState`-assigned Schema is
+   * populated) and rebuilt if `room.state` is replaced. Rooms whose state is
+   * not a `Schema` (lifecycle-only fixtures) simply do not replicate — there
+   * is nothing the real encoder can carry.
+   */
+  private encoder?: Encoder<Schema>;
+  private hasFilters = false;
+  /** Set when `room.state` is REPLACED (setState) so all clients get a fresh full snapshot. */
+  private pendingResyncAll = false;
 
   constructor(
     roomClass: RoomClass<T>,
     private readonly roomName: string,
     options?: unknown,
   ) {
+    // The room class is also the client-side decoder root source; register it
+    // so a co-located client (loopback, browser host-local, universal Node)
+    // resolves the decoder from the same class the host encodes with.
+    registerLoopbackRoom(roomName, roomClass);
     this.room = new roomClass();
     this.room._attachRuntime({
       broadcastMessage: (type, payload, options) => this.broadcastMessage(type, payload, options),
@@ -115,7 +134,7 @@ export class UniversalRoomRuntime<T extends Room = Room> {
       reconnectionToken: pendingReconnection?.previousClient.reconnectionToken ?? sessionId,
       ref: events,
       channel,
-      lastState: undefined,
+      clock: 0,
       raw: (data, _options, cb) => {
         channel.send({ kind: 'message', type: 'raw', payload: data });
         cb?.();
@@ -171,16 +190,19 @@ export class UniversalRoomRuntime<T extends Room = Room> {
     } else {
       this.room.onJoin?.(client, options);
     }
-    const snapshot = this.createSnapshot();
-    client.lastState = clone(snapshot.state);
+    // Full state for THIS client (respecting its `@view()`), then the delta
+    // that onJoin produced goes to the OTHER clients only — the joiner already
+    // has it in its full snapshot, so it must not also receive the patch.
+    const fullBytes = this.encodeFullState(client.view);
+    client.clock += 1;
     channel.send({
       kind: 'join-ok',
       requestId,
       sessionId,
-      snapshot,
-      clock: ++this.clock,
+      state: bytesToBase64(fullBytes),
+      clock: client.clock,
     });
-    this.broadcastState();
+    this.flushPatches(sessionId);
   }
 
   private removeByChannel(channel: PacketChannel, consented: boolean): void {
@@ -238,18 +260,141 @@ export class UniversalRoomRuntime<T extends Room = Room> {
   }
 
   broadcastState(): boolean {
-    const snapshot = this.createSnapshot();
-    let clock: number | undefined;
-    let sent = false;
-    for (const client of this.clients.values()) {
-      const patch = createStatePatch(client.lastState, snapshot.state);
-      if (patch.operations.length === 0) continue;
-      clock ??= ++this.clock;
-      client.lastState = clone(snapshot.state);
-      client.channel.send({ kind: 'state-patch', patch, clock });
-      sent = true;
+    return this.flushPatches();
+  }
+
+  /**
+   * Bind (or rebind) the real encoder to `room.state`. Returns undefined when
+   * the room has no `Schema` state — such a room simply does not replicate.
+   */
+  private ensureEncoder(): Encoder<Schema> | undefined {
+    const state = this.room.state as unknown;
+    // Stateless / lifecycle-only rooms are legitimate — nothing to replicate,
+    // stay silent.
+    if (state === undefined || state === null) return undefined;
+    // A non-Schema state (e.g. `setState({ score: 0 })` with a plain object)
+    // CANNOT be replicated by the real encoder. Real Colyseus throws on this;
+    // surface it LOUDLY at the call rather than silently dropping replication —
+    // a silent divergence is exactly the defect this seam exists to kill.
+    if (!(state instanceof Schema)) {
+      const got =
+        typeof state === 'object'
+          ? ((state as { constructor?: { name?: string } }).constructor?.name ?? 'plain object')
+          : typeof state;
+      throw new Error(
+        `@vgai/p2p-colyseus: room "${this.roomName}" state must extend @colyseus/schema Schema; ` +
+          `got ${got}. setState(plainObject) does not replicate — declare a Schema state class ` +
+          `(e.g. \`class State extends Schema { @type('number') score = 0 }\`) and ` +
+          `setState(new State()).`,
+      );
+    }
+    if (this.encoder && this.encoder.state === state) return this.encoder;
+    if (this.encoder) this.pendingResyncAll = true; // state instance was replaced (setState)
+    this.encoder = new Encoder(state);
+    this.hasFilters = this.encoder.context.hasFilters;
+    return this.encoder;
+  }
+
+  /**
+   * Encode the FULL current state for a client — filtered to its `@view()`
+   * when the schema has view-gated fields and the client has a view. Mirrors
+   * `@colyseus/core` `SchemaSerializer.getFullState`.
+   */
+  private encodeFullState(view?: StateView): Uint8Array {
+    const encoder = this.ensureEncoder();
+    if (!encoder) return EMPTY_BYTES;
+    const it = { offset: 0 };
+    const full = encoder.encodeAll(it);
+    const sharedOffset = it.offset;
+    if (this.hasFilters && view) {
+      return Uint8Array.from(encoder.encodeAllView(view, sharedOffset, it));
     }
-    return sent;
+    return Uint8Array.from(full);
+  }
+
+  /**
+   * Encode the pending delta once and fan it out per client — mirrors
+   * `@colyseus/core` `SchemaSerializer.applyPatches`: viewless clients share
+   * one encoded patch, while each `@view()` client gets `encodeView` bytes that
+   * NEVER contain another view's filtered fields (the confidentiality property).
+   * `exceptSessionId` skips a just-joined client that already holds the full
+   * state.
+   */
+  private flushPatches(exceptSessionId?: string): boolean {
+    const encoder = this.ensureEncoder();
+    const recipients = [...this.clients.values()].filter(
+      (client) => client.sessionId !== exceptSessionId,
+    );
+    if (!encoder || recipients.length === 0) {
+      encoder?.discardChanges();
+      return false;
+    }
+
+    if (this.pendingResyncAll) {
+      this.pendingResyncAll = false;
+      for (const client of recipients) this.sendSnapshotTo(client);
+      encoder.discardChanges();
+      return true;
+    }
+
+    if (!encoder.hasChanges) {
+      // No state mutation, but a client may have manual view add/remove ops.
+      if (this.hasFilters) {
+        const it = { offset: 0 };
+        const sharedOffset = it.offset;
+        for (const client of recipients) {
+          if (client.view && client.view.changes.size > 0) {
+            this.sendPatchTo(
+              client,
+              Uint8Array.from(encoder.encodeView(client.view, sharedOffset, it)),
+            );
+          }
+        }
+      }
+      return false;
+    }
+
+    const it = { offset: 0 };
+    const encodedChanges = encoder.encode(it);
+    const sharedOffset = it.offset;
+    // Copy the shared (non-filtered) changes before any encodeView reuses the buffer.
+    const sharedCopy = Uint8Array.from(encodedChanges);
+    if (!this.hasFilters) {
+      for (const client of recipients) this.sendPatchTo(client, sharedCopy);
+    } else {
+      const perView = new Map<StateView, Uint8Array>();
+      for (const client of recipients) {
+        if (!client.view) {
+          this.sendPatchTo(client, sharedCopy);
+          continue;
+        }
+        let bytes = perView.get(client.view);
+        if (!bytes) {
+          bytes = Uint8Array.from(encoder.encodeView(client.view, sharedOffset, it));
+          perView.set(client.view, bytes);
+        }
+        this.sendPatchTo(client, bytes);
+      }
+    }
+    encoder.discardChanges();
+    return true;
+  }
+
+  private sendPatchTo(client: RuntimeClient, bytes: Uint8Array): void {
+    client.channel.send({
+      kind: 'state-patch',
+      patch: bytesToBase64(bytes),
+      clock: ++client.clock,
+    });
+  }
+
+  private sendSnapshotTo(client: RuntimeClient): void {
+    const bytes = this.encodeFullState(client.view);
+    client.channel.send({
+      kind: 'state-snapshot',
+      state: bytesToBase64(bytes),
+      clock: ++client.clock,
+    });
   }
 
   private async disconnect(code = 4000): Promise<void> {
@@ -293,13 +438,7 @@ export class UniversalRoomRuntime<T extends Room = Room> {
   }
 
   private sendSnapshot(client: RuntimeClient): void {
-    const snapshot = this.createSnapshot();
-    client.lastState = clone(snapshot.state);
-    client.channel.send({ kind: 'state-snapshot', snapshot, clock: ++this.clock });
-  }
-
-  private createSnapshot(): Snapshot {
-    return { type: 'snapshot', state: encodeSnapshot(this.room._snapshot()) };
+    this.sendSnapshotTo(client);
   }
 }
 

package/src/webrtc.ts

@@ -13,23 +13,53 @@ interface DataChannelLike {
 type EnvelopeHandler = (envelope: Envelope) => void;
 type CloseHandler = (reason?: string) => void;
 
+/**
+ * The label of the SECOND data channel — unordered, `maxRetransmits: 0` — that
+ * carries `sendUnreliable` traffic. The offerer creates it alongside the
+ * reliable channel; the answerer receives it via `ondatachannel` and hands it
+ * to `attachUnreliableChannel`. Exported so the negotiation code (`engine.ts`)
+ * and this class agree on the one string.
+ */
+export const WEBRTC_UNRELIABLE_CHANNEL_LABEL = 'p2p-colyseus-unreliable';
+
 export class WebRTCDataChannelPacketChannel implements PacketChannel {
   readonly mode = 'webrtc' as const;
   private readonly envelopeHandlers = new Set<EnvelopeHandler>();
   private readonly closeHandlers = new Set<CloseHandler>();
+  private unreliableChannel: DataChannelLike | null = null;
 
   constructor(
     readonly peerId: string,
     private readonly dataChannel: DataChannelLike,
+    unreliableChannel?: DataChannelLike,
   ) {
-    dataChannel.addEventListener('message', (event) => {
+    this.bindReceive(dataChannel);
+    dataChannel.addEventListener('close', () => {
+      for (const handler of this.closeHandlers) handler('closed');
+    });
+    if (unreliableChannel) this.attachUnreliableChannel(unreliableChannel);
+  }
+
+  /**
+   * Attach the unreliable sub-channel after construction. The answerer learns
+   * of it through a SEPARATE `ondatachannel` event, which may arrive before or
+   * after the reliable channel that constructs this object; the offerer passes
+   * it in the constructor instead. Frames received on it dispatch through the
+   * same envelope handlers as the reliable channel. The unreliable channel does
+   * NOT govern this channel's lifecycle — the reliable channel's `close` does —
+   * so no close handler is bound to it.
+   */
+  attachUnreliableChannel(channel: DataChannelLike): void {
+    this.unreliableChannel = channel;
+    this.bindReceive(channel);
+  }
+
+  private bindReceive(channel: DataChannelLike): void {
+    channel.addEventListener('message', (event) => {
       if (typeof event.data !== 'string') return;
       const envelope = JSON.parse(event.data) as Envelope;
       for (const handler of this.envelopeHandlers) handler(envelope);
     });
-    dataChannel.addEventListener('close', () => {
-      for (const handler of this.closeHandlers) handler('closed');
-    });
   }
 
   send(envelope: Envelope): void {
@@ -39,6 +69,17 @@ export class WebRTCDataChannelPacketChannel implements PacketChannel {
     this.dataChannel.send(JSON.stringify(envelope));
   }
 
+  sendUnreliable(envelope: Envelope): void {
+    const channel = this.unreliableChannel;
+    if (channel && channel.readyState === 'open') {
+      channel.send(JSON.stringify(envelope));
+      return;
+    }
+    // No unreliable channel yet (still negotiating) or it has gone away — never
+    // drop or throw: fall back to the reliable channel so the message arrives.
+    this.send(envelope);
+  }
+
   onEnvelope(handler: EnvelopeHandler): () => void {
     this.envelopeHandlers.add(handler);
     return () => this.envelopeHandlers.delete(handler);
@@ -51,6 +92,7 @@ export class WebRTCDataChannelPacketChannel implements PacketChannel {
 
   close(): void {
     this.dataChannel.close();
+    this.unreliableChannel?.close();
   }
 
   closeAfterFlush(delayMs = 100): void {
@@ -73,6 +115,7 @@ export class WebRTCDataChannelPacketChannel implements PacketChannel {
 export function createWebRTCDataChannelPacketChannel(
   peerId: string,
   dataChannel: RTCDataChannel,
+  unreliableChannel?: RTCDataChannel,
 ): PacketChannel {
-  return new WebRTCDataChannelPacketChannel(peerId, dataChannel);
+  return new WebRTCDataChannelPacketChannel(peerId, dataChannel, unreliableChannel);
 }

package/src/websocket.ts

@@ -30,7 +30,7 @@ export class WebSocketPacketChannel implements PacketChannel {
         // A real Colyseus server speaks a binary schema-diff protocol, not
         // this package's JSON Envelope format — a binary frame here is a
         // live signal the peer is wire-incompatible, not something to
-        // silently discard (see docs/decisions/h4-endpoint-interop.md).
+        // silently discard.
         for (const handler of this.protocolErrorHandlers) {
           handler('received a non-text (binary) WebSocket frame');
         }

package/src/wire-bytes.ts

@@ -0,0 +1,35 @@
+/**
+ * Base64 carriage for real `@colyseus/schema` binary state on the JSON
+ * `Envelope` wire.
+ *
+ * The replication seam encodes host state with the REAL `@colyseus/schema`
+ * `Encoder`, which emits a `Uint8Array`. Every P2P transport (browser-hosted
+ * WebRTC, universal WebSocket, forced/​fallback Cloudflare relay, in-process
+ * loopback) carries an `Envelope` that is `JSON.stringify`'d, so the binary
+ * patch/snapshot bytes ride as a base64 STRING field inside that envelope —
+ * universal, and unchanged by `JSON.stringify`. There is deliberately no
+ * native binary frame kind: a raw binary frame during join is the live signal
+ * `client.ts`'s H4 guard uses to detect a real Colyseus server, and a separate
+ * binary-frame optimization is out of scope here.
+ *
+ * `btoa`/`atob` exist in browsers and in Node ≥16 (`globalThis`), so these work
+ * in the deployed static bundle and in headless unit tests without a Buffer
+ * dependency.
+ */
+
+const CHUNK = 0x8000;
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+
+export function base64ToBytes(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}