murow 0.0.2 → 0.0.3

package/dist/net/client.d.ts

@@ -2,6 +2,8 @@ import type { IntentRegistry } from "../protocol/intent/intent-registry";
 import type { SnapshotRegistry } from "../protocol/snapshot/snapshot-registry";
 import type { Snapshot } from "../protocol/snapshot/snapshot";
 import type { Intent } from "../protocol/intent/intent";
+import type { RpcRegistry } from "../protocol/rpc/rpc-registry";
+import type { DefinedRpc } from "../protocol/rpc/rpc";
 import { type TransportAdapter, type NetworkConfig } from "./types";
 /**
  * Configuration for ClientNetwork
@@ -13,6 +15,8 @@ export interface ClientNetworkConfig<TSnapshots> {
     intentRegistry: IntentRegistry;
     /** Snapshot registry for decoding server snapshots */
     snapshotRegistry: SnapshotRegistry<TSnapshots>;
+    /** RPC registry for bidirectional remote procedure calls (optional) */
+    rpcRegistry?: RpcRegistry;
     /** Network configuration */
     config?: NetworkConfig;
 }
@@ -42,9 +46,12 @@ export declare class ClientNetwork<TSnapshots = unknown> {
     private transport;
     private intentRegistry;
     private snapshotRegistry;
+    private rpcRegistry?;
     private config;
     /** Snapshot type handlers: type -> handler[] (supports multiple handlers) */
     private snapshotHandlers;
+    /** RPC method handlers: method -> handler[] (supports multiple handlers) */
+    private rpcHandlers;
     /** Connection lifecycle handlers */
     private connectHandlers;
     private disconnectHandlers;
@@ -98,6 +105,46 @@ export declare class ClientNetwork<TSnapshots = unknown> {
      * @returns Unsubscribe function to remove this handler
      */
     onSnapshot<T extends Partial<TSnapshots>>(type: string, handler: (snapshot: Snapshot<T>) => void): () => void;
+    /**
+     * Send an RPC to the server (type-safe)
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     *
+     * @example
+     * ```ts
+     * const BuyItem = defineRpc({
+     *   method: 'buyItem',
+     *   schema: { itemId: BinaryCodec.string(32) }
+     * });
+     *
+     * client.sendRpc(BuyItem, { itemId: 'long_sword' });
+     * ```
+     */
+    sendRpc<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, data: TSchema): void;
+    /**
+     * Register a handler for incoming RPCs from the server (type-safe)
+     * Supports multiple handlers per RPC method
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param handler Callback function to handle the RPC
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * client.onRpc(MatchCountdown, (rpc) => {
+     *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
+     * });
+     * ```
+     */
+    onRpc<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, handler: (data: TSchema) => void): () => void;
     /**
      * Register a handler for connection events
      */
