@liveblocks/server 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -562,6 +562,11 @@ interface IStorageDriver {
      * Delete a leased session by session ID.
      */
     delete_leased_session(sessionId: string): Awaitable<void>;
+    /**
+     * Return the number of storage rows written since last call to this method,
+     * and reset the counter.
+     */
+    takeRowsWritten?(): number;
 }
 
 /**
@@ -838,7 +843,7 @@ declare class YjsStorage {
      * @returns a base64 encoded array of YJS updates
      */
     getYDocUpdate(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<string | null>;
-    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<Uint8Array | null>;
+    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<Uint8Array<ArrayBuffer> | null>;
     getYStateVector(guid?: Guid): Promise<string | null>;
     getSnapshotHash(options: {
         guid?: Guid;
@@ -890,6 +895,8 @@ declare class YjsStorage {
 
 type LoadingState = "initial" | "loading" | "loaded";
 type ActorID = Brand<number, "ActorID">;
+/** Number of milliseconds since Unix epoch. */
+type Millis = Brand<number, "Millis">;
 /**
  * Session keys are also known as the "nonce" in the protocol. It's a random,
  * unique, but PRIVATE, identifier for the session, and it's important that
@@ -938,14 +945,13 @@ declare class BrowserSession<SM, CM extends JsonObject> {
     #private;
     readonly version: ProtocolVersion;
     readonly actor: ActorID;
-    readonly createdAt: Date;
+    readonly createdAt: Millis;
     readonly user: IUserData;
     readonly scopes: string[];
     readonly meta: SM;
     readonly publicMeta?: CM;
-    get lastActiveAt(): Date;
+    get lastActiveAt(): Millis;
     get hasNotifiedClientStorageUpdateError(): boolean;
-    markActive(now?: Date): void;
     setHasNotifiedClientStorageUpdateError(): void;
     sendPong(): number;
     send(serverMsg: ServerMsg | ServerMsg[] | PreSerializedServerMsg): number;
@@ -1048,6 +1054,15 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     meta: RM;
     readonly driver: IStorageDriver;
     logger: Logger;
+    /**
+     * While a room is in "maintenance mode", all WebSocket connections to the
+     * room should be rejected until it's pulled out of maintenance mode again.
+     * Maintenance mode should only last a couple of milliseconds, typically.
+     *
+     * This mutex ensures that concurrent destructive operations (like
+     * init-storage, storage-reset, etc.) cannot interfere with one another.
+     */
+    private readonly _maintenanceMode;
     private _loadData$;
     private _data;
     private _qsize;
@@ -1060,6 +1075,17 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     get yjsStorage(): YjsStorage;
     get mutex(): Mutex;
     private get data();
+    /**
+     * Returns true if the room is currently in maintenance mode.
+     * When in maintenance mode, callers should refuse new WebSocket connections.
+     */
+    get isInMaintenance(): boolean;
+    /**
+     * Tries to enter maintenance mode and run the given callback exclusively.
+     * If the room is already in maintenance mode, throws E_ALREADY_LOCKED
+     * immediately instead of queuing the request.
+     */
+    runInMaintenanceMode<T>(callback: () => Promise<T>): Promise<T>;
     /**
      * Initializes the Room, so it's ready to start accepting connections. Safe
      * to call multiple times. After awaiting `room.load()` the Room is ready to
@@ -1102,6 +1128,8 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
         ticket: Ticket<SM, CM>;
         socket: IServerWebSocket;
         lastActivity: Date;
+        /** Original session creation time (e.g. from persisted attachment). Required for correct session duration after hibernation. */
+        createdAt?: Date;
     }[]): void;
     private sendSessionStartMessages;
     /**
@@ -1230,7 +1258,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
 /**
  * Concatenates multiple Uint8Arrays into a single Uint8Array.
  */
-declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array<ArrayBuffer>;
 /**
  * Check if a leased session is expired.
  * Returns true if the current time is greater than or equal to updatedAt + ttl.
@@ -1468,18 +1496,19 @@ declare class InMemoryDriver implements IStorageDriver {
         initialActor?: number;
         initialNodes?: Iterable<[string, SerializedCrdt]>;
     });
-    raw_iter_nodes(): IterableIterator<[string, SerializedCrdt]>;
+    raw_iter_nodes(): MapIterator<[string, SerializedCrdt]>;
     /** Deletes all nodes and replaces them with the given document. */
     DANGEROUSLY_reset_nodes(doc: PlainLsonObject): void;
     get_meta(key: string): Promise<Json | undefined>;
     put_meta(key: string, value: Json): Promise<void>;
     delete_meta(key: string): Promise<void>;
-    list_leased_sessions(): Promise<IterableIterator<[string, LeasedSession]>>;
+    list_leased_sessions(): Promise<MapIterator<[string, LeasedSession]>>;
     get_leased_session(sessionId: string): Promise<LeasedSession | undefined>;
     put_leased_session(session: LeasedSession): Promise<void>;
     delete_leased_session(sessionId: string): Promise<void>;
+    takeRowsWritten(): number;
     next_actor(): number;
-    iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array]>>;
+    iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array<ArrayBufferLike>]>>;
     write_y_updates(docId: YDocId, key: string, data: Uint8Array): Promise<void>;
     delete_y_updates(docId: YDocId, keys: string[]): Promise<void>;
     /** @private Only use this in unit tests, never in production. */
