nostr-websocket-utils 0.2.4 → 0.3.0

package/dist/types/websocket.js

@@ -0,0 +1,5 @@
+/**
+ * @file WebSocket type definitions and extensions
+ * @module types/websocket
+ */
+export {};

package/dist/utils/http.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file HTTP utility functions
+ * @module utils/http
+ */
+/**
+ * Fetches JSON data from a URL
+ * @param url URL to fetch from
+ * @returns Parsed JSON data
+ */
+export declare function fetchJson<T>(url: string): Promise<T>;

package/dist/utils/http.js

@@ -0,0 +1,24 @@
+/**
+ * @file HTTP utility functions
+ * @module utils/http
+ */
+import { getLogger } from './logger';
+const logger = getLogger('http');
+/**
+ * Fetches JSON data from a URL
+ * @param url URL to fetch from
+ * @returns Parsed JSON data
+ */
+export async function fetchJson(url) {
+    try {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        logger.error({ error, url }, 'Failed to fetch JSON');
+        throw error;
+    }
+}

package/dist/utils/logger.d.ts

@@ -1,2 +1,11 @@
-import winston from 'winston';
-export declare function getLogger(name?: string): winston.Logger;
+/**
+ * @file Logger utility
+ * @module utils/logger
+ */
+import { Logger } from '../types/logger';
+/**
+ * Creates a logger instance for a specific component
+ * @param component Component name for the logger
+ * @returns Logger instance
+ */
+export declare function getLogger(component: string): Logger;

package/dist/utils/logger.js

