@pluv/client 0.38.14 → 0.39.0

package/src/PluvRoom.ts

@@ -10,6 +10,7 @@ import type {
     InferIOAuthorizeUser,
     InferIOInput,
     InferIOOutput,
+    InputZodLike,
     JsonObject,
 } from "@pluv/types";
 import { AbstractRoom } from "./AbstractRoom";
@@ -40,13 +41,18 @@ import type {
     UserInfo,
     WebSocketConnection,
     WebSocketState,
+    WithMetadata,
 } from "./types";
 import { debounce } from "./utils";
 
 const ADD_TO_STORAGE_STATE_DEBOUNCE_MS = 1_000;
 const HEARTBEAT_INTERVAL_MS = 10_000;
 const PONG_TIMEOUT_MS = 2_000;
-const RECONNECT_TIMEOUT_MS = 30_000;
+
+const RECONNECT_TIMEOUT_MS = 5_000;
+const MIN_RECONNECT_TIMEOUT_MS = 1_000;
+const MAX_RECONNECT_TIMEOUT_MS = 60_000;
+
 const ORIGIN_INITIALIZED = "$initialized";
 const ORIGIN_STORAGE_UPDATED = "$storageUpdated";
 
@@ -69,7 +75,11 @@ export const DEFAULT_PLUV_CLIENT_ADDON = <
     storage: new StorageStore(input.room.id),
 });
 
+interface CloseWsOptions {
+    connectionState?: ConnectionState;
+}
 interface WindowListeners {
+    onNavigatorOffline: () => void;
     onNavigatorOnline: () => void;
     onVisibilityChange: () => void;
 }
@@ -137,6 +147,19 @@ export type PluvRoomDebug<TIO extends IOLike> = Id<{
     input: readonly (keyof InferIOInput<TIO>)[];
 }>;
 
+type GetPublickKeyParams<TMetadata extends JsonObject = {}> = WithMetadata<TMetadata>;
+type GetAuthEndpointParams<TMetadata extends JsonObject = {}> = WithMetadata<TMetadata>;
+type GetWsEndpointParams<TMetadata extends JsonObject = {}> = WithMetadata<TMetadata>;
+
+export type RoomConnectParams<TMetadata extends JsonObject = {}> = keyof TMetadata extends never
+    ? []
+    : [WithMetadata<TMetadata>];
+
+export interface ReconnectTimeoutMsParams {
+    attempts: number;
+}
+export type ReconnectTimeoutMs = number | ((params: ReconnectTimeoutMsParams) => number);
+
 export type RoomConfig<
     TIO extends IOLike,
     TMetadata extends JsonObject = {},
@@ -148,12 +171,13 @@ export type RoomConfig<
         addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TStorage>[];
         debug?: boolean | PluvRoomDebug<TIO>;
         onAuthorizationFail?: (error: Error) => void;
+        metadata?: InputZodLike<TMetadata>;
         publicKey?: PublicKey<TMetadata>;
+        reconnectTimeoutMs?: ReconnectTimeoutMs;
         router?: PluvRouter<TIO, TPresence, TStorage, TEvents>;
     } & RoomEndpoints<TIO, TMetadata> &
         Pick<CrdtManagerOptions<TStorage>, "initialStorage"> &
-        UsersManagerConfig<TPresence> &
-        (keyof TMetadata extends never ? { metadata?: undefined } : { metadata: TMetadata })
+        UsersManagerConfig<TPresence>
 >;
 
 export class PluvRoom<
@@ -165,6 +189,8 @@ export class PluvRoom<
 > extends AbstractRoom<TIO, TPresence, TStorage> {
     readonly _endpoints: RoomEndpoints<TIO, TMetadata>;
 
+    public readonly metadata?: InputZodLike<TMetadata>;
+
     private readonly _crdtManager: CrdtManager<TStorage>;
     private readonly _crdtNotifier = new CrdtNotifier<TStorage>();
     private readonly _debug: boolean | PluvRoomDebug<TIO>;
@@ -173,9 +199,9 @@ export class PluvRoom<
         heartbeat: null,
     };
     private readonly _listeners: InternalListeners;
-    private readonly _metadata: TMetadata = {} as TMetadata;
     private readonly _otherNotifier = new OtherNotifier<TIO>();
     private readonly _publicKey: PublicKey<TMetadata> | null = null;