@@ -1487,4 +1516,4 @@ declare class InMemoryDriver implements IStorageDriver {
     load_nodes_api(): IStorageDriverNodeAPI;
 }
 
-export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };
+export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, type Millis, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };

package/dist/index.d.ts

@@ -562,6 +562,11 @@ interface IStorageDriver {
      * Delete a leased session by session ID.
      */
     delete_leased_session(sessionId: string): Awaitable<void>;
+    /**
+     * Return the number of storage rows written since last call to this method,
+     * and reset the counter.
+     */
+    takeRowsWritten?(): number;
 }
 
 /**
@@ -838,7 +843,7 @@ declare class YjsStorage {
      * @returns a base64 encoded array of YJS updates
      */
     getYDocUpdate(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<string | null>;
-    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<Uint8Array | null>;
+    getYDocUpdateBinary(logger: Logger, stateVector?: string, guid?: Guid, isV2?: boolean): Promise<Uint8Array<ArrayBuffer> | null>;
     getYStateVector(guid?: Guid): Promise<string | null>;
     getSnapshotHash(options: {
         guid?: Guid;
@@ -890,6 +895,8 @@ declare class YjsStorage {
 
 type LoadingState = "initial" | "loading" | "loaded";
 type ActorID = Brand<number, "ActorID">;
+/** Number of milliseconds since Unix epoch. */
+type Millis = Brand<number, "Millis">;
 /**
  * Session keys are also known as the "nonce" in the protocol. It's a random,
  * unique, but PRIVATE, identifier for the session, and it's important that
@@ -938,14 +945,13 @@ declare class BrowserSession<SM, CM extends JsonObject> {
     #private;
     readonly version: ProtocolVersion;
     readonly actor: ActorID;
-    readonly createdAt: Date;
+    readonly createdAt: Millis;
     readonly user: IUserData;
     readonly scopes: string[];
     readonly meta: SM;
     readonly publicMeta?: CM;
-    get lastActiveAt(): Date;
+    get lastActiveAt(): Millis;
     get hasNotifiedClientStorageUpdateError(): boolean;
-    markActive(now?: Date): void;
     setHasNotifiedClientStorageUpdateError(): void;
     sendPong(): number;
     send(serverMsg: ServerMsg | ServerMsg[] | PreSerializedServerMsg): number;
@@ -1048,6 +1054,15 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     meta: RM;
     readonly driver: IStorageDriver;
     logger: Logger;
+    /**
+     * While a room is in "maintenance mode", all WebSocket connections to the
+     * room should be rejected until it's pulled out of maintenance mode again.
+     * Maintenance mode should only last a couple of milliseconds, typically.
+     *
+     * This mutex ensures that concurrent destructive operations (like
+     * init-storage, storage-reset, etc.) cannot interfere with one another.
+     */
+    private readonly _maintenanceMode;
     private _loadData$;
     private _data;
     private _qsize;
@@ -1060,6 +1075,17 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
     get yjsStorage(): YjsStorage;
     get mutex(): Mutex;
     private get data();
+    /**
+     * Returns true if the room is currently in maintenance mode.
+     * When in maintenance mode, callers should refuse new WebSocket connections.
+     */
+    get isInMaintenance(): boolean;
+    /**
+     * Tries to enter maintenance mode and run the given callback exclusively.
+     * If the room is already in maintenance mode, throws E_ALREADY_LOCKED
+     * immediately instead of queuing the request.
+     */
+    runInMaintenanceMode<T>(callback: () => Promise<T>): Promise<T>;
     /**
      * Initializes the Room, so it's ready to start accepting connections. Safe
      * to call multiple times. After awaiting `room.load()` the Room is ready to
@@ -1102,6 +1128,8 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
         ticket: Ticket<SM, CM>;
         socket: IServerWebSocket;
         lastActivity: Date;
+        /** Original session creation time (e.g. from persisted attachment). Required for correct session duration after hibernation. */
+        createdAt?: Date;
     }[]): void;
     private sendSessionStartMessages;
     /**
@@ -1230,7 +1258,7 @@ declare class Room<RM, SM, CM extends JsonObject, C = undefined> {
 /**
  * Concatenates multiple Uint8Arrays into a single Uint8Array.
  */
-declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array;
+declare function concatUint8Arrays(arrays: Uint8Array[]): Uint8Array<ArrayBuffer>;
 /**
  * Check if a leased session is expired.
  * Returns true if the current time is greater than or equal to updatedAt + ttl.
@@ -1468,18 +1496,19 @@ declare class InMemoryDriver implements IStorageDriver {
         initialActor?: number;
         initialNodes?: Iterable<[string, SerializedCrdt]>;
     });
-    raw_iter_nodes(): IterableIterator<[string, SerializedCrdt]>;
+    raw_iter_nodes(): MapIterator<[string, SerializedCrdt]>;
     /** Deletes all nodes and replaces them with the given document. */
     DANGEROUSLY_reset_nodes(doc: PlainLsonObject): void;
     get_meta(key: string): Promise<Json | undefined>;
     put_meta(key: string, value: Json): Promise<void>;
     delete_meta(key: string): Promise<void>;
-    list_leased_sessions(): Promise<IterableIterator<[string, LeasedSession]>>;
+    list_leased_sessions(): Promise<MapIterator<[string, LeasedSession]>>;
     get_leased_session(sessionId: string): Promise<LeasedSession | undefined>;
     put_leased_session(session: LeasedSession): Promise<void>;
     delete_leased_session(sessionId: string): Promise<void>;
+    takeRowsWritten(): number;
     next_actor(): number;
-    iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array]>>;
+    iter_y_updates(docId: YDocId): Promise<IterableIterator<[string, Uint8Array<ArrayBufferLike>]>>;
     write_y_updates(docId: YDocId, key: string, data: Uint8Array): Promise<void>;
     delete_y_updates(docId: YDocId, keys: string[]): Promise<void>;
     /** @private Only use this in unit tests, never in production. */
@@ -1487,4 +1516,4 @@ declare class InMemoryDriver implements IStorageDriver {
     load_nodes_api(): IStorageDriverNodeAPI;
 }
 
-export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };
+export { type ActorID, BackendSession, BrowserSession, ConsoleTarget, type CreateTicketOptions, DefaultMap, type FixOp, type Guid, type IReadableSnapshot, type IServerWebSocket, type IStorageDriver, type IStorageDriverNodeAPI, type IUserData, InMemoryDriver, type LeasedSession, type LoadingState, LogLevel, LogTarget, Logger, type MetadataDB, type Millis, NestedMap, type NodeMap, type NodeStream, type NodeTuple, type Pos, type PreSerializedServerMsg, ProtocolVersion, ROOT_YDOC_ID, Room, type SessionKey, type Ticket, UniqueMap, type YDocId, type YUpdate, type YVector, ackIgnoredOp, clientMsgDecoder, concatUint8Arrays, guidDecoder, isLeasedSessionExpired, jsonObjectYolo, jsonYolo, makeInMemorySnapshot, makeMetadataDB, plainLsonToNodeStream, protocolVersionDecoder, quote, serialize as serializeServerMsg, snapshotToLossyJson_eager, snapshotToLossyJson_lazy, snapshotToNodeStream, snapshotToPlainLson_eager, snapshotToPlainLson_lazy, Storage as test_only__Storage, YjsStorage as test_only__YjsStorage, transientClientMsgDecoder, tryCatch };

