@socket-mesh/client 18.0.8 → 18.1.0

package/README.md

@@ -1,7 +1,7 @@
-SocketCluster JavaScript client
+SocketMesh JavaScript client
 ======
 
-Client module for SocketCluster.
+Client module for SocketMesh.
 
 ## Setting up
 

package/dist/client-auth-engine.d.ts

@@ -0,0 +1,22 @@
+import { SignedAuthToken } from "@socket-mesh/auth";
+export interface ClientAuthEngine {
+    saveToken(token: SignedAuthToken, options?: {
+        [key: string]: any;
+    }): Promise<SignedAuthToken>;
+    removeToken(): Promise<SignedAuthToken>;
+    loadToken(): Promise<SignedAuthToken | null>;
+}
+export declare function isAuthEngine(auth: ClientAuthEngine | LocalStorageAuthEngineOptions): auth is ClientAuthEngine;
+export interface LocalStorageAuthEngineOptions {
+    authTokenName?: string;
+}
+export declare class LocalStorageAuthEngine implements ClientAuthEngine {
+    private readonly _authTokenName;
+    private readonly _internalStorage;
+    readonly isLocalStorageEnabled: boolean;
+    constructor({ authTokenName }?: LocalStorageAuthEngineOptions);
+    private _checkLocalStorageEnabled;
+    saveToken(token: string): Promise<SignedAuthToken>;
+    removeToken(): Promise<SignedAuthToken>;
+    loadToken(): Promise<SignedAuthToken>;
+}

package/dist/client-auth-engine.js

@@ -0,0 +1,52 @@
+export function isAuthEngine(auth) {
+    return (typeof auth === 'object' && 'saveToken' in auth && 'removeToken' in auth && 'loadToken' in auth);
+}
+export class LocalStorageAuthEngine {
+    constructor({ authTokenName } = {}) {
+        this._internalStorage = {};
+        this.isLocalStorageEnabled = this._checkLocalStorageEnabled();
+        this._authTokenName = authTokenName ?? 'socketmesh.authToken';
+    }
+    _checkLocalStorageEnabled() {
+        let err;
+        try {
+            // Safari, in Private Browsing Mode, looks like it supports localStorage but all calls to setItem
+            // throw QuotaExceededError. We're going to detect this and avoid hard to debug edge cases.
+            localStorage.setItem('__localStorageTest', "1");
+            localStorage.removeItem('__localStorageTest');
+        }
+        catch (e) {
+            err = e;
+        }
+        return !err;
+    }
+    async saveToken(token) {
+        if (this.isLocalStorageEnabled) {
+            localStorage.setItem(this._authTokenName, token);
+        }
+        else {
+            this._internalStorage[this._authTokenName] = token;
+        }
+        return token;
+    }
+    async removeToken() {
+        let loadPromise = this.loadToken();
+        if (this.isLocalStorageEnabled) {
+            localStorage.removeItem(this._authTokenName);
+        }
+        else {
+            delete this._internalStorage[this._authTokenName];
+        }
+        return loadPromise;
+    }
+    async loadToken() {
+        let token;
+        if (this.isLocalStorageEnabled) {
+            token = localStorage.getItem(this._authTokenName);
+        }
+        else {
+            token = this._internalStorage[this._authTokenName] || null;
+        }
+        return token;
+    }
+}

package/dist/client-channels.d.ts

@@ -0,0 +1,22 @@
+import { ChannelDetails, Channels, ChannelsOptions } from "@socket-mesh/channels";
+import { ClientTransport } from "./client-transport.js";
+import { ClientMap } from "./maps/client-map.js";
+export interface ClientChannelsOptions extends ChannelsOptions {
+    autoSubscribeOnConnect?: boolean;
+}
+export declare class ClientChannels<T extends ClientMap> extends Channels<T['Channel']> {
+    autoSubscribeOnConnect: boolean;
+    protected readonly _transport: ClientTransport<T>;
+    protected _preparingPendingSubscriptions: boolean;
+    constructor(transport: ClientTransport<T>, options?: ClientChannelsOptions);
+    private suspendSubscriptions;
+    protected trySubscribe(channel: ChannelDetails): void;
+    private processPendingSubscriptions;
+    unsubscribe(channelName: keyof T['Channel'] & string | string): void;
+    protected tryUnsubscribe(channel: ChannelDetails): void;
+    private triggerChannelSubscribeFail;
+    transmitPublish<U extends keyof T['Channel'] & string>(channelName: U, data: T['Channel'][U]): Promise<void>;
+    transmitPublish<U>(channelName: string, data: U): Promise<void>;
+    invokePublish<U extends keyof T['Channel'] & string>(channelName: keyof T['Channel'] & string, data: T['Channel'][U]): Promise<void>;
+    invokePublish<U>(channelName: string, data: U): Promise<void>;
+}