+    private readonly _reconnectTimeoutMs: ReconnectTimeoutMs;
     private readonly _router: PluvRouter<TIO, TPresence, TStorage, TEvents>;
     private readonly _stateNotifier = new StateNotifier<TIO, TPresence>();
     private readonly _storageStore: AbstractStorageStore;
@@ -188,12 +214,14 @@ export class PluvRoom<
     };
     private readonly _usersManager: UsersManager<TIO, TPresence>;
 
+    private _lastMetadata: TMetadata | null = null;
     private _state: WebSocketState<TIO> = {
         authorization: {
             token: null,
             user: null,
         },
         connection: {
+            attempts: 0,
             count: 0,
             id: null,
             state: ConnectionState.Untouched,
@@ -214,6 +242,7 @@ export class PluvRoom<
             onAuthorizationFail,
             presence,
             publicKey,
+            reconnectTimeoutMs = RECONNECT_TIMEOUT_MS,
             router,
             wsEndpoint,
         } = options;
@@ -227,21 +256,17 @@ export class PluvRoom<
             ...addon({ room: this }),
         };
 
+        this.metadata = metadata;
+
         this._debug = debug;
         this._endpoints = { authEndpoint, wsEndpoint } as RoomEndpoints<TIO, TMetadata>;
+        this._reconnectTimeoutMs = reconnectTimeoutMs;
         this._storageStore = storage;
 
-        if (typeof metadata !== "undefined") this._metadata = metadata;
         if (!!publicKey) this._publicKey = publicKey;
 
         this._listeners = {
             onAuthorizationFail: (error) => {
-                this._clearTimeout(this._timeouts.reconnect);
-                this._timeouts.reconnect = setTimeout(
-                    this._reconnect.bind(this),
-                    RECONNECT_TIMEOUT_MS,
-                ) as unknown as number;
-
                 onAuthorizationFail?.(error);
             },
         };
@@ -328,10 +353,13 @@ export class PluvRoom<
         return !!this._crdtManager.doc.canUndo();
     };
 
