murow 0.0.70 → 0.0.71

package/src/protocol/rpc/rpc-registry.test.ts

@@ -1,168 +0,0 @@
-import { describe, it, expect, beforeEach } from "bun:test";
-import { RpcRegistry } from "./rpc-registry";
-import { defineRPC } from "./define-rpc";
-import { BinaryCodec } from "../../core/binary-codec";
-
-// Define RPCs for testing
-const MockRpc = defineRPC({
-	method: 'mockRpc',
-	schema: {
-		value: BinaryCodec.u32,
-	},
-});
-
-const AnotherRpc = defineRPC({
-	method: 'anotherRpc',
-	schema: {
-		data: BinaryCodec.string(64),
-	},
-});
-
-type MockRpcType = typeof MockRpc.type;
-type AnotherRpcType = typeof AnotherRpc.type;
-
-describe("RpcRegistry", () => {
-	let registry: RpcRegistry;
-
-	beforeEach(() => {
-		registry = new RpcRegistry();
-	});
-
-	describe("register", () => {
-		it("should register an RPC", () => {
-			registry.register(MockRpc);
-			expect(registry.has('mockRpc')).toBe(true);
-		});
-
-		it("should throw error when registering duplicate method", () => {
-			registry.register(MockRpc);
-			expect(() => registry.register(MockRpc)).toThrow(
-				'RPC "mockRpc" is already registered'
-			);
-		});
-
-		it("should allow registering multiple different RPCs", () => {
-			registry.register(MockRpc);
-			registry.register(AnotherRpc);
-			expect(registry.has('mockRpc')).toBe(true);
-			expect(registry.has('anotherRpc')).toBe(true);
-		});
-
-		it("should assign sequential method IDs", () => {
-			registry.register(MockRpc);
-			registry.register(AnotherRpc);
-
-			expect(registry.getMethodId('mockRpc')).toBe(0);
-			expect(registry.getMethodId('anotherRpc')).toBe(1);
-		});
-	});
-
-	describe("encode", () => {
-		it("should encode an RPC using registered codec", () => {
-			registry.register(MockRpc);
-			const data: MockRpcType = { value: 42 };
-			const buf = registry.encode(MockRpc, data);
-
-			expect(buf).toBeInstanceOf(Uint8Array);
-			expect(buf.byteLength).toBeGreaterThan(2); // At least methodId (2 bytes) + data
-		});
-
-		it("should throw error when encoding unregistered RPC", () => {
-			const data: MockRpcType = { value: 42 };
-			expect(() => registry.encode(MockRpc, data)).toThrow(
-				'RPC "mockRpc" is not registered'
-			);
-		});
-
-		it("should encode different RPC types correctly", () => {
-			registry.register(MockRpc);
-			registry.register(AnotherRpc);
-
-			const data1: MockRpcType = { value: 42 };
-			const data2: AnotherRpcType = { data: "test" };
-
-			const buf1 = registry.encode(MockRpc, data1);
-			const buf2 = registry.encode(AnotherRpc, data2);
-
-			expect(buf1).toBeInstanceOf(Uint8Array);
-			expect(buf2).toBeInstanceOf(Uint8Array);
-			expect(buf1[0]).not.toBe(buf2[0]); // Different method IDs
-		});
-	});
-
-	describe("decode", () => {
-		it("should decode an RPC using registered codec", () => {
-			registry.register(MockRpc);
-			const data: MockRpcType = { value: 42 };
-			const encoded = registry.encode(MockRpc, data);
-			const decoded = registry.decode(encoded);
-
-			expect(decoded.method).toBe('mockRpc');
-			expect(decoded.data.value).toBe(42);
-		});
-
-		it("should throw error when decoding unknown method ID", () => {
-			// Create buffer with invalid method ID
-			const buf = new Uint8Array([0xFF, 0xFF]);
-
-			expect(() => registry.decode(buf)).toThrow(
-				'Unknown RPC method ID: 65535'
-			);
-		});
-
-		it("should throw error when buffer is too small", () => {
-			const buf = new Uint8Array([0x00]); // Only 1 byte, needs at least 2
-
-			expect(() => registry.decode(buf)).toThrow(
-				'Buffer too small for RPC message'
-			);
-		});
-
-		it("should roundtrip encode/decode correctly", () => {
-			registry.register(MockRpc);
-			registry.register(AnotherRpc);
-
-			const data1: MockRpcType = { value: 12345 };
-			const data2: AnotherRpcType = { data: "hello world" };
-
-			const encoded1 = registry.encode(MockRpc, data1);
-			const encoded2 = registry.encode(AnotherRpc, data2);
-
-			const decoded1 = registry.decode(encoded1);
-			const decoded2 = registry.decode(encoded2);
-
-			expect(decoded1.method).toBe('mockRpc');
-			expect(decoded1.data.value).toBe(12345);
-
-			expect(decoded2.method).toBe('anotherRpc');
-			expect(decoded2.data.data).toBe('hello world');
-		});
-	});
-
-	describe("getMethods", () => {
-		it("should return empty array when no RPCs registered", () => {
-			expect(registry.getMethods()).toEqual([]);
-		});
-
-		it("should return all registered method names", () => {
-			registry.register(MockRpc);
-			registry.register(AnotherRpc);
-
-			const methods = registry.getMethods();
-			expect(methods).toContain('mockRpc');
-			expect(methods).toContain('anotherRpc');
-			expect(methods.length).toBe(2);
-		});
-	});
-
-	describe("getMethodId", () => {
-		it("should return undefined for unregistered method", () => {
-			expect(registry.getMethodId('unknown')).toBeUndefined();
-		});
-
-		it("should return correct method ID", () => {
-			registry.register(MockRpc);
-			expect(registry.getMethodId('mockRpc')).toBe(0);
-		});
-	});
-});