@@ -1,16 +1,21 @@
-import winston from 'winston';
-const logger = winston.createLogger({
+/**
+ * @file Logger utility
+ * @module utils/logger
+ */
+import pino from 'pino';
+const rootLogger = pino({
     level: process.env.LOG_LEVEL || 'info',
-    format: winston.format.combine(winston.format.timestamp(), winston.format.json()),
-    transports: [
-        new winston.transports.Console({
-            format: winston.format.combine(winston.format.colorize(), winston.format.simple())
-        })
-    ]
+    timestamp: true,
+    formatters: {
+        level: (label) => ({ level: label }),
+        bindings: (bindings) => bindings,
+    },
 });
-export function getLogger(name) {
-    if (name) {
-        return logger.child({ service: name });
-    }
-    return logger;
+/**
+ * Creates a logger instance for a specific component
+ * @param component Component name for the logger
+ * @returns Logger instance
+ */
+export function getLogger(component) {
+    return rootLogger.child({ component });
 }

package/dist/utils/metrics.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file Metrics tracking for Nostr WebSocket connections
+ * @module metrics
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+export interface RelayMetrics {
+    totalConnections: number;
+    activeConnections: number;
+    connectionErrors: number;
+    messagesReceived: number;
+    messagesSent: number;
+    bytesReceived: number;
+    bytesSent: number;
+    averageLatency: number;
+    maxLatency: number;
+    minLatency: number;
+    totalErrors: number;
+    lastError?: string;
+    eventsReceived: number;
+    eventsSent: number;
+    subscriptions: number;
+    uptime: number;
+    reliability: number;
+    lastSeen: number;
+    score: number;
+}
+export declare class RelayMetricsTracker extends EventEmitter {
+    private metrics;
+    private startTime;
+    constructor();
+    /**
+     * Get metrics for a specific relay
+     */
+    getRelayMetrics(relayUrl: string): RelayMetrics;
+    /**
+     * Get metrics for all relays
+     */
+    getAllMetrics(): Map<string, RelayMetrics>;
+    /**
+     * Initialize metrics for a new relay
+     */
+    private initializeMetrics;
+    /**
+     * Update connection metrics
+     */
+    trackConnection(relayUrl: string, connected: boolean): void;
+    /**
+     * Track message metrics
+     */
+    trackMessage(relayUrl: string, sent: boolean, bytes: number): void;
+    /**
+     * Track latency
+     */
+    trackLatency(relayUrl: string, latencyMs: number): void;
+    /**
+     * Track errors
+     */
+    trackError(relayUrl: string, error: Error): void;
+    /**
+     * Track protocol-specific events
+     */
+    trackProtocolEvent(relayUrl: string, type: 'event' | 'subscription', sent: boolean): void;
+    /**
+     * Calculate relay score based on metrics
+     */
+    private calculateScore;
+    /**
+     * Update scores for all relays
+     */
+    private updateScores;
+    /**
+     * Get high-value relays (score > threshold)
+     */
+    getHighValueRelays(threshold?: number): string[];
+    /**
+     * Export metrics in Prometheus format
+     */
+    getPrometheusMetrics(): string;
+}
+export declare const metricsTracker: RelayMetricsTracker;

package/dist/utils/metrics.js

@@ -0,0 +1,206 @@
+/**
+ * @file Metrics tracking for Nostr WebSocket connections
+ * @module metrics
+ */
+import { EventEmitter } from 'events';
+import { getLogger } from './logger';
+const logger = getLogger('RelayMetrics');
+export class RelayMetricsTracker extends EventEmitter {
+    constructor() {
+        super();
+        this.metrics = new Map();
+        this.startTime = Date.now();
+        // Periodically calculate scores
+        setInterval(() => this.updateScores(), 60000); // Every minute
+    }
+    /**
+     * Get metrics for a specific relay
+     */
+    getRelayMetrics(relayUrl) {
+        if (!this.metrics.has(relayUrl)) {
+            this.initializeMetrics(relayUrl);
+        }
+        return this.metrics.get(relayUrl);
+    }
+    /**
+     * Get metrics for all relays
+     */
+    getAllMetrics() {
+        return this.metrics;
+    }
+    /**
+     * Initialize metrics for a new relay
+     */
+    initializeMetrics(relayUrl) {
+        this.metrics.set(relayUrl, {
+            totalConnections: 0,
+            activeConnections: 0,
+            connectionErrors: 0,
+            messagesReceived: 0,
+            messagesSent: 0,
+            bytesReceived: 0,
+            bytesSent: 0,
+            averageLatency: 0,
+            maxLatency: 0,
+            minLatency: Infinity,
+            totalErrors: 0,
+            eventsReceived: 0,
+            eventsSent: 0,
+            subscriptions: 0,
+            uptime: 0,
+            reliability: 1,
+            lastSeen: Date.now(),
+            score: 100
+        });
+    }
+    /**
+     * Update connection metrics
+     */
+    trackConnection(relayUrl, connected) {
+        const metrics = this.getRelayMetrics(relayUrl);
+        if (connected) {
+            metrics.totalConnections++;
+            metrics.activeConnections++;
+            metrics.lastSeen = Date.now();
+        }
+        else {
+            metrics.activeConnections = Math.max(0, metrics.activeConnections - 1);
+        }
+        this.emit('metrics.update', relayUrl, metrics);
+    }
+    /**
+     * Track message metrics
+     */
+    trackMessage(relayUrl, sent, bytes) {
+        const metrics = this.getRelayMetrics(relayUrl);
+        if (sent) {
+            metrics.messagesSent++;
+            metrics.bytesSent += bytes;
+        }
+        else {
+            metrics.messagesReceived++;
+            metrics.bytesReceived += bytes;
+        }
+        metrics.lastSeen = Date.now();
+        this.emit('metrics.update', relayUrl, metrics);
+    }
+    /**
+     * Track latency
+     */
+    trackLatency(relayUrl, latencyMs) {
+        const metrics = this.getRelayMetrics(relayUrl);
+        metrics.maxLatency = Math.max(metrics.maxLatency, latencyMs);
+        metrics.minLatency = Math.min(metrics.minLatency, latencyMs);
+        // Exponential moving average for smoothing
+        metrics.averageLatency = metrics.averageLatency * 0.9 + latencyMs * 0.1;
+        this.emit('metrics.update', relayUrl, metrics);
+    }
+    /**
+     * Track errors
+     */
+    trackError(relayUrl, error) {
+        const metrics = this.getRelayMetrics(relayUrl);
+        metrics.totalErrors++;
+        metrics.lastError = error.message;
+        metrics.connectionErrors++;
+        this.emit('metrics.update', relayUrl, metrics);
+    }
+    /**
+     * Track protocol-specific events
+     */
+    trackProtocolEvent(relayUrl, type, sent) {
+        const metrics = this.getRelayMetrics(relayUrl);
+        if (type === 'event') {
+            sent ? metrics.eventsSent++ : metrics.eventsReceived++;
+        }
+        else if (type === 'subscription') {
+            metrics.subscriptions += sent ? 1 : -1;
+            metrics.subscriptions = Math.max(0, metrics.subscriptions);
+        }
+        this.emit('metrics.update', relayUrl, metrics);
+    }
+    /**
+     * Calculate relay score based on metrics
+     */
+    calculateScore(metrics) {
+        const now = Date.now();
+        // Calculate weighted scores for different aspects
+        const latencyScore = Math.max(0, 100 - (metrics.averageLatency / 10)); // Lower is better
+        const reliabilityScore = metrics.reliability * 100;
+        const uptimeScore = Math.min(100, (metrics.uptime / (60 * 60 * 24)) * 100); // Score based on 24h uptime
+        const errorScore = Math.max(0, 100 - (metrics.connectionErrors * 5)); // Each error reduces score by 5
+        const activityScore = metrics.lastSeen ? Math.max(0, 100 - ((now - metrics.lastSeen) / (60 * 1000))) : 0; // Activity in last hour
+        // Weighted average
+        return Math.round((latencyScore * 0.2) +
+            (reliabilityScore * 0.3) +
+            (uptimeScore * 0.2) +
+            (errorScore * 0.2) +
+            (activityScore * 0.1));
+    }
+    /**
+     * Update scores for all relays
+     */
+    updateScores() {
+        const now = Date.now();
+        for (const [url, metrics] of this.metrics.entries()) {
+            // Update uptime
+            metrics.uptime = (now - this.startTime) / 1000;
+            // Update reliability based on successful vs total connections
+            metrics.reliability = metrics.totalConnections > 0
+                ? 1 - (metrics.connectionErrors / metrics.totalConnections)
+                : 1;
+            // Calculate composite score
+            metrics.score = this.calculateScore(metrics);
+            this.emit('metrics.score', url, metrics.score);
+            logger.info({ url, score: metrics.score }, 'Updated relay score');
+        }
+    }
+    /**
+     * Get high-value relays (score > threshold)
+     */
+    getHighValueRelays(threshold = 70) {
+        return Array.from(this.metrics.entries())
+            .filter(([_, metrics]) => metrics.score >= threshold)
+            .map(([url]) => url);
+    }
+    /**
+     * Export metrics in Prometheus format
+     */
+    getPrometheusMetrics() {
+        const lines = [];
+        // Helper to format metric line
+        const formatMetric = (name, value, labels = {}) => {
+            const labelStr = Object.entries(labels)
+                .map(([k, v]) => `${k}="${v}"`)
+                .join(',');
+            lines.push(`nostr_${name}${labelStr ? `{${labelStr}}` : ''} ${value}`);
+        };
+        for (const [url, metrics] of this.metrics.entries()) {
+            const labels = { relay: url };
+            // Connection metrics
+            formatMetric('connections_total', metrics.totalConnections, labels);
+            formatMetric('connections_active', metrics.activeConnections, labels);
+            formatMetric('connection_errors_total', metrics.connectionErrors, labels);
+            // Message metrics
+            formatMetric('messages_received_total', metrics.messagesReceived, labels);
+            formatMetric('messages_sent_total', metrics.messagesSent, labels);
+            formatMetric('bytes_received_total', metrics.bytesReceived, labels);
+            formatMetric('bytes_sent_total', metrics.bytesSent, labels);
+            // Performance metrics
+            formatMetric('latency_average', metrics.averageLatency, labels);
+            formatMetric('latency_max', metrics.maxLatency, labels);
+            formatMetric('latency_min', metrics.minLatency, labels);
+            // Protocol metrics
+            formatMetric('events_received_total', metrics.eventsReceived, labels);
+            formatMetric('events_sent_total', metrics.eventsSent, labels);
+            formatMetric('subscriptions_active', metrics.subscriptions, labels);
+            // Scoring metrics
+            formatMetric('uptime_seconds', metrics.uptime, labels);
+            formatMetric('reliability_score', metrics.reliability, labels);
+            formatMetric('composite_score', metrics.score, labels);
+        }
+        return lines.join('\n') + '\n';
+    }
+}
+// Export singleton instance
+export const metricsTracker = new RelayMetricsTracker();

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @file WebSocket Rate Limiter
+ * @module utils/rate-limiter
+ */
+import type { NostrWSMessage } from '../types/messages';
+import type { Logger } from '../types/logger';
+/**
+ * Rate limit configuration for different message types
+ */
+export interface RateLimitConfig {
+    windowMs: number;
+    maxRequests: number;
+    blockDurationMs?: number;
+}
+/**
+ * Client state for rate limiting
+ */
+interface ClientState {
+    requests: Map<string, number[]>;
+    blockedUntil?: number;
+}
+/**
+ * Rate limiter interface
+ */
+export interface RateLimiter {
+    shouldLimit(clientId: string, message: NostrWSMessage): Promise<boolean>;
+    recordRequest(clientId: string, message: NostrWSMessage): void;
+    getRemainingRequests(clientId: string, messageType: string): number;
+    isBlocked(clientId: string): boolean;
+    getClientState(clientId: string): ClientState;
+}
+/**
+ * Rate limit rules for different event types
+ */
+export declare const DEFAULT_RATE_LIMITS: Record<string, RateLimitConfig>;
+/**
+ * Creates a rate limiter
+ * @param config - Rate limit configuration
+ * @param _logger - Logger instance
+ * @returns {RateLimiter} Rate limiter
+ */
+export declare function createRateLimiter(config: Record<string, RateLimitConfig> | undefined, _logger: Logger): RateLimiter;
+/**
+ * WebSocket connection rate limiter interface
+ */
+export interface ConnectionRateLimiter {
+    /**
+     * Checks if a new connection should be allowed
+     * @param clientId - Client identifier
+     * @returns {Promise<boolean>} True if connection is allowed
+     */
+    allowConnection(clientId: string): Promise<boolean>;
+    /**
+     * Records a connection attempt
+     * @param clientId - Client identifier
+     * @param successful - Whether connection was successful
+     */
+    recordConnection(clientId: string, successful: boolean): void;
+}
+/**
+ * Creates a connection rate limiter
+ * @param config - Connection limit configuration
+ * @param logger - Logger instance
+ * @returns {ConnectionRateLimiter} Connection rate limiter
+ */
+export declare function createConnectionRateLimiter(config: {
+    maxConnectionsPerMinute: number;
+    maxConcurrentConnections: number;
+    blockAfterFailures: number;
+    blockDurationMs: number;
+}, logger: Logger): ConnectionRateLimiter;
+/**
+ * Rate limiter implementation
+ */
+export declare class RateLimiterImpl implements RateLimiter {
+    private clients;
+    private config;
+    constructor(config: RateLimitConfig);
+    getClientState(clientId: string): ClientState;
+    shouldLimit(clientId: string, message: NostrWSMessage): Promise<boolean>;
+    recordRequest(clientId: string, message: NostrWSMessage): void;
+    getRemainingRequests(clientId: string, messageType: string): number;
+    isBlocked(clientId: string): boolean;
+}
+export {};

package/dist/utils/rate-limiter.js

@@ -0,0 +1,175 @@
+/**
+ * @file WebSocket Rate Limiter
+ * @module utils/rate-limiter
+ */
+/**
+ * Rate limit rules for different event types
+ */
+export const DEFAULT_RATE_LIMITS = {
+    EVENT: {
+        windowMs: 60000, // 1 minute
+        maxRequests: 60,
+        blockDurationMs: 300000 // 5 minutes
+    },
+    REQ: {
+        windowMs: 60000,
+        maxRequests: 30,
+        blockDurationMs: 300000
+    },
+    CLOSE: {
+        windowMs: 60000,
+        maxRequests: 50
+    },
+    AUTH: {
+        windowMs: 300000, // 5 minutes
+        maxRequests: 10,
+        blockDurationMs: 900000 // 15 minutes
+    }
+};
+/**
+ * Creates a rate limiter
+ * @param config - Rate limit configuration
+ * @param _logger - Logger instance
+ * @returns {RateLimiter} Rate limiter
+ */
+export function createRateLimiter(config = DEFAULT_RATE_LIMITS, _logger) {
+    return new RateLimiterImpl(config.EVENT || {
+        windowMs: 60000,
+        maxRequests: 100,
+        blockDurationMs: 300000
+    });
+}
+/**
+ * Creates a connection rate limiter
+ * @param config - Connection limit configuration
+ * @param logger - Logger instance
+ * @returns {ConnectionRateLimiter} Connection rate limiter
+ */
+export function createConnectionRateLimiter(config, logger) {
+    const clients = new Map();
+    function cleanOldAttempts(attempts) {
+        const now = Date.now();
+        return attempts.filter(attempt => now - attempt.timestamp < 60000);
+    }
+    return {
+        async allowConnection(clientId) {
+            const now = Date.now();
+            const state = clients.get(clientId) || {
+                attempts: [],
+                currentConnections: 0
+            };
+            // Check if blocked
+            if (state.blockedUntil && now < state.blockedUntil) {
+                logger.debug('Connection blocked', {
+                    clientId,
+                    until: new Date(state.blockedUntil)
+                });
+                return false;
+            }
+            // Clean old attempts
+            state.attempts = cleanOldAttempts(state.attempts);
+            // Check rate limits
+            if (state.attempts.length >= config.maxConnectionsPerMinute) {
+                logger.debug('Too many connection attempts', {
+                    clientId,
+                    attempts: state.attempts.length
+                });
+                return false;
+            }
+            // Check concurrent connections
+            if (state.currentConnections >= config.maxConcurrentConnections) {
+                logger.debug('Too many concurrent connections', {
+                    clientId,
+                    connections: state.currentConnections
+                });
+                return false;
+            }
+            // Check failure rate
+            const recentFailures = state.attempts.filter(a => !a.successful).length;
+            if (recentFailures >= config.blockAfterFailures) {
+                state.blockedUntil = now + config.blockDurationMs;
+                clients.set(clientId, state);
+                logger.debug('Client blocked due to failures', {
+                    clientId,
+                    failures: recentFailures,
+                    until: new Date(state.blockedUntil)
+                });
+                return false;
+            }
+            return true;
+        },
+        recordConnection(clientId, successful) {
+            const state = clients.get(clientId) || {
+                attempts: [],
+                currentConnections: 0
+            };
+            state.attempts.push({
+                timestamp: Date.now(),
+                successful
+            });
+            if (successful) {
+                state.currentConnections++;
+            }
+            clients.set(clientId, state);
+        }
+    };
+}
+/**
+ * Rate limiter implementation
+ */
+export class RateLimiterImpl {
+    constructor(config) {
+        this.clients = new Map();
+        this.config = {
+            windowMs: config.windowMs || 60000,
+            maxRequests: config.maxRequests || 100,
+            blockDurationMs: config.blockDurationMs || 300000
+        };
+    }
+    getClientState(clientId) {
+        let state = this.clients.get(clientId);
+        if (!state) {
+            state = { requests: new Map() };
+            this.clients.set(clientId, state);
+        }
+        return state;
+    }
+    async shouldLimit(clientId, message) {
+        const now = Date.now();
+        const state = this.getClientState(clientId);
+        // Check if client is blocked
+        if (state.blockedUntil && state.blockedUntil > now) {
+            return true;
+        }
+        // Get requests for message type
+        const requests = state.requests.get(message.type) || [];
+        const validRequests = requests.filter(time => time > now - this.config.windowMs);
+        // Update requests
+        state.requests.set(message.type, validRequests);
+        // Check if limit exceeded
+        if (validRequests.length >= this.config.maxRequests) {
+            state.blockedUntil = now + this.config.blockDurationMs;
+            return true;
+        }
+        // Add new request
+        validRequests.push(now);
+        return false;
+    }
+    recordRequest(clientId, message) {
+        const state = this.getClientState(clientId);
+        const requests = state.requests.get(message.type) || [];
+        requests.push(Date.now());
+        state.requests.set(message.type, requests);
+    }
+    getRemainingRequests(clientId, messageType) {
+        const state = this.getClientState(clientId);
+        const now = Date.now();
+        const requests = state.requests.get(messageType) || [];
+        const validRequests = requests.filter(time => time > now - this.config.windowMs);
+        return Math.max(0, this.config.maxRequests - validRequests.length);
+    }
+    isBlocked(clientId) {
+        const state = this.getClientState(clientId);
+        return !!state.blockedUntil && state.blockedUntil > Date.now();
+    }
+}