@mesh-kit/server 2.0.4 → 2.0.6

package/dist/index.d.mts

@@ -112,6 +112,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 +177,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;
 
@@ -653,6 +683,121 @@ declare class RecordManager {
     }) => Promise<void> | void): () => void;
 }
 
+type RecordPersistencePattern = {
+    writePattern: string | RegExp;
+    restorePattern: string;
+};
+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 object with writePattern (for runtime matching) and restorePattern (for database queries)
+     * @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 MeshServer extends WebSocketServer {
     readonly instanceId: string;
     private redisManager;
@@ -664,6 +809,7 @@ declare class MeshServer extends WebSocketServer {
     private collectionManager;
     private broadcastManager;
     private persistenceManager;
+    private authenticateConnection?;
     roomManager: RoomManager;
     recordManager: RecordManager;
     connectionManager: ConnectionManager;
@@ -746,11 +892,11 @@ declare class MeshServer extends WebSocketServer {
     /**
      * Enables persistence for records matching the specified pattern.
      *
-     * @param {ChannelPattern} pattern - The record ID pattern to enable persistence for.
+     * @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.
      */
-    enableRecordPersistence(pattern: ChannelPattern$1, options?: RecordPersistenceOptions): void;
+    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
     /**
      * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
      *
@@ -1015,115 +1161,4 @@ declare class MessageStream extends EventEmitter$1 {
     }) => void): void;
 }
 
-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 or regexp pattern to match record IDs
-     * @param options persistence options
-     */
-    enableRecordPersistence(pattern: string | RegExp, 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>;
-}
-
-export { type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };
+export { type AuthenticateConnectionFn, type AuthenticationError, 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 };

package/dist/index.d.ts

@@ -112,6 +112,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 +177,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;
 
@@ -653,6 +683,121 @@ declare class RecordManager {
     }) => Promise<void> | void): () => void;
 }
 
+type RecordPersistencePattern = {
+    writePattern: string | RegExp;
+    restorePattern: string;
+};
+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 object with writePattern (for runtime matching) and restorePattern (for database queries)
+     * @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 MeshServer extends WebSocketServer {
     readonly instanceId: string;
     private redisManager;
@@ -664,6 +809,7 @@ declare class MeshServer extends WebSocketServer {
     private collectionManager;
     private broadcastManager;
     private persistenceManager;
+    private authenticateConnection?;
     roomManager: RoomManager;
     recordManager: RecordManager;
     connectionManager: ConnectionManager;
@@ -746,11 +892,11 @@ declare class MeshServer extends WebSocketServer {
     /**
      * Enables persistence for records matching the specified pattern.
      *
-     * @param {ChannelPattern} pattern - The record ID pattern to enable persistence for.
+     * @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.
      */
-    enableRecordPersistence(pattern: ChannelPattern$1, options?: RecordPersistenceOptions): void;
+    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
     /**
      * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
      *
@@ -1015,115 +1161,4 @@ declare class MessageStream extends EventEmitter$1 {
     }) => void): void;
 }
 
-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 or regexp pattern to match record IDs
-     * @param options persistence options
-     */
-    enableRecordPersistence(pattern: string | RegExp, 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>;
-}
-
-export { type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };
+export { type AuthenticateConnectionFn, type AuthenticationError, 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 };