package/src/protocol/rpc/rpc-registry.ts

@@ -1,176 +0,0 @@
-import type { DefinedRPC, RpcCodec } from './rpc';
-
-/**
- * Registry for managing RPC definitions with binary encoding/decoding
- *
- * Maps RPC method names to numeric IDs for efficient binary protocol:
- * - Method names are assigned sequential IDs (0, 1, 2, ...)
- * - Binary format: [methodId: u16][data: variable]
- * - Supports bidirectional RPCs (client ↔ server)
- *
- * @example
- * ```ts
- * const registry = new RpcRegistry();
- *
- * // Register RPCs
- * registry.register(MatchCountdown);
- * registry.register(BuyItem);
- *
- * // Encode RPC to binary
- * const binary = registry.encode(MatchCountdown, { secondsRemaining: 10 });
- *
- * // Decode RPC from binary
- * const { method, data } = registry.decode(binary);
- * console.log(method); // 'matchCountdown'
- * console.log(data.secondsRemaining); // 10
- * ```
- */
-export class RpcRegistry {
-	private codecs = new Map<string, RpcCodec<any>>();
-	private methodToId = new Map<string, number>();
-	private idToMethod = new Map<number, string>();
-	private nextId = 0;
-
-	/**
-	 * Register an RPC definition
-	 *
-	 * @param rpc The RPC definition created by defineRPC()
-	 * @throws Error if method is already registered
-	 *
-	 * @example
-	 * ```ts
-	 * const MatchCountdown = defineRPC({
-	 *   method: 'matchCountdown',
-	 *   schema: { secondsRemaining: BinaryCodec.u8 }
-	 * });
-	 *
-	 * registry.register(MatchCountdown);
-	 * ```
-	 */
-	register<TSchema extends Record<string, any>>(rpc: DefinedRPC<TSchema>): void {
-		if (this.codecs.has(rpc.method)) {
-			throw new Error(`RPC "${rpc.method}" is already registered`);
-		}
-
-		const id = this.nextId++;
-		this.codecs.set(rpc.method, rpc.codec);
-		this.methodToId.set(rpc.method, id);
-		this.idToMethod.set(id, rpc.method);
-	}
-
-	/**
-	 * Encode an RPC to binary format
-	 *
-	 * Binary format: [methodId: u16][data: variable]
-	 *
-	 * @param rpc The RPC definition
-	 * @param data The RPC data to encode
-	 * @returns Encoded binary data
-	 * @throws Error if RPC is not registered
-	 *
-	 * @example
-	 * ```ts
-	 * const binary = registry.encode(MatchCountdown, {
-	 *   secondsRemaining: 10
-	 * });
-	 * ```
-	 */
-	encode<TSchema extends Record<string, any>>(rpc: DefinedRPC<TSchema>, data: TSchema): Uint8Array {
-		const codec = this.codecs.get(rpc.method);
-		if (!codec) {
-			throw new Error(`RPC "${rpc.method}" is not registered`);
-		}
-
-		const methodId = this.methodToId.get(rpc.method)!;
-		const encodedData = codec.encode(data);
-
-		// Message format: [methodId: u16][data]
-		const buffer = new Uint8Array(2 + encodedData.byteLength);
-		new DataView(buffer.buffer).setUint16(0, methodId, true);
-		buffer.set(new Uint8Array(encodedData), 2);
-
-		return buffer;
-	}
-
-	/**
-	 * Decode an RPC from binary format
-	 *
-	 * @param buffer Binary data to decode
-	 * @returns Object with method name and decoded data
-	 * @throws Error if method ID is unknown
-	 *
-	 * @example
-	 * ```ts
-	 * const { method, data } = registry.decode(binary);
-	 * console.log(method); // 'matchCountdown'
-	 * console.log(data.secondsRemaining); // 10
-	 * ```
-	 */
-	decode(buffer: Uint8Array): { method: string; data: any } {
-		if (buffer.byteLength < 2) {
-			throw new Error('Buffer too small for RPC message');
-		}
-
-		const view = new DataView(buffer.buffer, buffer.byteOffset);
-		const methodId = view.getUint16(0, true);
-
-		const method = this.idToMethod.get(methodId);
-		if (!method) {
-			throw new Error(`Unknown RPC method ID: ${methodId}`);
-		}
-
-		const codec = this.codecs.get(method)!;
-		const data = codec.decode(buffer.slice(2));
-
-		return { method, data };
-	}
-
-	/**
-	 * Check if an RPC method is registered
-	 *
-	 * @param method Method name to check
-	 * @returns True if registered, false otherwise
-	 */
-	has(method: string): boolean {
-		return this.codecs.has(method);
-	}
-
-	/**
-	 * Get all registered RPC method names
-	 *
-	 * @returns Array of method names
-	 */
-	getMethods(): string[] {
-		return Array.from(this.codecs.keys());
-	}
-
-	/**
-	 * Get the numeric ID for a method
-	 *
-	 * @param method Method name
-	 * @returns Method ID or undefined if not registered
-	 */
-	getMethodId(method: string): number | undefined {
-		return this.methodToId.get(method);
-	}
-
-	/**
-	 * Release a decoded RPC data object back to the pool.
-	 * Call this after you're done processing the RPC to enable object pooling.
-	 *
-	 * @param method The RPC method name (same as used in decode)
-	 * @param data The RPC data object to release
-	 */
-	release(method: string, data: any): void {
-		const codec = this.codecs.get(method);
-
-		if (!codec) {
-			throw new Error(`RPC "${method}" is not registered`);
-		}
-
-		// Only release if the codec supports pooling
-		if ('release' in codec && typeof codec.release === 'function') {
-			codec.release(data);
-		}
-	}
-}