-    public async connect(): Promise<void> {
-        if (!this._endpoints.wsEndpoint) {
-            throw new Error("Must provide an wsEndpoint.");
-        }
+    public async connect(...args: RoomConnectParams<TMetadata>): Promise<void> {
+        const params = (args[0] ?? {}) as WithMetadata<TMetadata>;
+        const metadata = params.metadata as TMetadata;
+
+        this._setMetadata(metadata);
+
+        if (!this._endpoints.wsEndpoint) throw new Error("Must provide a wsEndpoint.");
 
         const canConnect = [ConnectionState.Closed, ConnectionState.Untouched].some(
             (state) => this._state.connection.state === state,
@@ -340,7 +368,6 @@ export class PluvRoom<
         if (!canConnect) return;
 
         this._clearTimeout(this._timeouts.reconnect);
-
         this._updateState((oldState) => {
             oldState.connection.state = ConnectionState.Connecting;
 
@@ -350,29 +377,36 @@ export class PluvRoom<
         await this._storageStore.initialize();
         await this._applyStorageStore();
 
-        const url = new URL(this._getWsEndpoint(this.id));
+        const url = new URL(this._getWsEndpoint(this.id, params));
 
         let authToken: string | null = null;
         let webSocket: WebSocket;
 
         try {
-            const publicKey = this._getPublicKey();
+            const publicKey = this._getPublicKey(params);
 
-            authToken = await this._getAuthorization(this.id);
+            authToken = await this._getAuthorization(this.id, params);
 
             authToken && url.searchParams.set("token", encodeURIComponent(authToken));
             publicKey && url.searchParams.set("public_key", encodeURIComponent(publicKey));
 
             webSocket = new WebSocket(url.toString());
         } catch (err) {
-            await this._storageStore.destroy();
+            this._updateState((oldState) => {
+                oldState.connection.attempts += 1;
 
-            this._onAuthorizationFail(err);
+                return oldState;
+            });
+
+            await this._storageStore.destroy();
+            this._pollReconnect();
+            await Promise.resolve(this._onAuthorizationFail(err));
 
             return;
         }
 
         this._updateState((oldState) => {
+            oldState.connection.attempts = 0;
             oldState.authorization.token = authToken;
             oldState.webSocket = webSocket;
 
@@ -384,10 +418,7 @@ export class PluvRoom<
     }
 
     public async disconnect(): Promise<void> {
-        if (!this._endpoints.wsEndpoint) {
-            throw new Error("Must provide an wsEndpoint.");
-        }
-
+        if (!this._endpoints.wsEndpoint) throw new Error("Must provide a wsEndpoint.");
         if (!this._state.webSocket) return;
 
         const canDisconnect = [ConnectionState.Connecting, ConnectionState.Open].some(
@@ -396,14 +427,19 @@ export class PluvRoom<
 
         if (!canDisconnect) return;
 
+        this._closeWs();
         this._clearInterval(this._intervals.heartbeat);
+        this._clearTimeout(this._timeouts.reconnect);
+        this._updateState((oldState) => {
+            oldState.authorization.token = null;
+            oldState.connection.state = ConnectionState.Closed;
+            oldState.webSocket = null;
 
-        this._closeWs();
+            return oldState;
+        });
 
         await this._storageStore.destroy();
-
         this._crdtManager.destroy();
-
         this._stateNotifier.subjects["my-presence"].next(null);
     }
 
@@ -571,10 +607,12 @@ export class PluvRoom<
         if (typeof document === "undefined") return;
 
         this._windowListeners = {
+            onNavigatorOffline: this._onNavigatorOffline.bind(this),
             onNavigatorOnline: this._onNavigatorOnline.bind(this),
             onVisibilityChange: this._onVisibilityChange.bind(this),
         };
 
+        window.addEventListener("offline", this._windowListeners.onNavigatorOffline);
         window.addEventListener("online", this._windowListeners.onNavigatorOnline);
         document.addEventListener("visibilitychange", this._windowListeners.onVisibilityChange);
     }
@@ -608,26 +646,17 @@ export class PluvRoom<
     }
 
     private _closeWs(): void {
-        if (!this._state.webSocket) return;
-
         this._subscriptions.observeCrdt?.();
 
+        this._clearInterval(this._intervals.heartbeat);
         this._clearTimeout(this._timeouts.pong);
-        this._clearTimeout(this._timeouts.reconnect);
-
         this._detachWindowListeners();
-
         this._usersManager.removeMyself();
         this._usersManager.removeUsers();
         this._otherNotifier.clear();
         this._stateNotifier.subjects.myself.next(null);
         this._stateNotifier.subjects.others.next([]);
-
-        const canClose = [WebSocket.CONNECTING, WebSocket.OPEN].some(
-            (readyState) => readyState === this._state.webSocket?.readyState,
-        );
-
-        if (canClose) this._state.webSocket.close();
+        this._state.webSocket?.close();
 
         this._detachWsListeners();
     }
@@ -700,7 +729,9 @@ export class PluvRoom<
         );
     };
 
-    private _getAuthFetchOptions(room: string): FetchOptions | null {
+    private _getAuthFetchOptions(room: string, params: GetAuthEndpointParams<TMetadata>): FetchOptions | null {
+        const metadata = params.metadata as TMetadata;
+
         if (typeof this._endpoints.authEndpoint === "undefined") return null;
 
         if (this._endpoints.authEndpoint === true) {
@@ -717,23 +748,20 @@ export class PluvRoom<
             };
         }
 
-        const result = this._endpoints.authEndpoint({ metadata: this._metadata, room });
+        const result = this._endpoints.authEndpoint({ metadata, room });
 
         return typeof result === "string" ? { url: result, options: {} } : result;
     }
 
-    private async _getAuthorization(room: string): Promise<string | null> {
-        const fetchOptions = this._getAuthFetchOptions(room);
+    private async _getAuthorization(room: string, params: GetAuthEndpointParams<TMetadata>): Promise<string | null> {
+        const fetchOptions = this._getAuthFetchOptions(room, params);
 
         if (!fetchOptions) return null;
 
         const { url, options } = fetchOptions;
-
         const res = await fetch(url, options);
 
-        if (!res.ok || res.status !== 200) {
-            throw new Error("Room is unauthorized");
-        }
+        if (!res.ok || res.status !== 200) throw new Error("Room is unauthorized");
 
         try {
             return await res.text().then((text) => text.trim());
@@ -742,21 +770,25 @@ export class PluvRoom<
         }
     }
 
-    private _getPublicKey(): string | null {
+    private _getPublicKey(params: GetPublickKeyParams<TMetadata>): string | null {
+        const metadata = params.metadata as TMetadata;
+
         if (!this._publicKey) return null;
         if (typeof this._publicKey === "string") return this._publicKey;
 
-        return this._publicKey({ metadata: this._metadata });
+        return this._publicKey({ metadata });
     }
 
-    private _getWsEndpoint(room: string): string {
+    private _getWsEndpoint(room: string, params: GetWsEndpointParams<TMetadata>): string {
+        const metadata = params.metadata as TMetadata;
+
         switch (typeof this._endpoints.wsEndpoint) {
             case "undefined":
-                return !!this._getPublicKey() ? `wss://rooms.pluv.io/api/room/${room}` : `/api/pluv/room/${room}`;
+                return !!this._getPublicKey(params) ? `wss://rooms.pluv.io/api/room/${room}` : `/api/pluv/room/${room}`;
             case "string":
                 return this._endpoints.wsEndpoint;
             default:
-                return this._endpoints.wsEndpoint({ metadata: this._metadata, room });
+                return this._endpoints.wsEndpoint({ metadata, room });
         }
     }
 
@@ -1016,25 +1048,33 @@ export class PluvRoom<
         });
     }
 
-    /**
-     * TODO
-     * @description Determine if ws was closed with a code for closing without retries.
-     * Otherwise, attempt to retry again with incremental backoff
-     * @author leedavidcs
-     * @date August 19, 2022
-     */
     private async _onClose(event: CloseEvent): Promise<void> {
         this._logDebug("WebSocket closed");
         !!event.reason && this._logDebug(event.reason);
 
-        this._clearInterval(this._intervals.heartbeat);
-        this._clearTimeout(this._timeouts.pong);
+        const shouldRetry = [
+            // Going away: Client/server is shutting down or navigating
+            1001,
+            // Abnormal closure: Usually network error
+            1006,
+            // Internal error: may be a larger problem, but try reconnecting for now
+            1011,
+            // Service restart: Server restarted
+            1012,
+            // Try again later: server overloaded
+            1013,
+            // Bad gateway
+            1014,
+        ].some((okToRetryCode) => event.code === okToRetryCode);
+
+        this._closeWs();
 
-        this._stateNotifier.subjects["myself"].next(null);
+        if (!shouldRetry) this._clearTimeout(this._timeouts.reconnect);
+        else this._pollReconnect();
 
         this._updateState((oldState) => {
             oldState.authorization.token = null;
-            oldState.connection.state = ConnectionState.Closed;
+            oldState.connection.state = shouldRetry ? ConnectionState.Unavailable : ConnectionState.Closed;
             oldState.webSocket = null;
 
             return oldState;
@@ -1044,7 +1084,6 @@ export class PluvRoom<
     /**
      * TODO
      * @description Handle websocket errors in a meaningful way, should they occur
-     * @author leedavidcs
      * @date August 19, 2022
      */
     private _onError(): void {}
@@ -1115,10 +1154,18 @@ export class PluvRoom<
         this._intervals.heartbeat = setInterval(this._heartbeat.bind(this), HEARTBEAT_INTERVAL_MS) as unknown as number;
     }
 
+    private async _onNavigatorOffline(): Promise<void> {
+        if (this._state.connection.state === ConnectionState.Closed) return;
+
+        this._updateState((oldState) => {
+            oldState.connection.state = ConnectionState.Unavailable;
+
+            return oldState;
+        });
+    }
+
     private async _onNavigatorOnline(): Promise<void> {
-        if (this._state.connection.state !== ConnectionState.Unavailable) {
-            return;
-        }
+        if (this._state.connection.state !== ConnectionState.Unavailable) return;
 
         await this._reconnect();
     }
@@ -1145,7 +1192,6 @@ export class PluvRoom<
         /**
          * !HACK
          * @description We'll only handle stringified JSONs for now
-         * @author leedavidcs
          * @date August 9, 2022
          */
         if (typeof message.data !== "string") return null;
@@ -1163,6 +1209,18 @@ export class PluvRoom<
         }
     }
 
+    private _pollReconnect(): void {
+        this._clearTimeout(this._timeouts.reconnect);
+
+        const timeoutMs =
+            typeof this._reconnectTimeoutMs === "number"
+                ? this._reconnectTimeoutMs
+                : this._reconnectTimeoutMs({ attempts: this._state.connection.attempts });
+        const clampedMs = Math.max(Math.min(MIN_RECONNECT_TIMEOUT_MS, timeoutMs), MAX_RECONNECT_TIMEOUT_MS);
+
+        this._timeouts.reconnect = setTimeout(this._reconnect.bind(this), clampedMs) as unknown as number;
+    }
+
     private async _reconnect(): Promise<void> {
         if (!this._endpoints.wsEndpoint) {
             throw new Error("Must provide an wsEndpoint.");
@@ -1172,15 +1230,10 @@ export class PluvRoom<
 
         this._closeWs();
 
-        this._updateState((oldState) => {
-            oldState.authorization.token = null;
-            oldState.connection.state = ConnectionState.Closed;
-            oldState.webSocket = null;
-
-            return oldState;
-        });
+        const metadata = this._lastMetadata;
+        const params = (typeof metadata === "undefined" ? [] : [{ metadata }]) as RoomConnectParams<TMetadata>;
 
-        await this.connect();
+        await this.connect(...params);
     }
 
     private _sendMessage(data: string): void;
@@ -1215,6 +1268,10 @@ export class PluvRoom<
         webSocket.send(message);
     }
 
+    private _setMetadata(metadata: TMetadata): TMetadata {
+        return this.metadata ? this.metadata.parse(metadata) : metadata;
+    }
+
     private _updateState(updater: (oldState: WebSocketState<TIO>) => WebSocketState<TIO>): WebSocketState<TIO> {
         let authorization: AuthorizationState<TIO>;
 

package/src/index.ts

@@ -9,11 +9,18 @@ export type { InferCallback } from "./infer";
 export { MockedRoom } from "./MockedRoom";
 export type { MockedRoomConfig, MockedRoomEvents } from "./MockedRoom";
 export { PluvClient } from "./PluvClient";
-export type { CreateRoomOptions, PluvClientOptions } from "./PluvClient";
+export type { CreateRoomOptions, EnterRoomParams, PluvClientOptions } from "./PluvClient";
 export type { PluvProcedureConfig } from "./PluvProcedure";
 export { PluvRoom } from "./PluvRoom";
-export type { PluvRoomAddon, PluvRoomAddonInput, PluvRoomAddonResult, PluvRoomDebug, RoomEndpoints } from "./PluvRoom";
+export type {
+    PluvRoomAddon,
+    PluvRoomAddonInput,
+    PluvRoomAddonResult,
+    PluvRoomDebug,
+    RoomConnectParams,
+    RoomEndpoints,
+} from "./PluvRoom";
 export type { MergeEvents, PluvRouter, PluvRouterEventConfig } from "./PluvRouter";
 export { register } from "./register";
 export type { RegisterParams } from "./register";
-export type { PublicKey, PublicKeyParams, UserInfo, WebSocketConnection, WebSocketState } from "./types";
+export type { InferMetadata, PublicKey, PublicKeyParams, UserInfo, WebSocketConnection, WebSocketState } from "./types";

package/src/types.ts

@@ -9,6 +9,7 @@ import type {
     MaybePromise,
 } from "@pluv/types";
 import type { ConnectionState } from "./enums";
+import type { PluvClient } from "./PluvClient";
 
 export interface AuthorizationState<TIO extends IOLike> {
     token: string | null;
@@ -34,6 +35,9 @@ export interface EventResolverContext<
     user: UserInfo<TIO, TPresence>;
 }
 
+export type InferMetadata<TClient extends PluvClient<any, any, any, any>> =
+    TClient extends PluvClient<any, any, any, infer IMetadata> ? IMetadata : never;
+
 export interface InternalSubscriptions {
     observeCrdt: (() => void) | null;
 }
@@ -69,6 +73,19 @@ export interface UserInfo<TIO extends IOLike, TPresence extends JsonObject = {}>
 }
 
 export interface WebSocketConnection {
+    /**
+     * @description How many times a connection attempt was made. This will increment upon each
+     * unsuccessful attempt, and will reset upon a successful connection.
+     * @date April 13, 2025
+     */
+    attempts: number;
+    /**
+     * @description How many times the user has connected to the room. This can be more than 1 in
+     * the case of reconnects. This is tracked because on the very first connection (i.e. when
+     * count is 0) we don't want to send the storage state as an update to the room and overwrite
+     * the upstream state.
+     * @date April 13, 2025
+     */
     count: number;
     id: string | null;
     state: ConnectionState;
@@ -79,3 +96,7 @@ export interface WebSocketState<TIO extends IOLike> {
     connection: WebSocketConnection;
     webSocket: WebSocket | null;
 }
+
+export type WithMetadata<TMetadata extends JsonObject = {}> = keyof TMetadata extends never
+    ? { metadata?: undefined }
+    : { metadata: TMetadata };

package/.eslintrc.js

@@ -1,4 +0,0 @@
-module.exports = {
-  root: true,
-  extends: ["pluv"],
-};