package/dist/index.js

@@ -650,7 +650,7 @@ import {
   tryParseJson,
   WebsocketCloseCodes as CloseCode
 } from "@liveblocks/core";
-import { Mutex } from "async-mutex";
+import { Mutex, tryAcquire } from "async-mutex";
 import { array as array2, formatInline } from "decoders";
 import { chunked } from "itertools";
 import { nanoid as nanoid2 } from "nanoid";
@@ -891,6 +891,9 @@ var InMemoryDriver = class {
   async delete_leased_session(sessionId) {
     this._leasedSessions.delete(sessionId);
   }
+  takeRowsWritten() {
+    return 0;
+  }
   next_actor() {
     return ++this._nextActor;
   }
@@ -1445,7 +1448,7 @@ var YjsStorage = class {
     let encodedTargetVector;
     try {
       encodedTargetVector = stateVector.length > 0 ? Base64.toUint8Array(stateVector) : void 0;
-    } catch (e) {
+    } catch {
       logger.warn(
         "Could not get update from passed vector, returning all updates"
       );
@@ -1701,7 +1704,7 @@ function stripOpId(op2) {
 var __socket, __debug, __lastActiveAt, __hasNotifiedClientStorageUpdateError;
 var BrowserSession = class {
   /** @internal - Never create a BrowserSession instance manually. Use the room.startBrowserSession() API instead. */
-  constructor(ticket, socket, debug) {
+  constructor(ticket, socket, debug, createdAt) {
     //                        ^^ User-defined Session Metadata
     //                            ^^ User-defined Client Metadata (sent to client in ROOM_STATE)
     __publicField(this, "version");
@@ -1719,6 +1722,7 @@ var BrowserSession = class {
     // Metadata sent to client in ROOM_STATE message's "meta" field
     __privateAdd(this, __socket);
     __privateAdd(this, __debug);
+    /** Updated on every incoming message (including pings) via handleData(). Used for idle timeout detection. */
     __privateAdd(this, __lastActiveAt);
     // We keep a status in-memory in the session of whether we already sent a rejected ops message to the client.
     __privateAdd(this, __hasNotifiedClientStorageUpdateError);
@@ -1730,15 +1734,15 @@ var BrowserSession = class {
     this.publicMeta = ticket.publicMeta;
     __privateSet(this, __socket, socket);
     __privateSet(this, __debug, debug);
-    const now = /* @__PURE__ */ new Date();
+    const now = createdAt?.getTime() ?? Date.now();
     this.createdAt = now;
     __privateSet(this, __lastActiveAt, now);
     __privateSet(this, __hasNotifiedClientStorageUpdateError, false);
   }
   get lastActiveAt() {
     const lastPing = __privateGet(this, __socket).getLastPongTimestamp?.();
-    if (lastPing && lastPing > __privateGet(this, __lastActiveAt)) {
-      return lastPing;
+    if (lastPing && lastPing.getTime() > __privateGet(this, __lastActiveAt)) {
+      return lastPing.getTime();
     } else {
       return __privateGet(this, __lastActiveAt);
     }
@@ -1746,10 +1750,9 @@ var BrowserSession = class {
   get hasNotifiedClientStorageUpdateError() {
     return __privateGet(this, __hasNotifiedClientStorageUpdateError);
   }
-  markActive(now = /* @__PURE__ */ new Date()) {
-    if (now > __privateGet(this, __lastActiveAt)) {
-      __privateSet(this, __lastActiveAt, now);
-    }
+  /** @internal - This should have to be called only from Room, never externally */
+  markActive(now) {
+    __privateSet(this, __lastActiveAt, now ? now.getTime() : Date.now());
   }
   setHasNotifiedClientStorageUpdateError() {
     __privateSet(this, __hasNotifiedClientStorageUpdateError, true);
@@ -1821,6 +1824,15 @@ var Room = class {
     __publicField(this, "meta");
     __publicField(this, "driver");
     __publicField(this, "logger");
+    /**
+     * While a room is in "maintenance mode", all WebSocket connections to the
+     * room should be rejected until it's pulled out of maintenance mode again.
+     * Maintenance mode should only last a couple of milliseconds, typically.
+     *
+     * This mutex ensures that concurrent destructive operations (like
+     * init-storage, storage-reset, etc.) cannot interfere with one another.
+     */
+    __publicField(this, "_maintenanceMode", new Mutex());
     __publicField(this, "_loadData$", null);
     __publicField(this, "_data", null);
     __publicField(this, "_qsize", 0);
@@ -1881,6 +1893,24 @@ var Room = class {
   }
   // prettier-ignore
   // ------------------------------------------------------------------------------------
+  // Maintenance mode
+  // ------------------------------------------------------------------------------------
+  /**
+   * Returns true if the room is currently in maintenance mode.
+   * When in maintenance mode, callers should refuse new WebSocket connections.
+   */
+  get isInMaintenance() {
+    return this._maintenanceMode.isLocked();
+  }
+  /**
+   * Tries to enter maintenance mode and run the given callback exclusively.
+   * If the room is already in maintenance mode, throws E_ALREADY_LOCKED
+   * immediately instead of queuing the request.
+   */
+  async runInMaintenanceMode(callback) {
+    return tryAcquire(this._maintenanceMode).runExclusive(callback);
+  }
+  // ------------------------------------------------------------------------------------
   // Public API
   // ------------------------------------------------------------------------------------
   /**
@@ -1973,8 +2003,13 @@ var Room = class {
     if (this.sessions.size > 0) {
       throw new Error("This API can only be called before any sessions exist");
     }
-    for (const { ticket, socket, lastActivity } of sessions) {
-      const newSession = new BrowserSession(ticket, socket, __privateGet(this, __debug2));
+    for (const { ticket, socket, lastActivity, createdAt } of sessions) {
+      const newSession = new BrowserSession(
+        ticket,
+        socket,
+        __privateGet(this, __debug2),
+        createdAt
+      );
       this.sessions.set(ticket.sessionKey, newSession);
       newSession.markActive(lastActivity);
     }
@@ -2119,6 +2154,7 @@ var Room = class {
     );
   }) {
     const text = typeof data === "string" ? data : raise3("Unsupported message format");
+    this.sessions.get(key)?.markActive();
     if (text === "ping") {
       await this.handlePing(key, ctx);
     } else {