package/dist/client-channels.js

@@ -0,0 +1,149 @@
+import { Channels } from "@socket-mesh/channels";
+export class ClientChannels extends Channels {
+    constructor(transport, options) {
+        if (!options) {
+            options = {};
+        }
+        super(options);
+        this.autoSubscribeOnConnect = options.autoSubscribeOnConnect ?? true;
+        this._transport = transport;
+        this._preparingPendingSubscriptions = false;
+        this._transport.plugins.push({
+            type: 'channels',
+            onAuthenticated: () => {
+                if (!this._preparingPendingSubscriptions) {
+                    this.processPendingSubscriptions();
+                }
+            },
+            onReady: () => {
+                if (this.autoSubscribeOnConnect) {
+                    this.processPendingSubscriptions();
+                }
+            },
+            onClose: () => {
+                this.suspendSubscriptions();
+            },
+        });
+    }
+    suspendSubscriptions() {
+        for (const channel in this._channelMap) {
+            this.triggerChannelUnsubscribe(this._channelMap[channel], true);
+        }
+    }
+    trySubscribe(channel) {
+        const meetsAuthRequirements = !channel.options.waitForAuth || !!this._transport.signedAuthToken;
+        // We can only ever have one pending subscribe action at any given time on a channel
+        if (this._transport.status === 'ready' &&
+            !this._preparingPendingSubscriptions &&
+            !channel.subscribePromise &&
+            meetsAuthRequirements) {
+            const subscriptionOptions = {};
+            if (channel.options.waitForAuth) {
+                subscriptionOptions.waitForAuth = true;
+            }
+            if (channel.options.data) {
+                subscriptionOptions.data = channel.options.data;
+            }
+            [channel.subscribePromise, channel.subscribeAbort] = this._transport.invoke({ method: '#subscribe', ackTimeoutMs: false }, {
+                channel: this.decorateChannelName(channel.name),
+                ...subscriptionOptions
+            });
+            channel.subscribePromise.then(() => {
+                delete channel.subscribePromise;
+                delete channel.subscribeAbort;
+                this.triggerChannelSubscribe(channel, subscriptionOptions);
+            }).catch(err => {
+                if (err.name === 'BadConnectionError') {
+                    // In case of a failed connection, keep the subscription
+                    // as pending; it will try again on reconnect.
+                    return;
+                }
+                if (err.name !== 'AbortError') {
+                    this.triggerChannelSubscribeFail(err, channel, subscriptionOptions);
+                }
+                delete channel.subscribePromise;
+                delete channel.subscribeAbort;
+            });
+            this.emit('subscribeRequest', {
+                channel: channel.name,
+                options: subscriptionOptions
+            });
+        }
+    }
+    processPendingSubscriptions() {
+        this._preparingPendingSubscriptions = false;
+        const pendingChannels = [];
+        Object.keys(this._channelMap).forEach((channelName) => {
+            const channel = this._channelMap[channelName];
+            if (channel.state === 'pending') {
+                pendingChannels.push(channel);
+            }
+        });
+        pendingChannels.sort((a, b) => {
+            const ap = a.options.priority || 0;
+            const bp = b.options.priority || 0;
+            if (ap > bp) {
+                return -1;
+            }
+            if (ap < bp) {
+                return 1;
+            }
+            return 0;
+        });
+        pendingChannels.forEach((channel) => {
+            this.trySubscribe(channel);
+        });
+    }
+    unsubscribe(channelName) {
+        const channel = this._channelMap[channelName];
+        if (channel) {
+            this.tryUnsubscribe(channel);
+        }
+    }
+    tryUnsubscribe(channel) {
+        this.triggerChannelUnsubscribe(channel);
+        if (this._transport.status === 'ready') {
+            // If there is a pending subscribe action, cancel the callback
+            this.cancelPendingSubscribeCallback(channel);
+            const decoratedChannelName = this.decorateChannelName(channel.name);
+            // This operation cannot fail because the TCP protocol guarantees delivery
+            // so long as the connection remains open. If the connection closes,
+            // the server will automatically unsubscribe the client and thus complete
+            // the operation on the server side.
+            this._transport
+                .transmit('#unsubscribe', decoratedChannelName)
+                .catch(err => { });
+        }
+    }
+    triggerChannelSubscribeFail(err, channel, options) {
+        const meetsAuthRequirements = !channel.options.waitForAuth || !!this._transport.signedAuthToken;
+        const hasChannel = !!this._channelMap[channel.name];
+        if (hasChannel && meetsAuthRequirements) {
+            delete this._channelMap[channel.name];
+            this._channelEventDemux.write(`${channel.name}/subscribeFail`, {
+                channel: channel.name,
+                error: err,
+                options
+            });
+            this.emit('subscribeFail', {
+                error: err,
+                channel: channel.name,
+                options
+            });
+        }
+    }
+    transmitPublish(channelName, data) {
+        const pubData = {
+            channel: this.decorateChannelName(channelName),
+            data
+        };
+        return this._transport.transmit('#publish', pubData);
+    }
+    invokePublish(channelName, data) {
+        const pubData = {
+            channel: this.decorateChannelName(channelName),
+            data
+        };
+        return this._transport.invoke('#publish', pubData)[0];
+    }
+}

package/dist/client-socket-options.d.ts

@@ -0,0 +1,24 @@
+import ws from "isomorphic-ws";
+import { SocketOptions } from "@socket-mesh/core";
+import { ClientAuthEngine, LocalStorageAuthEngineOptions } from "./client-auth-engine.js";
+import { SocketMapFromClient } from "./maps/socket-map.js";
+import { ClientMap } from "./maps/client-map.js";
+export interface AutoReconnectOptions {
+    initialDelay: number;
+    randomness: number;
+    multiplier: number;
+    maxDelayMs: number;
+}
+export interface ConnectOptions {
+    address?: string | URL;
+    connectTimeoutMs?: number;
+    wsOptions?: ws.ClientOptions;
+}
+export interface ClientSocketOptions<T extends ClientMap> extends SocketOptions<SocketMapFromClient<T>>, ConnectOptions {
+    autoConnect?: boolean;
+    authEngine?: ClientAuthEngine | LocalStorageAuthEngineOptions | null;
+    autoReconnect?: Partial<AutoReconnectOptions> | boolean;
+    autoSubscribeOnConnect?: boolean;
+    channelPrefix?: string;
+}
+export declare function parseClientOptions<T extends ClientMap>(options: ClientSocketOptions<T> | string | URL): ClientSocketOptions<T>;

package/dist/client-socket-options.js

@@ -0,0 +1,6 @@
+export function parseClientOptions(options) {
+    if (typeof options === 'string' || 'pathname' in options) {
+        options = { address: options };
+    }
+    return Object.assign({}, options);
+}

package/dist/client-socket.d.ts

@@ -0,0 +1,26 @@
+import { AutoReconnectOptions, ClientSocketOptions, ConnectOptions } from "./client-socket-options.js";
+import { SignedAuthToken } from "@socket-mesh/auth";
+import { Socket } from "@socket-mesh/core";
+import { ClientChannels } from "./client-channels.js";
+import { SocketMapFromClient } from "./maps/socket-map.js";
+import { ClientMap } from "./maps/client-map.js";
+export declare class ClientSocket<T extends ClientMap> extends Socket<SocketMapFromClient<T>> {
+    private readonly _clientTransport;
+    readonly channels: ClientChannels<T>;
+    constructor(address: string | URL);
+    constructor(options: ClientSocketOptions<T>);
+    authenticate(signedAuthToken: SignedAuthToken): Promise<void>;
+    get autoReconnect(): AutoReconnectOptions | false;
+    set autoReconnect(value: Partial<AutoReconnectOptions> | boolean);
+    connect(options?: ConnectOptions): void;
+    get connectTimeoutMs(): number;
+    set connectTimeoutMs(timeoutMs: number);
+    deauthenticate(): Promise<boolean>;
+    get isPingTimeoutDisabled(): boolean;
+    set isPingTimeoutDisabled(isDisabled: boolean);
+    get pingTimeoutMs(): number;
+    set pingTimeoutMs(timeoutMs: number);
+    reconnect(code?: number, reason?: string): void;
+    get type(): 'client';
+    get uri(): URL;
+}

package/dist/client-socket.js

