@vgai/p2p-colyseus 0.1.0

package/src/cloudflare/durable-room.ts

@@ -0,0 +1,377 @@
+import { verifyP2PAccessToken } from '../access-token';
+import { isEnvelope, P2P_CLOSE_CODES } from '../protocol';
+import { SignalingRelayCoordinator } from './coordinator';
+import type { SignalEnvelope } from './protocol';
+
+interface CloudflareWebSocket extends WebSocket {
+  accept(): void;
+}
+
+type ErrorSignalEnvelope = Extract<SignalEnvelope, { kind: 'error' }>;
+
+interface DurableObjectStateLike {
+  storage?: {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    put(key: string, value: unknown): Promise<void>;
+  };
+}
+
+interface DurableRoomEnv {
+  P2P_COLYSEUS_RELAY_DISABLED?: string | undefined;
+  P2P_COLYSEUS_RELAY_DAILY_BUDGET_USD?: string | undefined;
+  P2P_COLYSEUS_RELAY_ESTIMATED_USD_PER_GIB?: string | undefined;
+  P2P_COLYSEUS_RELAY_MAX_GLOBAL_BYTES_PER_DAY?: string | undefined;
+  P2P_COLYSEUS_MAX_GLOBAL_REQUESTS_PER_DAY?: string | undefined;
+  P2P_COLYSEUS_MAX_GLOBAL_WEBSOCKET_MESSAGES_PER_DAY?: string | undefined;
+  P2P_COLYSEUS_MAX_ACTIVE_RELAY_SOCKETS?: string | undefined;
+  P2P_COLYSEUS_ACCESS_TOKEN_SECRET?: string | undefined;
+}
+
+export class P2PColyseusDurableRoom {
+  private readonly coordinator = new SignalingRelayCoordinator();
+  private readonly sockets = new Map<string, CloudflareWebSocket>();
+
+  constructor(
+    private readonly state?: DurableObjectStateLike,
+    private readonly env: DurableRoomEnv = {},
+  ) {}
+
+  async fetch(request: Request): Promise<Response> {
+    if (isRelayDisabled(this.env)) {
+      return json({ kind: 'error', message: String(P2P_CLOSE_CODES.relayQuotaExceeded) }, 503);
+    }
+
+    const requestBudgetResult = await this.consumeDailyCounter(
+      'relay-global-requests',
+      1,
+      getMaxGlobalRequestsPerDay(this.env),
+    );
+    if (requestBudgetResult) return json(requestBudgetResult, 429);
+
+    if (request.headers.get('Upgrade')?.toLowerCase() === 'websocket') {
+      return this.acceptWebSocket(request);
+    }
+
+    if (request.method === 'OPTIONS') {
+      return json(null);
+    }
+
+    if (request.method === 'GET') {
+      return json(await this.diagnostics());
+    }
+
+    if (request.method !== 'POST') {
+      return json({ kind: 'error', message: 'Use POST' }, 405);
+    }
+
+    let envelope: SignalEnvelope & { from?: string | undefined; ipHash?: string | undefined };
+    try {
+      envelope = (await request.json()) as SignalEnvelope & {
+        from?: string | undefined;
+        ipHash?: string | undefined;
+      };
+    } catch {
+      return json({ kind: 'error', message: String(P2P_CLOSE_CODES.badEnvelope) }, 400);
+    }
+    if (!isSignalEnvelope(envelope)) {
+      return json({ kind: 'error', message: String(P2P_CLOSE_CODES.badEnvelope) }, 400);
+    }
+    const ipHash = envelope.ipHash ?? request.headers.get('x-p2p-ip-hash') ?? undefined;
+    return json(await this.handle(ipHash ? { ...envelope, ipHash } : envelope));
+  }
+
+  async handle(
+    envelope: SignalEnvelope & { from?: string | undefined; ipHash?: string | undefined },
+  ): Promise<unknown> {
+    if (envelope.kind === 'host-register') {
+      const authError = await this.verifyAccess(
+        envelope.accessToken,
+        envelope.roomName,
+        envelope.from,
+      );
+      if (authError) return authError;
+      return this.coordinator.registerHost(
+        envelope.roomName,
+        envelope.from ?? 'host',
+        envelope.ipHash,
+      );
+    }
+
+    if (envelope.kind === 'join-request') {
+      const authError = await this.verifyAccess(
+        envelope.accessToken,
+        envelope.roomName,
+        envelope.from,
+      );
+      if (authError) return authError;
+      return this.coordinator.join(envelope.roomName, envelope.from ?? 'client');
+    }
+
+    if (
+      envelope.kind === 'rtc-offer' ||
+      envelope.kind === 'rtc-answer' ||
+      envelope.kind === 'rtc-ice' ||
+      envelope.kind === 'relay-open' ||
+      envelope.kind === 'relay-data'
+    ) {
+      if (envelope.kind === 'relay-data') {
+        const budgetResult = await this.consumeGlobalRelayBudget(byteLength(envelope));
+        if (budgetResult) return budgetResult;
+      }
+      return this.coordinator.forward(envelope) ?? { kind: 'ok' };
+    }
+
+    if (envelope.kind === 'relay-drain') {
+      return { kind: 'relay-drained', messages: this.coordinator.drain(envelope.peerId) };
+    }
+
+    if (envelope.kind === 'heartbeat') {
+      return this.coordinator.heartbeat(
+        envelope.roomId,
+        envelope.from ?? this.coordinator.diagnostics().hostSignalId,
+      );
+    }
+
+    return { kind: 'error', message: `Unsupported signal: ${envelope.kind}` };
+  }
+
+  private acceptWebSocket(request: Request): Response {
+    if (this.sockets.size >= getMaxActiveRelaySockets(this.env)) {
+      return json({ kind: 'error', message: String(P2P_CLOSE_CODES.relayQuotaExceeded) }, 429);
+    }
+    const url = new URL(request.url);
+    const peerId = url.searchParams.get('peerId');
+    const targetPeerId = url.searchParams.get('targetPeerId');
+    const roomId = url.searchParams.get('roomId');
+    if (!peerId || !targetPeerId || !roomId) {
+      return json({ kind: 'error', message: 'Missing peerId, targetPeerId, or roomId' }, 400);
+    }
+
+    const pair = newWebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    server.accept();
+    this.coordinator.ensureRelayPeer(roomId, peerId, targetPeerId);
+    this.coordinator.forward({ kind: 'relay-open', roomId, target: targetPeerId, from: peerId });
+    this.sockets.set(peerId, server);
+    server.addEventListener('message', async (event) => {
+      if (typeof event.data !== 'string') return;
+      const messageBudgetResult = await this.consumeDailyCounter(
+        'relay-global-websocket-messages',
+        1,
+        getMaxGlobalWebSocketMessagesPerDay(this.env),
+      );
+      if (messageBudgetResult) {
+        server.send(JSON.stringify(messageBudgetResult));
+        server.close(Number(messageBudgetResult.message), messageBudgetResult.message);
+        return;
+      }
+      const envelope = JSON.parse(event.data) as unknown;
+      const signalEnvelope: SignalEnvelope & { target: string; from: string } = {
+        kind: 'relay-data',
+        roomId,
+        target: targetPeerId,
+        from: peerId,
+        envelope: envelope as never,
+      };
+      const budgetResult = await this.consumeGlobalRelayBudget(byteLength(signalEnvelope));
+      const result = budgetResult ?? this.coordinator.forward(signalEnvelope);
+      if (result?.kind === 'error') {
+        server.send(JSON.stringify(result));
+        server.close(Number(result.message), result.message);
+        return;
+      }
+      this.sockets.get(targetPeerId)?.send(JSON.stringify(envelope));
+    });
+    server.addEventListener('close', () => {
+      this.sockets.delete(peerId);
+    });
+
+    return new Response(null, { status: 101, webSocket: client } as ResponseInit);
+  }
+
+  private async consumeGlobalRelayBudget(bytes: number): Promise<ErrorSignalEnvelope | null> {
+    return this.consumeDailyCounter(
+      'relay-global-bytes',
+      bytes,
+      getDailyGlobalRelayBytes(this.env),
+    );
+  }
+
+  private async consumeDailyCounter(
+    prefix: string,
+    amount: number,
+    max: number,
+  ): Promise<ErrorSignalEnvelope | null> {
+    if (!Number.isFinite(max) || max <= 0) {
+      return { kind: 'error', message: String(P2P_CLOSE_CODES.relayQuotaExceeded) };
+    }
+    const storage = this.state?.storage;
+    if (!storage) return null;
+
+    const key = `${prefix}:${dayKey(Date.now())}`;
+    try {
+      const current = (await storage.get<number>(key)) ?? 0;
+      if (current + amount > max) {
+        return { kind: 'error', message: String(P2P_CLOSE_CODES.relayQuotaExceeded) };
+      }
+      await storage.put(key, current + amount);
+      return null;
+    } catch {
+      return { kind: 'error', message: String(P2P_CLOSE_CODES.relayQuotaExceeded) };
+    }
+  }
+
+  private async diagnostics() {
+    const diagnostics = this.coordinator.diagnostics();
+    return {
+      ...diagnostics,
+      quota: {
+        ...diagnostics.quota,
+        maxGlobalRelayBytesPerDay: getDailyGlobalRelayBytes(this.env),
+        maxGlobalRequestsPerDay: getMaxGlobalRequestsPerDay(this.env),
+        maxGlobalWebSocketMessagesPerDay: getMaxGlobalWebSocketMessagesPerDay(this.env),
+        maxActiveRelaySockets: getMaxActiveRelaySockets(this.env),
+      },
+      dailyUsage: await this.dailyUsage(),
+    };
+  }
+
+  private async dailyUsage() {
+    const day = dayKey(Date.now());
+    const storage = this.state?.storage;
+    if (!storage) {
+      return {
+        day,
+        globalRequests: 0,
+        globalRelayBytes: 0,
+        globalWebSocketMessages: 0,
+      };
+    }
+    const [globalRequests, globalRelayBytes, globalWebSocketMessages] = await Promise.all([
+      storage.get<number>(`relay-global-requests:${day}`),
+      storage.get<number>(`relay-global-bytes:${day}`),
+      storage.get<number>(`relay-global-websocket-messages:${day}`),
+    ]);
+    return {
+      day,
+      globalRequests: globalRequests ?? 0,
+      globalRelayBytes: globalRelayBytes ?? 0,
+      globalWebSocketMessages: globalWebSocketMessages ?? 0,
+    };
+  }
+
+  private async verifyAccess(
+    token: string | undefined,
+    roomName: string,
+    peerId: string | undefined,
+  ): Promise<ErrorSignalEnvelope | null> {
+    const secret = this.env.P2P_COLYSEUS_ACCESS_TOKEN_SECRET;
+    if (!secret) return null;
+    if (!token) return { kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) };
+    const verified = await verifyP2PAccessToken(secret, token, { roomName, peerId });
+    return verified ? null : { kind: 'error', message: String(P2P_CLOSE_CODES.unauthorized) };
+  }
+}
+
+export function getDailyGlobalRelayBytes(env: DurableRoomEnv = {}): number {
+  const explicit = parsePositiveNumber(env.P2P_COLYSEUS_RELAY_MAX_GLOBAL_BYTES_PER_DAY);
+  if (explicit !== undefined) return Math.floor(explicit);
+
+  const budgetUsd = parsePositiveNumber(env.P2P_COLYSEUS_RELAY_DAILY_BUDGET_USD) ?? 100;
+  const estimatedUsdPerGib = parsePositiveNumber(env.P2P_COLYSEUS_RELAY_ESTIMATED_USD_PER_GIB) ?? 1;
+  return Math.floor((budgetUsd / estimatedUsdPerGib) * 1024 * 1024 * 1024);
+}
+
+export function getMaxGlobalRequestsPerDay(env: DurableRoomEnv = {}): number {
+  return Math.floor(parsePositiveNumber(env.P2P_COLYSEUS_MAX_GLOBAL_REQUESTS_PER_DAY) ?? 250_000);
+}
+
+export function getMaxGlobalWebSocketMessagesPerDay(env: DurableRoomEnv = {}): number {
+  return Math.floor(
+    parsePositiveNumber(env.P2P_COLYSEUS_MAX_GLOBAL_WEBSOCKET_MESSAGES_PER_DAY) ?? 2_000_000,
+  );
+}
+
+export function getMaxActiveRelaySockets(env: DurableRoomEnv = {}): number {
+  return Math.floor(parsePositiveNumber(env.P2P_COLYSEUS_MAX_ACTIVE_RELAY_SOCKETS) ?? 200);
+}
+
+function json(value: unknown, status = 200): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type',
+    },
+  });
+}
+
+function isSignalEnvelope(value: unknown): value is SignalEnvelope {
+  if (!isRecord(value) || typeof value['kind'] !== 'string') return false;
+  switch (value['kind']) {
+    case 'host-register':
+    case 'join-request':
+      return typeof value['roomName'] === 'string' && value['roomName'].length > 0;
+    case 'rtc-offer':
+    case 'rtc-answer':
+      return (
+        typeof value['roomId'] === 'string' &&
+        typeof value['target'] === 'string' &&
+        isRecord(value['sdp'])
+      );
+    case 'rtc-ice':
+      return (
+        typeof value['roomId'] === 'string' &&
+        typeof value['target'] === 'string' &&
+        isRecord(value['candidate'])
+      );
+    case 'relay-open':
+      return typeof value['roomId'] === 'string' && typeof value['target'] === 'string';
+    case 'relay-data':
+      return (
+        typeof value['roomId'] === 'string' &&
+        typeof value['target'] === 'string' &&
+        isEnvelope(value['envelope'])
+      );
+    case 'relay-drain':
+      return typeof value['peerId'] === 'string';
+    case 'heartbeat':
+      return typeof value['roomId'] === 'string';
+    default:
+      return false;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function newWebSocketPair(): [CloudflareWebSocket, CloudflareWebSocket] {
+  const Pair = (
+    globalThis as unknown as { WebSocketPair?: new () => Record<'0' | '1', CloudflareWebSocket> }
+  ).WebSocketPair;
+  if (!Pair) throw new Error('WebSocketPair is not available in this runtime');
+  const pair = new Pair();
+  return [pair[0], pair[1]];
+}
+
+function parsePositiveNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === '') return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function isRelayDisabled(env: DurableRoomEnv): boolean {
+  return env.P2P_COLYSEUS_RELAY_DISABLED === 'true' || env.P2P_COLYSEUS_RELAY_DISABLED === '1';
+}
+
+function dayKey(time: number): string {
+  return new Date(time).toISOString().slice(0, 10);
+}
+
+function byteLength(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}

package/src/cloudflare/limits.ts

@@ -0,0 +1,22 @@
+export const DEFAULT_RELAY_LIMITS = {
+  maxPlayers: 8,
+  maxConcurrentHostedRoomsPerIpHash: 3,
+  maxConcurrentRelayRoomsPerIpHash: 2,
+  maxGlobalRelayBytesPerDay: 100 * 1024 * 1024 * 1024,
+  maxGlobalRequestsPerDay: 250_000,
+  maxGlobalWebSocketMessagesPerDay: 2_000_000,
+  maxActiveRelaySockets: 200,
+  maxRelayBytesPerRoom: 100 * 1024 * 1024,
+  maxRelayBytesPerIpHashPerDay: 500 * 1024 * 1024,
+  maxRelayRoomDurationMs: 2 * 60 * 60 * 1000,
+  idleTimeoutMs: 120_000,
+  hostHeartbeatTimeoutMs: 15_000,
+  maxEnvelopeBytes: 16 * 1024,
+  maxMessagesPerPeerPerSecond: 30,
+  maxSignalingMessagesPerPeerPerMinute: 120,
+  maxIceCandidatesPerPeerPerJoin: 64,
+} as const;
+
+export type RelayLimits = {
+  readonly [K in keyof typeof DEFAULT_RELAY_LIMITS]: number;
+};

package/src/cloudflare/protocol.ts

@@ -0,0 +1,75 @@
+import type { Envelope } from '../protocol';
+
+export interface RoomMetadata {
+  maxClients?: number | undefined;
+  [key: string]: unknown;
+}
+
+export type SignalEnvelope =
+  | {
+      readonly kind: 'host-register';
+      readonly roomName: string;
+      readonly metadata?: RoomMetadata | undefined;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly accessToken?: string | undefined;
+    }
+  | { readonly kind: 'host-registered'; readonly roomId: string; readonly hostSignalId: string }
+  | {
+      readonly kind: 'join-request';
+      readonly roomName: string;
+      readonly roomId?: string | undefined;
+      readonly options?: unknown;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly accessToken?: string | undefined;
+    }
+  | {
+      readonly kind: 'join-routed';
+      readonly roomId: string;
+      readonly hostSignalId: string;
+      readonly clientSignalId: string;
+    }
+  | {
+      readonly kind: 'rtc-offer';
+      readonly roomId: string;
+      readonly target: string;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly sdp: RTCSessionDescriptionInit;
+    }
+  | {
+      readonly kind: 'rtc-answer';
+      readonly roomId: string;
+      readonly target: string;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly sdp: RTCSessionDescriptionInit;
+    }
+  | {
+      readonly kind: 'rtc-ice';
+      readonly roomId: string;
+      readonly target: string;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly candidate: RTCIceCandidateInit;
+    }
+  | {
+      readonly kind: 'relay-open';
+      readonly roomId: string;
+      readonly target: string;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+    }
+  | {
+      readonly kind: 'relay-data';
+      readonly roomId: string;
+      readonly target: string;
+      readonly from?: string | undefined;
+      readonly ipHash?: string | undefined;
+      readonly envelope: Envelope;
+    }
+  | { readonly kind: 'relay-drain'; readonly peerId: string }
+  | { readonly kind: 'relay-drained'; readonly messages: readonly SignalEnvelope[] }
+  | { readonly kind: 'heartbeat'; readonly roomId: string; readonly from?: string | undefined }
+  | { readonly kind: 'error'; readonly message: string };

package/src/cloudflare/worker.ts

@@ -0,0 +1,110 @@
+export { P2PColyseusDurableRoom } from './durable-room';
+
+interface Env {
+  P2P_COLYSEUS_ROOM: {
+    idFromName(name: string): unknown;
+    get(id: unknown): { fetch(request: Request): Promise<Response> };
+  };
+  P2P_COLYSEUS_MAX_REQUEST_BODY_BYTES?: string | undefined;
+  P2P_COLYSEUS_ALLOWED_ORIGINS?: string | undefined;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    let forwardedRequest = request;
+    if (request.method === 'OPTIONS') {
+      if (!isOriginAllowed(request, env)) {
+        return json({ kind: 'error', message: 'Origin not allowed' }, 403, request, env);
+      }
+      return new Response(null, { headers: corsHeaders(request, env) });
+    }
+    if (request.method !== 'GET' && request.method !== 'POST') {
+      return json({ kind: 'error', message: 'Use GET or POST' }, 405, request, env);
+    }
+    if (!isOriginAllowed(request, env)) {
+      return json({ kind: 'error', message: 'Origin not allowed' }, 403, request, env);
+    }
+    const upgrade = request.headers.get('Upgrade')?.toLowerCase();
+    if (upgrade === 'websocket') {
+      const url = new URL(request.url);
+      if (
+        !url.searchParams.get('peerId') ||
+        !url.searchParams.get('targetPeerId') ||
+        !url.searchParams.get('roomId')
+      ) {
+        return json(
+          { kind: 'error', message: 'Missing peerId, targetPeerId, or roomId' },
+          400,
+          request,
+          env,
+        );
+      }
+    } else if (request.method === 'POST') {
+      const body = await request.text();
+      if (byteLength(body) > getMaxRequestBodyBytes(env)) {
+        return json({ kind: 'error', message: 'Request body too large' }, 413, request, env);
+      }
+      forwardedRequest = new Request(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body,
+      });
+    }
+    const id = env.P2P_COLYSEUS_ROOM.idFromName('global');
+    const room = env.P2P_COLYSEUS_ROOM.get(id);
+    if (upgrade === 'websocket') {
+      return room.fetch(forwardedRequest);
+    }
+    const response = await room.fetch(forwardedRequest);
+    const headers = new Headers(response.headers);
+    for (const [key, value] of Object.entries(corsHeaders(request, env))) headers.set(key, value);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  },
+};
+
+function json(value: unknown, status = 200, request?: Request, env?: Env): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...corsHeaders(request, env),
+    },
+  });
+}
+
+function byteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function corsHeaders(request?: Request, env?: Env): Record<string, string> {
+  const origin = request?.headers.get('Origin') ?? '*';
+  const allowedOrigin = env && isOriginAllowed(request, env) && origin !== '*' ? origin : '*';
+  return {
+    'Access-Control-Allow-Origin': allowedOrigin,
+    'Access-Control-Allow-Methods': 'GET,POST,OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type',
+  };
+}
+
+function isOriginAllowed(request: Request | undefined, env: Env): boolean {
+  const origin = request?.headers.get('Origin');
+  if (!origin) return true;
+  const configured = env.P2P_COLYSEUS_ALLOWED_ORIGINS;
+  if (!configured) return true;
+  const allowed = configured
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return allowed.includes('*') || allowed.includes(origin);
+}
+
+function getMaxRequestBodyBytes(env: Env): number {
+  const value = env.P2P_COLYSEUS_MAX_REQUEST_BODY_BYTES;
+  if (!value) return 32 * 1024;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 32 * 1024;
+}

