@camera.ui/rpc 1.0.1

package/dist/chunking.js

@@ -0,0 +1,151 @@
+import { decode } from './codec.js';
+/**
+ * Split data into chunks
+ */
+export function* createChunks(encoded, chunkId, maxChunkSize) {
+    const totalSize = encoded.length;
+    const totalChunks = Math.ceil(totalSize / maxChunkSize);
+    for (let i = 0; i < totalChunks; i++) {
+        const start = i * maxChunkSize;
+        const end = Math.min(start + maxChunkSize, totalSize);
+        const chunk = encoded.subarray(start, end);
+        yield {
+            id: chunkId,
+            chunkIndex: i,
+            data: chunk,
+            isLast: i === totalChunks - 1,
+        };
+    }
+}
+/**
+ * Reassemble chunks back into original data using a pre-allocated buffer.
+ * Chunks are written directly to the buffer - no intermediate Map storage.
+ */
+export class ChunkAssembler {
+    id;
+    buffer;
+    receivedChunks = new Set();
+    totalChunks = 0;
+    chunkSize = 0;
+    constructor(id, totalSize, totalChunks, chunkSize) {
+        this.id = id;
+        this.totalChunks = totalChunks;
+        // Use provided chunkSize or calculate from totalSize/totalChunks
+        this.chunkSize = chunkSize ?? Math.ceil(totalSize / totalChunks);
+        this.buffer = new Uint8Array(totalSize);
+    }
+    /**
+     * Add a chunk to the assembler.
+     * Writes directly to the pre-allocated buffer.
+     * @returns true if all chunks are received
+     */
+    addChunk(chunk) {
+        if (chunk.id !== this.id) {
+            throw new Error(`Chunk ID mismatch: expected ${this.id}, got ${chunk.id}`);
+        }
+        // Write chunk directly to pre-allocated buffer
+        const offset = chunk.chunkIndex * this.chunkSize;
+        this.buffer.set(chunk.data, offset);
+        this.receivedChunks.add(chunk.chunkIndex);
+        return this.isComplete();
+    }
+    /**
+     * Check if all chunks have been received
+     */
+    isComplete() {
+        return this.receivedChunks.size === this.totalChunks;
+    }
+    /**
+     * Get the reassembled data.
+     * Buffer is already complete, just decode - no copy needed.
+     */
+    getData() {
+        if (!this.isComplete()) {
+            throw new Error('Not all chunks received');
+        }
+        return decode(this.buffer);
+    }
+    /**
+     * Get progress information
+     */
+    getProgress() {
+        const received = this.receivedChunks.size;
+        const total = this.totalChunks;
+        const percentage = total > 0 ? (received / total) * 100 : 0;
+        return { received, total, percentage };
+    }
+}
+/**
+ * Manager for handling multiple chunk transfers
+ */
+export class ChunkingManager {
+    assemblers = new Map();
+    completedCallbacks = new Map();
+    errorCallbacks = new Map();
+    /**
+     * Start receiving chunks for a transfer.
+     * Pre-allocates buffer for direct chunk writing.
+     */
+    startReceiving(id, totalChunks, onComplete, onError, totalSize, chunkSize) {
+        const assembler = new ChunkAssembler(id, totalSize, totalChunks, chunkSize);
+        this.assemblers.set(id, assembler);
+        this.completedCallbacks.set(id, onComplete);
+        this.errorCallbacks.set(id, onError);
+    }
+    /**
+     * Process an incoming chunk
+     */
+    processChunk(chunk) {
+        const assembler = this.assemblers.get(chunk.id);
+        if (!assembler) {
+            console.warn(`Received chunk for unknown transfer: ${chunk.id}`);
+            return;
+        }
+        try {
+            const isComplete = assembler.addChunk(chunk);
+            if (isComplete) {
+                const data = assembler.getData();
+                const callback = this.completedCallbacks.get(chunk.id);
+                // Cleanup
+                this.assemblers.delete(chunk.id);
+                this.completedCallbacks.delete(chunk.id);
+                this.errorCallbacks.delete(chunk.id);
+                // Notify completion
+                if (callback) {
+                    callback(data);
+                }
+            }
+        }
+        catch (error) {
+            const errorCallback = this.errorCallbacks.get(chunk.id);
+            // Cleanup
+            this.assemblers.delete(chunk.id);
+            this.completedCallbacks.delete(chunk.id);
+            this.errorCallbacks.delete(chunk.id);
+            // Notify error
+            if (errorCallback) {
+                errorCallback(error);
+            }
+        }
+    }
+    /**
+     * Cancel a transfer
+     */
+    cancel(id) {
+        const errorCallback = this.errorCallbacks.get(id);
+        this.assemblers.delete(id);
+        this.completedCallbacks.delete(id);
+        this.errorCallbacks.delete(id);
+        if (errorCallback) {
+            errorCallback(new Error('Transfer cancelled'));
+        }
+    }
+    /**
+     * Get progress for a transfer
+     */
+    getProgress(id) {
+        const assembler = this.assemblers.get(id);
+        return assembler ? assembler.getProgress() : null;
+    }
+}
+//# sourceMappingURL=chunking.js.map

