@actuallab/rpc 12.1.100 → 12.2.21

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Encoder, Decoder } from '@msgpack/msgpack';
 import { EventHandlerSet, PromiseSource, RetryDelayer } from '@actuallab/core';
 
 /** Identifies the type of an RPC call on the wire. */
@@ -30,6 +31,29 @@ declare const ENVELOPE_DELIMITER = "\n";
 declare const ARG_DELIMITER = "\u001F";
 declare const FRAME_DELIMITER = "\n\u001E";
 
+/**
+ * Registry mapping RPC method wire names to/from their 4-byte XXH3 hashes.
+ * Hashes match .NET's RpcMethodRef.ComputeHashCode.
+ * Hashes are computed lazily on first access and cached.
+ */
+declare class RpcMethodRegistry {
+    private _nameToHash;
+    private _hashToName;
+    /** Register a method name and compute its hash. */
+    register(methodName: string): void;
+    /** Register all wire method names from a service definition. */
+    registerService(serviceName: string, methods: ReadonlyMap<string, {
+        name: string;
+        wireArgCount: number;
+    }>): void;
+    /** Get the hash for a method name. Computes on demand if not registered. */
+    getHash(methodName: string): number;
+    /** Get the method name for a hash. Returns undefined if not registered. */
+    getName(hash: number): string | undefined;
+    /** Get the hash for a method name, throwing if not registered. */
+    requireHash(methodName: string): number;
+}
+
 /** Serializes an RpcMessage + args into the json5 wire format. */
 declare function serializeMessage(message: RpcMessage, args?: unknown[]): string;
 /** Serializes multiple messages into a single WebSocket frame. */
@@ -41,11 +65,189 @@ declare function deserializeMessage(raw: string): {
     message: RpcMessage;
     args: unknown[];
 };
