nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/server.js

@@ -1,50 +1,59 @@
-import { EventEmitter } from 'events';
 import { WebSocket } from 'ws';
+import { EventEmitter } from 'events';
 import { v4 as uuidv4 } from 'uuid';
+/**
+ * WebSocket server implementation for Nostr protocol
+ * Extends EventEmitter to provide event-based message handling
+ */
 export class NostrWSServer extends EventEmitter {
     constructor(wss, options = {}) {
         super();
-        this.heartbeatInterval = null;
+        this.wss = null;
         this.clients = new Map();
+        this.heartbeatInterval = null;
         if (!options.logger) {
             throw new Error('Logger is required');
         }
-        if (!options.handlers?.message) {
-            throw new Error('Message handler is required');
-        }
+        this.wss = wss;
         this.options = {
-            heartbeatInterval: options.heartbeatInterval || 30000,
+            heartbeatInterval: 30000,
             logger: options.logger,
-            WebSocketImpl: options.WebSocketImpl || WebSocket,
+            WebSocketImpl: WebSocket,
+            ...options,
             handlers: {
-                message: options.handlers.message,
-                error: options.handlers.error || (() => { }),
-                close: options.handlers.close || (() => { })
-            }
+                message: async (_ws, _message) => { },
+                ...options.handlers,
+            },
         };
-        this.wss = wss;
         this.setupServer();
     }
     setupServer() {
+        if (!this.wss)
+            return;
         this.wss.on('connection', (ws) => {
-            this.handleConnection(ws);
+            const extWs = ws;
+            this.handleConnection(extWs);
         });
-        if (this.options.heartbeatInterval && this.options.heartbeatInterval > 0) {
+        if (this.options.heartbeatInterval) {
             this.startHeartbeat();
         }
     }
     handleConnection(ws) {
         ws.isAlive = true;
         ws.subscriptions = new Set();
-        ws.clientId = ws.clientId || uuidv4();
+        ws.clientId = uuidv4();
+        ws.messageQueue = [];
         this.clients.set(ws.clientId, ws);
         ws.on('message', async (data) => {
             try {
                 const message = JSON.parse(data.toString());
-                await this.options.handlers.message(ws, message);
+                if (this.options.handlers?.message) {
+                    await this.options.handlers.message(ws, message);
+                }
             }
             catch (error) {
-                if (this.options.handlers.error) {
+                this.options.logger.error('Error handling message:', error);
+                if (this.options.handlers?.error) {
                     this.options.handlers.error(ws, error);
                 }
             }
@@ -53,35 +62,39 @@ export class NostrWSServer extends EventEmitter {
             if (ws.clientId) {
                 this.clients.delete(ws.clientId);
             }
-            if (this.options.handlers.close) {
+            if (this.options.handlers?.close) {
                 this.options.handlers.close(ws);
             }
         });
         ws.on('error', (error) => {
-            if (ws.clientId) {
-                this.clients.delete(ws.clientId);
-            }
-            if (this.options.handlers.error) {
+            this.options.logger.error('WebSocket error:', error);
+            if (this.options.handlers?.error) {
                 this.options.handlers.error(ws, error);
             }
         });
     }
     startHeartbeat() {
+        if (this.heartbeatInterval)
+            return;
         this.heartbeatInterval = setInterval(() => {
-            this.wss.clients.forEach((ws) => {
-                const extWs = ws;
-                if (!extWs.isAlive) {
-                    extWs.terminate();
-                    return;
-                }
-                extWs.isAlive = false;
-                if (ws.readyState === WebSocket.OPEN) {
-                    ws.ping();
+            if (!this.wss)
+                return;
+            this.wss.clients.forEach((client) => {
+                const extClient = client;
+                if (extClient.isAlive === false) {
+                    if (extClient.clientId) {
+                        this.clients.delete(extClient.clientId);
+                    }
+                    return extClient.terminate();
                 }
+                extClient.isAlive = false;
+                extClient.ping();
             });
         }, this.options.heartbeatInterval);
     }
     broadcast(message) {
+        if (!this.wss)
+            return;
         this.wss.clients.forEach((client) => {
             if (client.readyState === WebSocket.OPEN) {
                 client.send(JSON.stringify(message));
@@ -89,17 +102,31 @@ export class NostrWSServer extends EventEmitter {
         });
     }
     broadcastToChannel(channel, message) {
+        if (!this.wss)
+            return;
         this.wss.clients.forEach((ws) => {
             const extWs = ws;
             if (extWs.readyState === WebSocket.OPEN && extWs.subscriptions?.has(channel)) {
-                ws.send(JSON.stringify(message));
+                extWs.send(JSON.stringify(message));
             }
         });
     }
     close() {
         if (this.heartbeatInterval) {
             clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
         }
-        this.wss.close();
+        if (this.wss) {
+            this.wss.close();
+            this.wss = null;
+        }
+    }
+    /**
+     * Check if a client with the given ID exists
+     * @param clientId - The ID of the client to check
+     * @returns boolean indicating if the client exists
+     */
+    hasClient(clientId) {
+        return this.clients.has(clientId);
     }
 }

package/dist/transport/base.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Base transport layer for Nostr connections
+ * @module transport/base
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import type { MetricsProvider, ScoringStrategy } from '../types/scoring';
+export interface TransportOptions {
+    metricsProvider?: MetricsProvider;
+    scoringStrategy?: ScoringStrategy;
+    metricsEnabled?: boolean;
+}
+export declare abstract class BaseTransport extends EventEmitter {
+    protected scoringStrategy: ScoringStrategy;
+    protected metricsProvider?: MetricsProvider;
+    protected metricsEnabled: boolean;
+    constructor(options?: TransportOptions);
+    /**
+     * Create a default metrics provider if none is supplied
+     */
+    protected createDefaultMetricsProvider(): MetricsProvider;
+    /**
+     * Track a metric update
+     */
+    protected trackMetric(endpoint: string, metricType: string, value: any): void;
+    /**
+     * Gets the score for an endpoint
+     * @param endpoint - Endpoint to get score for
+     * @returns {number} Score between 0 and 100
+     */
+    getScore(endpoint: string): number;
+    /**
+     * Gets scores for all endpoints
+     * @returns {Map<string, number>} Map of endpoint scores
+     */
+    getAllScores(): Map<string, number>;
+    /**
+     * Enable/disable metrics
+     */
+    setMetricsEnabled(enabled: boolean): void;
+    /**
+     * Updates the scoring strategy
+     * @param strategy - New scoring strategy
+     */
+    updateScoringStrategy(strategy: ScoringStrategy): void;
+    /**
+     * Updates the metrics provider
+     * @param provider - New metrics provider
+     */
+    updateMetricsProvider(provider?: MetricsProvider): void;
+    abstract connect(endpoint: string): Promise<void>;
+    abstract disconnect(endpoint: string): Promise<void>;
+    abstract send(endpoint: string, data: any): Promise<void>;
+}

package/dist/transport/base.js

@@ -0,0 +1,104 @@
+/**
+ * @file Base transport layer for Nostr connections
+ * @module transport/base
+ */
+import { EventEmitter } from 'events';
+import { getLogger } from '../utils/logger';
+import { DefaultScoringStrategy } from '../types/scoring';
+const logger = getLogger('BaseTransport');
+export class BaseTransport extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.scoringStrategy = options.scoringStrategy ?? new DefaultScoringStrategy();
+        this.metricsProvider = options.metricsProvider;
+        this.metricsEnabled = !!this.metricsProvider;
+    }
+    /**
+     * Create a default metrics provider if none is supplied
+     */
+    createDefaultMetricsProvider() {
+        return {
+            getMetrics: () => ({
+                totalConnections: 0,
+                activeConnections: 0,
+                connectionErrors: 0,
+                messagesReceived: 0,
+                messagesSent: 0,
+                bytesReceived: 0,
+                bytesSent: 0,
+                averageLatency: 0,
+                lastSeen: Date.now()
+            }),
+            getAllMetrics: () => new Map(),
+            trackMetric: () => { }
+        };
+    }
+    /**
+     * Track a metric update
+     */
+    trackMetric(endpoint, metricType, value) {
+        if (!this.metricsEnabled)
+            return;
+        try {
+            this.metricsProvider?.trackMetric(endpoint, metricType, value);
+            const event = {
+                endpoint,
+                metricType,
+                value,
+                timestamp: Date.now()
+            };
+            this.emit('metric', event);
+        }
+        catch (error) {
+            logger.error({ error, endpoint, metricType }, 'Error tracking metric');
+        }
+    }
+    /**
+     * Gets the score for an endpoint
+     * @param endpoint - Endpoint to get score for
+     * @returns {number} Score between 0 and 100
+     */
+    getScore(endpoint) {
+        if (!this.metricsEnabled)
+            return 100;
+        const metrics = this.metricsProvider?.getMetrics(endpoint);
+        if (!metrics)
+            return 100;
+        return this.scoringStrategy.calculateScore(metrics);
+    }
+    /**
+     * Gets scores for all endpoints
+     * @returns {Map<string, number>} Map of endpoint scores
+     */
+    getAllScores() {
+        if (!this.metricsEnabled || !this.metricsProvider)
+            return new Map();
+        const scores = new Map();
+        const allMetrics = this.metricsProvider.getAllMetrics();
+        for (const [endpoint, metrics] of allMetrics) {
+            scores.set(endpoint, this.scoringStrategy.calculateScore(metrics));
+        }
+        return scores;
+    }
+    /**
+     * Enable/disable metrics
+     */
+    setMetricsEnabled(enabled) {
+        this.metricsEnabled = enabled;
+    }
+    /**
+     * Updates the scoring strategy
+     * @param strategy - New scoring strategy
+     */
+    updateScoringStrategy(strategy) {
+        this.scoringStrategy = strategy;
+    }
+    /**
+     * Updates the metrics provider
+     * @param provider - New metrics provider
+     */
+    updateMetricsProvider(provider) {
+        this.metricsProvider = provider;
+        this.metricsEnabled = !!provider;
+    }
+}

package/dist/transport/websocket.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file WebSocket transport implementation
+ * @module transport/websocket
+ */
+import { BaseTransport } from './base';
+import type { TransportOptions } from './base';
+export declare class WebSocketTransport extends BaseTransport {
+    private connections;
+    constructor(options?: TransportOptions);
+    connect(endpoint: string): Promise<void>;
+    disconnect(endpoint: string): Promise<void>;
+    send(endpoint: string, data: any): Promise<void>;
+    private checkEndpointHealth;
+    /**
+     * Get all active WebSocket connections
+     */
+    getActiveConnections(): string[];
+    /**
+     * Check if connected to endpoint
+     */
+    isConnected(endpoint: string): boolean;
+}

package/dist/transport/websocket.js

@@ -0,0 +1,122 @@
+/**
+ * @file WebSocket transport implementation
+ * @module transport/websocket
+ */
+import WebSocket from 'ws';
+import { BaseTransport } from './base';
+import { getLogger } from '../utils/logger';
+const logger = getLogger('WebSocketTransport');
+export class WebSocketTransport extends BaseTransport {
+    constructor(options = {}) {
+        super(options);
+        this.connections = new Map();
+    }
+    async connect(endpoint) {
+        if (this.connections.has(endpoint)) {
+            logger.warn({ endpoint }, 'Already connected to endpoint');
+            return;
+        }
+        try {
+            const ws = new WebSocket(endpoint);
+            ws.on('open', () => {
+                this.trackMetric(endpoint, 'connection', true);
+                this.trackMetric(endpoint, 'openHandshake', Date.now());
+            });
+            ws.on('close', () => {
+                this.trackMetric(endpoint, 'connection', false);
+                this.trackMetric(endpoint, 'closeHandshake', Date.now());
+                this.connections.delete(endpoint);
+            });
+            ws.on('message', (data) => {
+                const length = data instanceof Buffer ? data.length :
+                    data instanceof ArrayBuffer ? data.byteLength :
+                        data instanceof Array ? data.reduce((acc, buf) => acc + buf.length, 0) : 0;
+                this.trackMetric(endpoint, 'messageReceived', length);
+            });
+            ws.on('error', (error) => {
+                this.trackMetric(endpoint, 'error', error);
+                logger.error({ error, endpoint }, 'WebSocket error');
+            });
+            // Track ping/pong for latency
+            ws.on('ping', () => {
+                this.trackMetric(endpoint, 'ping', Date.now());
+            });
+            ws.on('pong', () => {
+                if (!this.metricsEnabled || !this.metricsProvider)
+                    return;
+                const now = Date.now();
+                const metrics = this.metricsProvider.getMetrics(endpoint);
+                if (!metrics || !metrics.lastSeen)
+                    return;
+                this.trackMetric(endpoint, 'latency', now - metrics.lastSeen);
+            });
+            this.connections.set(endpoint, ws);
+        }
+        catch (error) {
+            this.trackMetric(endpoint, 'connectionError', error);
+            throw error;
+        }
+    }
+    async disconnect(endpoint) {
+        const ws = this.connections.get(endpoint);
+        if (!ws)
+            return;
+        return new Promise((resolve, reject) => {
+            ws.close();
+            ws.on('close', () => {
+                this.connections.delete(endpoint);
+                resolve();
+            });
+            ws.on('error', reject);
+        });
+    }
+    async send(endpoint, data) {
+        const ws = this.connections.get(endpoint);
+        if (!ws)
+            throw new Error(`Not connected to ${endpoint}`);
+        return new Promise((resolve, reject) => {
+            ws.send(data, (error) => {
+                if (error) {
+                    this.trackMetric(endpoint, 'sendError', error);
+                    reject(error);
+                }
+                else {
+                    this.trackMetric(endpoint, 'messageSent', data.length);
+                    resolve();
+                }
+            });
+        });
+    }
+    async checkEndpointHealth(endpoint) {
+        try {
+            if (!this.metricsEnabled || !this.metricsProvider) {
+                return true;
+            }
+            const metrics = this.metricsProvider.getMetrics(endpoint);
+            if (!metrics || !metrics.lastSeen) {
+                return true;
+            }
+            const now = Date.now();
+            const elapsed = now - metrics.lastSeen;
+            // If we haven't seen a ping response in 30 seconds, consider unhealthy
+            return elapsed < 30000;
+        }
+        catch (error) {
+            logger.error('Error checking endpoint health:', error);
+            return false;
+        }
+    }
+    /**
+     * Get all active WebSocket connections
+     */
+    getActiveConnections() {
+        return Array.from(this.connections.keys());
+    }
+    /**
+     * Check if connected to endpoint
+     */
+    isConnected(endpoint) {
+        const ws = this.connections.get(endpoint);
+        return ws?.readyState === WebSocket.OPEN;
+    }
+}

package/dist/types/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @file Event type definitions
+ * @module types/events
+ */
+/**
+ * Base Nostr event interface following NIP-01 specification
+ * @see https://github.com/nostr-protocol/nips/blob/master/01.md
+ */
+export interface NostrEvent {
+    /** Event ID in hex format */
+    id: string;
+    /** Public key of the event creator in hex format */
+    pubkey: string;
+    /** Unix timestamp in seconds */
+    created_at: number;
+    /** Event kind number */
+    kind: number;
+    /** Array of tags */
+    tags: string[][];
+    /** Event content */
+    content: string;
+    /** Signature of the event data in hex format */
+    sig: string;
+}
+/**
+ * Signed Nostr event with id and signature
+ * @extends NostrEvent
+ */
+export interface SignedNostrEvent extends NostrEvent {
+    /** Event ID in hex format */
+    id: string;
+    /** Signature of the event data in hex format */
+    sig: string;
+}
+/**
+ * Event validation result
+ */
+export interface NostrEventValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Event subscription filter
+ */
+export interface NostrEventFilter {
+    ids?: string[];
+    authors?: string[];
+    kinds?: number[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    [key: string]: unknown;
+}
+/**
+ * Nostr subscription event interface
+ * Used for creating subscription messages to relays
+ */
+export interface NostrSubscriptionEvent {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** Array of filters */
+    filters: NostrEventFilter[];
+}

package/dist/types/events.js

@@ -0,0 +1,5 @@
+/**
+ * @file Event type definitions
+ * @module types/events
+ */
+export {};

package/dist/types/filters.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Filter type definitions
+ * @module types/filters
+ */
+import { NostrEventFilter } from './events';
+/**
+ * Subscription request filter
+ */
+export interface NostrSubscriptionFilter extends NostrEventFilter {
+    subscriptionId?: string;
+    limit?: number;
+}
+/**
+ * Filter validation result
+ */
+export interface NostrFilterValidationResult {
+    valid: boolean;
+    error?: string;
+}

package/dist/types/filters.js

@@ -0,0 +1,5 @@
+/**
+ * @file Filter type definitions
+ * @module types/filters
+ */
+export {};

package/dist/types/handlers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file Handler type definitions for WebSocket events
+ * @module types/handlers
+ */
+import type { WebSocket } from 'ws';
+import type { NostrWSMessage } from './messages';
+import type { ExtendedWebSocket } from './websocket';
+/**
+ * Events emitted by the NostrWSClient
+ * @interface NostrWSClientEvents
+ */
+export interface NostrWSClientEvents {
+    /**
+     * Emitted when the client connects to the relay
+     */
+    connect: () => void;
+    /**
+     * Emitted when the client disconnects from the relay
+     */
+    disconnect: () => void;
+    /**
+     * Emitted when the client reconnects to the relay
+     */
+    reconnect: () => void;
+    /**
+     * Emitted when a message is received from the relay
+     * @param message - The received message
+     */
+    message: (message: NostrWSMessage) => void;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error object
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Events emitted by the NostrWSServer
+ * @interface NostrWSServerEvents
+ */
+export interface NostrWSServerEvents {
+    /**
+     * Emitted when a client connects to the server
+     * @param client - The connected client
+     */
+    connection: (client: ExtendedWebSocket) => void;
+    /**
+     * Emitted when a message is received from a client
+     * @param message - The received message
+     * @param client - The client that sent the message
+     */
+    message: (message: NostrWSMessage, client: ExtendedWebSocket) => void;
+    /**
+     * Emitted when an error occurs
+     * @param error - The error object
+     */
+    error: (error: Error) => void;
+}
+/**
+ * Configuration options for WebSocket handlers
+ * @interface NostrWSHandlers
+ */
+export interface NostrWSHandlers {
+    /**
+     * Handler for incoming messages
+     * @param ws - The WebSocket instance
+     * @param message - The received message
+     */
+    message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+    /**
+     * Handler for WebSocket errors
+     * @param ws - The WebSocket instance
+     * @param error - The error object
+     */
+    error?: (ws: WebSocket, error: Error) => void;
+    /**
+     * Handler for WebSocket connection close
+     * @param ws - The WebSocket instance
+     */
+    close?: (ws: WebSocket) => void;
+}

package/dist/types/handlers.js

@@ -0,0 +1,5 @@
+/**
+ * @file Handler type definitions for WebSocket events
+ * @module types/handlers
+ */
+export {};