ocpp-ws-io 2.1.3 → 2.1.4

package/dist/index.js

@@ -32,6 +32,7 @@ var src_exports = {};
 __export(src_exports, {
   ConnectionState: () => ConnectionState,
   InMemoryAdapter: () => InMemoryAdapter,
+  LRUMap: () => LRUMap,
   MessageType: () => MessageType,
   MiddlewareStack: () => MiddlewareStack,
   NOREPLY: () => NOREPLY,
@@ -119,6 +120,11 @@ var InMemoryAdapter = class {
   async removePresence(identity) {
     this._presence.delete(identity);
   }
+  async setPresenceBatch(entries) {
+    for (const { identity, nodeId } of entries) {
+      this._presence.set(identity, nodeId);
+    }
+  }
 };
 function defineAdapter(adapter) {
   return adapter;
@@ -234,6 +240,25 @@ var IoRedisDriver = class {
     };
     await Promise.all([close(this.pub), close(this.sub)]);
   }
+  async setPresenceBatch(entries) {
+    if (entries.length === 0) return;
+    const pipeline = this.pub.pipeline();
+    for (const { key, value, ttlSeconds } of entries) {
+      pipeline.set(key, value, "EX", ttlSeconds);
+    }
+    await pipeline.exec();
+  }
+  async expire(key, ttlSeconds) {
+    await this.pub.expire(key, ttlSeconds);
+  }
+  onError(handler) {
+    this.pub.on("error", handler);
+    return () => this.pub.removeListener("error", handler);
+  }
+  onReconnect(handler) {
+    this.pub.on("connect", handler);
+    return () => this.pub.removeListener("connect", handler);
+  }
 };
 var NodeRedisDriver = class {
   constructor(pub, sub, blocking) {
@@ -320,6 +345,25 @@ var NodeRedisDriver = class {
   async disconnect() {
     await Promise.all([this.pub.disconnect(), this.sub.disconnect()]);
   }
+  async setPresenceBatch(entries) {
+    if (entries.length === 0) return;
+    const multi = this.pub.multi();
+    for (const { key, value, ttlSeconds } of entries) {
+      multi.set(key, value, { EX: ttlSeconds });
+    }
+    await multi.exec();
+  }
+  async expire(key, ttlSeconds) {
+    await this.pub.expire(key, ttlSeconds);
+  }
+  onError(handler) {
+    this.pub.on("error", handler);
+    return () => this.pub.removeListener("error", handler);
+  }
+  onReconnect(handler) {
+    this.pub.on("connect", handler);
+    return () => this.pub.removeListener("connect", handler);
+  }
 };
 function createDriver(pub, sub, blocking) {
   if (sub.isOpen !== void 0 && typeof sub.subscribe === "function") {
@@ -333,6 +377,8 @@ var RedisAdapter = class {
   _driver;
   _prefix;
   _streamMaxLen;
+  _streamTtlSeconds;
+  _presenceTtlSeconds;
   _handlers = /* @__PURE__ */ new Map();
   _streamOffsets = /* @__PURE__ */ new Map();
   // streamKey -> lastId
@@ -340,20 +386,48 @@ var RedisAdapter = class {
   // Active streams to poll
   _polling = false;
   _closed = false;
+  // C4: Per-stream sequence counter for message ordering
+  _sequenceCounters = /* @__PURE__ */ new Map();
+  // C3: Rehydration callbacks
+  _unsubError;
+  _unsubReconnect;
+  // Stored presence entries for rehydration on reconnect
+  _presenceCache = /* @__PURE__ */ new Map();
   constructor(options) {
     this._prefix = options.prefix ?? "ocpp-ws-io:";
     this._streamMaxLen = options.streamMaxLen ?? 1e3;
+    this._streamTtlSeconds = options.streamTtlSeconds ?? 300;
+    this._presenceTtlSeconds = options.presenceTtlSeconds ?? 300;
     this._driver = createDriver(
       options.pubClient,
       options.subClient,
       options.blockingClient
     );
+    if (this._driver.onError) {
+      this._unsubError = this._driver.onError((err) => {
+        console.error("[RedisAdapter] Redis error:", err.message);
+      });
+    }
+    if (this._driver.onReconnect) {
+      this._unsubReconnect = this._driver.onReconnect(() => {
+        this._rehydratePresence().catch(() => {
+        });
+      });
+    }
   }
   async publish(channel, data) {
     const prefixedChannel = this._prefix + channel;
+    const payload = data;
+    if (payload && typeof payload === "object" && channel.startsWith("ocpp:node:")) {
+      const seq = (this._sequenceCounters.get(channel) ?? 0) + 1;
+      this._sequenceCounters.set(channel, seq);
+      payload.__seq = seq;
+    }
     const message = JSON.stringify(data);
     if (channel.startsWith("ocpp:node:")) {
       await this._driver.xadd(prefixedChannel, { message }, this._streamMaxLen);
+      await this._driver.expire(prefixedChannel, this._streamTtlSeconds).catch(() => {
+      });
     } else {
       await this._driver.publish(prefixedChannel, message);
     }
@@ -419,6 +493,10 @@ var RedisAdapter = class {
     this._closed = true;
     this._handlers.clear();
     this._streams.clear();
+    this._presenceCache.clear();
+    this._sequenceCounters.clear();
+    if (this._unsubError) this._unsubError();
+    if (this._unsubReconnect) this._unsubReconnect();
     await this._driver.disconnect();
   }
   _handleMessage(channel, message) {
@@ -478,6 +556,7 @@ var RedisAdapter = class {
   // ─── Presence Registry ─────────────────────────────────────────────
   async setPresence(identity, nodeId, ttl) {
     const key = `${this._prefix}presence:${identity}`;
+    this._presenceCache.set(identity, { nodeId, ttl });
     await this._driver.set(key, nodeId, ttl);
   }
   async getPresence(identity) {
@@ -515,6 +594,37 @@ var RedisAdapter = class {
       streamDetails
     };
   }
+  // ─── C1: Batch Presence Pipeline ────────────────────────────────────
+  /**
+   * Set multiple presence entries in a single Redis pipeline.
+   * Reduces N network round-trips to 1 for bulk presence updates.
+   */
+  async setPresenceBatch(entries) {
+    if (entries.length === 0) return;
+    const batchEntries = entries.map(({ identity, nodeId, ttl }) => {
+      const key = `${this._prefix}presence:${identity}`;
+      const ttlSeconds = ttl ?? this._presenceTtlSeconds;
+      this._presenceCache.set(identity, { nodeId, ttl: ttlSeconds });
+      return { key, value: nodeId, ttlSeconds };
+    });
+    await this._driver.setPresenceBatch(batchEntries);
+  }
+  // ─── C3: Redis Failure Rehydration ──────────────────────────────────
+  /**
+   * Re-syncs all cached presence entries to Redis after a reconnection.
+   * Called automatically when the Redis client reconnects.
+   */
+  async _rehydratePresence() {
+    if (this._presenceCache.size === 0) return;
+    const entries = Array.from(this._presenceCache.entries()).map(
+      ([identity, { nodeId, ttl }]) => ({
+        key: `${this._prefix}presence:${identity}`,
+        value: nodeId,
+        ttlSeconds: ttl
+      })
+    );
+    await this._driver.setPresenceBatch(entries);
+  }
 };
 
 // src/client.ts
@@ -37095,6 +37205,7 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
   _badMessageCount = 0;
   _lastActivity = 0;
   _outboundBuffer = [];
+  _offlineQueue = [];
   _middleware;
   _validators = [];
   _strictProtocols = null;
@@ -37249,6 +37360,7 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
         }
         this._attachWebsocket(ws);
         this._startPing();
+        this._flushOfflineQueue();
         if (this._outboundBuffer.length > 0) {
           const buffer = this._outboundBuffer;
           this._outboundBuffer = [];
@@ -37430,8 +37542,32 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
       options = args[2] ?? {};
     }
     if (this._state !== OPEN) {
+      if (this._options.offlineQueue && (this._state === CLOSED || this._state === CONNECTING)) {
+        return new Promise((resolve, reject) => {
+          const maxSize = this._options.offlineQueueMaxSize ?? 100;
+          if (this._offlineQueue.length >= maxSize) {
+            this._offlineQueue.shift();
+            this._logger?.warn?.(
+              "Offline queue full \u2014 dropping oldest message",
+              {
+                method,
+                queueSize: this._offlineQueue.length
+              }
+            );
+          }
+          this._offlineQueue.push({ method, params, options, resolve, reject });
+          this._logger?.debug?.("Call queued offline", {
+            method,
+            queueSize: this._offlineQueue.length
+          });
+        });
+      }
       throw new Error(`Cannot call: client is in state ${this._state}`);
     }
+    const maxRetries = options.retries ?? 0;
+    if (maxRetries > 0) {
+      return this._callWithRetry(method, params, options, maxRetries);
+    }
     return this._callQueue.push(() => this._sendCall(method, params, options));
   }
   async safeCall(...args) {
@@ -37456,7 +37592,7 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
     }
   }
   async _sendCall(method, params, options) {
-    const msgId = (0, import_cuid2.createId)();
+    const msgId = options.idempotencyKey ?? (0, import_cuid2.createId)();
     const timeoutMs = options.timeoutMs ?? this._options.callTimeoutMs;
     const ctx = {
       type: "outgoing_call",
@@ -37504,7 +37640,7 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
           sentAt: Date.now()
         });
         if (this._ws?.readyState === import_ws.default.OPEN) {
-          this._ws.send(messageStr, (err) => {
+          this._safeSend(this._ws, messageStr, (err) => {
             if (err) {
               clearTimeout(timeoutHandle);
               this._pendingCalls.delete(msgId);
@@ -37851,6 +37987,87 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
       }
     }, delayMs);
   }
+  // ─── Internal: Offline Queue ──────────────────────────────────
+  /**
+   * Atomically drains the offline queue and sends each message via _sendCall.
+   * Uses splice(0) to prevent re-entry bugs (double billing) if the connection
+   * drops again mid-flush — the queue is empty before any sends begin.
+   */
+  _flushOfflineQueue() {
+    if (this._offlineQueue.length === 0) return;
+    const snapshot = this._offlineQueue.splice(0, this._offlineQueue.length);
+    this._logger?.info?.("Flushing offline queue", { count: snapshot.length });
+    for (const entry of snapshot) {
+      this._callQueue.push(() => this._sendCall(entry.method, entry.params, entry.options)).then(entry.resolve).catch(entry.reject);
+    }
+  }
+  // ─── Internal: Call Retry with Full Jitter ───────────────────
+  /**
+   * Retry wrapper using Full Jitter exponential backoff.
+   * delay = random(0, min(retryMaxDelayMs, retryDelayMs * 2^attempt))
+   * Only retries on TimeoutError — all other errors propagate immediately.
+   */
+  async _callWithRetry(method, params, options, maxRetries) {
+    const baseDelay = options.retryDelayMs ?? 1e3;
+    const maxDelay = options.retryMaxDelayMs ?? 3e4;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this._callQueue.push(
+          () => this._sendCall(method, params, options)
+        );
+      } catch (err) {
+        if (attempt === maxRetries || !(err instanceof TimeoutError)) {
+          throw err;
+        }
+        const expDelay = Math.min(maxDelay, baseDelay * 2 ** attempt);
+        const jitteredDelay = Math.random() * expDelay;
+        this._logger?.warn?.("Call retry", {
+          method,
+          attempt: attempt + 1,
+          maxRetries,
+          delayMs: Math.round(jitteredDelay)
+        });
+        await new Promise((r) => setTimeout(r, jitteredDelay));
+      }
+    }
+    throw new Error("Retry exhausted");
+  }
+  // ─── Internal: Backpressure-Aware Send ───────────────────────
+  /** Maximum bytes allowed in the ws send buffer before applying backpressure (512KB) */
+  static _BACKPRESSURE_THRESHOLD = 512 * 1024;
+  /**
+   * Wraps ws.send() with backpressure protection.
+   * If bufferedAmount exceeds the threshold, waits for the buffer to drain
+   * before sending. Prevents OOM on slow 2G/3G charger connections.
+   */
+  _safeSend(ws, data, cb) {
+    if (!ws || ws.readyState !== import_ws.default.OPEN) {
+      cb?.(new Error("WebSocket is not open"));
+      return;
+    }
+    if (ws.bufferedAmount > _OCPPClient._BACKPRESSURE_THRESHOLD) {
+      this._logger?.warn?.("Backpressure \u2014 pausing send", {
+        bufferedAmount: ws.bufferedAmount,
+        threshold: _OCPPClient._BACKPRESSURE_THRESHOLD
+      });
+      this.emit("backpressure", { bufferedAmount: ws.bufferedAmount });
+      let waited = 0;
+      const drainCheck = setInterval(() => {
+        waited += 50;
+        if (!ws || ws.readyState !== import_ws.default.OPEN) {
+          clearInterval(drainCheck);
+          cb?.(new Error("WebSocket closed during backpressure wait"));
+          return;
+        }
+        if (ws.bufferedAmount <= _OCPPClient._BACKPRESSURE_THRESHOLD || waited >= 1e4) {
+          clearInterval(drainCheck);
+          ws.send(data, cb);
+        }
+      }, 50);
+    } else {
+      ws.send(data, cb);
+    }
+  }
   // ─── Internal: Ping/Pong ─────────────────────────────────────
   _startPing() {
     if (this._options.pingIntervalMs <= 0) return;
@@ -38000,6 +38217,52 @@ var OCPPClient = class _OCPPClient extends import_node_events.EventEmitter {
   }
 };
 
+// src/lru-map.ts
+var LRUMap = class extends Map {
+  _maxSize;
+  constructor(maxSize) {
+    super();
+    if (maxSize < 1) throw new RangeError("LRUMap maxSize must be >= 1");
+    this._maxSize = maxSize;
+  }
+  /**
+   * Returns the configured maximum capacity of this LRU cache.
+   */
+  get maxSize() {
+    return this._maxSize;
+  }
+  /**
+   * Sets a key-value pair. If the key already exists, it is promoted to the
+   * most-recently-used position. If inserting a new key would exceed capacity,
+   * the oldest (least-recently-used) entry is evicted.
+   */
+  set(key, value) {
+    if (this.has(key)) {
+      this.delete(key);
+    }
+    super.set(key, value);
+    if (this.size > this._maxSize) {
+      const oldest = this.keys().next().value;
+      if (oldest !== void 0) {
+        this.delete(oldest);
+      }
+    }
+    return this;
+  }
+  /**
+   * Gets a value by key and promotes it to the most-recently-used position.
+   * Uses `this.has(key)` instead of a value truthiness check to correctly
+   * handle stored values of `undefined`, `null`, `0`, `""`, etc.
+   */
+  get(key) {
+    if (!this.has(key)) return void 0;
+    const value = super.get(key);
+    this.delete(key);
+    super.set(key, value);
+    return value;
+  }
+};
+
 // src/router.ts
 var import_node_events2 = require("events");
 async function executeMiddlewareChain(middlewares, ctx) {
@@ -38356,6 +38619,7 @@ var OCPPServerClient = class extends OCPPClient {
     this._ws = context.ws;
     this._protocol = context.protocol ?? context.ws.protocol;
     this._attachServerWebsocket(context.ws);
+    this._startPing();
   }
   // ─── Rate Limiting State ──────────────────────────────────────────
   _rateLimits = {};
@@ -38523,9 +38787,11 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
   _httpServerAbortControllers = /* @__PURE__ */ new Set();
   _logger = null;
   _globalCORS;
+  // Connection-level rate limiting (per-IP token bucket)
+  _connectionBuckets = /* @__PURE__ */ new Map();
   // Robustness & Clustering
   _nodeId = (0, import_cuid22.createId)();
-  _sessions = /* @__PURE__ */ new Map();
+  _sessions;
   _gcInterval = null;
   _sessionTimeoutMs;
   constructor(options = {}) {
@@ -38550,6 +38816,8 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
       ...options
     };
     this._sessionTimeoutMs = this._options.sessionTtlMs;
+    const maxSessions = this._options.maxSessions ?? 5e4;
+    this._sessions = new LRUMap(maxSessions);
     this._wss = new import_ws2.WebSocketServer({ noServer: true });
     this._gcInterval = setInterval(() => {
       const now = Date.now();
@@ -38764,6 +39032,69 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
     };
     httpServer.on("upgrade", upgradeHandler);
     this._httpServers.add(httpServer);
+    if (this._options.healthEndpoint) {
+      httpServer.on("request", (req, res) => {
+        const url = req.url ?? "";
+        if (url === "/health") {
+          const s = this.stats();
+          const body = JSON.stringify({
+            status: this._state === "OPEN" ? "ok" : "degraded",
+            state: this._state,
+            connectedClients: s.connectedClients,
+            activeSessions: s.activeSessions,
+            uptimeSeconds: Math.round(s.uptimeSeconds),
+            pid: s.pid
+          });
+          res.writeHead(200, {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-cache"
+          });
+          res.end(body);
+          return;
+        }
+        if (url === "/metrics") {
+          const s = this.stats();
+          const lines = [
+            "# HELP ocpp_connected_clients Number of currently connected OCPP clients",
+            "# TYPE ocpp_connected_clients gauge",
+            `ocpp_connected_clients ${s.connectedClients}`,
+            "",
+            "# HELP ocpp_active_sessions Number of active in-memory sessions",
+            "# TYPE ocpp_active_sessions gauge",
+            `ocpp_active_sessions ${s.activeSessions}`,
+            "",
+            "# HELP ocpp_uptime_seconds Process uptime in seconds",
+            "# TYPE ocpp_uptime_seconds gauge",
+            `ocpp_uptime_seconds ${Math.round(s.uptimeSeconds)}`,
+            "",
+            "# HELP ocpp_memory_rss_bytes Resident set size in bytes",
+            "# TYPE ocpp_memory_rss_bytes gauge",
+            `ocpp_memory_rss_bytes ${s.memoryUsage.rss}`,
+            "",
+            "# HELP ocpp_memory_heap_used_bytes V8 heap used in bytes",
+            "# TYPE ocpp_memory_heap_used_bytes gauge",
+            `ocpp_memory_heap_used_bytes ${s.memoryUsage.heapUsed}`,
+            "",
+            "# HELP ocpp_memory_heap_total_bytes V8 heap total in bytes",
+            "# TYPE ocpp_memory_heap_total_bytes gauge",
+            `ocpp_memory_heap_total_bytes ${s.memoryUsage.heapTotal}`,
+            "",
+            "# HELP ocpp_ws_buffered_bytes Total buffered WebSocket bytes",
+            "# TYPE ocpp_ws_buffered_bytes gauge",
+            `ocpp_ws_buffered_bytes ${s.webSockets?.bufferedAmount ?? 0}`,
+            ""
+          ];
+          res.writeHead(200, {
+            "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+            "Cache-Control": "no-cache"
+          });
+          res.end(lines.join("\n"));
+          return;
+        }
+        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.end("Not Found");
+      });
+    }
     if (options?.signal) {
       const ac = new AbortController();
       this._httpServerAbortControllers.add(ac);
@@ -38827,6 +39158,30 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
       abortHandshake(socket, 503, "Server is shutting down");
       return;
     }
+    const connRateLimit = this._options.connectionRateLimit;
+    if (connRateLimit) {
+      const ip = req.socket.remoteAddress ?? "unknown";
+      const now = Date.now();
+      let bucket = this._connectionBuckets.get(ip);
+      if (!bucket) {
+        bucket = { tokens: connRateLimit.limit, lastRefill: now };
+        this._connectionBuckets.set(ip, bucket);
+      } else {
+        const elapsed = now - bucket.lastRefill;
+        const refillRate = connRateLimit.limit / connRateLimit.windowMs;
+        bucket.tokens = Math.min(
+          connRateLimit.limit,
+          bucket.tokens + elapsed * refillRate
+        );
+        bucket.lastRefill = now;
+      }
+      if (bucket.tokens < 1) {
+        this._logger?.warn?.("Connection rate limit exceeded", { ip });
+        abortHandshake(socket, 429, "Too Many Requests");
+        return;
+      }
+      bucket.tokens -= 1;
+    }
     if (socket.readyState !== "open") {
       this._logger?.debug?.("Socket not open at upgrade start");
       if (!socket.destroyed) socket.destroy();
@@ -39145,6 +39500,20 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
         protocol: selectedProtocol
       });
       this._updateSessionActivity(identity, client.session);
+      const existingClient = this._clientsByIdentity.get(identity);
+      if (existingClient && existingClient !== client) {
+        this._logger?.warn?.("Evicting stale connection for identity", {
+          identity,
+          reason: "Duplicate identity replaced by new connection"
+        });
+        existingClient.close({
+          code: 4e3,
+          reason: "Evicted by new connection",
+          force: true
+        }).catch(() => {
+        });
+        this._clients.delete(existingClient);
+      }
       this._clients.add(client);
       this._clientsByIdentity.set(identity, client);
       if (this._adapter?.setPresence) {
@@ -39200,6 +39569,29 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
       clearInterval(this._gcInterval);
       this._gcInterval = null;
     }
+    if (!options.force) {
+      const drainTimeout = 5e3;
+      const drainPromises = Array.from(this._clients).map(async (client) => {
+        const ws = client._ws;
+        if (ws && ws.bufferedAmount > 0) {
+          this._logger?.debug?.("Waiting for client buffer to drain", {
+            identity: client.identity,
+            bufferedAmount: ws.bufferedAmount
+          });
+          await new Promise((resolve) => {
+            let elapsed = 0;
+            const check = setInterval(() => {
+              elapsed += 50;
+              if (!ws || ws.bufferedAmount === 0 || elapsed >= drainTimeout) {
+                clearInterval(check);
+                resolve();
+              }
+            }, 50);
+          });
+        }
+      });
+      await Promise.allSettled(drainPromises);
+    }
     const closePromises = Array.from(this._clients).map(
       (client) => client.close(options).catch(() => {
       })
@@ -39427,6 +39819,7 @@ var OCPPServer = class extends import_node_events3.EventEmitter {
 0 && (module.exports = {
   ConnectionState,
   InMemoryAdapter,
+  LRUMap,
   MessageType,
   MiddlewareStack,
   NOREPLY,