package/src/codec.ts

@@ -0,0 +1,78 @@
+import type { StatePatch, StatePatchOperation } from './protocol';
+import { encodeSnapshotState } from './schema';
+
+export function encodeSnapshot(value: unknown): unknown {
+  return encodeSnapshotState(value);
+}
+
+export function createStatePatch(previous: unknown, next: unknown): StatePatch {
+  const operations: StatePatchOperation[] = [];
+  diffValue([], previous, next, operations);
+  return { type: 'patch', operations };
+}
+
+export function applyStatePatch(previous: unknown, patch: StatePatch): unknown {
+  const root = clone(previous);
+  for (const operation of patch.operations) {
+    if (operation.op === 'set') setPath(root, operation.path, operation.value);
+    else deletePath(root, operation.path);
+  }
+  return root;
+}
+
+export function clone<T>(value: T): T {
+  if (value === undefined) return value;
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+function diffValue(
+  path: string[],
+  previous: unknown,
+  next: unknown,
+  operations: StatePatchOperation[],
+): void {
+  if (isRecord(previous) && isRecord(next)) {
+    for (const key of Object.keys(previous)) {
+      if (!(key in next)) operations.push({ op: 'delete', path: [...path, key] });
+    }
+    for (const [key, nextValue] of Object.entries(next)) {
+      diffValue([...path, key], previous[key], nextValue, operations);
+    }
+    return;
+  }
+
+  if (JSON.stringify(previous) !== JSON.stringify(next)) {
+    operations.push({ op: 'set', path, value: clone(next) });
+  }
+}
+
+function setPath(root: unknown, path: readonly string[], value: unknown): void {
+  if (path.length === 0) return;
+  const parent = parentAt(root, path);
+  parent[path[path.length - 1]!] = clone(value);
+}
+
+function deletePath(root: unknown, path: readonly string[]): void {
+  if (path.length === 0) return;
+  const parent = parentAt(root, path);
+  delete parent[path[path.length - 1]!];
+}
+
+function parentAt(root: unknown, path: readonly string[]): Record<string, unknown> {
+  if (!isRecord(root)) throw new Error('Cannot patch non-object state root');
+  let parent = root;
+  for (const segment of path.slice(0, -1)) {
+    const child = parent[segment];
+    if (!isRecord(child)) {
+      parent[segment] = {};
+      parent = parent[segment] as Record<string, unknown>;
+    } else {
+      parent = child;
+    }
+  }
+  return parent;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}