@actuallab/rpc 12.1.62

package/dist/index.d.cts

@@ -0,0 +1,440 @@
+import { EventHandlerSet, PromiseSource, RetryDelayer } from '@actuallab/core';
+
+/** Identifies the type of an RPC call on the wire. */
+declare const enum RpcCallTypeId {
+    Regular = 0,
+    Reliable = 1
+}
+/** Identifies system call methods — names include :argCount suffix for .NET interop. */
+declare const RpcSystemCalls: {
+    readonly handshake: "$sys.Handshake:1";
+    readonly ok: "$sys.Ok:1";
+    readonly error: "$sys.Error:1";
+    readonly cancel: "$sys.Cancel:0";
+    readonly keepAlive: "$sys.KeepAlive:1";
+    readonly reconnect: "$sys.Reconnect:3";
+};
+/** Wire-format RPC message envelope. */
+interface RpcMessage {
+    CallType?: number;
+    RelatedId?: number;
+    Method?: string;
+    Headers?: unknown[];
+}
+declare const ENVELOPE_DELIMITER = "\n";
+declare const ARG_DELIMITER = "\u001F";
+declare const FRAME_DELIMITER = "\n\u001E";
+
+/** 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. */
+declare function serializeFrame(messages: string[]): string;
+/** Splits a WebSocket text frame into individual message strings. */
+declare function splitFrame(frame: string): string[];
+/** Deserializes a single message string into envelope + args. */
+declare function deserializeMessage(raw: string): {
+    message: RpcMessage;
+    args: unknown[];
+};
+
+/** Abstract WebSocket interface — works with both browser WebSocket and Node.js ws. */
+interface WebSocketLike {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+}
+declare const WebSocketState: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/** Abstract RPC connection — transport-agnostic interface for sending/receiving messages. */
+interface RpcConnection {
+    readonly isOpen: boolean;
+    readonly whenConnected: Promise<void>;
+    readonly messageReceived: EventHandlerSet<string>;
+    readonly closed: EventHandlerSet<{
+        code: number;
+        reason: string;
+    }>;
+    send(serializedMessage: string): void;
+    close(code?: number, reason?: string): void;
+}
+/** WebSocket-based RpcConnection — handles frame splitting and message queueing. */
+declare class RpcWebSocketConnection implements RpcConnection {
+    private _ws;
+    private _sendBuffer;
+    private _connected;
+    readonly messageReceived: EventHandlerSet<string>;
+    readonly closed: EventHandlerSet<{
+        code: number;
+        reason: string;
+    }>;
+    readonly error: EventHandlerSet<unknown>;
+    constructor(ws: WebSocketLike);
+    get isOpen(): boolean;
+    get whenConnected(): Promise<void>;
+    send(serializedMessage: string): void;
+    sendBatch(messages: string[]): void;
+    close(code?: number, reason?: string): void;
+    private _flush;
+}
+
+/** MessagePort-based RpcConnection — for in-process testing without WebSocket mocks. */
+declare class RpcMessageChannelConnection implements RpcConnection {
+    private _port;
+    private _open;
+    readonly messageReceived: EventHandlerSet<string>;
+    readonly closed: EventHandlerSet<{
+        code: number;
+        reason: string;
+    }>;
+    readonly whenConnected: Promise<void>;
+    constructor(port: MessagePort);
+    get isOpen(): boolean;
+    send(serializedMessage: string): void;
+    close(code?: number, reason?: string): void;
+}
+/** Creates a pair of connected RpcMessageChannelConnections for testing. */
+declare function createMessageChannelPair(): [RpcMessageChannelConnection, RpcMessageChannelConnection];
+
+/** Describes a single method on an RPC service. */
+interface RpcMethodDef {
+    readonly name: string;
+    readonly serviceName: string;
+    readonly argCount: number;
+    readonly wireArgCount: number;
+    readonly callTypeId: number;
+    readonly stream: boolean;
+    readonly noWait: boolean;
+}
+/** Describes an RPC service — its name and method definitions. */
+interface RpcServiceDef {
+    readonly name: string;
+    readonly methods: ReadonlyMap<string, RpcMethodDef>;
+}
+interface RpcMethodDefInput {
+    args: unknown[];
+    returns?: symbol;
+    callTypeId?: number;
+    stream?: boolean;
+    noWait?: boolean;
+}
+declare const RpcType: {
+    readonly object: symbol;
+    readonly stream: symbol;
+    readonly void: symbol;
+};
+interface RpcServiceDefOptions {
+    ctOffset?: number;
+}
+/** Returns the full wire method name: "ServiceName.MethodName:wireArgCount". */
+declare function wireMethodName(def: RpcMethodDef): string;
+declare function defineRpcService(name: string, methods: Record<string, RpcMethodDefInput>, options?: RpcServiceDefOptions): RpcServiceDef;
+
+/** Tracks a pending outbound RPC call. */
+declare class RpcOutboundCall {
+    readonly callId: number;
+    readonly method: string;
+    readonly result: PromiseSource<unknown>;
+    /** 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;
+    constructor(callId: number, method: string);
+    /** Called when the connection is lost. Subclasses can override to resolve invalidation promises. */
+    onDisconnect(): void;
+}
+/** Manages outbound calls by their RelatedId. */
+declare class RpcOutboundCallTracker {
+    private _calls;
+    private _nextId;
+    get size(): number;
+    nextId(): number;
+    register(call: RpcOutboundCall): void;
+    get(callId: number): RpcOutboundCall | undefined;
+    remove(callId: number): RpcOutboundCall | undefined;
+    values(): IterableIterator<RpcOutboundCall>;
+    activeCallIds(): number[];
+    /** Reject all pending calls with the given error.
+     *  Stage-3 compute calls (result resolved, awaiting invalidation) are kept in the tracker. */
+    rejectAll(error: Error): void;
+    /** Invalidate all remaining stage-3 calls (on reconnect or peer stop). */
+    invalidateAll(): void;
+    clear(): void;
+}
+/** Tracks an incoming inbound RPC call. */
+declare class RpcInboundCall {
+    readonly callId: number;
+    readonly method: string;
+    readonly args: unknown[];
+    constructor(callId: number, method: string, args: unknown[]);
+}
+/** Manages inbound calls by their RelatedId. */
+declare class RpcInboundCallTracker {
+    private _calls;
+    get size(): number;
+    register(call: RpcInboundCall): void;
+    get(callId: number): RpcInboundCall | undefined;
+    remove(callId: number): RpcInboundCall | undefined;
+    clear(): void;
+}
+
+/** Handles an incoming system call message and dispatches to the appropriate tracker. */
+declare function handleSystemCall(message: RpcMessage, args: unknown[], outboundTracker: RpcOutboundCallTracker, inboundTracker: RpcInboundCallTracker): void;
+
+/** Sends system RPC messages — like .NET's RpcSystemCallSender. */
+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;
+}
+
+declare class RpcClientPeerReconnectDelayer extends RetryDelayer {
+    constructor();
+}
+
+type RpcServiceImpl = Record<string, (...args: unknown[]) => unknown>;
+/** Context passed to service dispatch — carries callId and connection for compute tracking. */
+interface RpcDispatchContext {
+    __rpcDispatch: true;
+    callId: number;
+    connection: RpcConnection;
+}
+/** Dispatches inbound RPC calls to registered service implementations. */
+declare class RpcServiceHost {
+    private _methods;
+    register(def: RpcServiceDef, impl: RpcServiceImpl): void;
+    dispatch(wireMethod: string, args: unknown[], context?: RpcDispatchContext): Promise<unknown>;
+    getMethodDef(wireMethod: string): RpcMethodDef | undefined;
+}
+
+/** Central RPC coordinator — manages peers, services, and configuration. */
+declare class RpcHub {
+    readonly hubId: string;
+    readonly peers: Map<string, RpcPeer>;
+    readonly serviceHost: RpcServiceHost;
+    readonly systemCallSender: RpcSystemCallSender;
+    constructor(hubId?: string);
+    addPeer(peer: RpcPeer): void;
+    removePeer(ref: string): void;
+    /** Get or create a peer by ref. Server peers have "server://" prefix, everything else is a client peer. */
+    getPeer(ref: string): RpcPeer;
+    /** Get or create a client peer for the given URL. */
+    getClientPeer(ref: string): RpcClientPeer;
+    /** Get or create a server peer for the given ref. */
+    getServerPeer(ref: string): RpcServerPeer;
+    /** Register a service with optional server method wrapping for custom call types. */
+    addService(defOrContract: RpcServiceDef | (abstract new (...args: any[]) => any), impl: RpcServiceImpl): void;
+    /** Create a typed client proxy for a service on a remote peer. */
+    addClient<T extends object>(peer: RpcPeer, defOrContract: RpcServiceDef | (abstract new (...args: any[]) => any)): T;
+    close(): void;
+    /** Dispatch an inbound system call. Override in FusionHub to handle compute-specific system calls. */
+    handleSystemCall(message: RpcMessage, args: unknown[], outbound: RpcOutboundCallTracker, inbound: RpcInboundCallTracker): void;
+    /** Build an RpcServiceDef from decorator metadata on a contract class. Override in FusionHub for compute support. */
+    protected _buildServiceDef(cls: abstract new (...args: any[]) => any): RpcServiceDef;
+    /** Resolve a service def from either a plain RpcServiceDef or a contract class. */
+    protected _resolveServiceDef(defOrContract: RpcServiceDef | (abstract new (...args: any[]) => any)): RpcServiceDef;
+    /** Override in FusionHub — default is pass-through (for methods with callTypeId !== 0). */
+    protected _wrapServerMethod(_methodDef: RpcMethodDef, fn: (...args: unknown[]) => unknown, _impl: object): (...args: unknown[]) => unknown;
+    /** Create a client method for the given methodDef. Override in FusionHub for custom call types. */
+    protected _createClientMethod(peer: RpcPeer, methodDef: RpcMethodDef): (...args: unknown[]) => unknown;
+}
+
+/**
+ * Default serialization format for RpcClientPeer connections.
+ * TS uses plain JSON.stringify without polymorphic type wrapping,
+ * so "json5np" (System.Text.Json, no polymorphism) is the correct match.
+ */
+declare const DEFAULT_SERIALIZATION_FORMAT = "json5np";
+/** Builds the WebSocket connection URL for an RpcClientPeer. */
+type RpcConnectionUrlResolver = (peer: RpcClientPeer) => string;
+/** Default connection URL provider — appends `clientId` and `f` query parameters. */
+declare const defaultConnectionUrlResolver: RpcConnectionUrlResolver;
+/** Options for RpcPeer.call() — allows custom call types and cancellation. */
+interface RpcCallOptions {
+    /** Wire CallType field (0 = regular). */
+    callTypeId?: number;
+    /** Factory for creating custom outbound call instances (e.g. compute calls). */
+    outboundCallFactory?: (id: number, method: string) => RpcOutboundCall;
+    /** AbortSignal for caller-initiated cancellation. */
+    signal?: AbortSignal;
+}
+/** Data extracted from an inbound $sys.Handshake message. */
+interface RemoteHandshake {
+    RemotePeerId?: string;
+    RemoteHubId?: string;
+    ProtocolVersion?: number;
+    Index?: number;
+}
+/** Base class for RPC peers — handles bidirectional message dispatch. */
+declare abstract class RpcPeer {
+    /** Routing/addressing key — used as key in hub.peers (URL for clients, "server://{uuid}" for servers). */
+    readonly ref: string;
+    /** Auto-generated GUID — used in handshakes only. */
+    readonly id: string;
+    protected _hub: RpcHub;
+    protected _connection: RpcConnection | undefined;
+    readonly outbound: RpcOutboundCallTracker;
+    readonly inbound: RpcInboundCallTracker;
+    readonly connected: EventHandlerSet<void>;
+    readonly disconnected: EventHandlerSet<{
+        code: number;
+        reason: string;
+    }>;
+    protected _pendingSends: RpcOutboundCall[];
+    private _keepAliveTimer;
+    constructor(ref: string, hub: RpcHub);
+    get connection(): RpcConnection | undefined;
+    get isConnected(): boolean;
+    protected setupConnection(conn: RpcConnection): void;
+    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;
+    /** Override in subclasses to handle the remote peer's handshake response. */
+    protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
+    private _handleMessage;
+    private _handleInbound;
+    private _startKeepAlive;
+    private _stopKeepAlive;
+}
+/** Connection state for RpcClientPeer. */
+declare const enum RpcPeerConnectionKind {
+    Disconnected = 0,
+    Connecting = 1,
+    Connected = 2
+}
+/** Client-side RPC peer — initiates WebSocket connection. ref = URL. */
+declare class RpcClientPeer extends RpcPeer {
+    private _disposed;
+    private _connectionKind;
+    private _tryIndex;
+    private _handshakeIndex;
+    private _lastRemoteHubId;
+    private _pendingHandshake;
+    private _reconnectsAt;
+    /** Base64url-encoded peer ID — matches .NET's RpcClientPeer.ClientId (Guid.ToBase64Url). */
+    readonly clientId: string;
+    /**
+     * Serialization format key sent to the server via `f=` query parameter.
+     * TS uses plain JSON.stringify (no polymorphic type wrapping), so `json5np`
+     * (no-polymorphism) is the correct default.
+     */
+    readonly serializationFormat: string;
+    /** Builds the WebSocket URL for this peer. Replace to customize URL construction. */
+    connectionUrlResolver: RpcConnectionUrlResolver;
+    readonly peerChanged: EventHandlerSet<void>;
+    readonly reconnectDelayer: RpcClientPeerReconnectDelayer;
+    readonly reconnectsAtChanged: EventHandlerSet<void>;
+    get reconnectsAt(): number;
+    private _setReconnectsAt;
+    constructor(hub: RpcHub, url: string, serializationFormat?: string);
+    get connectionKind(): RpcPeerConnectionKind;
+    /** One-shot connection for tests — no reconnection loop, no handshake. */
+    connectWith(conn: RpcConnection): void;
+    /** Start the reconnection loop — runs until disposed. */
+    run(wsFactory?: (url: string) => WebSocketLike): Promise<void>;
+    /** Re-send outbound calls after reconnection + flush pending sends.
+     *  Stage-3 compute calls are always self-invalidated: without $sys.Reconnect
+     *  protocol, the server's invalidation tracking is lost on disconnect, and
+     *  re-sending would get a duplicate $sys.Ok that is ignored (PromiseSource
+     *  already resolved). Self-invalidation forces a fresh recompute that
+     *  establishes new invalidation tracking on the new connection.
+     *  Regular in-flight calls are re-sent transparently. */
+    private _reconnect;
+    protected _onHandshakeReceived(handshake: RemoteHandshake): void;
+    close(): void;
+}
+/** Server-side RPC peer — wraps an accepted connection. ref = "server://{uuid}". */
+declare class RpcServerPeer extends RpcPeer {
+    constructor(hub: RpcHub, ref: string);
+    /** Accept an incoming connection — sets up message handling and handshake response. */
+    accept(conn: RpcConnection): void;
+    protected _onHandshakeReceived(_handshake: RemoteHandshake): void;
+}
+
+/** Creates a typed RPC client proxy — intercepts method calls and sends them over RPC. */
+declare function createRpcClient<T extends object>(peer: RpcPeer, serviceDef: RpcServiceDef): T;
+
+/** Abstract WebSocket server interface — implement with `ws` or other library. */
+interface WebSocketServer {
+    onConnection(handler: (ws: WebSocketLike) => void): void;
+    close(): void;
+}
+
+interface MethodMeta {
+    argCount: number;
+    stream?: boolean;
+    noWait?: boolean;
+    [key: symbol]: unknown;
+}
+interface ServiceMeta {
+    name: string;
+    ctOffset?: number;
+}
+/** Read method metadata from a decorated class. */
+declare function getMethodsMeta(cls: abstract new (...args: any[]) => any): Record<string, MethodMeta> | undefined;
+/** Read service metadata from a decorated class. */
+declare function getServiceMeta(cls: abstract new (...args: any[]) => any): ServiceMeta | undefined;
+/** Class decorator — stores the RPC service wire name and optional ctOffset. */
+declare function rpcService(serviceName: string, options?: {
+    ctOffset?: number;
+}): <T extends abstract new (...args: any[]) => any>(_target: T, context: ClassDecoratorContext<T>) => void;
+/** Method decorator — stores RPC method metadata (argCount, stream, noWait). Does NOT wrap the method. */
+declare function rpcMethod(options?: {
+    stream?: boolean;
+    noWait?: boolean;
+}): <This, Args extends unknown[], Return>(target: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
+
+declare const enum RpcPeerStateKind {
+    Connected = 0,
+    JustDisconnected = 1,
+    Disconnected = 2,
+    JustConnected = 3
+}
+interface RpcPeerState {
+    readonly kind: RpcPeerStateKind;
+    readonly lastError?: Error;
+    readonly reconnectsIn: number;
+}
+declare function isConnected(state: RpcPeerState): boolean;
+declare function likelyConnected(state: RpcPeerState): boolean;
+declare function getStateDescription(state: RpcPeerState, useLastError?: boolean): string;
+
+declare class RpcPeerStateMonitor {
+    readonly peer: RpcClientPeer;
+    readonly stateChanged: EventHandlerSet<RpcPeerState>;
+    private _rawConnected;
+    private _connectedAt;
+    private _disconnectedAt;
+    private _lastError;
+    private _state;
+    private _timer;
+    private _onConnected;
+    private _onDisconnected;
+    private _onReconnectsAtChanged;
+    private _onCancelDelaysChanged;
+    constructor(peer: RpcClientPeer);
+    get state(): RpcPeerState;
+    dispose(): void;
+    private _recompute;
+    private _setState;
+    private _scheduleRecompute;
+}
+
+export { ARG_DELIMITER, DEFAULT_SERIALIZATION_FORMAT, ENVELOPE_DELIMITER, FRAME_DELIMITER, 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, RpcOutboundCall, RpcOutboundCallTracker, RpcPeer, RpcPeerConnectionKind, type RpcPeerState, RpcPeerStateKind, RpcPeerStateMonitor, RpcServerPeer, type RpcServiceDef, type RpcServiceDefOptions, RpcServiceHost, type RpcServiceImpl, RpcSystemCallSender, RpcSystemCalls, RpcType, RpcWebSocketConnection, type ServiceMeta, type WebSocketLike, type WebSocketServer, WebSocketState, createMessageChannelPair, createRpcClient, defaultConnectionUrlResolver, defineRpcService, deserializeMessage, getMethodsMeta, getServiceMeta, getStateDescription, handleSystemCall, isConnected, likelyConnected, rpcMethod, rpcService, serializeFrame, serializeMessage, splitFrame, wireMethodName };