ocpp-ws-io 2.2.2 → 2.3.0

package/dist/{types-xFfIgIuS.d.ts → types-tTYOr5Gm.d.ts}

@@ -4465,6 +4465,11 @@ declare class OCPPRouter extends OCPPRouter_base {
      * @internal
      */
     _regexPatterns: CompiledRegexPattern[];
+    /**
+     * @internal Set by OCPPServer when the router is registered, so patterns
+     * added after registration still reach the trie / regex list.
+     */
+    _onPatternAdded?: (pattern: string | RegExp) => void;
     constructor(patterns?: Array<string | RegExp>, middlewares?: ConnectionMiddleware[]);
     /**
      * Appends URL paths or regular expressions to this router's match condition.
@@ -4573,7 +4578,7 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
     private _pendingResponses;
     private _callQueue;
     private _pingTimer;
-    private _pongTimer;
+    protected _pongTimer: ReturnType<typeof setTimeout> | null;
     private _closePromise;
     private _reconnectAttempt;
     private _reconnectTimer;
@@ -4608,6 +4613,11 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
      * The connection endpoint URL.
      */
     get endpoint(): string;
+    /**
+     * Bytes currently queued in the underlying WebSocket send buffer
+     * (0 when disconnected). Useful for backpressure monitoring and drain checks.
+     */
+    get bufferedAmount(): number;
     /**
      * The current configuration options for this client.
      */
@@ -4690,6 +4700,11 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
      * Remove a registered handler for a specific version and method.
      */
     removeHandler(version: OCPPProtocol, method: string): void;
+    /**
+     * Check whether a handler is registered for a method
+     * (optionally version-scoped, matching the handle() overloads).
+     */
+    hasHandler(method: string, version?: string): boolean;
     /**
      * Remove all registered handlers for this client, including the wildcard handler.
      */
@@ -4715,6 +4730,12 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
     call<M extends AllMethodNames<P>>(method: M, params: OCPPRequestType<P, M>, options?: CallOptions): Promise<OCPPResponseType<P, M>>;
     /** Call a known typed method with explicit response type. */
     call<TResult = unknown>(method: string, params?: Record<string, unknown>, options?: CallOptions): Promise<TResult>;
+    /**
+     * Execute a call immediately, bypassing the callConcurrency queue.
+     * Used by OCPPServer.sendBatch to pipeline warm-up calls without
+     * mutating the client's configured concurrency (report M9).
+     */
+    callImmediate<TResult = unknown>(method: string, params?: Record<string, unknown>, options?: CallOptions): Promise<TResult>;
     /**
      * Version-specific safe call. Returns `undefined` on error instead of throwing.
      */
@@ -4754,7 +4775,7 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
      * Reject all in-flight calls and clear pending state.
      */
     private _rejectPendingCalls;
-    private _onClose;
+    protected _onClose(code: number, reason: Buffer): void;
     /** Errors that should stop reconnection immediately */
     private static readonly _INTOLERABLE_ERRORS;
     private _scheduleReconnect;
@@ -4772,20 +4793,27 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
     private _callWithRetry;
     /** Maximum bytes allowed in the ws send buffer before applying backpressure (512KB) */
     private static readonly _BACKPRESSURE_THRESHOLD;
+    /** Sends queued while the socket is backpressured (FIFO). */
+    private _backpressureQueue;
+    private _backpressureTimer;
     /**
      * Protected hook for plugins to intercept outbound messages before serialization.
      * Return `false` to suppress the message transmission.
      */
     protected _invokeBeforeSend(_message: OCPPMessage): boolean | Promise<boolean>;
     /**
-     * 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.
+     * Wraps ws.send() with backpressure protection. When bufferedAmount
+     * exceeds the threshold, sends are queued and flushed FIFO by a single
+     * shared 50ms drain timer (one per client, not one per send — report M10).
+     * Entries older than 10s are sent regardless, preserving the previous
+     * timeout semantics. Prevents OOM on slow 2G/3G charger connections.
      */
     private _safeSend;
-    private _startPing;
+    private _startBackpressureDrain;
+    private _stopBackpressureDrain;
+    protected _startPing(): void;
     private _stopPing;
-    private _recordActivity;
+    protected _recordActivity(): void;
     private _setupValidators;
     private _validateOutbound;
     private _validateInbound;
@@ -4800,6 +4828,8 @@ interface WorkerPoolOptions {
     poolSize?: number;
     /** Max pending parse jobs before rejecting (default: 10000) */
     maxQueueSize?: number;
+    /** Override the worker entry path (used by tests; defaults to parse-worker.cjs next to this file) */
+    workerPath?: string;
 }
 interface ParseResult {
     message: unknown;
@@ -4815,7 +4845,16 @@ declare class WorkerPool {
     private _pending;
     private _maxQueueSize;
     private _terminated;
+    private readonly _workerPath;
     constructor(options?: WorkerPoolOptions);
+    /**
+     * Create (or recreate) a worker bound to a fixed pool index, wiring up
+     * message/error/exit handlers. On a crash the worker is respawned at the
+     * same index and any tasks it owned are rejected so callers never hang.
+     */
+    private _createWorker;
+    /** Reject every pending task that was dispatched to the given worker index. */
+    private _failWorkerTasks;
     /** Number of worker threads in the pool */
     get size(): number;
     /** Number of pending (unresolved) parse tasks */
@@ -4858,9 +4897,17 @@ declare class OCPPServerClient extends OCPPClient {
     private _rateLimits;
     private _adaptiveMultiplier;
     private _workerPool;
+    /**
+     * Per-connection inbound pipeline. Serializes async pre-processing
+     * (plugin onBeforeReceive, rate-limit parse, worker-pool parse) so
+     * messages are dispatched in wire order — OCPP transaction semantics
+     * depend on it (e.g. StartTransaction before StopTransaction).
+     */
+    private _inboundChain;
     private _checkRateLimit;
     protected _invokeBeforeSend(message: OCPPMessage): boolean | Promise<boolean>;
     private _attachServerWebsocket;
+    private _processInboundMessage;
     private _handleRateLimitExceeded;
     /**
      * Session data associated with this client connection.
@@ -4909,6 +4956,10 @@ declare class OCPPServer extends OCPPServer_base {
     private _clients;
     private _clientsByIdentity;
     private _httpServers;
+    /** HTTP servers created by listen() — we own their lifecycle. */
+    private _ownedHttpServers;
+    /** Listeners we attached per server, for removal on close(). */
+    private _attachedHttpHandlers;
     private _wss;
     private _state;
     private _adapter;
@@ -4920,7 +4971,12 @@ declare class OCPPServer extends OCPPServer_base {
     private _plugins;
     private _workerPool;
     private _telemetryInterval;
+    private _presenceInterval;
     private readonly _nodeId;
+    /** Pending cross-node RPC calls awaiting a correlated response. */
+    private _pendingRemoteCalls;
+    /** Extra wait on top of the call timeout to absorb cross-node transit. */
+    private static readonly _REMOTE_RESPONSE_GRACE_MS;
     private _sessions;
     private _gcInterval;
     private readonly _sessionTimeoutMs;
@@ -5064,21 +5120,25 @@ declare class OCPPServer extends OCPPServer_base {
      */
     private _handleUpgrade;
     private _updateSessionActivity;
+    /**
+     * Evict per-IP connection buckets that have been idle longer than the
+     * rate-limit window. Recreating a bucket grants a full token allowance,
+     * which is exactly what a full refill after `windowMs` idle would yield —
+     * so eviction is behavior-preserving while bounding memory (report H4).
+     */
+    private _sweepConnectionBuckets;
     close(options?: CloseOptions): Promise<void>;
     reconfigure(options: Partial<ServerOptions>): void;
     /**
      * Send a request to a specific client (local or remote).
      *
-     * 1. Checks local clients.
-     * 2. Checks Presence Registry -> Unicast.
-     * 3. Fallback: Broadcast.
-     */
-    /**
-     * Send a request to a specific client (local or remote).
+     * 1. Local clients are called directly.
+     * 2. Otherwise the presence registry routes the call to the owning node,
+     *    and the response is correlated back over the adapter (cross-node RPC).
+     * 3. Unknown identity → rejects with "Client <identity> not found".
      *
-     * 1. Checks local clients.
-     * 2. Checks Presence Registry -> Unicast.
-     * 3. Fallback: Error (Client not found).
+     * Backward compatibility: nodes running older versions deliver the call
+     * but never publish a response — such calls reject with TimeoutError.
      */
     sendToClient<V extends OCPPProtocol, M extends AllMethodNames<V>>(identity: string, version: V, method: M, params: OCPPRequestType<V, M>, options?: CallOptions): Promise<OCPPResponseType<V, M> | undefined>;
     sendToClient<M extends AllMethodNames<any>>(identity: string, method: M, params: OCPPRequestType<any, M>, options?: CallOptions): Promise<OCPPResponseType<any, M> | undefined>;
@@ -5111,8 +5171,12 @@ declare class OCPPServer extends OCPPServer_base {
         options?: CallOptions;
     }>): Promise<Array<unknown | undefined>>;
     setAdapter(adapter: EventAdapterInterface): Promise<void>;
+    private _startPresenceRefresh;
+    private _refreshPresence;
     private _onBroadcast;
     private _onUnicast;
+    /** Publish the result of a remotely requested call back to the origin node. */
+    private _publishRemoteResult;
     publish(channel: string, data: unknown): Promise<void>;
     broadcast<V extends AllMethodNames<any>>(method: V, params: OCPPRequestType<any, V>): Promise<void>;
     /**
@@ -5126,6 +5190,13 @@ declare class OCPPServer extends OCPPServer_base {
      * @param options Call options
      */
     broadcastBatch<V extends AllMethodNames<any>>(identities: string[], method: V, params: OCPPRequestType<any, V>, options?: CallOptions): Promise<void>;
+    /**
+     * Builds a `noServer` WebSocketServer with the configured transport-layer
+     * settings (max payload + per-message compression). Centralized so every
+     * (re)creation site — constructor, upgrade re-init, and close/restart —
+     * stays consistent.
+     */
+    private _createWss;
     private _buildCompressionConfig;
 }
 
@@ -5163,9 +5234,11 @@ declare class Validator {
     hasSchema(schemaId: string): boolean;
 }
 /**
- * Create or retrieve a cached validator for a specific subprotocol version.
- * E5: Returns an existing instance if one was already created for this subprotocol,
- * preventing duplicate AJV instances and saving memory.
+ * Create a validator for a specific subprotocol version.
+ *
+ * Always returns a fresh instance so custom schema sets are never shadowed
+ * by previously created validators for the same subprotocol (report M8).
+ * Standard validators are cached separately by getStandardValidators().
  */
 declare function createValidator(subprotocol: string, schemas: ValidatorSchema[]): Validator;
 
@@ -5442,7 +5515,11 @@ interface ClientOptions {
     strictModeMethods?: Array<AllMethodNames<OCPPProtocol>>;
     /** Custom validators for strict mode */
     strictModeValidators?: Validator[];
-    /** Max number of bad messages before closing (default: Infinity) */
+    /**
+     * Max number of bad messages before closing.
+     * Default: Infinity (never disconnects on bad messages) — set a finite
+     * value in production.
+     */
     maxBadMessages?: number;
     /** Include error details in responses (default: false) */
     respondWithDetailedErrors?: boolean;
@@ -5548,12 +5625,30 @@ interface RouterConfig {
     rateLimit?: RateLimitOptions;
 }
 interface CORSOptions {
-    /** Allowed IPv4, IPv6, or CIDR ranges (e.g. "10.0.0.0/8") */
+    /**
+     * Allowed exact IPv4/IPv6 addresses or CIDR ranges
+     * (e.g. "10.0.0.0/8", "2001:db8::/32").
+     */
     allowedIPs?: string[];
-    /** Allowed Origin header values (e.g. "https://dashboard.example.com") */
+    /**
+     * Allowed `Origin` header values (e.g. "https://dashboard.example.com").
+     *
+     * **Note:** this is a *browser-side* defense only. Requests with **no**
+     * `Origin` header pass through (physical charging stations don't send one),
+     * so a non-browser client can bypass this by simply omitting the header.
+     * Do not rely on `allowedOrigins` for authentication — use `auth()` / Basic
+     * Auth / mTLS for that.
+     */
     allowedOrigins?: string[];
     /** Allowed WebSocket protocol schemes */
     allowedSchemes?: ("ws" | "wss")[];
+    /**
+     * Honor `X-Forwarded-Proto` from a reverse proxy when evaluating
+     * `allowedSchemes`. Leave false (default) unless the server is only
+     * reachable through a trusted proxy — otherwise clients can spoof the
+     * header to bypass wss-only rules.
+     */
+    trustProxy?: boolean;
 }
 interface ServerOptionsBase {
     /** OCPP Security Profile (default: NONE) */
@@ -5574,7 +5669,11 @@ interface ServerOptionsBase {
     strictModeValidators?: Validator[];
     /** Rate Limiting configuration — inherited */
     rateLimit?: RateLimitOptions;
-    /** Max bad messages — inherited (default: Infinity) */
+    /**
+     * Max bad messages — inherited.
+     * Default: Infinity (never disconnects on bad messages) — set a finite
+     * value in production.
+     */
     maxBadMessages?: number;
     /** Include error details in responses — inherited (default: false) */
     respondWithDetailedErrors?: boolean;
@@ -5583,6 +5682,12 @@ interface ServerOptionsBase {
      * (default: 7200000 / 2 hours)
      */
     sessionTtlMs?: number;
+    /**
+     * TTL (seconds) for cluster presence registry entries, and the basis for
+     * the automatic presence heartbeat (refreshed every ttl/2 while clients
+     * are connected). Default: 300.
+     */
+    presenceTtlSeconds?: number;
     /**
      * Maximum time (ms) to wait for the auth callback to resolve during
      * a WebSocket upgrade handshake. If the callback does not settle within
@@ -5613,10 +5718,20 @@ interface ServerOptionsBase {
      * (default: 50000)
      */
     maxSessions?: number;
+    /**
+     * Hard cap on concurrent client connections, enforced before the TLS/auth
+     * handshake work is done (the connection-guard plugin only closes after
+     * the fact). Excess upgrades are rejected with HTTP 503.
+     */
+    maxConnections?: number;
     /**
      * Enable the built-in HTTP health/metrics endpoint.
      * When enabled, non-upgrade HTTP requests to `/health` return a JSON health check,
      * and requests to `/metrics` return Prometheus-compatible text metrics.
+     * When attaching to a user-provided server (listen(..., { server })),
+     * only /health and /metrics are handled; all other routes are left to
+     * the application, and close() will not close the external server.
+     * Ensure your app does not also write responses for /health or /metrics.
      * (default: false)
      */
     healthEndpoint?: boolean;
@@ -5791,7 +5906,7 @@ interface ClientEvents {
  */
 interface SecurityEvent {
     /** Event type identifier */
-    type: "AUTH_FAILED" | "RATE_LIMIT_EXCEEDED" | "UPGRADE_ABORTED" | "CONNECTION_RATE_LIMIT" | "INVALID_PAYLOAD" | "ANOMALY_RAPID_RECONNECT" | "ANOMALY_AUTH_BRUTE_FORCE" | "ANOMALY_MESSAGE_FUZZING" | "ANOMALY_IDENTITY_COLLISION";
+    type: "AUTH_FAILED" | "RATE_LIMIT_EXCEEDED" | "UPGRADE_ABORTED" | "CONNECTION_RATE_LIMIT" | "CONNECTION_LIMIT" | "INVALID_PAYLOAD" | "ANOMALY_RAPID_RECONNECT" | "ANOMALY_AUTH_BRUTE_FORCE" | "ANOMALY_MESSAGE_FUZZING" | "ANOMALY_IDENTITY_COLLISION";
     /** Station identity (if known) */
     identity?: string;
     /** Remote IP address */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocpp-ws-io",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "OCPP RPC WebSocket client and server for OCPP 1.6J, 2.0.1, and 2.1. Type-safe TypeScript toolkit for EV charging, CSMS backends, Redis scaling, and protocol validation.",
   "repository": {
     "type": "git",
@@ -171,6 +171,6 @@
     "reflect-metadata": "^0.2.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }