typeferry 0.6.0

package/dist/client/client-socket.js

@@ -0,0 +1,317 @@
+import { TYPEFERRY_WS_PATH, ClientEvents, MessageType, Presentation, isAuthMessage, isEventMessage, isPingMessage, isRpcResponse, } from '../utils/index.js';
+import EventEmitter2 from '../utils/event-emitter.js';
+import { LogLevel } from './logger.js';
+const MAX_RECONNECT_ATTEMPTS = 10;
+const BASE_RECONNECT_DELAY = 500;
+const MAX_RECONNECT_DELAY = 10000;
+const JITTER_FACTOR = 0.5;
+/**
+ * Native WebSocket transport for the TypeFerry client.
+ *
+ * Replaces Socket.IO with the browser's built-in WebSocket API. RPC calls
+ * are correlated via UUID — the client generates an `id` per call and the
+ * server echoes it back in the response.
+ *
+ * Reconnection uses exponential backoff (500ms → 10s, 10 attempts, 0.5
+ * jitter) matching the previous Socket.IO configuration.
+ */
+export class ClientSocket extends EventEmitter2 {
+    client;
+    socket;
+    protocol;
+    uri;
+    stopped = false;
+    connecting = false;
+    options = {
+        path: TYPEFERRY_WS_PATH,
+    };
+    /** UUID-keyed map of in-flight RPC calls awaiting responses. */
+    pending = new Map();
+    reconnectAttempt = 0;
+    reconnectTimer;
+    /** Prevents infinite loop between scheduleReconnect and VisibilityManager. */
+    exhaustedReconnect = false;
+    get ready() {
+        return this.socket?.readyState === WebSocket.OPEN;
+    }
+    constructor(client, options = {}) {
+        super();
+        this.client = client;
+        Object.assign(this.options, options ?? {});
+        const wsProtocol = this.client.options.secure ? 'wss://' : 'ws://';
+        this.protocol = this.client.options.secure ? 'https://' : 'http://';
+        if (this.client.options.port) {
+            this.uri = `${wsProtocol}${this.client.options.host}:${this.client.options.port}`;
+        }
+        else {
+            this.uri = `${wsProtocol}${this.client.options.host}`;
+        }
+    }
+    /**
+     * Opens a socket immediately and supersedes any scheduled backoff attempt.
+     */
+    connect() {
+        // An explicit connection supersedes exponential backoff for the old socket.
+        this.clearReconnectTimer();
+        if (this.ready) {
+            this.client.logger.connection(LogLevel.WARN, 'Already connected');
+            return;
+        }
+        this.stopped = false;
+        this.connecting = true;
+        this.reconnectAttempt = 0;
+        this.client.emit(ClientEvents.CONNECTING);
+        this.createSocket();
+    }
+    /**
+     * Builds the WebSocket URL with auth data as query parameters and opens
+     * a new connection. Query params mirror the old `socket.handshake.auth`.
+     */
+    createSocket() {
+        const { token } = this.client.context ?? {};
+        const params = new URLSearchParams();
+        if (token)
+            params.set('token', String(token));
+        params.set('uuid', this.client.uuid);
+        const meta = this.client.options.meta;
+        if (meta && Object.keys(meta).length > 0) {
+            params.set('meta', JSON.stringify(meta));
+        }
+        const url = `${this.uri}${this.options.path}?${params.toString()}`;
+        const ws = new WebSocket(url);
+        this.socket = ws;
+        /**
+         * Event handlers are bound per-socket to prevent stale close events
+         * from old sockets (which fire asynchronously) from affecting the
+         * current connection. Each handler checks `this.socket === ws` to
+         * ensure it's still the active socket.
+         */
+        ws.onopen = () => {
+            if (this.socket === ws)
+                this.handleOpen();
+        };
+        ws.onmessage = (ev) => {
+            if (this.socket === ws)
+                this.handleMessage(ev.data);
+        };
+        ws.onclose = () => {
+            if (this.socket === ws)
+                this.handleClose();
+        };
+        ws.onerror = () => {
+            if (this.socket === ws) {
+                this.handleSocketError(new Error('WebSocket error'));
+            }
+        };
+    }
+    async close() {
+        this.stopped = true;
+        this.connecting = false;
+        this.clearReconnectTimer();
+        this.clearAllPending();
+        if (!this.socket) {
+            this.client.emit(ClientEvents.WEBSOCKET_CLOSED);
+            return;
+        }
+        if (this.socket.readyState === WebSocket.CLOSED) {
+            this.socket = undefined;
+            this.client.emit(ClientEvents.WEBSOCKET_CLOSED);
+            return;
+        }
+        const socketToClose = this.socket;
+        const closed = new Promise(resolve => {
+            if (!socketToClose)
+                return resolve();
+            const onClose = () => {
+                socketToClose.removeEventListener('close', onClose);
+                resolve();
+            };
+            socketToClose.addEventListener('close', onClose);
+        });
+        socketToClose.close();
+        await closed;
+        // Only clear if this is still the active socket (connect() may have
+        // replaced it with a new one during the async close wait).
+        if (this.socket === socketToClose) {
+            this.socket = undefined;
+        }
+        this.client.emit(ClientEvents.WEBSOCKET_CLOSED);
+    }
+    /**
+     * Sends a fire-and-forget RPC message (void call).
+     * @param data - Object containing `method` and optional `params`
+     */
+    send(_event, data) {
+        if (!this.ready) {
+            this.client.logger.connection(LogLevel.WARN, 'Socket not ready, cannot send', { ready: this.ready, connecting: this.connecting });
+            return;
+        }
+        this.socket?.send(Presentation.encode({
+            t: MessageType.RPC_VOID,
+            method: data.method,
+            params: data.params,
+        }));
+    }
+    /**
+     * Sends an RPC call and returns a promise that resolves when the server
+     * responds with a correlated `{ t: "rpc:res", id }` message.
+     *
+     * Uses UUID-based request correlation instead of Socket.IO acknowledgments.
+     */
+    emitWithAck(_event, data, timeout = 20000) {
+        return new Promise((resolve, reject) => {
+            if (!this.ready) {
+                reject(new Error('Socket not ready'));
+                return;
+            }
+            const id = Presentation.uuid();
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error('Acknowledgment timeout'));
+            }, timeout);
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            this.socket?.send(Presentation.encode({
+                t: MessageType.RPC,
+                id,
+                method: data.method,
+                params: data.params,
+            }));
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Message handling
+    // ---------------------------------------------------------------------------
+    handleMessage(raw) {
+        try {
+            const msg = Presentation.decode(raw);
+            if (isRpcResponse(msg)) {
+                this.handleRpcResponse(msg);
+            }
+            else if (isEventMessage(msg)) {
+                this.handleTypedEvent(raw);
+            }
+            else if (isAuthMessage(msg)) {
+                this.handleTypedAuth(msg);
+            }
+            else if (isPingMessage(msg)) {
+                this.socket?.send(Presentation.encode({ t: MessageType.PONG }));
+            }
+        }
+        catch {
+            // Malformed message — ignore
+        }
+    }
+    /**
+     * Resolves or rejects the pending RPC call matching the response `id`.
+     */
+    handleRpcResponse(msg) {
+        const entry = this.pending.get(msg.id);
+        if (!entry)
+            return;
+        this.pending.delete(msg.id);
+        clearTimeout(entry.timer);
+        if (msg.error) {
+            entry.reject(new Error(msg.error));
+        }
+        else {
+            entry.resolve(msg.result);
+        }
+    }
+    /** Handles subscription events from the server. */
+    handleTypedEvent(raw) {
+        const payload = Presentation.decode(raw);
+        if (!payload)
+            return;
+        this.client.handleEvent(payload);
+    }
+    /** Handles authentication result from the server. */
+    handleTypedAuth(msg) {
+        this.client.authenticated = msg.authenticated;
+        this.client.initialize();
+    }
+    // ---------------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------------
+    handleOpen() {
+        this.client.emit(ClientEvents.WEBSOCKET_CONNECTED);
+        this.connecting = false;
+        this.reconnectAttempt = 0;
+        this.exhaustedReconnect = false;
+    }
+    handleClose() {
+        this.client.initialized = false;
+        this.client.initializing = false;
+        this.rejectAllPending('Connection lost');
+        this.client.emit(ClientEvents.WEBSOCKET_CLOSED);
+        if (this.stopped) {
+            this.socket = undefined;
+            return;
+        }
+        this.scheduleReconnect();
+    }
+    handleSocketError = (error) => {
+        this.connecting = false;
+        this.client.logger.connection(LogLevel.ERROR, 'Socket error', { uri: this.uri, socketReady: this.ready }, error);
+        this.client.emit(ClientEvents.ERROR, error);
+    };
+    // ---------------------------------------------------------------------------
+    // Reconnection with exponential backoff
+    // ---------------------------------------------------------------------------
+    /**
+     * Schedules a reconnection attempt with exponential backoff and jitter.
+     * After exhausting all attempts, delegates to VisibilityManager for a
+     * full reconnect (token refresh + new socket). Stops after one
+     * VisibilityManager cycle to prevent infinite loops when the server
+     * is unreachable.
+     */
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.reconnectAttempt++;
+        if (this.reconnectAttempt > MAX_RECONNECT_ATTEMPTS) {
+            if (!this.exhaustedReconnect) {
+                this.exhaustedReconnect = true;
+                this.client.visibilityManager?.reconnect();
+            }
+            return;
+        }
+        const base = Math.min(BASE_RECONNECT_DELAY * Math.pow(2, this.reconnectAttempt - 1), MAX_RECONNECT_DELAY);
+        const jitter = base * JITTER_FACTOR * Math.random();
+        const delay = base + jitter;
+        this.connecting = true;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.socket = undefined;
+            this.createSocket();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    /** Rejects all in-flight RPC calls on unexpected disconnect. */
+    rejectAllPending(reason) {
+        for (const [, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+    /**
+     * Clears all in-flight RPC calls without rejecting during intentional close.
+     * Prevents unhandled rejections when callers don't `.catch()` abandoned calls.
+     */
+    clearAllPending() {
+        for (const [, entry] of this.pending) {
+            clearTimeout(entry.timer);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=client-socket.js.map

package/dist/client/client-socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-socket.js","sourceRoot":"","sources":["../../src/client/client-socket.ts"],"names":[],"mappings":"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"}

package/dist/client/client.d.ts

@@ -0,0 +1,149 @@
+import type { CallOptions, MethodParams, ServerMethods } from '../utils/index.js';
+import { Presentation } from '../utils/index.js';
+import { ClientChannel } from './client-channel.js';
+import { ClientHttp } from './client-http.js';
+import { ClientSocket } from './client-socket.js';
+import type { TypeFerryContext } from './context-manager.js';
+import { ContextManager } from './context-manager.js';
+import { IdleTimer } from './idle-timer.js';
+import type { TypeFerryLogger } from './logger.js';
+import { LogLevel } from './logger.js';
+import { VisibilityManager } from './visibility-manager.js';
+type Timeout = ReturnType<typeof setTimeout>;
+export type ErrorHandler = (error: Record<string, any>) => any;
+export type WebSocketOptions = {
+    path?: string;
+    /**
+     * Workaround for Safari not reconnecting after the app is brought back to the foreground.
+     */
+    disconnectOnPageHide?: boolean;
+};
+export type WebSocketRequestParams = {
+    [x: string]: any;
+    [x: number]: any;
+};
+export type ClientOptions = {
+    host?: string;
+    port?: number;
+    /**
+     * Port for HTTP requests (login, refresh). When omitted, falls back
+     * to `port`. Leave undefined in dev so HTTP goes through Vite's proxy
+     * (same origin as page), ensuring HttpOnly cookies work correctly.
+     */
+    httpPort?: number;
+    secure?: boolean;
+    ws?: WebSocketOptions;
+    errorHandler?: ErrorHandler;
+    /** @deprecated Use logLevel instead */
+    debug?: boolean;
+    /** Log level for the client (default: WARN) */
+    logLevel?: LogLevel;
+    allowedContextKeys?: string[];
+    meta?: Record<string, any>;
+    idlenessTimeout?: number;
+    /**
+     * Initial context to set before the first WebSocket connection.
+     * With native WebSocket, auth data is sent as query parameters during
+     * connection — the token must be available at socket creation time.
+     */
+    initialContext?: Record<string, unknown>;
+};
+export type ProxyMethodCall = {
+    [key: string]: ProxyMethodCall;
+} & (<T = any, R = any>(params?: MethodParams<T>, options?: CallOptions) => Promise<R>);
+/**
+ * When working with Next.js, it is probably a good idea to not run this in the
+ * server side by using it inside a `useEffect` hook.
+ */
+export declare class Client<MethodsType extends ServerMethods = ServerMethods> extends ClientChannel {
+    uuid: string;
+    clientSocket: ClientSocket;
+    clientHttp: ClientHttp;
+    contextManager: ContextManager;
+    errorHandler: ErrorHandler;
+    channels: Map<string, ClientChannel>;
+    timeouts: Set<Timeout>;
+    initialized: boolean;
+    authenticated: boolean;
+    options: ClientOptions;
+    /** Logger instance for this client */
+    logger: TypeFerryLogger;
+    initializing: boolean;
+    visibilityManager: VisibilityManager;
+    idleTimer: IdleTimer | null;
+    m: MethodsType;
+    get context(): TypeFerryContext;
+    set context(value: TypeFerryContext);
+    constructor(options?: ClientOptions);
+    get isConnecting(): boolean;
+    /**
+     * Forces a reconnection. Useful for testing or manual recovery.
+     */
+    reconnect(): void;
+    get isOffline(): boolean;
+    get isOnline(): boolean;
+    get connected(): boolean;
+    /**
+     * Opens the WebSocket connection and waits for initialization.
+     * Reconnection is handled entirely by ClientSocket's exponential
+     * backoff — this method just waits for the first successful init.
+     */
+    connect(): Promise<void>;
+    /** Delegates to ContextManager. */
+    loadContext(): void;
+    /** Delegates to ContextManager. */
+    setContext(context: Record<string, unknown>): void;
+    /**
+     * Sets context (if changed) and reconnects the socket to re-authenticate.
+     * Stops the current socket without triggering auto-reconnection, then
+     * opens a fresh connection with the new context (token in query params).
+     */
+    setContextAndReInit(context: Record<string, unknown>): Promise<void>;
+    /** Delegates to ContextManager. */
+    updateContext(context: Record<string, unknown>): void;
+    /** Delegates to ContextManager. */
+    clearContext(): void;
+    close(): Promise<void>;
+    /**
+     * Initializes the client. It should be called before any other method.
+     *
+     * It should be called whenever a transport is connected, either on reconnection or from calling `connect`.
+     * Auth now happens during connection handshake. The authenticated state is set by AUTH_RESULT message.
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * The login method is always called via http so a http-only cookie can be set if the user so prefers.
+     */
+    login(params: WebSocketRequestParams, opts?: CallOptions): Promise<void>;
+    logout(): Promise<void>;
+    resubscribeAllChannels(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * Calls a method without expecting a return value (fire-and-forget).
+     */
+    void<T = any>(method: string, params?: MethodParams<T>, { http, httpFallback }?: CallOptions): Promise<void>;
+    private waitForInitialization;
+    /**
+     * Executes a method call using WebSocket RPC or HTTP fallback.
+     * Uses UUID-based request/response correlation.
+     */
+    private executeCall;
+    private static readonly DEFAULT_CALL_OPTIONS;
+    private normalizeCallOptions;
+    private retryCall;
+    call<P = Record<string, any>, R = any>(method: string, params?: P, options?: CallOptions): Promise<R>;
+    typed<T extends ServerMethods>(types: T): Client<T>;
+    combine<T extends Client>(methods: T): Client<InferClientMethods<T> & MethodsType>;
+    /** Handles subscription events from the server. */
+    handleEvent(payload: Presentation.Payload): boolean;
+    /**
+     * Generates a URL path from string parts. The last argument can be a query
+     * string object definition.
+     */
+    href(...path: (string | Record<string, any>)[]): string;
+    channel(name?: string | object): ClientChannel;
+    isConnected(): Promise<unknown>;
+    fetch(url: string, options?: Record<string, unknown>): Promise<Response>;
+}
+export type InferClientMethods<T extends Client> = T['m'];
+export {};