@@ -0,0 +1,100 @@
+import { ClientTransport } from "./client-transport.js";
+import { parseClientOptions } from "./client-socket-options.js";
+import { setAuthTokenHandler } from "./handlers/set-auth-token.js";
+import { removeAuthTokenHandler } from "./handlers/remove-auth-token.js";
+import { hydrateError } from "@socket-mesh/errors";
+import { Socket, wait } from "@socket-mesh/core";
+import { ClientChannels } from "./client-channels.js";
+import { publishHandler } from "./handlers/publish.js";
+import { kickOutHandler } from "./handlers/kickout.js";
+export class ClientSocket extends Socket {
+    constructor(options) {
+        options = parseClientOptions(options);
+        options.handlers =
+            Object.assign({
+                "#kickOut": kickOutHandler,
+                "#publish": publishHandler,
+                "#setAuthToken": setAuthTokenHandler,
+                "#removeAuthToken": removeAuthTokenHandler
+            }, options.handlers);
+        const clientTransport = new ClientTransport(options);
+        super(clientTransport, options);
+        this._clientTransport = clientTransport;
+        this.channels = new ClientChannels(this._clientTransport, options);
+        if (options.autoConnect !== false) {
+            this.connect(options);
+        }
+    }
+    async authenticate(signedAuthToken) {
+        try {
+            await this._clientTransport.invoke('#authenticate', signedAuthToken)[0];
+            this._clientTransport.setAuthorization(signedAuthToken);
+            // In order for the events to trigger we need to wait for the next tick.
+            await wait(0);
+        }
+        catch (err) {
+            if (err.name !== 'BadConnectionError' && err.name !== 'TimeoutError') {
+                // In case of a bad/closed connection or a timeout, we maintain the last
+                // known auth state since those errors don't mean that the token is invalid.
+                await this._clientTransport.changeToUnauthenticatedState();
+                // In order for the events to trigger we need to wait for the next tick.
+                await wait(0);
+            }
+            throw hydrateError(err);
+        }
+    }
+    get autoReconnect() {
+        return this._clientTransport.autoReconnect;
+    }
+    set autoReconnect(value) {
+        this._clientTransport.autoReconnect = value;
+    }
+    connect(options) {
+        this._clientTransport.connect(options);
+    }
+    get connectTimeoutMs() {
+        return this._clientTransport.connectTimeoutMs;
+    }
+    set connectTimeoutMs(timeoutMs) {
+        this._clientTransport.connectTimeoutMs = timeoutMs;
+    }
+    async deauthenticate() {
+        (async () => {
+            let oldAuthToken;
+            try {
+                oldAuthToken = await this._clientTransport.authEngine.removeToken();
+            }
+            catch (err) {
+                this._clientTransport.onError(err);
+                return;
+            }
+            this.emit('removeAuthToken', { oldAuthToken });
+        })();
+        if (this.status !== 'closed') {
+            await this._clientTransport.transmit('#removeAuthToken');
+        }
+        return await super.deauthenticate();
+    }
+    get isPingTimeoutDisabled() {
+        return this._clientTransport.isPingTimeoutDisabled;
+    }
+    set isPingTimeoutDisabled(isDisabled) {
+        this._clientTransport.isPingTimeoutDisabled = isDisabled;
+    }
+    get pingTimeoutMs() {
+        return this._clientTransport.pingTimeoutMs;
+    }
+    set pingTimeoutMs(timeoutMs) {
+        this._clientTransport.pingTimeoutMs = timeoutMs;
+    }
+    reconnect(code, reason) {
+        this.disconnect(code, reason);
+        this.connect();
+    }
+    get type() {
+        return this._clientTransport.type;
+    }
+    get uri() {
+        return this._clientTransport.uri;
+    }
+}

package/dist/client-transport.d.ts