package/src/protocol/rpc/rpc.ts

@@ -1,37 +0,0 @@
-/**
- * RPC (Remote Procedure Call) type definitions
- *
- * RPCs are bidirectional one-off events/commands for:
- * - Meta-game events (achievements, notifications)
- * - Match lifecycle (countdown, results)
- * - Request/response patterns
- * - System announcements
- *
- * NOT for game state synchronization (use Snapshots) or player inputs (use Intents)
- */
-
-/**
- * Codec interface for encoding/decoding RPCs
- */
-export interface RpcCodec<T> {
-	encode(value: T): Uint8Array;
-	decode(buf: Uint8Array): T;
-}
-
-/**
- * Runtime RPC message structure
- */
-export interface RPC<T = unknown> {
-	method: string;
-	data: T;
-}
-
-/**
- * Compile-time RPC definition with type safety
- * Created by defineRPC() helper
- */
-export interface DefinedRPC<TSchema extends Record<string, any>> {
-	method: string;
-	codec: RpcCodec<TSchema>;
-	type: TSchema; // Phantom type for inference
-}

package/src/protocol/snapshot/index.ts

@@ -1,45 +0,0 @@
-/**
- * Snapshot system for server-to-client state updates.
- *
- * Snapshots are delta updates that contain:
- * 1. Server tick number
- * 2. Partial state updates (only what changed)
- *
- * They need to be:
- * 1. Encoded efficiently (binary)
- * 2. Sent over network
- * 3. Decoded on the client
- * 4. Merged into client state
- *
- * @example
- * ```ts
- * import { Snapshot, SnapshotCodec, applySnapshot } from './protocol/snapshot';
- * import { PooledCodec } from '../core/pooled-codec';
- * import { BinaryCodec } from '../core/binary-codec';
- *
- * interface GameState {
- *   players: Record<number, { x: number; y: number }>;
- * }
- *
- * // 1. Create codec once (reuse this instance)
- * const snapshotCodec = new SnapshotCodec<GameState>(
- *   new PooledCodec({ players: // ... your schema })
- * );
- *
- * // 2. Server: Encode snapshot
- * const snapshot: Snapshot<GameState> = {
- *   tick: 100,
- *   updates: { players: { 1: { x: 5, y: 10 } } }
- * };
- * const buf = snapshotCodec.encode(snapshot);
- *
- * // 3. Client: Decode and apply
- * const snapshot = snapshotCodec.decode(buf);
- * applySnapshot(clientState, snapshot);
- * ```
- */
-
-export type { Snapshot } from "./snapshot";
-export { applySnapshot } from "./snapshot";
-export { SnapshotCodec } from "./snapshot-codec";
-export { SnapshotRegistry } from "./snapshot-registry";

