nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/core/client.js

@@ -0,0 +1,360 @@
+/**
+ * @file WebSocket client implementation
+ * @module core/client
+ */
+import WebSocket from 'ws';
+import { EventEmitter } from 'events';
+import { v4 as uuidv4 } from 'uuid';
+import { ConnectionState, MessagePriority } from '../types';
+import { MessageQueue } from './queue';
+import { getLogger } from '../utils/logger';
+const logger = getLogger('client');
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 10,
+    initialDelay: 1000,
+    maxDelay: 30000,
+    backoffFactor: 1.5
+};
+const DEFAULT_QUEUE_CONFIG = {
+    maxSize: 1000,
+    maxRetries: 3,
+    retryDelay: 1000,
+    staleTimeout: 300000 // 5 minutes
+};
+const DEFAULT_HEARTBEAT_CONFIG = {
+    interval: 30000,
+    timeout: 5000,
+    maxMissed: 3
+};
+/**
+ * WebSocket client implementation for Nostr protocol communication
+ * Extends EventEmitter to provide event-based message handling
+ */
+export class NostrWSClient extends EventEmitter {
+    constructor(url, options = {}) {
+        super();
+        this.url = url;
+        this.ws = null;
+        this.state = ConnectionState.DISCONNECTED;
+        this.reconnectTimeout = null;
+        this.heartbeatInterval = null;
+        this.heartbeatTimeout = null;
+        this.missedHeartbeats = 0;
+        this.reconnectAttempts = 0;
+        this.subscriptions = new Map();
+        this.clientId = uuidv4();
+        // Initialize options with defaults
+        this.options = {
+            WebSocketImpl: options.WebSocketImpl || WebSocket,
+            handlers: {
+                message: options.handlers?.message || (async () => { }),
+                error: options.handlers?.error || (() => { }),
+                close: options.handlers?.close || (() => { }),
+                stateChange: options.handlers?.stateChange,
+                heartbeat: options.handlers?.heartbeat,
+                connect: options.handlers?.connect || (() => { }),
+                disconnect: options.handlers?.disconnect || (() => { }),
+                reconnect: options.handlers?.reconnect || (() => { })
+            },
+            retry: { ...DEFAULT_RETRY_CONFIG, ...options.retry },
+            queue: { ...DEFAULT_QUEUE_CONFIG, ...options.queue },
+            heartbeat: { ...DEFAULT_HEARTBEAT_CONFIG, ...options.heartbeat },
+            autoReconnect: options.autoReconnect !== false,
+            bufferMessages: options.bufferMessages !== false,
+            cleanStaleMessages: options.cleanStaleMessages !== false,
+            logger: options.logger || logger
+        };
+        // Initialize message queue
+        this.messageQueue = new MessageQueue(this.options.queue);
+    }
+    /**
+     * Gets the current connection state
+     */
+    get connectionState() {
+        return this.state;
+    }
+    /**
+     * Updates the connection state and notifies handlers
+     */
+    setState(newState) {
+        this.state = newState;
+        logger.debug({ state: newState }, 'Connection state changed');
+        this.options.handlers.stateChange?.(newState);
+    }
+    /**
+     * Establishes a connection to the WebSocket server
+     */
+    async connect() {
+        if (this.ws) {
+            logger.warn('Connection already exists');
+            return;
+        }
+        try {
+            this.setState(ConnectionState.CONNECTING);
+            this.ws = new this.options.WebSocketImpl(this.url);
+            this.setupEventHandlers();
+            // Wait for connection to establish
+            await new Promise((resolve, reject) => {
+                const onOpen = () => {
+                    this.ws?.removeEventListener('open', onOpen);
+                    this.ws?.removeEventListener('error', onError);
+                    resolve();
+                };
+                const onError = (error) => {
+                    this.ws?.removeEventListener('open', onOpen);
+                    this.ws?.removeEventListener('error', onError);
+                    reject(new Error(error?.message || 'Failed to connect'));
+                };
+                this.ws?.addEventListener('open', onOpen);
+                this.ws?.addEventListener('error', onError);
+            });
+            this.setState(ConnectionState.CONNECTED);
+            this.reconnectAttempts = 0;
+            this.startHeartbeat();
+            this.flushMessageQueue();
+            this.resubscribeAll();
+            this.options.handlers.connect?.();
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to establish connection');
+            this.handleConnectionError(error);
+        }
+    }
+    /**
+     * Sets up event handlers for the WebSocket connection
+     */
+    setupEventHandlers() {
+        if (!this.ws)
+            return;
+        this.ws.addEventListener('message', async (event) => {
+            try {
+                const message = JSON.parse(event.data.toString());
+                // Handle heartbeat responses
+                if (message.type === 'PONG') {
+                    this.handleHeartbeatResponse();
+                    return;
+                }
+                await this.options.handlers.message(message);
+            }
+            catch (error) {
+                logger.error({ error }, 'Error handling message');
+                this.options.handlers.error(error);
+            }
+        });
+        this.ws.addEventListener('error', (error) => {
+            const wsError = error?.error || new Error('WebSocket error');
+            logger.error({ error: wsError }, 'WebSocket error');
+            this.options.handlers.error(wsError);
+        });
+        this.ws.addEventListener('close', () => {
+            this.handleDisconnection();
+        });
+    }
+    /**
+     * Starts the heartbeat mechanism
+     */
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatInterval = setInterval(() => {
+            if (this.state !== ConnectionState.CONNECTED)
+                return;
+            this.send({
+                type: 'PING',
+                priority: MessagePriority.LOW
+            });
+            this.heartbeatTimeout = setTimeout(() => {
+                this.missedHeartbeats++;
+                logger.warn({ missed: this.missedHeartbeats }, 'Missed heartbeat');
+                if (this.missedHeartbeats >= (this.options.heartbeat?.maxMissed || DEFAULT_HEARTBEAT_CONFIG.maxMissed)) {
+                    logger.error('Too many missed heartbeats, reconnecting');
+                    this.reconnect();
+                }
+            }, this.options.heartbeat?.timeout || DEFAULT_HEARTBEAT_CONFIG.timeout);
+        }, this.options.heartbeat?.interval || DEFAULT_HEARTBEAT_CONFIG.interval);
+    }
+    /**
+     * Handles heartbeat responses
+     */
+    handleHeartbeatResponse() {
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+        this.missedHeartbeats = 0;
+        this.options.handlers.heartbeat?.();
+    }
+    /**
+     * Stops the heartbeat mechanism
+     */
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+    }
+    /**
+     * Handles connection errors
+     */
+    handleConnectionError(error) {
+        logger.error({ error }, 'Connection error');
+        this.options.handlers.error(error);
+        this.handleDisconnection();
+    }
+    /**
+     * Handles disconnection and cleanup
+     */
+    handleDisconnection() {
+        this.stopHeartbeat();
+        this.setState(ConnectionState.DISCONNECTED);
+        this.ws = null;
+        this.options.handlers.disconnect?.();
+        this.options.handlers.close();
+        if (this.options.autoReconnect) {
+            this.reconnect();
+        }
+    }
+    /**
+     * Initiates reconnection with exponential backoff
+     */
+    reconnect() {
+        if (this.reconnectTimeout || this.state === ConnectionState.CONNECTING) {
+            return;
+        }
+        this.reconnectAttempts++;
+        const maxAttempts = this.options.retry?.maxAttempts || DEFAULT_RETRY_CONFIG.maxAttempts;
+        if (this.reconnectAttempts > maxAttempts) {
+            this.setState(ConnectionState.FAILED);
+            logger.error('Max reconnection attempts exceeded');
+            return;
+        }
+        const initialDelay = this.options.retry?.initialDelay || DEFAULT_RETRY_CONFIG.initialDelay;
+        const backoffFactor = this.options.retry?.backoffFactor || DEFAULT_RETRY_CONFIG.backoffFactor;
+        const maxDelay = this.options.retry?.maxDelay || DEFAULT_RETRY_CONFIG.maxDelay;
+        const delay = Math.min(initialDelay * Math.pow(backoffFactor, this.reconnectAttempts - 1), maxDelay);
+        this.setState(ConnectionState.RECONNECTING);
+        logger.info({ attempt: this.reconnectAttempts, delay }, 'Scheduling reconnection');
+        this.reconnectTimeout = setTimeout(async () => {
+            this.reconnectTimeout = null;
+            try {
+                await this.connect();
+            }
+            catch (error) {
+                logger.error({ error }, 'Reconnection failed');
+            }
+        }, delay);
+        this.options.handlers.reconnect?.();
+    }
+    /**
+     * Subscribes to a channel with optional filter
+     */
+    subscribe(channel, filter) {
+        const subscription = {
+            type: 'REQ',
+            data: { channel, filter },
+            priority: MessagePriority.HIGH
+        };
+        this.subscriptions.set(channel, subscription);
+        this.send(subscription);
+    }
+    /**
+     * Resubscribes to all active subscriptions
+     */
+    resubscribeAll() {
+        for (const subscription of this.subscriptions.values()) {
+            this.send(subscription);
+        }
+    }
+    /**
+     * Unsubscribes from a channel
+     */
+    unsubscribe(channel) {
+        const subscription = this.subscriptions.get(channel);
+        if (subscription) {
+            this.send({
+                type: 'CLOSE',
+                data: { channel },
+                priority: MessagePriority.HIGH
+            });
+            this.subscriptions.delete(channel);
+        }
+    }
+    /**
+     * Flushes the message queue by sending pending messages
+     */
+    async flushMessageQueue() {
+        if (this.state !== ConnectionState.CONNECTED)
+            return;
+        while (this.messageQueue.size > 0) {
+            const message = this.messageQueue.dequeue();
+            if (!message)
+                break;
+            try {
+                await this.sendImmediate(message);
+            }
+            catch (error) {
+                await this.messageQueue.retry(message);
+            }
+        }
+    }
+    /**
+     * Sends a message immediately without queueing
+     */
+    async sendImmediate(message) {
+        if (!this.ws || this.state !== ConnectionState.CONNECTED) {
+            throw new Error('Not connected');
+        }
+        return new Promise((resolve, reject) => {
+            this.ws.send(JSON.stringify(message), (error) => {
+                if (error) {
+                    logger.error({ error, message }, 'Failed to send message');
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Sends a message to the WebSocket server
+     */
+    async send(message) {
+        if (this.state === ConnectionState.CONNECTED) {
+            try {
+                await this.sendImmediate(message);
+                return;
+            }
+            catch (error) {
+                if (!this.options.bufferMessages) {
+                    throw error;
+                }
+            }
+        }
+        if (this.options.bufferMessages) {
+            this.messageQueue.enqueue(message);
+        }
+        else {
+            throw new Error('Not connected and message buffering is disabled');
+        }
+    }
+    /**
+     * Closes the WebSocket connection
+     */
+    close() {
+        this.options.autoReconnect = false;
+        if (this.reconnectTimeout) {
+            clearTimeout(this.reconnectTimeout);
+            this.reconnectTimeout = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+        }
+        this.handleDisconnection();
+        this.messageQueue.clear();
+        this.subscriptions.clear();
+    }
+}

package/dist/core/nostr-server.d.ts

@@ -0,0 +1,27 @@
+import { NostrWSServerOptions } from '../types/websocket';
+/**
+ * Represents a Nostr WebSocket server
+ */
+export declare class NostrWSServer {
+    /**
+     * The underlying WebSocket server instance
+     */
+    private server;
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
+    constructor(options: NostrWSServerOptions);
+    /**
+     * Closes the WebSocket server
+     */
+    stop(): void;
+}
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
+export declare function createWSServer(options: NostrWSServerOptions): NostrWSServer;

package/dist/core/nostr-server.js

@@ -0,0 +1,95 @@
+import { WebSocketServer } from 'ws';
+import { v4 as uuidv4 } from 'uuid';
+import { getLogger } from '../utils/logger';
+const logger = getLogger('NostrWSServer');
+/**
+ * Represents a Nostr WebSocket server
+ */
+export class NostrWSServer {
+    /**
+     * Creates a new Nostr WebSocket server instance
+     *
+     * @param {NostrWSServerOptions} options - Server configuration options
+     */
+    constructor(options) {
+        this.server = new WebSocketServer({
+            port: options.port,
+            host: options.host
+        });
+        /**
+         * Handles incoming WebSocket connections
+         *
+         * @param {WebSocket} ws - The connected WebSocket client
+         */
+        this.server.on('connection', async (ws) => {
+            const socket = ws;
+            socket.clientId = uuidv4();
+            socket.subscriptions = new Set();
+            socket.isAlive = true;
+            logger.info(`Client connected: ${socket.clientId}`);
+            /**
+             * Calls the onConnection handler if provided
+             */
+            await options.onConnection?.(socket);
+            /**
+             * Handles incoming messages from the client
+             *
+             * @param {Buffer} data - The incoming message data
+             */
+            socket.on('message', async (data) => {
+                try {
+                    const message = JSON.parse(data.toString());
+                    logger.info('Received message:', message);
+                    /**
+                     * Calls the onMessage handler if provided
+                     */
+                    await options.onMessage?.(message, socket);
+                }
+                catch (error) {
+                    logger.error('Error processing message:', error);
+                    /**
+                     * Calls the onError handler if provided
+                     */
+                    options.onError?.(error, socket);
+                }
+            });
+            /**
+             * Handles WebSocket errors
+             *
+             * @param {Error} error - The error that occurred
+             */
+            socket.on('error', (error) => {
+                logger.error(`Client error (${socket.clientId}):`, error);
+                /**
+                 * Calls the onError handler if provided
+                 */
+                options.onError?.(error, socket);
+            });
+            /**
+             * Handles client disconnections
+             */
+            socket.on('close', () => {
+                logger.info(`Client disconnected: ${socket.clientId}`);
+                /**
+                 * Calls the onClose handler if provided
+                 */
+                options.onClose?.(socket);
+            });
+        });
+    }
+    /**
+     * Closes the WebSocket server
+     */
+    stop() {
+        this.server.close();
+    }
+}
+/**
+ * Creates a new Nostr WebSocket server instance
+ *
+ * @param {NostrWSServerOptions} options - Server configuration options
+ * @returns {NostrWSServer} The created server instance
+ */
+export function createWSServer(options) {
+    return new NostrWSServer(options);
+}

package/dist/core/queue.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Message queue implementation for WebSocket communication
+ * @module core/queue
+ */
+import { NostrWSMessage } from '../types/messages';
+/**
+ * Options for message queue configuration
+ */
+interface QueueOptions {
+    maxSize?: number;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+/**
+ * Message queue implementation with priority handling and retry logic
+ */
+export declare class MessageQueue {
+    private queue;
+    private maxSize;
+    private maxRetries;
+    private retryDelay;
+    constructor(options?: QueueOptions);
+    /**
+     * Adds a message to the queue with priority handling
+     * @param message Message to enqueue
+     * @returns true if message was added, false if queue is full
+     */
+    enqueue(message: NostrWSMessage): boolean;
+    /**
+     * Gets the next message from the queue
+     * @returns Next message or undefined if queue is empty
+     */
+    dequeue(): NostrWSMessage | undefined;
+    /**
+     * Handles message retry logic
+     * @param message Message that failed to send
+     * @returns true if message was requeued, false if max retries exceeded
+     */
+    retry(message: NostrWSMessage): Promise<boolean>;
+    /**
+     * Gets the current size of the queue
+     */
+    get size(): number;
+    /**
+     * Clears all messages from the queue
+     */
+    clear(): void;
+    /**
+     * Gets messages that have been in the queue longer than the specified duration
+     * @param duration Duration in milliseconds
+     * @returns Array of stale messages
+     */
+    getStaleMessages(duration: number): NostrWSMessage[];
+    /**
+     * Removes messages that have been in the queue longer than the specified duration
+     * @param duration Duration in milliseconds
+     * @returns Number of messages removed
+     */
+    removeStaleMessages(duration: number): number;
+}
+export {};

package/dist/core/queue.js

@@ -0,0 +1,108 @@
+/**
+ * @file Message queue implementation for WebSocket communication
+ * @module core/queue
+ */
+import { MessagePriority } from '../types/messages';
+import { getLogger } from '../utils/logger';
+const logger = getLogger('queue');
+/**
+ * Message queue implementation with priority handling and retry logic
+ */
+export class MessageQueue {
+    constructor(options = {}) {
+        this.queue = [];
+        this.maxSize = options.maxSize || 1000;
+        this.maxRetries = options.maxRetries || 3;
+        this.retryDelay = options.retryDelay || 1000;
+    }
+    /**
+     * Adds a message to the queue with priority handling
+     * @param message Message to enqueue
+     * @returns true if message was added, false if queue is full
+     */
+    enqueue(message) {
+        if (this.queue.length >= this.maxSize) {
+            logger.warn({ message }, 'Queue is full, message dropped');
+            return false;
+        }
+        const queuedMessage = {
+            ...message,
+            priority: message.priority || MessagePriority.MEDIUM,
+            queuedAt: Date.now(),
+            retryCount: 0
+        };
+        // Insert message in priority order
+        const insertIndex = this.queue.findIndex(m => (m.priority || MessagePriority.MEDIUM) > queuedMessage.priority);
+        if (insertIndex === -1) {
+            this.queue.push(queuedMessage);
+        }
+        else {
+            this.queue.splice(insertIndex, 0, queuedMessage);
+        }
+        logger.debug({ message: queuedMessage }, 'Message enqueued');
+        return true;
+    }
+    /**
+     * Gets the next message from the queue
+     * @returns Next message or undefined if queue is empty
+     */
+    dequeue() {
+        return this.queue.shift();
+    }
+    /**
+     * Handles message retry logic
+     * @param message Message that failed to send
+     * @returns true if message was requeued, false if max retries exceeded
+     */
+    async retry(message) {
+        const retryCount = (message.retryCount || 0) + 1;
+        if (retryCount > this.maxRetries) {
+            logger.warn({ message }, 'Max retries exceeded, message dropped');
+            return false;
+        }
+        // Wait before retrying
+        await new Promise(resolve => setTimeout(resolve, this.retryDelay * retryCount));
+        return this.enqueue({
+            ...message,
+            retryCount,
+            queuedAt: Date.now()
+        });
+    }
+    /**
+     * Gets the current size of the queue
+     */
+    get size() {
+        return this.queue.length;
+    }
+    /**
+     * Clears all messages from the queue
+     */
+    clear() {
+        this.queue = [];
+        logger.info('Queue cleared');
+    }
+    /**
+     * Gets messages that have been in the queue longer than the specified duration
+     * @param duration Duration in milliseconds
+     * @returns Array of stale messages
+     */
+    getStaleMessages(duration) {
+        const now = Date.now();
+        return this.queue.filter(message => message.queuedAt && (now - message.queuedAt) > duration);
+    }
+    /**
+     * Removes messages that have been in the queue longer than the specified duration
+     * @param duration Duration in milliseconds
+     * @returns Number of messages removed
+     */
+    removeStaleMessages(duration) {
+        const now = Date.now();
+        const initialSize = this.queue.length;
+        this.queue = this.queue.filter(message => message.queuedAt && (now - message.queuedAt) <= duration);
+        const removedCount = initialSize - this.queue.length;
+        if (removedCount > 0) {
+            logger.info({ removedCount }, 'Stale messages removed from queue');
+        }
+        return removedCount;
+    }
+}

package/dist/core/server.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file WebSocket server implementation
+ * @module core/server
+ */
+import { NostrWSServerOptions } from '../types/websocket';
+/**
+ * NostrWSServer class for handling WebSocket connections
+ */
+export declare class NostrWSServer {
+    private wss;
+    private options;
+    private rateLimiter?;
+    private pingInterval?;
+    constructor(options: NostrWSServerOptions);
+    /**
+     * Set up WebSocket server event handlers
+     */
+    private setupServer;
+    /**
+     * Start ping interval to check client connections
+     */
+    private startPingInterval;
+    /**
+     * Stop the server and clean up resources
+     */
+    stop(): void;
+}