@@ -0,0 +1,52 @@
+import { AnyPacket, AnyResponse, FunctionReturnType, InvokeMethodOptions, InvokeServiceOptions, SocketTransport, SocketStatus } from "@socket-mesh/core";
+import ws from "isomorphic-ws";
+import { ClientAuthEngine } from "./client-auth-engine.js";
+import { ServerPrivateMap } from "./maps/server-map.js";
+import { AutoReconnectOptions, ClientSocketOptions, ConnectOptions } from "./client-socket-options.js";
+import { AuthToken } from "@socket-mesh/auth";
+import { SocketMapFromClient } from "./maps/socket-map.js";
+import { ClientMap } from "./maps/client-map.js";
+export declare class ClientTransport<T extends ClientMap> extends SocketTransport<SocketMapFromClient<T>> {
+    readonly authEngine: ClientAuthEngine;
+    private _uri;
+    private _wsOptions;
+    connectTimeoutMs: number;
+    private _connectTimeoutRef;
+    private _autoReconnect;
+    private _connectAttempts;
+    private _pendingReconnectTimeout;
+    private _pingTimeoutMs;
+    isPingTimeoutDisabled: boolean;
+    constructor(options: ClientSocketOptions<T>);
+    get autoReconnect(): AutoReconnectOptions | false;
+    set autoReconnect(value: Partial<AutoReconnectOptions> | boolean);
+    connect(options?: ConnectOptions): void;
+    get connectAttempts(): number;
+    protected decode(data: string | ws.RawData): AnyPacket<SocketMapFromClient<T>> | AnyPacket<SocketMapFromClient<T>>[] | AnyResponse<SocketMapFromClient<T>> | AnyResponse<SocketMapFromClient<T>>[];
+    disconnect(code?: number, reason?: string): void;
+    private handshake;
+    protected onOpen(): void;
+    protected onPing(data: Buffer): void;
+    protected onClose(code: number, reason?: Buffer): void;
+    get pendingReconnect(): boolean;
+    get pingTimeoutMs(): number;
+    set pingTimeoutMs(value: number);
+    private resetReconnect;
+    setAuthorization(authToken: AuthToken): Promise<boolean>;
+    setAuthorization(signedAuthToken: string, authToken?: AuthToken): Promise<boolean>;
+    get status(): SocketStatus;
+    private tryReconnect;
+    type: 'client';
+    get uri(): URL;
+    protected get webSocket(): ws.WebSocket | null;
+    protected set webSocket(value: ws.WebSocket | null);
+    transmit<TMethod extends keyof SocketMapFromClient<T>['Outgoing']>(method: TMethod, arg?: Parameters<SocketMapFromClient<T>['Outgoing'][TMethod]>[0]): Promise<void>;
+    transmit<TService extends keyof SocketMapFromClient<T>['Service'], TMethod extends keyof SocketMapFromClient<T>['Service'][TService]>(options: [TService, TMethod], arg?: Parameters<SocketMapFromClient<T>['Service'][TService][TMethod]>[0]): Promise<void>;
+    transmit<TMethod extends keyof (SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)>(method: TMethod, arg?: Parameters<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)[TMethod]>[0]): Promise<void>;
+    invoke<TMethod extends keyof SocketMapFromClient<T>['Outgoing']>(method: TMethod, arg?: Parameters<SocketMapFromClient<T>['Outgoing'][TMethod]>[0]): [Promise<FunctionReturnType<SocketMapFromClient<T>['Outgoing'][TMethod]>>, () => void];
+    invoke<TService extends keyof SocketMapFromClient<T>['Service'], TMethod extends keyof SocketMapFromClient<T>['Service'][TService]>(options: [TService, TMethod, (number | false)?], arg?: Parameters<SocketMapFromClient<T>['Service'][TService][TMethod]>[0]): [Promise<FunctionReturnType<SocketMapFromClient<T>['Service'][TService][TMethod]>>, () => void];
+    invoke<TService extends keyof SocketMapFromClient<T>['Service'], TMethod extends keyof SocketMapFromClient<T>['Service'][TService]>(options: InvokeServiceOptions<SocketMapFromClient<T>['Service'], TService, TMethod>, arg?: Parameters<SocketMapFromClient<T>['Service'][TService][TMethod]>[0]): [Promise<FunctionReturnType<SocketMapFromClient<T>['Service'][TService][TMethod]>>, () => void];
+    invoke<TMethod extends keyof SocketMapFromClient<T>['Outgoing']>(options: InvokeMethodOptions<SocketMapFromClient<T>['Outgoing'], TMethod>, arg?: Parameters<SocketMapFromClient<T>['Outgoing'][TMethod]>[0]): [Promise<FunctionReturnType<SocketMapFromClient<T>['Outgoing'][TMethod]>>, () => void];
+    invoke<TMethod extends keyof (SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)>(method: TMethod, arg: Parameters<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)[TMethod]>[0]): [Promise<FunctionReturnType<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)[TMethod]>>, () => void];
+    invoke<TMethod extends keyof (SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)>(options: InvokeMethodOptions<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap), TMethod>, arg?: Parameters<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)[TMethod]>[0]): [Promise<FunctionReturnType<(SocketMapFromClient<T>['PrivateOutgoing'] & ServerPrivateMap)[TMethod]>>, () => void];
+}