package/src/protocol/snapshot/snapshot-codec.test.ts

@@ -1,138 +0,0 @@
-import { describe, it, expect } from "bun:test";
-import { SnapshotCodec } from "./snapshot-codec";
-import { Snapshot } from "./snapshot";
-import { Codec } from "./snapshot-codec";
-
-// Simple mock codec for testing
-class MockCodec<T> implements Codec<T> {
-  encode(value: T): Uint8Array {
-    const json = JSON.stringify(value);
-    return new TextEncoder().encode(json);
-  }
-
-  decode(buf: Uint8Array): T {
-    const json = new TextDecoder().decode(buf);
-    return JSON.parse(json);
-  }
-}
-
-interface TestState {
-  x: number;
-  y: number;
-  health?: number;
-}
-
-describe("SnapshotCodec", () => {
-  it("should encode and decode a snapshot", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const snapshot: Snapshot<TestState> = {
-      tick: 100,
-      updates: { x: 10, y: 20 },
-    };
-
-    const buf = codec.encode(snapshot);
-    const decoded = codec.decode(buf);
-
-    expect(decoded.tick).toBe(100);
-    expect(decoded.updates.x).toBe(10);
-    expect(decoded.updates.y).toBe(20);
-  });
-
-  it("should handle partial updates", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const snapshot: Snapshot<TestState> = {
-      tick: 50,
-      updates: { x: 5 },
-    };
-
-    const buf = codec.encode(snapshot);
-    const decoded = codec.decode(buf);
-
-    expect(decoded.tick).toBe(50);
-    expect(decoded.updates.x).toBe(5);
-    expect(decoded.updates.y).toBeUndefined();
-  });
-
-  it("should handle large tick numbers", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const snapshot: Snapshot<TestState> = {
-      tick: 4294967295, // Max u32
-      updates: { x: 1, y: 2 },
-    };
-
-    const buf = codec.encode(snapshot);
-    const decoded = codec.decode(buf);
-
-    expect(decoded.tick).toBe(4294967295);
-  });
-
-  it("should preserve tick in binary format", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const snapshot: Snapshot<TestState> = {
-      tick: 12345,
-      updates: { x: 1 },
-    };
-
-    const buf = codec.encode(snapshot);
-
-    // First 4 bytes should be the tick (little-endian)
-    const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
-    expect(tick).toBe(12345);
-  });
-
-  it("should handle empty updates", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const snapshot: Snapshot<TestState> = {
-      tick: 100,
-      updates: {},
-    };
-
-    const buf = codec.encode(snapshot);
-    const decoded = codec.decode(buf);
-
-    expect(decoded.tick).toBe(100);
-    expect(decoded.updates).toEqual({});
-  });
-
-  it("should handle nested state", () => {
-    interface NestedState {
-      player: {
-        position: { x: number; y: number };
-        health: number;
-      };
-    }
-
-    const codec = new SnapshotCodec<NestedState>(new MockCodec());
-    const snapshot: Snapshot<NestedState> = {
-      tick: 200,
-      updates: {
-        player: {
-          position: { x: 10, y: 20 },
-          health: 80,
-        },
-      },
-    };
-
-    const buf = codec.encode(snapshot);
-    const decoded = codec.decode(buf);
-
-    expect(decoded.tick).toBe(200);
-    expect(decoded.updates.player?.position.x).toBe(10);
-    expect(decoded.updates.player?.position.y).toBe(20);
-    expect(decoded.updates.player?.health).toBe(80);
-  });
-
-  it("should round-trip multiple times", () => {
-    const codec = new SnapshotCodec<TestState>(new MockCodec());
-    const original: Snapshot<TestState> = {
-      tick: 999,
-      updates: { x: 123, y: 456, health: 78 },
-    };
-
-    for (let i = 0; i < 10; i++) {
-      const buf = codec.encode(original);
-      const decoded = codec.decode(buf);
-      expect(decoded).toEqual(original);
-    }
-  });
-});