package/dist/chunking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.js","sourceRoot":"","sources":["../src/chunking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAYpC;;GAEG;AACH,MAAM,SAAS,CAAC,CAAC,YAAY,CAAC,OAAmB,EAAE,OAAe,EAAE,YAAoB;IACtF,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IACjC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,YAAY,CAAC,CAAC;IAExD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,YAAY,EAAE,SAAS,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAE3C,MAAM;YACJ,EAAE,EAAE,OAAO;YACX,UAAU,EAAE,CAAC;YACb,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,CAAC,KAAK,WAAW,GAAG,CAAC;SAC9B,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,cAAc;IAOP;IANV,MAAM,CAAc;IACpB,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,WAAW,GAAG,CAAC,CAAC;IAChB,SAAS,GAAG,CAAC,CAAC;IAEtB,YACkB,EAAU,EAC1B,SAAiB,EACjB,WAAmB,EACnB,SAAkB;QAHF,OAAE,GAAF,EAAE,CAAQ;QAK1B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,iEAAiE;QACjE,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,GAAG,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAC,KAAmB;QACjC,IAAI,KAAK,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,EAAE,SAAS,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC;QAED,+CAA+C;QAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAE1C,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,IAAI,CAAC,WAAW,CAAC;IACvD,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACI,WAAW;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;QAC/B,MAAM,UAAU,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACzC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAe;IAClB,UAAU,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC/C,kBAAkB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC5D,cAAc,GAAG,IAAI,GAAG,EAAkC,CAAC;IAEnE;;;OAGG;IACI,cAAc,CAAC,EAAU,EAAE,WAAmB,EAAE,UAA+B,EAAE,OAA+B,EAAE,SAAiB,EAAE,SAAkB;QAC5J,MAAM,SAAS,GAAG,IAAI,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;QAC5E,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QACnC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC5C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACI,YAAY,CAAC,KAAmB;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,wCAAwC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YACjE,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,UAAU,EAAE,CAAC;gBACf,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;gBACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAEvD,UAAU;gBACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACjC,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBACzC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAErC,oBAAoB;gBACpB,IAAI,QAAQ,EAAE,CAAC;oBACb,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAExD,UAAU;YACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjC,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACzC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAErC,eAAe;YACf,IAAI,aAAa,EAAE,CAAC;gBAClB,aAAa,CAAC,KAAc,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,EAAU;QACtB,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAElD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3B,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAE/B,IAAI,aAAa,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;OAEG;IACI,WAAW,CAAC,EAAU;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,245 @@
+import { Channel, PrivateChannel } from './channel.js';
+import { ChunkingManager } from './chunking.js';
+import { RPCService } from './service.js';
+import type { MsgHdrs, NatsConnection, Status } from '@nats-io/nats-core';
+import type { Promisify, RPCAuthOptions, RPCClient as RPCClientImpl, RPCClientOptions } from './types.js';
+export declare function createRPCClient(options: RPCClientOptions): RPCClientImpl;
+export declare class RPCClient implements RPCClientImpl {
+    options: RPCClientOptions;
+    readonly service: RPCService;
+    chunkingManager: ChunkingManager;
+    private pullIteratorCleanups;
+    private callbackCleanups;
+    private nc?;
+    private subscriptions;
+    private _subscriptionMeta;
+    private _maxPayloadSize;
+    private connectionPromise?;
+    private closed;
+    private isolatedClients;
+    private pendingRequests;
+    private streamHandlers;
+    /**
+     * Check connection status
+     */
+    get isConnected(): boolean;
+    get isClosed(): boolean;
+    /**
+     * Get the maximum payload size
+     */
+    get maxPayloadSize(): number;
+    /**
+     * Access the underlying NATS connection status events.
+     * Yields events like 'reconnect', 'disconnect', 'reconnecting'.
+     */
+    status(): AsyncIterable<Status> | undefined;
+    /**
+     * Active liveness probe via NATS PING/PONG round-trip. Resolves when a PONG
+     * arrives, rejects on timeout. Caller treats timeout as "connection is dead"
+     * — the underlying socket may still report OPEN in that case (silent-dead
+     * TCP). Use a tight timeout (a few seconds) so a stale connection is
+     * detected promptly.
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    constructor(options: RPCClientOptions);
+    /**
+     * Create a new isolated RPC client
+     * @param options - Options for the isolated client
+     */
+    createIsolatedClient(options: RPCClientOptions): RPCClient;
+    /**
+     * Connect to NATS server. Accepts an AbortSignal so callers can cancel
+     * an in-flight handshake when another candidate has won.
+     * The underlying nats-js connect() does not itself accept a signal,
+     * so we wrap it: on abort we synchronously close any late-arriving connection
+     * via the fork's abortClose() and reject with AbortError.
+     */
+    connect(options?: {
+        signal?: AbortSignal;
+    }): Promise<NatsConnection>;
+    /**
+     * Disconnect from NATS server
+     * Cleans up resources without rejecting pending operations
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Update connection options between suspend() and connect(). Used for token
+     * rotation / endpoint switching: subscription metadata is preserved by
+     * suspend(), reconfigure() points the next connect() at the new server, and
+     * connect() re-subscribes everything on the fresh transport.
+     */
+    reconfigure(overrides: {
+        servers?: string[];
+        auth?: RPCAuthOptions;
+    }): void;
+    /**
+     * Hot-swap the server pool without dropping the live connection.
+     * Use this when only the URL needs to change but the existing connection
+     * is still authenticated and serving traffic. The new pool kicks in on the next auto-reconnect.
+     *
+     * For a forced switch (e.g. endpoint host changed), use suspend() +
+     * reconfigure() + connect() instead.
+     */
+    setServers(servers: string[]): void;
+    /**
+     * Force the current dial loop (if any) to immediately retry with the latest
+     * server pool — including from a stuck mid-handshake or sleeping-on-delay
+     * state. Falls back to standard `reconnect()` on transports that don't ship
+     * the fork's `forceReconnect()` (e.g. server-side TCP via npm `@nats-io/nats-core`).
+     */
+    forceReconnect(): Promise<void>;
+    /**
+     * Synchronous force-tear-down without awaiting the transport's close
+     * handshake. Use during network changes when the WS is half-open and a
+     * normal `close()` would hang for 2s+ on the dead socket. Falls back to
+     * fire-and-forget `close()` on transports without the fork patch.
+     */
+    abortClose(err?: Error): void;
+    /**
+     * Suspend the connection without clearing subscription metadata.
+     * After calling suspend(), connect() will restore previous subscriptions.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Public publish method
+     */
+    publish<TMessage = any>(subject: string, data: TMessage, opts?: {
+        headers?: MsgHdrs;
+        reply?: string;
+    }): Promise<void>;
+    /**
+     * Public subscribe method
+     */
+    subscribe<TResponse = any>(pattern: string, handler: (data: TResponse) => void | Promise<void>, options?: {
+        queue?: string;
+    }): Promise<() => void>;
+    /**
+     * Native NATS request/reply
+     * @param subject - The subject to send the request to
+     * @param data - The request data
+     * @param options - Request options including timeout and per-call retry override
+     */
+    request<TRequest = any, TResponse = any>(subject: string, data: TRequest, options?: {
+        timeout?: number;
+        headers?: MsgHdrs;
+        noResponderRetry?: {
+            maxRetries?: number;
+            delays?: number[];
+        };
+    }): Promise<TResponse>;
+    private _requestOnce;
+    /**
+     * Retry helper for 503 / no-responder errors. The per-call `override`
+     * lets a request that targets a known-flaky responder (e.g. a child
+     * process that may be restarting) extend the wait window without
+     * affecting the client-wide default.
+     */
+    private withNoResponderRetry;
+    /**
+     * Make an RPC call
+     */
+    call<TResponse = any>(subject: string, ...args: any[]): Promise<TResponse>;
+    /**
+     * Make an RPC call (single attempt)
+     */
+    private _callOnce;
+    /**
+     * Make a streaming RPC call
+     */
+    callStream<TResponse = any>(subject: string, ...args: any[]): AsyncGenerator<TResponse>;
+    /**
+     * Make a streaming RPC call (single attempt).
+     *
+     * Manual iterator — see callPullIteratorWithCallback for rationale.
+     * The push-based stream still parks the client at `await resolver`
+     * while waiting for the next stream message; if the server stops
+     * sending without an `end` frame, the generator would hang on
+     * iter.return(). Force-settling the pending resolver lets return()
+     * run cleanup cleanly.
+     */
+    private _callStreamOnce;
+    /**
+     * Make a pull-based iterator RPC call
+     */
+    callPullIterator<TResponse = any>(subject: string, ...args: any[]): AsyncGenerator<TResponse>;
+    /**
+     * Pull-iterator-with-callbacks call.
+     *
+     * Combines a client-driven pull iterator (1 RTT per batch) with a oneway
+     * callback channel (fire-and-forget server → client) for low-latency
+     * frame-level data delivery with coarse-grained backpressure.
+     *
+     * The returned async generator yields `undefined` for each batch boundary
+     * the server produces. Meaningful data is dispatched through the provided
+     * callback object.
+     */
+    callPullIteratorWithCallback(subject: string, callbacks: Record<string, (...a: any[]) => any>, onewayMethods: string[], ...args: any[]): AsyncGenerator<void>;
+    /**
+     * Make an RPC call with a callback subscription.
+     * Returns an unsubscribe function.
+     */
+    callWithCallback<TResponse = any>(subject: string, args: any[], callback: (value: TResponse) => void | Promise<void>): Promise<() => void>;
+    /**
+     * Register RPC handlers
+     */
+    registerHandler(namespace: string, handlers: object, options?: {
+        isolatedConnection?: boolean;
+        withoutDecorators?: boolean;
+        queue?: string;
+    }): Promise<() => Promise<void>>;
+    /**
+     * Setup a request handler (responder)
+     * @param pattern - The subject pattern to listen for requests
+     * @param handler - The handler function that receives data and subject
+     */
+    onRequest<TRequest = any, TResponse = any>(pattern: string, handler: (data: TRequest) => Promise<TResponse> | TResponse): Promise<() => void>;
+    /**
+     * Create or join a bidirectional channel
+     * @param channelId - Unique channel identifier
+     * @param options - Optional configuration
+     */
+    channel(channelId: string, options?: {
+        isolatedConnection?: boolean;
+    }): Promise<Channel>;
+    /**
+     * Create a private 1:1 channel
+     * @param channelId - Unique channel identifier
+     * @param targetClientId - Target client to connect to
+     * @param options - Optional configuration
+     */
+    privateChannel(channelId: string, targetClientId: string, options?: {
+        isolatedConnection?: boolean;
+    }): Promise<PrivateChannel>;
+    /**
+     * Create proxy for type-safe RPC calls
+     * @param namespace - The namespace for RPC calls
+     * @param options - Optional configuration
+     */
+    createProxy<T extends object>(namespace: string): Promisify<T>;
+    createProxy<T extends object>(namespace: string, options: {
+        isolatedConnection: false;
+    }): Promisify<T>;
+    createProxy<T extends object>(namespace: string, options: {
+        isolatedConnection: true;
+    }): {
+        proxy: Promisify<T>;
+        close: () => Promise<void>;
+    };
+    /**
+     * Create a service client proxy with automatic service discovery
+     */
+    createServiceProxy<T extends object>(serviceName: string): Promise<Promisify<T>>;
+    createServiceProxy<T extends object>(serviceName: string, options: {
+        preferredId?: string;
+        timeout?: number;
+        isolatedConnection?: false;
+    }): Promise<Promisify<T>>;
+    createServiceProxy<T extends object>(serviceName: string, options: {
+        preferredId?: string;
+        timeout?: number;
+        isolatedConnection?: true;
+    }): Promise<{
+        proxy: Promisify<T>;
+        close: () => Promise<void>;
+    }>;
+}