murow 0.0.2 → 0.0.3

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

@@ -0,0 +1,168 @@
+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

@@ -0,0 +1,156 @@
+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);
+	}
+}

package/src/protocol/rpc/rpc.ts

@@ -0,0 +1,37 @@
+/**
+ * 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
+}