@mesh-kit/server 2.0.5 → 2.0.7

package/dist/index.d.mts

@@ -3,9 +3,9 @@ export { ServerOptions } from 'ws';
 import { LogLevel, Status, Command } from '@mesh-kit/shared';
 import { EventEmitter } from 'node:events';
 import { IncomingMessage } from 'node:http';
-import Redis$1, { RedisOptions, Redis } from 'ioredis';
-import { EventEmitter as EventEmitter$1 } from 'events';
+import Redis, { RedisOptions, Redis as Redis$1 } from 'ioredis';
 import { Operation } from 'fast-json-patch';
+import { EventEmitter as EventEmitter$1 } from 'events';
 
 declare class Latency {
     start: number;
@@ -71,21 +71,19 @@ interface ChannelPersistenceOptions {
      */
     maxBufferSize?: number;
 }
-interface RecordPersistenceOptions {
-    /**
-     * Optional adapter override for this pattern
-     */
+interface RecordPersistenceAdapterConfig {
     adapter?: PersistenceAdapter;
-    /**
-     * How often (in ms) to flush buffered records to the database
-     * @default 500
-     */
+    restorePattern: string;
+}
+interface RecordPersistenceHooksConfig {
+    persist: (records: CustomPersistedRecord[]) => Promise<void>;
+    restore: () => Promise<CustomPersistedRecord[]>;
+}
+interface RecordPersistenceConfig {
+    pattern: string | RegExp;
+    adapter?: RecordPersistenceAdapterConfig;
+    hooks?: RecordPersistenceHooksConfig;
     flushInterval?: number;
-    /**
-     * Maximum number of records to hold in memory before flushing
-     * If this limit is reached, the buffer is flushed immediately
-     * @default 100
-     */
     maxBufferSize?: number;
 }
 interface PersistedRecord {
@@ -94,6 +92,11 @@ interface PersistedRecord {
     value: string;
     timestamp: number;
 }
+interface CustomPersistedRecord {
+    recordId: string;
+    value: unknown;
+    version: number;
+}
 interface PersistenceAdapterOptions {
     /**
      * Database file path for file-based adapters
@@ -112,6 +115,11 @@ interface PostgreSQLAdapterOptions extends PersistenceAdapterOptions {
     max?: number;
 }
 
+interface AuthenticationError {
+    code?: number;
+    message?: string;
+}
+type AuthenticateConnectionFn = (req: IncomingMessage) => Promise<any> | any;
 type SocketMiddleware = (context: MeshContext<any>) => any | Promise<any>;
 interface MeshServerOptions extends ServerOptions {
     /**
@@ -172,6 +180,31 @@ interface MeshServerOptions extends ServerOptions {
      * @default "sqlite"
      */
     persistenceAdapter?: "sqlite" | "postgres";
+    /**
+     * Called during WebSocket upgrade to authenticate the connection.
+     * Receives the raw HTTP request with headers and cookies.
+     *
+     * Return any truthy value to accept the connection - the returned data
+     * will be automatically stored as the connection's initial metadata.
+     *
+     * Throw an error or return null/undefined to reject with 401 Unauthorized.
+     * Throw an object with { code, message } for custom HTTP status codes.
+     *
+     * @example
+     * ```ts
+     * authenticateConnection: async (req) => {
+     *   const cookies = parseCookie(req.headers.cookie || "");
+     *   const token = cookies["auth_token"];
+     *
+     *   const user = await validateToken(token);
+     *   if (!user) throw { code: 401, message: "Invalid token" };
+     *
+     *   // returned data becomes connection metadata
+     *   return { userId: user.id, email: user.email };
+     * }
+     * ```
+     */
+    authenticateConnection?: AuthenticateConnectionFn;
 }
 type ChannelPattern$1 = string | RegExp;
 
@@ -195,230 +228,10 @@ declare class Connection extends EventEmitter {
     close(): Promise<boolean>;
 }
 
-declare class RecordManager {
-    private redis;
-    private recordUpdateCallbacks;
-    private recordRemovedCallbacks;
-    private server;
-    constructor(options: {
-        redis: Redis;
-        server: MeshServer;
-    });
-    /**
-     * Gets the server instance associated with this record manager
-     */
-    getServer(): MeshServer;
-    /**
-     * Gets the Redis instance used by this record manager
-     * This is used by the persistence manager to restore records
-     */
-    getRedis(): Redis;
-    recordKey(recordId: string): string;
-    recordVersionKey(recordId: string): string;
-    /**
-     * Retrieves a record from Redis by its unique identifier. Attempts to parse
-     * the stored data as JSON before returning. If the record does not exist,
-     * returns null.
-     *
-     * @param {string} recordId - The unique identifier of the record to retrieve.
-     * @returns {Promise<any | null>} A promise that resolves to the parsed record object,
-     * or null if the record does not exist.
-     * @throws {SyntaxError} If the stored data is not valid JSON and cannot be parsed.
-     * @throws {Error} If an error occurs during the Redis operation.
-     */
-    getRecord(recordId: string): Promise<any | null>;
-    /**
-     * Retrieves the version number associated with the specified record ID from Redis.
-     * If no version is found, returns 0.
-     *
-     * @param {string} recordId - The unique identifier for the record whose version is to be retrieved.
-     * @returns {Promise<number>} A promise that resolves to the version number of the record. Returns 0 if not found.
-     * @throws {Error} If there is an issue communicating with Redis or parsing the version.
-     */
-    getVersion(recordId: string): Promise<number>;
-    /**
-     * Retrieves a record and its associated version from Redis.
-     * Fetches both the record data and its version by their respective keys.
-     *
-     * @param {string} recordId - The unique identifier for the record to retrieve.
-     * @returns {Promise<{ record: any | null; version: number }>}
-     *          A promise that resolves to an object containing the parsed record (or null if not found)
-     *          and its version number (0 if version data is not found or invalid).
-     * @throws {Error} If there is a Redis error or if JSON parsing fails for the record data.
-     */
-    getRecordAndVersion(recordId: string): Promise<{
-        record: any | null;
-        version: number;
-    }>;
-    /**
-     * Publishes an update to a record by computing and applying a JSON Patch,
-     * incrementing the version, and persisting the updated value and version in Redis.
-     * If there are no changes between the old and new value, returns null.
-     *
-     * @param {string} recordId - The unique identifier of the record to update.
-     * @param {any} newValue - The new value to set for the record, or partial value when using merge strategy.
-     * @param {"replace" | "merge" | "deepMerge"} [strategy="replace"] - Update strategy: "replace" (default) replaces the entire record, "merge" merges with existing object properties, "deepMerge" recursively merges nested objects.
-     * @returns {Promise<{ patch: Operation[]; version: number; finalValue: any } | null>}
-     *          A promise resolving to an object containing the JSON Patch operations, new version number, and final merged value,
-     *          or null if there were no changes to publish.
-     * @throws {Error} If there is a failure reading or writing to Redis, or during patch computation, the promise will be rejected with the error.
-     */
-    publishUpdate(recordId: string, newValue: any, strategy?: "replace" | "merge" | "deepMerge"): Promise<{
-        patch: Operation[];
-        version: number;
-        finalValue: any;
-    } | null>;
-    /**
-     * Deletes a record and its associated version from Redis storage.
-     *
-     * @param {string} recordId - The unique identifier of the record to be deleted.
-     * @returns {Promise<{ version: number }|null>} A promise that resolves to the final version of the deleted record, or null if the record didn't exist.
-     * @throws {Error} If an error occurs during the Redis pipeline execution, the promise will be rejected with the error.
-     */
-    deleteRecord(recordId: string): Promise<{
-        version: number;
-    } | null>;
-    /**
-     * Registers a callback function to be called when a record is updated.
-     *
-     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is updated.
-     * @returns {() => void} A function that, when called, will unregister the callback.
-     */
-    onRecordUpdate(callback: (data: {
-        recordId: string;
-        value: any;
-    }) => Promise<void> | void): () => void;
-    /**
-     * Registers a callback function to be called when a record is removed.
-     *
-     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is removed.
-     * @returns {() => void} A function that, when called, will unregister the callback.
-     */
-    onRecordRemoved(callback: (data: {
-        recordId: string;
-        value: any;
-    }) => Promise<void> | void): () => void;
-}
-
-type RecordPersistencePattern = string | RegExp | {
-    writePattern: string | RegExp;
-    restorePattern: string | RegExp;
-};
-declare class PersistenceManager extends EventEmitter$1 {
-    private defaultAdapter;
-    private channelPatterns;
-    private recordPatterns;
-    private messageBuffer;
-    private recordBuffer;
-    private flushTimers;
-    private recordFlushTimer;
-    private isShuttingDown;
-    private initialized;
-    private recordManager;
-    private pendingRecordUpdates;
-    private messageStream;
-    constructor(options: {
-        defaultAdapterOptions?: any;
-        adapterType?: "sqlite" | "postgres";
-    });
-    /**
-     * Sets the record manager reference for record restoration
-     * @param recordManager The record manager instance
-     */
-    setRecordManager(recordManager: RecordManager): void;
-    /**
-     * Waits until the persistence manager is fully ready and initialized.
-     *
-     * @returns {Promise<void>} A promise that resolves when persistence is ready.
-     */
-    ready(): Promise<void>;
-    /**
-     * Processes any record updates that were buffered during initialization
-     */
-    private processPendingRecordUpdates;
-    initialize(): Promise<void>;
-    /**
-     * Restores persisted records from storage into Redis on startup
-     */
-    restorePersistedRecords(): Promise<void>;
-    /**
-     * Handle a message received from the internal message stream.
-     */
-    private handleStreamMessage;
-    /**
-     * Enable persistence for channels matching the given pattern.
-     * @param pattern string or regexp pattern to match channel names
-     * @param options persistence options
-     */
-    enableChannelPersistence(pattern: string | RegExp, options?: ChannelPersistenceOptions): void;
-    /**
-     * Enable persistence for records matching the given pattern.
-     * @param pattern string, regexp, or object with writePattern/restorePattern
-     * @param options persistence options
-     */
-    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
-    /**
-     * Check if a channel has persistence enabled and return its options.
-     * @param channel channel name to check
-     * @returns the persistence options if enabled, undefined otherwise
-     */
-    getChannelPersistenceOptions(channel: string): Required<ChannelPersistenceOptions> | undefined;
-    /**
-     * Check if a record has persistence enabled and return its options.
-     * @param recordId record ID to check
-     * @returns the persistence options if enabled, undefined otherwise
-     */
-    getRecordPersistenceOptions(recordId: string): Required<RecordPersistenceOptions> | undefined;
-    /**
-     * Handle an incoming message for potential persistence.
-     * @param channel channel the message was published to
-     * @param message the message content
-     * @param instanceId id of the server instance
-     */
-    handleChannelMessage(channel: string, message: string, instanceId: string, timestamp?: number): void;
-    /**
-     * Flush buffered messages for a specific channel to its adapter.
-     * @param channel channel to flush
-     */
-    private flushChannel;
-    /**
-     * Flush all buffered messages across all channels.
-     */
-    flushAll(): Promise<void>;
-    /**
-     * Get persisted messages for a channel.
-     * @param channel channel to get messages for
-     * @param since optional cursor (timestamp or message id) to retrieve messages after
-     * @param limit maximum number of messages to retrieve
-     */
-    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
-    /**
-     * Handles a record update for potential persistence
-     * @param recordId ID of the record
-     * @param value record value (will be stringified)
-     * @param version record version
-     */
-    handleRecordUpdate(recordId: string, value: any, version: number): void;
-    /**
-     * Flush all buffered records to storage
-     */
-    flushRecords(): Promise<void>;
-    /**
-     * Retrieve persisted records matching a pattern
-     * @param pattern pattern to match record IDs
-     * @returns array of persisted records
-     */
-    getPersistedRecords(pattern: string): Promise<PersistedRecord[]>;
-    /**
-     * Shutdown the persistence manager, flushing pending messages and closing adapters.
-     */
-    shutdown(): Promise<void>;
-}
-
 declare class RoomManager {
     private redis;
     constructor(options: {
-        redis: Redis$1;
+        redis: Redis;
     });
     private roomKey;
     private connectionsRoomKey;
@@ -554,7 +367,7 @@ declare class ConnectionManager {
     private localConnections;
     private roomManager;
     constructor(options: {
-        redis: Redis$1;
+        redis: Redis;
         instanceId: string;
         roomManager: RoomManager;
     });
@@ -638,21 +451,21 @@ declare class RedisManager {
      * @returns The Redis client
      * @throws Error if Redis is not initialized
      */
-    get redis(): Redis;
+    get redis(): Redis$1;
     /**
      * Gets the Redis client for publishing
      *
      * @returns The publishing Redis client
      * @throws Error if Redis is not initialized
      */
-    get pubClient(): Redis;
+    get pubClient(): Redis$1;
     /**
      * Gets the Redis client for subscribing
      *
      * @returns The subscribing Redis client
      * @throws Error if Redis is not initialized
      */
-    get subClient(): Redis;
+    get subClient(): Redis$1;
     /**
      * Disconnects all Redis clients
      */
@@ -695,7 +508,7 @@ declare class PresenceManager {
     private roomTTLs;
     private defaultTTL;
     constructor(options: {
-        redis: Redis;
+        redis: Redis$1;
         roomManager: RoomManager;
         redisManager: RedisManager;
         enableExpirationEvents?: boolean;
@@ -768,6 +581,111 @@ declare class PresenceManager {
     cleanup(): Promise<void>;
 }
 
+declare class RecordManager {
+    private redis;
+    private recordUpdateCallbacks;
+    private recordRemovedCallbacks;
+    private server;
+    constructor(options: {
+        redis: Redis$1;
+        server: MeshServer;
+    });
+    /**
+     * Gets the server instance associated with this record manager
+     */
+    getServer(): MeshServer;
+    /**
+     * Gets the Redis instance used by this record manager
+     * This is used by the persistence manager to restore records
+     */
+    getRedis(): Redis$1;
+    recordKey(recordId: string): string;
+    recordVersionKey(recordId: string): string;
+    /**
+     * Retrieves a record from Redis by its unique identifier. Attempts to parse
+     * the stored data as JSON before returning. If the record does not exist,
+     * returns null.
+     *
+     * @param {string} recordId - The unique identifier of the record to retrieve.
+     * @returns {Promise<any | null>} A promise that resolves to the parsed record object,
+     * or null if the record does not exist.
+     * @throws {SyntaxError} If the stored data is not valid JSON and cannot be parsed.
+     * @throws {Error} If an error occurs during the Redis operation.
+     */
+    getRecord(recordId: string): Promise<any | null>;
+    /**
+     * Retrieves the version number associated with the specified record ID from Redis.
+     * If no version is found, returns 0.
+     *
+     * @param {string} recordId - The unique identifier for the record whose version is to be retrieved.
+     * @returns {Promise<number>} A promise that resolves to the version number of the record. Returns 0 if not found.
+     * @throws {Error} If there is an issue communicating with Redis or parsing the version.
+     */
+    getVersion(recordId: string): Promise<number>;
+    /**
+     * Retrieves a record and its associated version from Redis.
+     * Fetches both the record data and its version by their respective keys.
+     *
+     * @param {string} recordId - The unique identifier for the record to retrieve.
+     * @returns {Promise<{ record: any | null; version: number }>}
+     *          A promise that resolves to an object containing the parsed record (or null if not found)
+     *          and its version number (0 if version data is not found or invalid).
+     * @throws {Error} If there is a Redis error or if JSON parsing fails for the record data.
+     */
+    getRecordAndVersion(recordId: string): Promise<{
+        record: any | null;
+        version: number;
+    }>;
+    /**
+     * Publishes an update to a record by computing and applying a JSON Patch,
+     * incrementing the version, and persisting the updated value and version in Redis.
+     * If there are no changes between the old and new value, returns null.
+     *
+     * @param {string} recordId - The unique identifier of the record to update.
+     * @param {any} newValue - The new value to set for the record, or partial value when using merge strategy.
+     * @param {"replace" | "merge" | "deepMerge"} [strategy="replace"] - Update strategy: "replace" (default) replaces the entire record, "merge" merges with existing object properties, "deepMerge" recursively merges nested objects.
+     * @returns {Promise<{ patch: Operation[]; version: number; finalValue: any } | null>}
+     *          A promise resolving to an object containing the JSON Patch operations, new version number, and final merged value,
+     *          or null if there were no changes to publish.
+     * @throws {Error} If there is a failure reading or writing to Redis, or during patch computation, the promise will be rejected with the error.
+     */
+    publishUpdate(recordId: string, newValue: any, strategy?: "replace" | "merge" | "deepMerge"): Promise<{
+        patch: Operation[];
+        version: number;
+        finalValue: any;
+    } | null>;
+    /**
+     * Deletes a record and its associated version from Redis storage.
+     *
+     * @param {string} recordId - The unique identifier of the record to be deleted.
+     * @returns {Promise<{ version: number }|null>} A promise that resolves to the final version of the deleted record, or null if the record didn't exist.
+     * @throws {Error} If an error occurs during the Redis pipeline execution, the promise will be rejected with the error.
+     */
+    deleteRecord(recordId: string): Promise<{
+        version: number;
+    } | null>;
+    /**
+     * Registers a callback function to be called when a record is updated.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is updated.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordUpdate(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+    /**
+     * Registers a callback function to be called when a record is removed.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is removed.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordRemoved(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+}
+
 declare class MeshServer extends WebSocketServer {
     readonly instanceId: string;
     private redisManager;
@@ -779,6 +697,7 @@ declare class MeshServer extends WebSocketServer {
     private collectionManager;
     private broadcastManager;
     private persistenceManager;
+    private authenticateConnection?;
     roomManager: RoomManager;
     recordManager: RecordManager;
     connectionManager: ConnectionManager;
@@ -860,12 +779,9 @@ declare class MeshServer extends WebSocketServer {
     enableChannelPersistence(pattern: ChannelPattern$1, options?: ChannelPersistenceOptions): void;
     /**
      * Enables persistence for records matching the specified pattern.
-     *
-     * @param {RecordPersistencePattern} pattern - The record ID pattern to enable persistence for.
-     * @param {RecordPersistenceOptions} [options] - Options for persistence.
-     * @throws {Error} If persistence is not enabled for this server instance.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
      */
-    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
+    enableRecordPersistence(config: RecordPersistenceConfig): void;
     /**
      * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
      *
@@ -1130,4 +1046,127 @@ declare class MessageStream extends EventEmitter$1 {
     }) => void): void;
 }
 
-export { type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistencePattern, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };
+interface RecordPatternConfig {
+    pattern: string | RegExp;
+    adapter?: {
+        adapter: PersistenceAdapter;
+        restorePattern: string;
+    };
+    hooks?: {
+        persist: (records: CustomPersistedRecord[]) => Promise<void>;
+        restore: () => Promise<CustomPersistedRecord[]>;
+    };
+    flushInterval: number;
+    maxBufferSize: number;
+}
+declare class PersistenceManager extends EventEmitter$1 {
+    private defaultAdapter;
+    private channelPatterns;
+    private recordPatterns;
+    private messageBuffer;
+    private recordBuffer;
+    private flushTimers;
+    private recordFlushTimer;
+    private isShuttingDown;
+    private initialized;
+    private recordManager;
+    private pendingRecordUpdates;
+    private messageStream;
+    constructor(options: {
+        defaultAdapterOptions?: any;
+        adapterType?: "sqlite" | "postgres";
+    });
+    /**
+     * Sets the record manager reference for record restoration
+     * @param recordManager The record manager instance
+     */
+    setRecordManager(recordManager: RecordManager): void;
+    /**
+     * Waits until the persistence manager is fully ready and initialized.
+     *
+     * @returns {Promise<void>} A promise that resolves when persistence is ready.
+     */
+    ready(): Promise<void>;
+    /**
+     * Processes any record updates that were buffered during initialization
+     */
+    private processPendingRecordUpdates;
+    initialize(): Promise<void>;
+    /**
+     * Restores persisted records from storage into Redis on startup
+     */
+    restorePersistedRecords(): Promise<void>;
+    /**
+     * Handle a message received from the internal message stream.
+     */
+    private handleStreamMessage;
+    /**
+     * Enable persistence for channels matching the given pattern.
+     * @param pattern string or regexp pattern to match channel names
+     * @param options persistence options
+     */
+    enableChannelPersistence(pattern: string | RegExp, options?: ChannelPersistenceOptions): void;
+    /**
+     * Enable persistence for records matching the given pattern.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
+     */
+    enableRecordPersistence(config: RecordPersistenceConfig): void;
+    /**
+     * Check if a channel has persistence enabled and return its options.
+     * @param channel channel name to check
+     * @returns the persistence options if enabled, undefined otherwise
+     */
+    getChannelPersistenceOptions(channel: string): Required<ChannelPersistenceOptions> | undefined;
+    /**
+     * Check if a record has persistence enabled and return its config.
+     * @param recordId record ID to check
+     * @returns the persistence config if enabled, undefined otherwise
+     */
+    getRecordPersistenceConfig(recordId: string): RecordPatternConfig | undefined;
+    /**
+     * Handle an incoming message for potential persistence.
+     * @param channel channel the message was published to
+     * @param message the message content
+     * @param instanceId id of the server instance
+     */
+    handleChannelMessage(channel: string, message: string, instanceId: string, timestamp?: number): void;
+    /**
+     * Flush buffered messages for a specific channel to its adapter.
+     * @param channel channel to flush
+     */
+    private flushChannel;
+    /**
+     * Flush all buffered messages across all channels.
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Get persisted messages for a channel.
+     * @param channel channel to get messages for
+     * @param since optional cursor (timestamp or message id) to retrieve messages after
+     * @param limit maximum number of messages to retrieve
+     */
+    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
+    /**
+     * Handles a record update for potential persistence
+     * @param recordId ID of the record
+     * @param value record value (will be stringified)
+     * @param version record version
+     */
+    handleRecordUpdate(recordId: string, value: any, version: number): void;
+    /**
+     * Flush all buffered records to storage
+     */
+    flushRecords(): Promise<void>;
+    /**
+     * Retrieve persisted records matching a pattern
+     * @param pattern pattern to match record IDs
+     * @returns array of persisted records
+     */
+    getPersistedRecords(pattern: string): Promise<PersistedRecord[]>;
+    /**
+     * Shutdown the persistence manager, flushing pending messages and closing adapters.
+     */
+    shutdown(): Promise<void>;
+}
+
+export { type AuthenticateConnectionFn, type AuthenticationError, type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, type CustomPersistedRecord, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistenceConfig, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };