@vgai/p2p-colyseus 0.1.0

package/src/protocol.ts

@@ -0,0 +1,56 @@
+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[] };
+
+export type Envelope =
+  | {
+      readonly kind: 'join';
+      readonly requestId: string;
+      readonly room: string;
+      readonly options?: unknown;
+    }
+  | {
+      readonly kind: 'join-ok';
+      readonly requestId: string;
+      readonly sessionId: string;
+      readonly snapshot: Snapshot;
+      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-resync'; readonly clock: number }
+  | { readonly kind: 'leave'; readonly code?: number; readonly reason?: string }
+  | { readonly kind: 'ping'; readonly t: number }
+  | { readonly kind: 'pong'; readonly t: number };
+
+export const P2P_CLOSE_CODES = {
+  badEnvelope: 4400,
+  unauthorized: 4401,
+  roomNotFound: 4404,
+  joinTimeout: 4408,
+  envelopeTooLarge: 4413,
+  rateLimited: 4429,
+  relayQuotaExceeded: 4430,
+  roomFull: 4431,
+  hostMissing: 4432,
+  relayNotAllowed: 4433,
+  internalError: 4500,
+} as const;
+
+export type P2PCloseCode = (typeof P2P_CLOSE_CODES)[keyof typeof P2P_CLOSE_CODES];
+
+export function isEnvelope(value: unknown): value is Envelope {
+  return typeof value === 'object' && value !== null && 'kind' in value;
+}

package/src/relay.ts

@@ -0,0 +1,60 @@
+import type { PacketChannel } from './channels';
+import type { SignalingRelayCoordinator } from './cloudflare/coordinator';
+import type { Envelope } from './protocol';
+
+type EnvelopeHandler = (envelope: Envelope) => void;
+type CloseHandler = (reason?: string) => void;
+
+export class CloudflareRelayPacketChannel implements PacketChannel {
+  readonly mode = 'relay' as const;
+  private readonly envelopeHandlers = new Set<EnvelopeHandler>();
+  private readonly closeHandlers = new Set<CloseHandler>();
+  private opened = false;
+
+  constructor(
+    readonly peerId: string,
+    private readonly roomId: string,
+    private readonly targetPeerId: string,
+    private readonly coordinator: SignalingRelayCoordinator,
+  ) {
+    coordinator.onEnvelope(peerId, (signal) => {
+      if (signal.kind !== 'relay-data') return;
+      for (const handler of this.envelopeHandlers) handler(signal.envelope);
+    });
+  }
+
+  send(envelope: Envelope): void {
+    if (!this.opened) {
+      const opened = this.coordinator.forward({
+        kind: 'relay-open',
+        roomId: this.roomId,
+        target: this.targetPeerId,
+        from: this.peerId,
+      });
+      if (opened?.kind === 'error') throw new Error(opened.message);
+      this.opened = true;
+    }
+    const result = this.coordinator.forward({
+      kind: 'relay-data',
+      roomId: this.roomId,
+      target: this.targetPeerId,
+      from: this.peerId,
+      envelope,
+    });
+    if (result?.kind === 'error') throw new Error(result.message);
+  }
+
+  onEnvelope(handler: EnvelopeHandler): () => void {
+    this.envelopeHandlers.add(handler);
+    return () => this.envelopeHandlers.delete(handler);
+  }
+
+  onClose(handler: CloseHandler): () => void {
+    this.closeHandlers.add(handler);
+    return () => this.closeHandlers.delete(handler);
+  }
+
+  close(reason?: string): void {
+    for (const handler of this.closeHandlers) handler(reason);
+  }
+}

package/src/replication.ts

@@ -0,0 +1,164 @@
+type AddHandler = (item: Record<string, unknown>, key: string) => void;
+type RemoveHandler = (item: Record<string, unknown>, key: string) => void;
+type ChangeHandler = () => void;
+type StateHandler = (state: Record<string, unknown>) => void;
+
+export class ClientReplication {
+  state: Record<string, unknown> = {};
+  private readonly collectionAdd = new Map<string, Set<AddHandler>>();
+  private readonly collectionRemove = new Map<string, Set<RemoveHandler>>();
+  private readonly itemChange = new WeakMap<object, Set<ChangeHandler>>();
+  private readonly stateChange = new Set<StateHandler>();
+
+  applySnapshot(next: unknown): void {
+    const incoming = isRecord(next) ? next : {};
+    this.mergeRoot(incoming);
+    for (const handler of [...this.stateChange]) handler(this.state);
+  }
+
+  onAdd(collection: string, handler: AddHandler): () => void {
+    const handlers = getSet(this.collectionAdd, collection);
+    handlers.add(handler);
+    const current = this.state[collection];
+    if (isRecord(current)) {
+      for (const [key, value] of Object.entries(current)) {
+        if (isRecord(value)) handler(value, key);
+      }
+    }
+    return () => handlers.delete(handler);
+  }
+
+  onRemove(collection: string, handler: RemoveHandler): () => void {
+    const handlers = getSet(this.collectionRemove, collection);
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+
+  onChange(item: Record<string, unknown>, handler: ChangeHandler): () => void {
+    const handlers = this.itemChange.get(item) ?? new Set<ChangeHandler>();
+    handlers.add(handler);
+    this.itemChange.set(item, handlers);
+    return () => handlers.delete(handler);
+  }
+
+  /**
+   * Mirror `properties` of a replicated item onto `target` — immediately (when
+   * `immediate`, the default, matching the real SDK) and again on every change.
+   * Compat with @colyseus/sdk's `StateCallbacks.bindTo(from, to, props?, immediate?)`;
+   * returns the unbind function.
+   */
+  bindTo<TTarget extends Record<string, unknown>>(
+    from: Record<string, unknown>,
+    to: TTarget,
+    properties?: readonly string[],
+    immediate = true,
+  ): () => void {
+    const copy = () => {
+      const keys = properties ?? Object.keys(from).filter((key) => typeof from[key] !== 'function');
+      for (const key of keys) {
+        (to as Record<string, unknown>)[key] = from[key];
+      }
+    };
+    if (immediate) copy();
+    return this.onChange(from, copy);
+  }
+
+  onStateChange(handler: StateHandler): () => void {
+    this.stateChange.add(handler);
+    return () => this.stateChange.delete(handler);
+  }
+
+  private mergeRoot(incoming: Record<string, unknown>): void {
+    for (const key of Object.keys(this.state)) {
+      if (!(key in incoming)) delete this.state[key];
+    }
+
+    for (const [key, value] of Object.entries(incoming)) {
+      const current = this.state[key];
+      if (isRecord(value) && isCollectionRecord(value)) {
+        this.state[key] = this.mergeCollection(key, isRecord(current) ? current : {}, value);
+      } else if (isRecord(value)) {
+        this.state[key] = mergeRecord(isRecord(current) ? current : {}, value, this.itemChange);
+      } else {
+        this.state[key] = value;
+      }
+    }
+  }
+
+  private mergeCollection(
+    collection: string,
+    current: Record<string, unknown>,
+    incoming: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const removeHandlers = this.collectionRemove.get(collection);
+    for (const key of Object.keys(current)) {
+      if (!(key in incoming)) {
+        const old = current[key];
+        if (isRecord(old)) {
+          for (const handler of removeHandlers ?? []) handler(old, key);
+        }
+        delete current[key];
+      }
+    }
+
+    const addHandlers = this.collectionAdd.get(collection);
+    for (const [key, value] of Object.entries(incoming)) {
+      if (!isRecord(value)) {
+        current[key] = value;
+        continue;
+      }
+
+      const existed = key in current;
+      const target = isRecord(current[key]) ? current[key] : {};
+      current[key] = mergeRecord(target, value, this.itemChange);
+      if (!existed && isRecord(current[key])) {
+        for (const handler of addHandlers ?? []) handler(current[key], key);
+      }
+    }
+
+    return current;
+  }
+}
+
+function mergeRecord(
+  target: Record<string, unknown>,
+  incoming: Record<string, unknown>,
+  itemChange: WeakMap<object, Set<ChangeHandler>>,
+): Record<string, unknown> {
+  let changed = false;
+  for (const key of Object.keys(target)) {
+    if (!(key in incoming)) {
+      delete target[key];
+      changed = true;
+    }
+  }
+  for (const [key, value] of Object.entries(incoming)) {
+    if (isRecord(value)) {
+      const child = isRecord(target[key]) ? target[key] : {};
+      target[key] = mergeRecord(child, value, itemChange);
+    } else if (target[key] !== value) {
+      target[key] = value;
+      changed = true;
+    }
+  }
+  if (changed) {
+    for (const handler of itemChange.get(target) ?? []) handler();
+  }
+  return target;
+}
+
+function getSet<K, V>(map: Map<K, Set<V>>, key: K): Set<V> {
+  const existing = map.get(key);
+  if (existing) return existing;
+  const created = new Set<V>();
+  map.set(key, created);
+  return created;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isCollectionRecord(value: Record<string, unknown>): boolean {
+  return Object.values(value).every((item) => isRecord(item));
+}

package/src/room.ts

@@ -0,0 +1,282 @@
+import { encodeSnapshotState } from './schema';
+
+export interface CompatClient {
+  readonly id: string;
+  readonly sessionId: string;
+  state: number;
+  userData?: unknown;
+  auth?: unknown;
+  reconnectionToken: string;
+  ref: {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    emit(event: string, ...args: unknown[]): void;
+  };
+  raw(data: Uint8Array | Buffer, options?: unknown, cb?: (err?: Error) => void): void;
+  enqueueRaw(data: Uint8Array | Buffer, options?: unknown): void;
+  send(type: string | number, payload?: unknown): void;
+  sendBytes(type: string | number, bytes: Uint8Array | Buffer): void;
+  leave(code?: number, data?: string): void;
+  close(code?: number, data?: string): void;
+  error(code: number, message?: string): void;
+}
+
+export type Client = CompatClient;
+
+export type MessageHandler = (client: CompatClient, payload: unknown) => void;
+export type WildcardMessageHandler = (
+  client: CompatClient,
+  type: string | number,
+  payload: unknown,
+) => void;
+
+export class ClientArray<C extends CompatClient = CompatClient> extends Array<C> {
+  getById(sessionId: string): C | undefined {
+    return this.find((client) => client.sessionId === sessionId);
+  }
+
+  delete(client: C): boolean {
+    const index = this.indexOf(client);
+    if (index < 0) return false;
+    this.splice(index, 1);
+    return true;
+  }
+}
+
+export interface BroadcastOptions {
+  except?: CompatClient | CompatClient[];
+  afterNextPatch?: boolean;
+}
+
+export interface RoomRuntimeBridge {
+  broadcastMessage(type: string | number, payload?: unknown, options?: BroadcastOptions): void;
+  broadcastState(): boolean;
+  disconnect(code?: number): Promise<void>;
+  send(client: CompatClient, type: string | number, payload?: unknown): void;
+  removeClient(client: CompatClient, code?: number, reason?: string): void;
+  allowReconnection(
+    client: CompatClient,
+    seconds: number | 'manual',
+  ): Promise<CompatClient> & {
+    reject(reason?: unknown): void;
+  };
+}
+
+export abstract class Room<State = unknown> {
+  maxClients = Infinity;
+  autoDispose = true;
+  patchRate: number | null = 50;
+  maxMessagesPerSecond = Infinity;
+  seatReservationTimeout = 15;
+  state!: State;
+  readonly clients = new ClientArray();
+  private explicitlyLocked = false;
+  private matchmakingPrivate = false;
+  private roomMetadata: unknown = {};
+  private readonly messageHandlers = new Map<string, Set<MessageHandler>>();
+  private readonly wildcardMessageHandlers = new Set<WildcardMessageHandler>();
+  private readonly simulationTimers = new Set<ReturnType<typeof setInterval>>();
+  private readonly timeoutTimers = new Set<ReturnType<typeof setTimeout>>();
+  private runtime: RoomRuntimeBridge | null = null;
+
+  get locked(): boolean {
+    return this.explicitlyLocked || this.hasReachedMaxClients();
+  }
+
+  get metadata(): unknown {
+    return this.roomMetadata;
+  }
+
+  set metadata(meta: unknown) {
+    this.roomMetadata = meta;
+  }
+
+  get isPrivate(): boolean {
+    return this.matchmakingPrivate;
+  }
+
+  setState(state: State): void {
+    this.state = state;
+    this.runtime?.broadcastState();
+  }
+
+  onMessage(type: '*', handler: WildcardMessageHandler): () => void;
+  onMessage(type: string | number, handler: MessageHandler): () => void;
+  onMessage(type: string | number, _validationSchema: unknown, handler: MessageHandler): () => void;
+  onMessage(
+    type: string | number,
+    handlerOrSchema: MessageHandler | WildcardMessageHandler | unknown,
+    maybeHandler?: MessageHandler,
+  ): () => void {
+    const handler = (maybeHandler ?? handlerOrSchema) as MessageHandler | WildcardMessageHandler;
+    if (type === '*') {
+      this.wildcardMessageHandlers.add(handler as WildcardMessageHandler);
+      return () => this.wildcardMessageHandlers.delete(handler as WildcardMessageHandler);
+    }
+
+    const key = String(type);
+    let handlers = this.messageHandlers.get(key);
+    if (!handlers) {
+      handlers = new Set();
+      this.messageHandlers.set(key, handlers);
+    }
+    handlers.add(handler as MessageHandler);
+    return () => handlers?.delete(handler as MessageHandler);
+  }
+
+  onMessageBytes(type: string | number, handler: MessageHandler): () => void;
+  onMessageBytes(
+    type: string | number,
+    _validationSchema: unknown,
+    handler: MessageHandler,
+  ): () => void;
+  onMessageBytes(
+    type: string | number,
+    handlerOrSchema: MessageHandler | unknown,
+    maybeHandler?: MessageHandler,
+  ): () => void {
+    return this.onMessage(type, (maybeHandler ?? handlerOrSchema) as MessageHandler);
+  }
+
+  send(client: CompatClient, type: string | number, payload?: unknown): void {
+    this.runtime?.send(client, type, payload);
+  }
+
+  broadcast(type: string | number, payload?: unknown, options?: BroadcastOptions): void {
+    this.runtime?.broadcastMessage(type, payload, options);
+  }
+
+  broadcastBytes(type: string | number, payload: Uint8Array, options?: BroadcastOptions): void {
+    this.broadcast(type, payload, options);
+  }
+
+  broadcastPatch(): boolean {
+    return this.runtime?.broadcastState() ?? false;
+  }
+
+  setSimulationInterval(callback: (dt: number) => void, ms = 16): void {
+    let last = Date.now();
+    const timer = setInterval(() => {
+      const now = Date.now();
+      callback(now - last);
+      last = now;
+      this.runtime?.broadcastState();
+    }, ms);
+    this.simulationTimers.add(timer);
+    (timer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  setPatchRate(milliseconds: number | null): void {
+    this.patchRate = milliseconds;
+  }
+
+  async setMetadata(meta: unknown): Promise<void> {
+    this.metadata = meta;
+  }
+
+  async setPrivate(bool = true): Promise<void> {
+    this.matchmakingPrivate = bool;
+  }
+
+  async setMatchmaking(updates: {
+    metadata?: unknown;
+    private?: boolean;
+    locked?: boolean;
+    maxClients?: number;
+    [key: string]: unknown;
+  }): Promise<void> {
+    if ('metadata' in updates) this.metadata = updates.metadata;
+    if (typeof updates.private === 'boolean') this.matchmakingPrivate = updates.private;
+    if (typeof updates.locked === 'boolean') this.explicitlyLocked = updates.locked;
+    if (typeof updates.maxClients === 'number') this.maxClients = updates.maxClients;
+  }
+
+  async lock(): Promise<void> {
+    this.explicitlyLocked = true;
+  }
+
+  async unlock(): Promise<void> {
+    this.explicitlyLocked = false;
+  }
+
+  hasReachedMaxClients(): boolean {
+    return this.clients.length >= this.maxClients;
+  }
+
+  setSeatReservationTime(seconds: number): this {
+    this.seatReservationTimeout = seconds;
+    return this;
+  }
+
+  hasReservedSeat(_sessionId: string): boolean {
+    return false;
+  }
+
+  checkReconnectionToken(reconnectionToken: string): string {
+    return reconnectionToken.split(':')[0] ?? reconnectionToken;
+  }
+
+  async disconnect(closeCode = 4000): Promise<void> {
+    await this.runtime?.disconnect(closeCode);
+  }
+
+  allowReconnection(
+    previousClient: CompatClient,
+    seconds: number | 'manual',
+  ): Promise<CompatClient> & { reject(reason?: unknown): void } {
+    if (!this.runtime) throw new Error('Room runtime is not attached');
+    return this.runtime.allowReconnection(previousClient, seconds);
+  }
+
+  onBeforeShutdown(): void {}
+
+  onCreate?(_options?: unknown): void;
+  onAuth?(
+    _client: CompatClient,
+    _options?: unknown,
+  ): boolean | unknown | Promise<boolean | unknown>;
+  onJoin?(_client: CompatClient, _options?: unknown): void;
+  onDrop?(_client: CompatClient, _code?: number): void;
+  onReconnect?(_client: CompatClient): void;
+  onLeave?(_client: CompatClient, _code?: number): void;
+  onDispose?(): void;
+
+  _attachRuntime(runtime: RoomRuntimeBridge): void {
+    this.runtime = runtime;
+  }
+
+  _dispatchMessage(client: CompatClient, type: string | number, payload: unknown): void {
+    for (const handler of this.messageHandlers.get(String(type)) ?? []) handler(client, payload);
+    for (const handler of this.wildcardMessageHandlers) handler(client, type, payload);
+    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);
+    this.simulationTimers.clear();
+    this.timeoutTimers.clear();
+    this.runtime = null;
+  }
+}
+
+export function validate(_format: unknown, handler: MessageHandler): MessageHandler {
+  return handler;
+}
+
+export function room<T extends Room>(options: Partial<T> & ThisType<T>): new () => T {
+  return class extends Room {
+    constructor() {
+      super();
+      Object.assign(this, options);
+      if ('state' in options && options.state !== undefined) {
+        this.state =
+          typeof options.state === 'function' ? (options.state as () => unknown)() : options.state;
+      }
+    }
+  } as unknown as new () => T;
+}