@@ -138,6 +185,10 @@ export declare class ClientNetwork<TSnapshots = unknown> {
      * Decode and handle a snapshot from server
      */
     private handleSnapshot;
+    /**
+     * Handle incoming RPC message from server
+     */
+    private handleRpc;
     /**
      * Handle disconnection from server
      */

package/dist/net/client.js

@@ -25,6 +25,8 @@ export class ClientNetwork {
     constructor(config) {
         /** Snapshot type handlers: type -> handler[] (supports multiple handlers) */
         this.snapshotHandlers = new Map();
+        /** RPC method handlers: method -> handler[] (supports multiple handlers) */
+        this.rpcHandlers = new Map();
         /** Connection lifecycle handlers */
         this.connectHandlers = [];
         this.disconnectHandlers = [];
@@ -43,6 +45,7 @@ export class ClientNetwork {
         this.transport = config.transport;
         this.intentRegistry = config.intentRegistry;
         this.snapshotRegistry = config.snapshotRegistry;
+        this.rpcRegistry = config.rpcRegistry;
         this.config = {
             maxMessageSize: config.config?.maxMessageSize ?? 65536,
             debug: config.config?.debug ?? false,
@@ -149,6 +152,93 @@ export class ClientNetwork {
             }
         };
     }
+    /**
+     * Send an RPC to the server (type-safe)
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     *
+     * @example
+     * ```ts
+     * const BuyItem = defineRpc({
+     *   method: 'buyItem',
+     *   schema: { itemId: BinaryCodec.string(32) }
+     * });
+     *
+     * client.sendRpc(BuyItem, { itemId: 'long_sword' });
+     * ```
+     */
+    sendRpc(rpc, data) {
+        if (!this.rpcRegistry) {
+            throw new Error('RpcRegistry not configured. Pass rpcRegistry to ClientNetworkConfig.');
+        }
+        if (!this.connected) {
+            this.log("Cannot send RPC: not connected");
+            return;
+        }
+        // Client-side rate limiting
+        if (!this.checkRateLimit()) {
+            this.log("Rate limit exceeded, dropping RPC");
+            return;
+        }
+        try {
+            // Encode RPC
+            const rpcData = this.rpcRegistry.encode(rpc, data);
+            // Wrap with message type header
+            const message = new Uint8Array(1 + rpcData.byteLength);
+            message[0] = MessageType.CUSTOM;
+            message.set(rpcData, 1);
+            // Send to server
+            this.transport.send(message);
+            this.log(`Sent RPC (method: ${rpc.method})`);
+        }
+        catch (error) {
+            this.log(`Failed to send RPC: ${error}`);
+        }
+    }
+    /**
+     * Register a handler for incoming RPCs from the server (type-safe)
+     * Supports multiple handlers per RPC method
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param handler Callback function to handle the RPC
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * client.onRpc(MatchCountdown, (rpc) => {
+     *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
+     * });
+     * ```
+     */
+    onRpc(rpc, handler) {
+        if (!this.rpcRegistry) {
+            throw new Error('RpcRegistry not configured. Pass rpcRegistry to ClientNetworkConfig.');
+        }
+        let handlers = this.rpcHandlers.get(rpc.method);
+        if (!handlers) {
+            handlers = [];
+            this.rpcHandlers.set(rpc.method, handlers);
+        }
+        handlers.push(handler);
+        // Return unsubscribe function
+        return () => {
+            const handlers = this.rpcHandlers.get(rpc.method);
+            if (handlers) {
+                const index = handlers.indexOf(handler);
+                if (index > -1) {
+                    handlers.splice(index, 1);
+                }
+            }
+        };
+    }
     /**
      * Register a handler for connection events
      */
@@ -278,8 +368,7 @@ export class ClientNetwork {
                 this.log("Received heartbeat from server");
                 break;
             case MessageType.CUSTOM:
-                // Could add custom message handlers here
-                this.log("Received custom message from server");
+                this.handleRpc(payload);
                 break;
             default:
                 this.log(`Unknown message type: ${messageType}`);
@@ -313,6 +402,38 @@ export class ClientNetwork {
             this.log(`Failed to decode snapshot: ${error}`);
         }
     }
+    /**
+     * Handle incoming RPC message from server
+     */
+    handleRpc(data) {
+        if (!this.rpcRegistry) {
+            this.log("Received RPC but RpcRegistry not configured");
+            return;
+        }
+        try {
+            // Decode using RPC registry (returns { method, data })
+            const decoded = this.rpcRegistry.decode(data);
+            this.log(`Received RPC (method: ${decoded.method})`);
+            // Call all method-specific handlers if registered
+            const handlers = this.rpcHandlers.get(decoded.method);
+            if (handlers && handlers.length > 0) {
+                for (const handler of handlers) {
+                    try {
+                        handler(decoded.data);
+                    }
+                    catch (error) {
+                        this.log(`Error in RPC handler: ${error}`);
+                    }
+                }
+            }
+            else {
+                this.log(`No handler registered for RPC method: ${decoded.method}`);
+            }
+        }
+        catch (error) {
+            this.log(`Failed to decode RPC: ${error}`);
+        }
+    }
     /**
      * Handle disconnection from server
      */

package/dist/net/server.d.ts

@@ -2,6 +2,8 @@ import type { IntentRegistry } from "../protocol/intent/intent-registry";
 import type { SnapshotRegistry } from "../protocol/snapshot/snapshot-registry";
 import type { Snapshot } from "../protocol/snapshot/snapshot";
 import type { Intent } from "../protocol/intent/intent";
+import type { RpcRegistry } from "../protocol/rpc/rpc-registry";
+import type { DefinedRpc } from "../protocol/rpc/rpc";
 import { MessagePriority, type PeerState, type ServerTransportAdapter, type TransportAdapter, type NetworkConfig } from "./types";
 import { DefinedIntent } from "../protocol";
 /**
@@ -14,6 +16,8 @@ export interface ServerNetworkConfig<TPeer extends TransportAdapter, TSnapshots>
     intentRegistry: IntentRegistry;
     /** Factory to create per-peer snapshot registries */
     createPeerSnapshotRegistry: () => SnapshotRegistry<TSnapshots>;
+    /** RPC registry for bidirectional remote procedure calls (optional) */
+    rpcRegistry?: RpcRegistry;
     /** Network configuration */
     config?: NetworkConfig;
 }
@@ -70,6 +74,7 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
     private transport;
     private intentRegistry;
     private createPeerSnapshotRegistry;
+    private rpcRegistry?;
     private config;
     /** Per-peer state tracking */
     private peers;
@@ -83,6 +88,8 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
     private intentHandlers;
     /** Global intent handler called for ALL intents before specific handlers */
     private anyIntentHandlers;
+    /** RPC method handlers: method -> handler[] (supports multiple handlers) */
+    private rpcHandlers;
     /** Connection lifecycle handlers */
     private connectionHandlers;
     private disconnectionHandlers;
@@ -133,6 +140,62 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
      * Register a handler for disconnections
      */
     onDisconnection(handler: (peerId: string) => void): void;
+    /**
+     * Send an RPC to a specific peer (type-safe)
+     *
+     * @template TSchema The RPC data type
+     * @param peerId The peer to send to
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     * @param priority Message priority (default: NORMAL)
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * server.sendRpc(peerId, MatchCountdown, { secondsRemaining: 10 });
+     * ```
+     */
+    sendRpc<TSchema extends Record<string, any>>(peerId: string, rpc: DefinedRpc<TSchema>, data: TSchema, priority?: MessagePriority): void;
+    /**
+     * Send an RPC to all connected peers (broadcast)
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     * @param priority Message priority (default: NORMAL)
+     *
+     * @example
+     * ```ts
+     * server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 3 });
+     * ```
+     */
+    sendRpcBroadcast<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, data: TSchema, priority?: MessagePriority): void;
+    /**
+     * Register a handler for incoming RPCs from clients (type-safe)
+     * Supports multiple handlers per RPC method
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param handler Callback function to handle the RPC
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```ts
+     * const BuyItem = defineRpc({
+     *   method: 'buyItem',
+     *   schema: { itemId: BinaryCodec.string(32) }
+     * });
+     *
+     * server.onRpc(BuyItem, (peerId, rpc) => {
+     *   console.log(`${peerId} wants to buy ${rpc.itemId}`);
+     * });
+     * ```
+     */
+    onRpc<TSchema extends Record<string, any>>(rpc: DefinedRpc<TSchema>, handler: (peerId: string, data: TSchema) => void): () => void;
     /**
      * Send a snapshot to a specific peer using their dedicated snapshot registry (type-safe)
      * @template T The specific snapshot update type
@@ -297,6 +360,10 @@ export declare class ServerNetwork<TPeer extends TransportAdapter = TransportAda
      * Decode and handle an intent from a peer
      */
     private handleIntent;
+    /**
+     * Handle incoming RPC message from a peer
+     */
+    private handleRpc;
     /**
      * Check rate limit for a peer
      * Returns true if message should be processed, false if rate limit exceeded

package/dist/net/server.js

@@ -63,6 +63,8 @@ export class ServerNetwork {
         this.intentHandlers = new Map();
         /** Global intent handler called for ALL intents before specific handlers */
         this.anyIntentHandlers = [];
+        /** RPC method handlers: method -> handler[] (supports multiple handlers) */
+        this.rpcHandlers = new Map();
         /** Connection lifecycle handlers */
         this.connectionHandlers = [];
         this.disconnectionHandlers = [];
@@ -73,6 +75,7 @@ export class ServerNetwork {
         this.transport = config.transport;
         this.intentRegistry = config.intentRegistry;
         this.createPeerSnapshotRegistry = config.createPeerSnapshotRegistry;
+        this.rpcRegistry = config.rpcRegistry;
         this.config = {
             maxMessageSize: config.config?.maxMessageSize ?? 65536,
             debug: config.config?.debug ?? false,
@@ -173,6 +176,129 @@ export class ServerNetwork {
     onDisconnection(handler) {
         this.disconnectionHandlers.push(handler);
     }
+    /**
+     * Send an RPC to a specific peer (type-safe)
+     *
+     * @template TSchema The RPC data type
+     * @param peerId The peer to send to
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     * @param priority Message priority (default: NORMAL)
+     *
+     * @example
+     * ```ts
+     * const MatchCountdown = defineRpc({
+     *   method: 'matchCountdown',
+     *   schema: { secondsRemaining: BinaryCodec.u8 }
+     * });
+     *
+     * server.sendRpc(peerId, MatchCountdown, { secondsRemaining: 10 });
+     * ```
+     */
+    sendRpc(peerId, rpc, data, priority = MessagePriority.NORMAL) {
+        if (!this.rpcRegistry) {
+            throw new Error('RpcRegistry not configured. Pass rpcRegistry to ServerNetworkConfig.');
+        }
+        const peer = this.peers.get(peerId);
+        if (!peer) {
+            this.log(`Cannot send RPC to unknown peer: ${peerId}`);
+            return;
+        }
+        try {
+            // Encode RPC
+            const rpcData = this.rpcRegistry.encode(rpc, data);
+            // Wrap with message type header (use pool if enabled)
+            let message;
+            if (this.messagePool) {
+                message = this.messagePool.wrap(MessageType.CUSTOM, rpcData);
+            }
+            else {
+                message = new Uint8Array(1 + rpcData.byteLength);
+                message[0] = MessageType.CUSTOM;
+                message.set(rpcData, 1);
+            }
+            // Check backpressure and queue if necessary
+            if (peer.isBackpressured || peer.sendQueue.length > 0) {
+                // Peer is experiencing backpressure, queue the message with priority
+                this.queueMessage(peer, message, priority);
+                // Release pooled buffer since we copied it in queueMessage
+                if (this.messagePool) {
+                    this.messagePool.release(message);
+                }
+                return;
+            }
+            // Try to send immediately
+            this.sendMessageToPeer(peer, message);
+            // Release pooled buffer after send
+            if (this.messagePool) {
+                this.messagePool.release(message);
+            }
+            this.log(`Sent RPC (method: ${rpc.method}) to peer: ${peerId}`);
+        }
+        catch (error) {
+            this.log(`Failed to send RPC to peer ${peerId}: ${error}`);
+        }
+    }
+    /**
+     * Send an RPC to all connected peers (broadcast)
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param data The RPC data to send
+     * @param priority Message priority (default: NORMAL)
+     *
+     * @example
+     * ```ts
+     * server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 3 });
+     * ```
+     */
+    sendRpcBroadcast(rpc, data, priority = MessagePriority.NORMAL) {
+        for (const peerId of this.getPeerIds()) {
+            this.sendRpc(peerId, rpc, data, priority);
+        }
+    }
+    /**
+     * Register a handler for incoming RPCs from clients (type-safe)
+     * Supports multiple handlers per RPC method
+     *
+     * @template TSchema The RPC data type
+     * @param rpc The RPC definition created by defineRpc()
+     * @param handler Callback function to handle the RPC
+     * @returns Unsubscribe function to remove this handler
+     *
+     * @example
+     * ```ts
+     * const BuyItem = defineRpc({
+     *   method: 'buyItem',
+     *   schema: { itemId: BinaryCodec.string(32) }
+     * });
+     *
+     * server.onRpc(BuyItem, (peerId, rpc) => {
+     *   console.log(`${peerId} wants to buy ${rpc.itemId}`);
+     * });
+     * ```
+     */
+    onRpc(rpc, handler) {
+        if (!this.rpcRegistry) {
+            throw new Error('RpcRegistry not configured. Pass rpcRegistry to ServerNetworkConfig.');
+        }
+        let handlers = this.rpcHandlers.get(rpc.method);
+        if (!handlers) {
+            handlers = [];
+            this.rpcHandlers.set(rpc.method, handlers);
+        }
+        handlers.push(handler);
+        // Return unsubscribe function
+        return () => {
+            const handlers = this.rpcHandlers.get(rpc.method);
+            if (handlers) {
+                const index = handlers.indexOf(handler);
+                if (index > -1) {
+                    handlers.splice(index, 1);
+                }
+            }
+        };
+    }
     /**
      * Send a snapshot to a specific peer using their dedicated snapshot registry (type-safe)
      * @template T The specific snapshot update type
@@ -685,8 +811,7 @@ export class ServerNetwork {
                 this.log(`Received heartbeat from peer ${peerId}`);
                 break;
             case MessageType.CUSTOM:
-                // Could add custom message handlers here
-                this.log(`Received custom message from peer ${peerId}`);
+                this.handleRpc(peerId, payload);
                 break;
             default:
                 this.log(`Unknown message type ${messageType} from peer ${peerId}`);
@@ -737,6 +862,43 @@ export class ServerNetwork {
             this.log(`Failed to decode intent from peer ${peerId}: ${error}`);
         }
     }
+    /**
+     * Handle incoming RPC message from a peer
+     */
+    handleRpc(peerId, data) {
+        if (!this.rpcRegistry) {
+            this.log("Received RPC but RpcRegistry not configured");
+            return;
+        }
+        // Rate limiting check
+        if (!this.checkRateLimit(peerId)) {
+            this.log(`Rate limit exceeded for peer ${peerId}, dropping RPC`);
+            return;
+        }
+        try {
+            // Decode using RPC registry (returns { method, data })
+            const decoded = this.rpcRegistry.decode(data);
+            this.log(`Received RPC (method: ${decoded.method}) from peer ${peerId}`);
+            // Call all method-specific handlers if registered
+            const handlers = this.rpcHandlers.get(decoded.method);
+            if (handlers && handlers.length > 0) {
+                for (const handler of handlers) {
+                    try {
+                        handler(peerId, decoded.data);
+                    }
+                    catch (error) {
+                        this.log(`Error in RPC handler: ${error}`);
+                    }
+                }
+            }
+            else {
+                this.log(`No handler registered for RPC method: ${decoded.method}`);
+            }
+        }
+        catch (error) {
+            this.log(`Failed to decode RPC from peer ${peerId}: ${error}`);
+        }
+    }
     /**
      * Check rate limit for a peer
      * Returns true if message should be processed, false if rate limit exceeded

package/dist/protocol/index.d.ts

@@ -89,3 +89,4 @@
  */
 export * from "./intent";
 export * from "./snapshot";
+export * from "./rpc";

package/dist/protocol/index.js

@@ -89,3 +89,4 @@
  */
 export * from "./intent";
 export * from "./snapshot";
+export * from "./rpc";

package/dist/protocol/rpc/define-rpc.d.ts

@@ -0,0 +1,72 @@
+import type { DefinedRpc } from "./rpc";
+/**
+ * Configuration for defining an RPC type.
+ * @template S The schema type describing the RPC's data fields
+ */
+export interface RpcDefinition<S extends Record<string, any>> {
+    /** Method name for this RPC (must be unique) */
+    method: string;
+    /** Schema describing the RPC's data fields */
+    schema: S;
+}
+/**
+ * Infers the TypeScript type from an RPC schema.
+ * @template S The schema type
+ */
+export type InferRpcType<S extends Record<string, any>> = {
+    [P in keyof S]: S[P] extends {
+        read(dv: DataView, o: number): infer R;
+    } ? R : never;
+};
+/**
+ * Define a type-safe RPC with automatic schema generation.
+ *
+ * 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)
+ *
+ * @template S The schema type
+ * @param definition RPC configuration with method and schema
+ * @returns A DefinedRpc object with method and codec
+ *
+ * @example Server → Client RPC
+ * ```ts
+ * const MatchCountdown = defineRpc({
+ *   method: 'matchCountdown',
+ *   schema: {
+ *     secondsRemaining: BinaryCodec.u8,
+ *   }
+ * });
+ *
+ * // Server sends
+ * server.sendRpcBroadcast(MatchCountdown, { secondsRemaining: 10 });
+ *
+ * // Client receives
+ * client.onRpc(MatchCountdown, (rpc) => {
+ *   console.log(`Match starting in ${rpc.secondsRemaining}s`);
+ * });
+ * ```
+ *
+ * @example Client → Server RPC
+ * ```ts
+ * const BuyItem = defineRpc({
+ *   method: 'buyItem',
+ *   schema: {
+ *     itemId: BinaryCodec.string(32),
+ *   }
+ * });
+ *
+ * // Client sends
+ * client.sendRpc(BuyItem, { itemId: 'long_sword' });
+ *
+ * // Server receives
+ * server.onRpc(BuyItem, (peerId, rpc) => {
+ *   console.log(`${peerId} wants to buy ${rpc.itemId}`);
+ * });
+ * ```
+ */
+export declare function defineRpc<S extends Record<string, any>>(definition: RpcDefinition<S>): DefinedRpc<InferRpcType<S>>;