+declare const defaultBinaryEncoder: Encoder<undefined>;
+declare const defaultBinaryDecoder: Decoder<undefined>;
+/** Exposed so connection code can instantiate a matching Encoder
+ *  with the same initial buffer size without needing to reach into
+ *  this module's private constants. */
+declare function createBinaryEncoder(): Encoder;
+/**
+ * Serializes an RpcMessage + args into V5 binary format (msgpack6np).
+ *
+ * Layout (NO frame-level size prefix; V5 with PersistsMessageSize=false):
+ *   envelope + argData
+ * Envelope:
+ *   [byte 0: (CallTypeId<<5) | HeaderCount] [VarUint relatedId]
+ *   [LVarSpan methodRef] [4-byte LE argLen]
+ * ArgData: concatenated MessagePack-encoded arguments
+ *
+ * Single-allocation build: pre-encodes args with the supplied reusable
+ * `Encoder`, computes the total envelope size, then writes everything
+ * into one `Uint8Array`. Eliminates the previous build's intermediate
+ * `headerParts` number array + four `Uint8Array` concats per call,
+ * which showed up as ~2% self time in the 300-pull profile and
+ * pulled the msgpack `resizeBuffer` + `Encoder` constructor along
+ * with it for another ~6%.
+ *
+ * NOTE: `@msgpack/msgpack` `Encoder.encode()` already returns a fresh
+ * copy of the internal buffer (there's a separate `encodeSharedRef()`
+ * for zero-copy access), so we can push the results straight into
+ * `argBufs` without an extra slice. The benefit of reusing the Encoder
+ * is that its internal write buffer stays at its high-water mark —
+ * once the first ~11 KB frame has grown it to the full size, no
+ * subsequent `resizeBuffer` calls are needed.
+ */
+declare function serializeBinaryMessage(message: RpcMessage, args?: unknown[], encoder?: Encoder): Uint8Array;
+/**
+ * Deserializes a single V5 binary message starting at `offset`.
+ * Returns parsed message, args, and number of bytes consumed.
+ *
+ * Accepts an optional `Decoder` for reuse across calls on the same
+ * connection — avoids constructing a new `@msgpack/msgpack.Decoder`
+ * (and its internal resolver/table state) on every inbound message.
+ */
+declare function deserializeBinaryMessage(data: Uint8Array, offset: number, decoder?: Decoder): {
+    message: RpcMessage;
+    args: unknown[];
+    bytesRead: number;
+};
+/**
+ * Splits a binary WebSocket frame into individual deserialized messages.
+ * V5 envelopes are self-delimiting (header + method + argLen + argData), so
+ * multiple envelopes concatenated in a single WebSocket frame can be decoded
+ * by iterating with the bytesRead returned from deserializeBinaryMessage.
+ *
+ * This must stay symmetric with serializeBinaryFrame() (which concatenates
+ * multiple envelopes). The .NET server batches outbound RPC messages into a
+ * single WebSocket frame via WebSocketChannel/WriteDelayer, so any assumption
+ * that a frame is a single envelope silently drops every trailing message.
+ *
+ * Accepts an optional `Decoder` for reuse across calls on the same
+ * connection — forwarded to `deserializeBinaryMessage`.
+ */
+declare function splitBinaryFrame(frame: Uint8Array, decoder?: Decoder): Array<{
+    message: RpcMessage;
+    args: unknown[];
+}>;
+/**
+ * Serializes multiple binary messages into a single WebSocket frame.
+ * Simply concatenates the already size-prefixed messages.
+ */
+declare function serializeBinaryFrame(messages: Uint8Array[]): Uint8Array;
+
+/**
+ * Serializes an RpcMessage + args into V5Compact binary format.
+ * Same as V5 except the method is encoded as a 4-byte LE hash
+ * instead of an LVar-prefixed UTF-8 string.
+ *
+ * Layout:
+ *   [byte 0: (CallTypeId<<5) | HeaderCount] [VarUint relatedId]
+ *   [4-byte LE methodHash] [4-byte LE argLen]
+ *   [argData]
+ */
+declare function serializeCompactBinaryMessage(message: RpcMessage, args?: unknown[], registry?: RpcMethodRegistry, encoder?: Encoder): Uint8Array;
+/**
+ * Deserializes a single V5Compact binary message starting at `offset`.
+ * Reads a 4-byte LE method hash and resolves it via the registry.
+ */
+declare function deserializeCompactBinaryMessage(data: Uint8Array, offset: number, registry?: RpcMethodRegistry, decoder?: Decoder): {
+    message: RpcMessage;
+    args: unknown[];
+    bytesRead: number;
+};
+/**
+ * Splits a compact binary frame into individual deserialized messages.
+ */
+declare function splitCompactBinaryFrame(frame: Uint8Array, registry?: RpcMethodRegistry, decoder?: Decoder): Array<{
+    message: RpcMessage;
+    args: unknown[];
+}>;
+
+/** Parsed inbound message — result of deserialization. */
+interface RpcDeserializedMessage {
+    message: RpcMessage;
+    args: unknown[];
+}
+/** Wire data produced by serialization — either text or binary. */
+type RpcWireData = string | Uint8Array;
+/**
+ * Base class for RPC serialization formats.
+ * Instances are immutable singletons — one per format key.
+ * State (like method registries) is passed via parameters.
+ */
+declare abstract class RpcSerializationFormat {
+    abstract readonly key: string;
+    abstract readonly isBinary: boolean;
+    /** Whether this format uses compact method hashes (needs RpcMethodRegistry). */
+    abstract readonly isCompact: boolean;
+    /** Serialize an outbound message. */
+    abstract serializeMessage(message: RpcMessage, args?: unknown[], encoder?: Encoder, registry?: RpcMethodRegistry): RpcWireData;
+    /** Deserialize a single text message (only called for text formats). */
+    abstract deserializeTextMessage(raw: string): RpcDeserializedMessage;
+    /** Split + deserialize a binary frame (only called for binary formats). */
+    abstract splitBinaryFrame(frame: Uint8Array, decoder?: Decoder, registry?: RpcMethodRegistry): RpcDeserializedMessage[];
+    /** Concatenate multiple serialized binary messages into one frame. */
+    abstract serializeBinaryFrame(messages: Uint8Array[]): Uint8Array;
+    /** Create a reusable binary encoder for this format. Returns undefined for text formats. */
+    createEncoder(): Encoder | undefined;
+    /** Create a reusable binary decoder for this format. Returns undefined for text formats. */
+    createDecoder(): Decoder | undefined;
+    private static _all;
+    static register(format: RpcSerializationFormat): void;
+    static get(key: string): RpcSerializationFormat;
+    static tryGet(key: string): RpcSerializationFormat | undefined;
+}
+/**
+ * JSON text format — "json5np" (System.Text.Json, no polymorphism).
+ */
+declare class RpcJsonSerializationFormat extends RpcSerializationFormat {
+    readonly key: string;
+    readonly isBinary = false;
+    readonly isCompact = false;
+    constructor(key: string);
+    serializeMessage(message: RpcMessage, args?: unknown[]): string;
+    deserializeTextMessage(raw: string): RpcDeserializedMessage;
+    splitBinaryFrame(): RpcDeserializedMessage[];
+    serializeBinaryFrame(): Uint8Array;
+}
+/**
+ * MessagePack binary format — "msgpack6" / "mempack6" (V5 wire format).
+ */
+declare class RpcMessagePackSerializationFormat extends RpcSerializationFormat {
+    readonly key: string;
+    readonly isBinary = true;
+    readonly isCompact = false;
+    constructor(key: string);
+    serializeMessage(message: RpcMessage, args?: unknown[], encoder?: Encoder): Uint8Array;
+    deserializeTextMessage(raw: string): RpcDeserializedMessage;
+    splitBinaryFrame(frame: Uint8Array, decoder?: Decoder): RpcDeserializedMessage[];
+    serializeBinaryFrame(messages: Uint8Array[]): Uint8Array;
+    createEncoder(): Encoder;
+    createDecoder(): Decoder;
+}
+/**
+ * MessagePack compact binary format — "msgpack6c" / "mempack6c" (V5Compact).
+ * Uses 4-byte method hash instead of full method name.
+ * Registry is passed via parameters — format instance is immutable.
+ */
+declare class RpcMessagePackCompactSerializationFormat extends RpcSerializationFormat {
+    readonly key: string;
+    readonly isBinary = true;
+    readonly isCompact = true;
+    constructor(key: string);
+    serializeMessage(message: RpcMessage, args?: unknown[], encoder?: Encoder, registry?: RpcMethodRegistry): Uint8Array;
+    deserializeTextMessage(raw: string): RpcDeserializedMessage;
+    splitBinaryFrame(frame: Uint8Array, decoder?: Decoder, registry?: RpcMethodRegistry): RpcDeserializedMessage[];
+    serializeBinaryFrame(messages: Uint8Array[]): Uint8Array;
+    createEncoder(): Encoder;
+    createDecoder(): Decoder;
+}
 
 /** Abstract WebSocket interface — works with both browser WebSocket and Node.js ws. */
 interface WebSocketLike {
     readonly readyState: number;
-    send(data: string): void;
+    binaryType?: string;
+    send(data: string | ArrayBufferLike | Uint8Array | ArrayBufferView): void;
     close(code?: number, reason?: string): void;
     onopen: ((ev: unknown) => void) | null;
     onmessage: ((ev: {
@@ -63,35 +265,72 @@ declare const WebSocketState: {
     readonly CLOSING: 2;
     readonly CLOSED: 3;
 };
+/** Received message — either text (string) or binary (already parsed). */
+type RpcReceivedMessage = {
+    kind: 'text';
+    raw: string;
+} | {
+    kind: 'binary';
+    message: RpcMessage;
+    args: unknown[];
+};
 /** Abstract RPC connection — transport-agnostic interface for sending/receiving messages. */
 interface RpcConnection {
     readonly isOpen: boolean;
+    readonly binaryMode: boolean;
     readonly whenConnected: Promise<void>;
-    readonly messageReceived: EventHandlerSet<string>;
+    readonly messageReceived: EventHandlerSet<RpcReceivedMessage>;
     readonly closed: EventHandlerSet<{
         code: number;
         reason: string;
     }>;
+    /** Optional reusable msgpack encoder for outbound binary messages.
+     *  Callers passing this to `serializeBinaryMessage` skip the per-call
+     *  Encoder construction + resizeBuffer growth. Implementations that
+     *  don't support binary serialization can leave it undefined. */
+    readonly encoder?: Encoder;
     send(serializedMessage: string): void;
+    sendBinary(data: Uint8Array): void;
     close(code?: number, reason?: string): void;
 }
-/** WebSocket-based RpcConnection — handles frame splitting and message queueing. */
+/** WebSocket-based RpcConnection — handles frame splitting, binary/text modes, and message queueing. */
 declare class RpcWebSocketConnection implements RpcConnection {
     private _ws;
     private _sendBuffer;
     private _connected;
-    readonly messageReceived: EventHandlerSet<string>;
+    /** Per-connection msgpack encoder — reused across outbound messages to
+     *  amortise construction cost and to keep the internal write buffer at
+     *  its largest observed size (avoids repeated `resizeBuffer` growth on
+     *  large video frames). See serializeBinaryMessage() for details. */
+    private _encoder;
+    /** Per-connection msgpack decoder — reused across inbound messages
+     *  rather than reconstructing one for every `decodeMulti` call. */
+    private _decoder;
+    /** Exposed for callers who need to encode outbound binary messages
+     *  through this connection (e.g. `serializeBinaryMessage`). Safe to
+     *  pass to synchronous encode calls on the same event-loop turn. */
+    get encoder(): Encoder;
+    get decoder(): Decoder;
+    private _format;
+    private _methodRegistry;
+    readonly binaryMode: boolean;
+    readonly messageReceived: EventHandlerSet<RpcReceivedMessage>;
     readonly closed: EventHandlerSet<{
         code: number;
         reason: string;
     }>;
     readonly error: EventHandlerSet<unknown>;
-    constructor(ws: WebSocketLike);
+    constructor(ws: WebSocketLike, binaryMode?: boolean, format?: RpcSerializationFormat, methodRegistry?: RpcMethodRegistry);
     get isOpen(): boolean;
     get whenConnected(): Promise<void>;
     send(serializedMessage: string): void;
-    sendBatch(messages: string[]): void;
+    sendBinary(data: Uint8Array): void;
+    sendTextBatch(messages: string[]): void;
+    sendBinaryBatch(messages: Uint8Array[]): void;
+    /** Split a binary frame using the format (compact-aware) or default splitter. */
+    private _splitBinary;
     close(code?: number, reason?: string): void;
+    private _sendRaw;
     private _flush;
 }
 
@@ -99,7 +338,8 @@ declare class RpcWebSocketConnection implements RpcConnection {
 declare class RpcMessageChannelConnection implements RpcConnection {
     private _port;
     private _open;
-    readonly messageReceived: EventHandlerSet<string>;
+    readonly binaryMode = false;
+    readonly messageReceived: EventHandlerSet<RpcReceivedMessage>;
     readonly closed: EventHandlerSet<{
         code: number;
         reason: string;
@@ -108,10 +348,14 @@ declare class RpcMessageChannelConnection implements RpcConnection {
     constructor(port: MessagePort);
     get isOpen(): boolean;
     send(serializedMessage: string): void;
+    sendBinary(data: Uint8Array): void;
     close(code?: number, reason?: string): void;
 }
 /** Creates a pair of connected RpcMessageChannelConnections for testing. */
-declare function createMessageChannelPair(): [RpcMessageChannelConnection, RpcMessageChannelConnection];
+declare function createMessageChannelPair(): [
+    RpcMessageChannelConnection,
+    RpcMessageChannelConnection
+];
 
 /** Describes a single method on an RPC service. */
 interface RpcMethodDef {
@@ -153,8 +397,8 @@ declare class RpcOutboundCall {
     /** Whether to remove this call from the tracker on $sys.Ok. Default: true.
      *  Subclasses (e.g. compute calls) override to false to stay in tracker for invalidation. */
     readonly removeOnOk: boolean;
-    /** The serialized wire message — stored for re-sending on reconnect. */
-    serializedMessage: string;
+    /** The serialized wire data — stored for re-sending on reconnect. */
+    serializedWireData: string | Uint8Array;
     constructor(callId: number, method: string);
     /** Called when the connection is lost. Subclasses can override to resolve invalidation promises. */
     onDisconnect(): void;
@@ -213,20 +457,49 @@ declare class RpcServiceHost {
     getMethodDef(wireMethod: string): RpcMethodDef | undefined;
 }
 
-/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
+/**
+ * Sends system RPC messages — like .NET's RpcSystemCallSender.
+ *
+ * Hot-path allocation notes: `item`, `batch`, `ack`, and `end` are called
+ * once per stream frame (or once per ack window). Naively building a fresh
+ * `{ Method, RelatedId }` envelope object plus a fresh two-element arg array
+ * on every call showed up as ~2-4% self time + non-trivial GC pressure in
+ * the 300-pull video-load-test profile.
+ *
+ * The sender itself is a per-Hub singleton and `_send`/format.serializeMessage
+ * are fully synchronous (no awaits, no re-entrancy on a single-threaded event
+ * loop), so we reuse a small pool of preallocated envelope + arg-array slots
+ * per hot method. Mutate fields just before the send call; the encoder reads
+ * them synchronously and produces a detached copy, after which the slot is
+ * free to be mutated again on the next call.
+ */
 declare class RpcSystemCallSender {
-    handshake(conn: RpcConnection, peerId: string, hubId: string, index: number): void;
-    ok(conn: RpcConnection, relatedId: number, result: unknown): void;
-    error(conn: RpcConnection, relatedId: number, error: unknown): void;
-    cancel(conn: RpcConnection, relatedId: number): void;
-    keepAlive(conn: RpcConnection, activeCallIds: number[]): void;
-    item(conn: RpcConnection, localId: number, index: number, item: unknown): void;
-    batch(conn: RpcConnection, localId: number, index: number, items: unknown[]): void;
-    end(conn: RpcConnection, localId: number, index: number, error?: {
+    private readonly _itemEnv;
+    private readonly _batchEnv;
+    private readonly _endEnv;
+    private readonly _ackEnv;
+    private readonly _ackEndEnv;
+    private readonly _itemArgs;
+    private readonly _batchArgs;
+    private readonly _endArgs;
+    private readonly _ackArgs;
+    private readonly _ackEndArgs;
+    private static readonly NO_ERROR;
+    registry?: RpcMethodRegistry;
+    private _send;
+    handshake(conn: RpcConnection, format: RpcSerializationFormat, peerId: string, hubId: string, index: number): void;
+    ok(conn: RpcConnection, format: RpcSerializationFormat, relatedId: number, result: unknown): void;
+    error(conn: RpcConnection, format: RpcSerializationFormat, relatedId: number, error: unknown): void;
+    cancel(conn: RpcConnection, format: RpcSerializationFormat, relatedId: number): void;
+    keepAlive(conn: RpcConnection, format: RpcSerializationFormat, activeCallIds: number[]): void;
+    item(conn: RpcConnection, format: RpcSerializationFormat, localId: number, index: number, item: unknown): void;
+    batch(conn: RpcConnection, format: RpcSerializationFormat, localId: number, index: number, items: unknown[]): void;
+    end(conn: RpcConnection, format: RpcSerializationFormat, localId: number, index: number, error?: {
+        TypeRef: string;
         Message: string;
-    } | null): void;
-    ack(conn: RpcConnection, localId: number, nextIndex: number, hostId: string): void;
-    ackEnd(conn: RpcConnection, localId: number, hostId: string): void;
+    }): void;
+    ack(conn: RpcConnection, format: RpcSerializationFormat, localId: number, nextIndex: number, hostId: string): void;
+    ackEnd(conn: RpcConnection, format: RpcSerializationFormat, localId: number, hostId: string): void;
 }
 
 /** Central RPC coordinator — manages peers, services, and configuration. */
@@ -236,6 +509,9 @@ declare class RpcHub {
     readonly serviceHost: RpcServiceHost;
     readonly systemCallSender: RpcSystemCallSender;
     systemCallHandler: RpcSystemCallHandler;
+    /** Method registry for compact format hash ↔ name resolution.
+     *  Created lazily, populated by addService/addClient. */
+    readonly registry: RpcMethodRegistry;
     constructor(hubId?: string);
     addPeer(peer: RpcPeer): void;
     removePeer(ref: string): void;
@@ -281,6 +557,7 @@ declare class RpcRemoteObjectTracker {
     private _objects;
     register(obj: IRpcObject): void;
     get(localId: number): IRpcObject | undefined;
+    keys(): IterableIterator<number>;
     unregister(obj: IRpcObject): void;
     disconnectAll(): void;
     reconnectAll(): void;
@@ -292,6 +569,7 @@ declare class RpcSharedObjectTracker {
     nextId(): number;
     register(obj: IRpcObject): void;
     get(localId: number): IRpcObject | undefined;
+    keys(): IterableIterator<number>;
     unregister(obj: IRpcObject): void;
     disconnectAll(): void;
 }
@@ -302,6 +580,8 @@ declare class RpcSharedObjectTracker {
  * so "json5np" (System.Text.Json, no polymorphism) is the correct match.
  */
 declare const DEFAULT_SERIALIZATION_FORMAT = "json5np";
+/** WebSocket close code sent by the server when the client's serialization format is unsupported. */
+declare const RPC_CLOSE_CODE_UNSUPPORTED_FORMAT = 4001;
 /** Builds the WebSocket connection URL for an RpcClientPeer. */
 type RpcConnectionUrlResolver = (peer: RpcClientPeer) => string;
 /** Default connection URL provider — appends `clientId` and `f` query parameters. */
@@ -346,11 +626,15 @@ declare abstract class RpcPeer {
     get connection(): RpcConnection | undefined;
     get isConnected(): boolean;
     protected setupConnection(conn: RpcConnection): void;
+    /** The serialization format used by this peer. Override in subclasses. */
+    get format(): RpcSerializationFormat;
     call(method: string, args?: unknown[], options?: RpcCallOptions): RpcOutboundCall;
     callNoWait(method: string, args?: unknown[]): void;
     close(): void;
     /** Send any messages buffered while disconnected. Call after connection + handshake are ready. */
     protected _flushPendingSends(): void;
+    /** Send pre-serialized wire data through the current connection. */
+    protected _sendWireData(data: string | Uint8Array): void;
     /** Override in subclasses to handle the remote peer's handshake response. */
     protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
     private _handleMessage;
@@ -384,11 +668,17 @@ declare class RpcClientPeer extends RpcPeer {
     /** Builds the WebSocket URL for this peer. Replace to customize URL construction. */
     connectionUrlResolver: RpcConnectionUrlResolver;
     readonly peerChanged: EventHandlerSet<void>;
+    /** Fired when the server rejects the connection due to an unsupported serialization format (close code 4010). */
+    readonly unsupportedFormat: EventHandlerSet<{
+        reason: string;
+    }>;
     readonly reconnectDelayer: RpcClientPeerReconnectDelayer;
     readonly reconnectsAtChanged: EventHandlerSet<void>;
     get reconnectsAt(): number;
     private _setReconnectsAt;
+    private _format;
     constructor(hub: RpcHub, url: string, serializationFormat?: string);
+    get format(): RpcSerializationFormat;
     get connectionKind(): RpcPeerConnectionKind;
     /** One-shot connection for tests — no reconnection loop, no handshake. */
     connectWith(conn: RpcConnection): void;
@@ -425,6 +715,7 @@ interface RpcStreamRef {
     readonly ackPeriod: number;
     readonly ackAdvance: number;
     readonly allowReconnect: boolean;
+    readonly isRealTime: boolean;
 }
 /**
  * Parses a stream reference string of the form "{hostId},{localId},{ackPeriod},{ackAdvance}".
@@ -471,6 +762,7 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
     dispose(): void;
     private _notifyConsumer;
     private _maybeSendAck;
+    private static readonly _emptyGuid;
     private _sendAck;
     private _sendAckEnd;
 }
@@ -498,17 +790,21 @@ declare class RpcStreamSender<T> implements IRpcObject {
     readonly id: RpcObjectId;
     readonly kind: 0;
     readonly allowReconnect: boolean;
+    readonly isRealTime: boolean;
+    readonly canSkipTo: (item: T) => boolean;
     readonly peer: RpcPeer;
     readonly ackPeriod: number;
     readonly ackAdvance: number;
     private _nextIndex;
     private _ended;
     private _started;
-    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean);
+    private _lastAckedIndex;
+    private _ackWaiting;
+    constructor(peer: RpcPeer, ackPeriod?: number, ackAdvance?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean);
     /** Returns the stream reference string for the $sys.Ok response. */
     toRef(): string;
     /** Called by system call handler when $sys.Ack is received from the client. */
-    onAck(_nextIndex: number, _hostId: string): void;
+    onAck(nextIndex: number, _hostId: string): void;
     /** Called by system call handler when $sys.AckEnd is received from the client. */
     onAckEnd(_hostId: string): void;
     /** Send a single item to the client. */
@@ -520,8 +816,15 @@ declare class RpcStreamSender<T> implements IRpcObject {
     /**
      * Consume an AsyncIterable and send all items to the client.
      * Waits for the client's initial Ack before starting to pump items.
+     *
+     * When `isRealTime` is true, applies flow control based on `ackAdvance`:
+     * if the sender is `ackAdvance` items ahead of the last ACK, it enters
+     * skip mode — draining the source and discarding items until it finds
+     * one where `canSkipTo` returns true.
      */
     writeFrom(source: AsyncIterable<T>): Promise<void>;
+    /** Wait until _nextIndex < _lastAckedIndex + ackAdvance. */
+    private _waitForAckBudget;
     reconnect(): void;
     disconnect(): void;
 }
@@ -590,4 +893,24 @@ declare class RpcPeerStateMonitor {
     private _scheduleRecompute;
 }
 
-export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, type RpcMessage, RpcMessageChannelConnection, type RpcMethodDef, type RpcMethodDefInput, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcRemoteObjectTracker, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };
+/**
+ * Compute XXH3-64 hash of a byte array. Returns a BigInt (unsigned 64-bit).
+ * Pure TypeScript, synchronous, supports any input length.
+ */
+declare function xxh3_64(input: Uint8Array, seed?: bigint): bigint;
+/**
+ * Compute XXH3-64 hash of a UTF-8 string. Returns a BigInt (unsigned 64-bit).
+ */
+declare function xxh3_64str(input: string, seed?: bigint): bigint;
+/**
+ * Compute the RPC method hash matching .NET's RpcMethodRef.ComputeHashCode.
+ * Returns a 32-bit signed integer (lower 32 bits of XXH3-64 of [prefix + utf8Name]).
+ *
+ * The prefix is uint32 LE of (67211 * utf8Name.length), which ensures methods
+ * with different name lengths but similar text produce different hashes.
+ *
+ * Computed on demand — caller should cache the result per method name.
+ */
+declare function computeMethodHash(methodName: string): number;
+
+export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, type IRpcObject, type MethodMeta, RPC_CLOSE_CODE_UNSUPPORTED_FORMAT, type RemoteHandshake, type RpcCallOptions, RpcCallTypeId, RpcClientPeer, RpcClientPeerReconnectDelayer, type RpcConnection, type RpcConnectionUrlResolver, type RpcDeserializedMessage, type RpcDispatchContext, RpcHub, RpcInboundCall, RpcInboundCallTracker, RpcJsonSerializationFormat, type RpcMessage, RpcMessageChannelConnection, RpcMessagePackCompactSerializationFormat, RpcMessagePackSerializationFormat, type RpcMethodDef, type RpcMethodDefInput, RpcMethodRegistry, type RpcObjectId, RpcObjectKind, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, type RpcReceivedMessage, RpcRemoteObjectTracker, RpcSerializationFormat, RpcServerPeer, type RpcServiceDef, RpcServiceHost, type RpcServiceImpl, RpcSharedObjectTracker, RpcStream, type RpcStreamRef, RpcStreamSender, RpcSystemCallHandler, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type RpcWireData, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, computeMethodHash, createBinaryEncoder, createMessageChannelPair, createRpcClient, defaultBinaryDecoder, defaultBinaryEncoder, defaultConnectionUrlResolver, defineRpcService, deserializeBinaryMessage, deserializeCompactBinaryMessage, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, isConnected, likelyConnected, parseStreamRef, resolveStreamRefs, rpcMethod, rpcService, serializeBinaryFrame, serializeBinaryMessage, serializeCompactBinaryMessage, serializeFrame, serializeMessage, splitBinaryFrame, splitCompactBinaryFrame, splitFrame, wireMethodName, xxh3_64, xxh3_64str };