package/src/protocol/snapshot/snapshot-codec.ts

@@ -1,87 +0,0 @@
-import type { Snapshot } from "./snapshot";
-
-/**
- * Generic codec interface (users import from core/pooled-codec)
- */
-export interface Codec<T> {
-  encode(value: T): Uint8Array;
-  decode(buf: Uint8Array): T;
-  calculateSize?(value: T): number;
-  encodeInto?(value: T, buffer: Uint8Array, offset: number): number;
-}
-
-/**
- * Codec for encoding/decoding snapshots with binary serialization.
- *
- * Users instantiate this once with a PooledCodec for their state schema.
- *
- * @example
- * ```ts
- * import { SnapshotCodec } from './protocol/snapshot';
- * import { PooledCodec } from './core/pooled-codec';
- * import { BinaryCodec } from './core/binary-codec';
- *
- * interface GameState {
- *   players: Record<number, { x: number; y: number }>;
- * }
- *
- * const snapshotCodec = new SnapshotCodec<GameState>(
- *   new PooledCodec({ players: // schema })
- * );
- *
- * // Encode/decode
- * const buf = snapshotCodec.encode(snapshot);
- * const decoded = snapshotCodec.decode(buf);
- * ```
- */
-export class SnapshotCodec<T> {
-  /**
-   * @param updatesCodec Codec for encoding/decoding the state updates
-   */
-  constructor(private updatesCodec: Codec<Partial<T>>) {}
-
-  /**
-   * Encode a snapshot into binary format.
-   * Format: [tick: u32][updates: encoded by updatesCodec]
-   *
-   * Uses zero-copy path if codec supports calculateSize and encodeInto.
-   */
-  encode(snapshot: Snapshot<T>): Uint8Array {
-    // Use zero-copy path if available
-    if (this.updatesCodec.calculateSize && this.updatesCodec.encodeInto) {
-      const updatesSize = this.updatesCodec.calculateSize(snapshot.updates);
-      const buf = new Uint8Array(4 + updatesSize);
-
-      // Encode tick (4 bytes, little-endian)
-      new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
-
-      // Write updates directly into buffer (ZERO COPY!)
-      this.updatesCodec.encodeInto(snapshot.updates, buf, 4);
-
-      return buf;
-    }
-
-    // Fallback to legacy path
-    const updatesBytes = this.updatesCodec.encode(snapshot.updates);
-    const buf = new Uint8Array(4 + updatesBytes.length);
-
-    new DataView(buf.buffer).setUint32(0, snapshot.tick, true);
-    buf.set(updatesBytes, 4);
-
-    return buf;
-  }
-
-  /**
-   * Decode binary data into a snapshot.
-   */
-  decode(buf: Uint8Array): Snapshot<T> {
-    // Decode tick (first 4 bytes)
-    const tick = new DataView(buf.buffer, buf.byteOffset).getUint32(0, true);
-
-    // Decode updates (remaining bytes)
-    const updatesBytes = buf.subarray(4);
-    const updates = this.updatesCodec.decode(updatesBytes);
-
-    return { tick, updates };
-  }
-}