ocpp-ws-io 2.1.7 → 2.1.9

package/dist/index.d.mts

@@ -1,10 +1,12 @@
-import { E as EventAdapterInterface, A as AuthCallback, L as LoggerLike, a as LoggingConfig, M as MiddlewareFunction, b as MiddlewareContext, C as ConnectionMiddleware, T as TypedEventEmitter, S as ServerEvents, c as CORSOptions, R as RouterConfig, O as OCPPProtocol, d as AllMethodNames, e as RouterHandlerContext, f as OCPPRequestType, g as OCPPResponseType, h as RouterWildcardHandler, i as ServerOptions, j as LoggerLikeNotOptional, k as OCPPServerClient, l as OCPPServerStats, m as ListenOptions, n as TLSOptions, o as CloseOptions, p as CallOptions, V as Validator } from './index-BRblF1XV.mjs';
-export { q as AnyOCPPProtocol, r as AuthAccept, s as CallHandler, t as ClientEvents, u as ClientOptions, v as ConnectionContext, w as ConnectionState, H as HandlerContext, x as HandshakeInfo, y as MessageType, z as MiddlewareNext, B as MiddlewareStack, N as NOREPLY, D as OCPP16Methods, F as OCPP201Methods, G as OCPP21Methods, I as OCPPCall, J as OCPPCallError, K as OCPPCallResult, P as OCPPClient, Q as OCPPMessage, U as OCPPMethodMap, W as OCPPProtocolKey, X as RedisAdapter, Y as SecurityProfile, Z as SessionData, _ as WildcardHandler, $ as createValidator } from './index-BRblF1XV.mjs';
-import { Server, IncomingMessage } from 'node:http';
-import { Duplex } from 'node:stream';
+import { E as EventAdapterInterface, A as AuthCallback, L as LoggerLike, a as LoggingConfig, M as MiddlewareFunction, b as MiddlewareContext, O as OCPPPlugin, C as ConnectionMiddleware, V as Validator } from './types-BZXEmDQ1.mjs';
+export { c as AllMethodNames, d as AnyOCPPProtocol, e as AuthAccept, f as CORSOptions, g as CallHandler, h as CallOptions, i as ClientEvents, j as ClientOptions, k as CloseOptions, l as CompressionOptions, m as ConnectionContext, n as ConnectionState, H as HandlerContext, o as HandshakeInfo, p as ListenOptions, q as MessageType, r as MiddlewareNext, s as MiddlewareStack, N as NOREPLY, t as OCPP16Methods, u as OCPP201Methods, v as OCPP21Methods, w as OCPPCall, x as OCPPCallError, y as OCPPCallResult, z as OCPPClient, B as OCPPMessage, D as OCPPMethodMap, F as OCPPProtocol, G as OCPPProtocolKey, I as OCPPRequestType, J as OCPPResponseType, K as OCPPRouter, P as OCPPServer, Q as OCPPServerClient, R as RateLimitOptions, S as RouterConfig, T as SecurityProfile, U as ServerEvents, W as ServerOptions, X as SessionData, Y as TLSOptions, Z as TypedEventEmitter, _ as WildcardHandler, $ as createRouter, a0 as createValidator } from './types-BZXEmDQ1.mjs';
+import { R as RedisPubSubDriver, S as StreamEntry } from './index-C0mn42-8.mjs';
+export { a as RedisAdapter } from './index-C0mn42-8.mjs';
+import { EventEmitter } from 'node:events';
 import 'ws';
 import 'node:https';
-import 'node:events';
+import 'node:http';
+import 'node:stream';
 import 'node:tls';
 import 'voltlog-io';
 import 'ajv';
@@ -51,6 +53,109 @@ declare class InMemoryAdapter implements EventAdapterInterface {
  */
 declare function defineAdapter(adapter: EventAdapterInterface): EventAdapterInterface;
 
+interface ClusterNode {
+    host: string;
+    port: number;
+}
+interface ClusterDriverOptions {
+    /** Seed nodes for the Redis Cluster */
+    nodes: ClusterNode[];
+    /** NAT mapping for Docker/k8s environments */
+    natMap?: Record<string, {
+        host: string;
+        port: number;
+    }>;
+    /** Additional ioredis options passed to the Cluster constructor */
+    redisOptions?: Record<string, unknown>;
+    /** Key prefix (used for hash tag generation) */
+    prefix?: string;
+}
+/**
+ * Redis Cluster driver that implements `RedisPubSubDriver`.
+ * Requires `ioredis` as a peer dependency.
+ *
+ * Hash-tag strategy:
+ * - Presence keys: `{identity}` → sharded by station identity
+ * - Stream keys: `{nodeId}` → sharded by server node ID
+ *
+ * @example
+ * ```ts
+ * const driver = createClusterDriver({
+ *   nodes: [{ host: '10.0.0.1', port: 6379 }, { host: '10.0.0.2', port: 6379 }],
+ * });
+ * const adapter = new RedisAdapter({ pubClient: {}, subClient: {}, driverFactory: () => driver });
+ * ```
+ */
+declare class ClusterDriver implements RedisPubSubDriver {
+    private _cluster;
+    private _subscriber;
+    private _handlers;
+    constructor(_options: ClusterDriverOptions);
+    publish(channel: string, message: string): Promise<void>;
+    subscribe(channel: string, handler: (message: string) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    get(key: string): Promise<string | null>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    del(key: string): Promise<void>;
+    xadd(stream: string, args: Record<string, string>, maxLen?: number): Promise<string>;
+    xaddBatch(messages: {
+        stream: string;
+        args: Record<string, string>;
+    }[], maxLen?: number): Promise<void>;
+    xread(streams: {
+        key: string;
+        id: string;
+    }[], count?: number, block?: number): Promise<StreamEntry[] | null>;
+    xlen(stream: string): Promise<number>;
+    disconnect(): Promise<void>;
+    setPresenceBatch(entries: {
+        key: string;
+        value: string;
+        ttlSeconds: number;
+    }[]): Promise<void>;
+    expire(key: string, ttlSeconds: number): Promise<void>;
+    onError(handler: (err: Error) => void): () => void;
+    onReconnect(handler: () => void): () => void;
+}
+
+interface AdaptiveLimiterOptions {
+    /** CPU usage % at which limits start tightening (default: 70) */
+    cpuThresholdPercent?: number;
+    /** Memory usage % at which limits start tightening (default: 85) */
+    memThresholdPercent?: number;
+    /** Cooldown before the multiplier recovers after an overload (default: 10000ms) */
+    cooldownMs?: number;
+    /** How often to sample system metrics (default: 2000ms) */
+    sampleIntervalMs?: number;
+}
+interface AdaptedEvent {
+    multiplier: number;
+    cpuPercent: number;
+    memPercent: number;
+}
+declare class AdaptiveLimiter extends EventEmitter {
+    private _cpuThreshold;
+    private _memThreshold;
+    private _cooldownMs;
+    private _sampleInterval;
+    private _timer;
+    private _lastOverloadTime;
+    private _multiplier;
+    private _prevCpuUsage;
+    private _prevTimestamp;
+    constructor(options?: AdaptiveLimiterOptions);
+    /** Current rate multiplier: 1.0 = normal, 0.25 = heavily throttled */
+    get multiplier(): number;
+    /** Start periodic sampling */
+    start(): void;
+    /** Stop sampling and reset multiplier */
+    stop(): void;
+    private _sample;
+    on(event: "adapted", listener: (data: AdaptedEvent) => void): this;
+    emit(event: "adapted", data: AdaptedEvent): boolean;
+}
+
 declare class TimeoutError extends Error {
     constructor(message?: string);
 }
@@ -139,6 +244,26 @@ declare class RPCFrameworkError extends RPCGenericError {
  * This provides immediate IDE autocomplete for the `ConnectionContext`.
  */
 declare function defineMiddleware(mw: ConnectionMiddleware): ConnectionMiddleware;
+/**
+ * Utility to define and strongly-type an `OCPPPlugin` object.
+ * Provides full IDE autocomplete for all lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * import { createPlugin } from 'ocpp-ws-io';
+ *
+ * const metricsPlugin = createPlugin({
+ *   name: 'metrics',
+ *   onInit(server)       { console.log('Metrics plugin ready'); },
+ *   onConnection(client) { metrics.gauge('connections').inc(); },
+ *   onDisconnect(client) { metrics.gauge('connections').dec(); },
+ *   onClose()            { metrics.flush(); },
+ * });
+ *
+ * server.plugin(metricsPlugin);
+ * ```
+ */
+declare function createPlugin(plugin: OCPPPlugin): OCPPPlugin;
 /**
  * Utility to define and strongly-type an RPC Middleware function.
  * This provides immediate IDE autocomplete for the `MiddlewareContext`
@@ -197,293 +322,8 @@ declare class LRUMap<K, V> extends Map<K, V> {
     get(key: K): V | undefined;
 }
 
-/**
- * Compiled regex pattern for RegExp-based route fallback.
- * Only used when a user registers a RegExp pattern (not string patterns).
- * @internal
- */
-interface CompiledRegexPattern {
-    regex: RegExp;
-    paramNames: string[];
-}
-declare const OCPPRouter_base: new () => TypedEventEmitter<ServerEvents>;
-/**
- * OCPPRouter — An Express-like Connection dispatcher.
- * Isolated handler for a specific set of matching URL route patterns.
- *
- * String patterns are matched via radix trie (O(k) lookup, managed by OCPPServer).
- * RegExp patterns fall back to linear matching.
- */
-declare class OCPPRouter extends OCPPRouter_base {
-    /** Raw registered patterns (strings and/or RegExp) for reference. */
-    patterns: Array<string | RegExp>;
-    /** Connection middlewares attached to this router. */
-    middlewares: ConnectionMiddleware[];
-    /** Auth callback for this route endpoint. */
-    authCallback: AuthCallback<unknown> | null;
-    /** Route-level CORS options. */
-    _routeCORS?: CORSOptions;
-    /** Route-level config overrides. */
-    _routeConfig?: RouterConfig;
-    /**
-     * Compiled RegExp patterns for fallback linear matching.
-     * Only populated when RegExp patterns are registered.
-     * @internal
-     */
-    _regexPatterns: CompiledRegexPattern[];
-    constructor(patterns?: Array<string | RegExp>, middlewares?: ConnectionMiddleware[]);
-    /**
-     * Appends URL paths or regular expressions to this router's match condition.
-     * String patterns are stored for trie insertion by OCPPServer.
-     * RegExp patterns are compiled for linear fallback matching.
-     */
-    route(...patterns: Array<string | RegExp>): this;
-    /**
-     * Appends connection middlewares to this router's execution chain.
-     */
-    use(...middlewares: ConnectionMiddleware[]): this;
-    /**
-     * Applies specific CORS rules to connections matching this router's paths.
-     */
-    cors(options: CORSOptions): this;
-    /**
-     * Overrides global connection settings (e.g. timeouts, protocols) for this router.
-     */
-    config(options: RouterConfig): this;
-    /**
-     * Registers an authentication and protocol-negotiation callback for this route endpoint.
-     */
-    auth<TSession = Record<string, unknown>>(callback: AuthCallback<TSession>): this;
-    /**
-     * Binds a version-specific OCPP message handler directly to all clients that match this route.
-     *
-     * @throws {Error} AT RUNTIME when a client connects, if a handler for this version and method is already registered for that client.
-     */
-    handle<V extends OCPPProtocol, M extends AllMethodNames<V>>(version: V, method: M, handler: (context: RouterHandlerContext<OCPPRequestType<V, M>>) => OCPPResponseType<V, M> | Promise<OCPPResponseType<V, M>>): this;
-    /**
-     * Binds a custom/extension message handler directly to all clients that match this route.
-     *
-     * @throws {Error} AT RUNTIME when a client connects, if a handler for this protocol and method is already registered for that client.
-     */
-    handle<S extends string>(version: S extends OCPPProtocol ? never : S, method: string, handler: (context: RouterHandlerContext<Record<string, any>>) => any): this;
-    /**
-     * Binds a message handler directly to all clients that match this route using the default protocol.
-     *
-     * @throws {Error} AT RUNTIME when a client connects, if a handler for this method is already registered for that client.
-     */
-    handle<M extends AllMethodNames<OCPPProtocol>>(method: M, handler: (context: RouterHandlerContext<OCPPRequestType<OCPPProtocol, M>>) => OCPPResponseType<OCPPProtocol, M> | Promise<OCPPResponseType<OCPPProtocol, M>>): this;
-    /**
-     * Binds a custom/extension method not in the typed map.
-     *
-     * @throws {Error} AT RUNTIME when a client connects, if a handler for this method is already registered for that client.
-     */
-    handle(method: string, handler: (context: RouterHandlerContext<Record<string, any>>) => any): this;
-    /**
-     * Binds a wildcard handler to all clients that match this route.
-     *
-     * @throws {Error} AT RUNTIME when a client connects, if a wildcard handler is already registered for that client.
-     */
-    handle(handler: RouterWildcardHandler): this;
-}
-/**
- * Creates a standalone, modular `OCPPRouter` instance that can be attached
- * to an `OCPPServer` later via `server.attachRouters()`.
- */
-declare function createRouter(...patterns: Array<string | RegExp>): OCPPRouter;
-
-declare const OCPPServer_base: new () => TypedEventEmitter<ServerEvents>;
-/**
- * OCPPServer — A typed WebSocket RPC server for OCPP communication.
- *
- * Supports all 3 OCPP Security Profiles:
- * - Profile 1: Basic Auth over unsecured WS
- * - Profile 2: TLS + Basic Auth (HTTPS server)
- * - Profile 3: Mutual TLS (HTTPS server with requestCert)
- */
-declare class OCPPServer extends OCPPServer_base {
-    private _options;
-    /** Radix trie for O(k) route matching (string patterns). */
-    private _trie;
-    /** Global middleware routers (server.use() with no patterns — catch-all). */
-    private _globalMiddlewareRouters;
-    /** Routers with RegExp patterns (fallback linear scan). */
-    private _regexRouters;
-    private _clients;
-    private _clientsByIdentity;
-    private _httpServers;
-    private _wss;
-    private _state;
-    private _adapter;
-    private _httpServerAbortControllers;
-    private _logger;
-    private _globalCORS?;
-    private _connectionBuckets;
-    private readonly _nodeId;
-    private _sessions;
-    private _gcInterval;
-    private readonly _sessionTimeoutMs;
-    constructor(options?: ServerOptions);
-    get log(): LoggerLikeNotOptional;
-    /**
-     * Returns a readonly set of all currently connected OCPPServerClient instances.
-     */
-    get clients(): ReadonlySet<OCPPServerClient>;
-    /**
-     * Returns the current server state (OPEN, CLOSING, CLOSED).
-     */
-    get state(): "OPEN" | "CLOSING" | "CLOSED";
-    /**
-     * Returns current node observability statistics
-     * (e.g. connected socket count, tracked memory sessions, and process CPU/Memory usage).
-     * Fully compatible with Loki/Prometheus node metric ingestion.
-     */
-    stats(): OCPPServerStats;
-    /**
-     * Returns observability statistics from the active Event Adapter (e.g. Redis).
-     * Useful for tracking consumer backlog and enabling Horizontal Pod Autoscaling.
-     */
-    adapterMetrics(): Promise<Record<string, unknown> | null>;
-    /**
-     * Synchronously returns the OCPPServerClient instance if the specific identity
-     * is connected to THIS local server node.
-     * Note: In a clustered environment, clients connected to other nodes will NOT be returned here.
-     *
-     * @param identity The client identity (username/station ID)
-     */
-    getLocalClient(identity: string): OCPPServerClient | undefined;
-    /**
-     * Synchronously checks if the specific identity is connected to THIS local server node.
-     * Note: In a clustered environment, this will return false if the client is connected to another node.
-     *
-     * @param identity The client identity (username/station ID)
-     */
-    hasLocalClient(identity: string): boolean;
-    /**
-     * Asynchronously checks if the specific identity is connected to the server.
-     * In a single-node setup, this checks the local connections.
-     * In a clustered setup (with a pub/sub adapter), this will also check the global presence registry
-     * to see if the client is connected to ANY node in the cluster.
-     *
-     * @param identity The client identity (username/station ID)
-     */
-    isClientConnected(identity: string): Promise<boolean>;
-    /**
-     * Applies global CORS rules to all incoming connections before routing.
-     */
-    cors(options: CORSOptions): this;
-    /**
-     * Registers a new routing dispatcher for multiplexing connections.
-     * `server.route("/api/:tenant").use(middleware).auth(cb).on("client", ...)`
-     */
-    route(...patterns: Array<string | RegExp>): OCPPRouter;
-    /**
-     * Attaches one or more standalone modular routers created via `createRouter()`.
-     * This is useful for separating route definitions across different files.
-     */
-    attachRouters(...routers: OCPPRouter[]): this;
-    /**
-     * Registers a new middleware chain, acting as a wildcard/catch-all router if no patterns are added.
-     * `server.use(middleware).route("/api").on("client", ...)`
-     */
-    use(...middlewares: ConnectionMiddleware[]): OCPPRouter;
-    /**
-     * Registers a top-level auth handler, returning a router to attach `.on()` or `.use()`.
-     */
-    auth<TSession = Record<string, unknown>>(callback: AuthCallback<TSession>): OCPPRouter;
-    /**
-     * Routes a router into the appropriate internal structure:
-     * - String patterns → radix trie (O(k) lookup)
-     * - RegExp patterns → linear fallback array
-     * - No patterns → global middleware (catch-all)
-     * @internal
-     */
-    private _registerRouter;
-    listen(port?: number, host?: string, options?: ListenOptions): Promise<Server>;
-    /**
-     * Hot-reloads the TLS certificate on all active HTTPS servers without
-     * dropping any existing WebSocket connections.
-     *
-     * **When to use:** Call this whenever your TLS certificate is renewed —
-     * for example, after a Let's Encrypt auto-renewal (every ~90 days).
-     * Without this, you would need to restart the Node.js process to pick up
-     * the new certificate, disconnecting all connected charging stations.
-     *
-     * **How to use:**
-     * ```ts
-     * server.updateTLS({ cert: newCert, key: newKey });
-     * ```
-     *
-     * **Optional:** Only relevant if you are terminating TLS directly in Node.js
-     * (i.e. `SecurityProfile.TLS_BASIC_AUTH` or `TLS_CLIENT_CERT`). If you are
-     * running behind a reverse proxy (Nginx, AWS ALB, etc.) that handles TLS,
-     * you do not need this method — just rotate the cert on the proxy.
-     *
-     * @throws If the server is not using a TLS Security Profile.
-     */
-    updateTLS(tlsOpts: TLSOptions): void;
-    get handleUpgrade(): (req: IncomingMessage, socket: Duplex, head: Buffer) => Promise<void>;
-    /**
-     * Core upgrade handler. Follows a strict pipeline:
-     *
-     * 1. Validate socket readyState & upgrade header
-     * 2. Parse URL → identity + endpoint
-     * 3. Enable TCP Keep-Alive
-     * 4. Parse & negotiate subprotocols
-     * 5. Parse Basic Auth (via modular parseBasicAuth)
-     * 6. Extract TLS client certificate (Profile 3)
-     * 7. Build HandshakeInfo
-     * 8. Run auth callback with AbortController + handshake timeout
-     * 9. Complete WebSocket upgrade
-     * 10. Create OCPPServerClient
-     */
-    private _handleUpgrade;
-    private _updateSessionActivity;
-    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. Checks local clients.
-     * 2. Checks Presence Registry -> Unicast.
-     * 3. Fallback: Error (Client not found).
-     */
-    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>;
-    sendToClient<_T = any>(identity: string, method: string, params: Record<string, any>, options?: CallOptions): Promise<any | undefined>;
-    safeSendToClient<V extends OCPPProtocol, M extends AllMethodNames<V>>(identity: string, version: V, method: M, params: OCPPRequestType<V, M>, options?: CallOptions): Promise<OCPPResponseType<V, M> | undefined>;
-    safeSendToClient<M extends AllMethodNames<any>>(identity: string, method: M, params: OCPPRequestType<any, M>, options?: CallOptions): Promise<OCPPResponseType<any, M> | undefined>;
-    safeSendToClient<_T = any>(identity: string, method: string, params: Record<string, any>, options?: CallOptions): Promise<any | undefined>;
-    setAdapter(adapter: EventAdapterInterface): Promise<void>;
-    private _onBroadcast;
-    private _onUnicast;
-    publish(channel: string, data: unknown): Promise<void>;
-    broadcast<V extends AllMethodNames<any>>(method: V, params: OCPPRequestType<any, V>): Promise<void>;
-    /**
-     * Send a specific method & params to a list of specific clients efficiently.
-     * This leverages adapter pipelining (e.g. Redis .pipeline()) to minimize network overhead
-     * when communicating with thousands of nodes simultaneously.
-     *
-     * @param identities Array of target client identities
-     * @param method The OCPP method to send
-     * @param params The request parameters
-     * @param options Call options
-     */
-    broadcastBatch<V extends AllMethodNames<any>>(identities: string[], method: V, params: OCPPRequestType<any, V>, options?: CallOptions): Promise<void>;
-}
-
 declare function getStandardValidators(): Validator[];
 
-/**
- * Instantiate a typed RPCError from a string error code.
- * Returns an RPCGenericError if the code is not recognized.
- */
 declare function createRPCError(code: string, message?: string, details?: Record<string, unknown>): RPCError;
 /**
  * Convert an Error (or subclass) into a plain, JSON-safe object.
@@ -502,4 +342,4 @@ declare function getErrorPlainObject(err: Error): Record<string, unknown>;
  */
 declare function getPackageIdent(): string;
 
-export { AllMethodNames, AuthCallback, CORSOptions, CallOptions, CloseOptions, ConnectionMiddleware, EventAdapterInterface, InMemoryAdapter, LRUMap, ListenOptions, LoggerLike, LoggingConfig, MiddlewareFunction, OCPPProtocol, OCPPRequestType, OCPPResponseType, OCPPRouter, OCPPServer, OCPPServerClient, type RPCError, RPCFormatViolationError, RPCFormationViolationError, RPCFrameworkError, RPCGenericError, RPCInternalError, RPCMessageTypeNotSupportedError, RPCNotImplementedError, RPCNotSupportedError, RPCOccurrenceConstraintViolationError, RPCPropertyConstraintViolationError, RPCProtocolError, RPCSecurityError, RPCTypeConstraintViolationError, RouterConfig, ServerEvents, ServerOptions, TLSOptions, TimeoutError, TypedEventEmitter, UnexpectedHttpResponse, Validator, WebsocketUpgradeError, combineAuth, createLoggingMiddleware, createRPCError, createRouter, defineAdapter, defineAuth, defineMiddleware, defineRpcMiddleware, getErrorPlainObject, getPackageIdent, getStandardValidators };
+export { type AdaptedEvent, AdaptiveLimiter, type AdaptiveLimiterOptions, AuthCallback, ClusterDriver, type ClusterDriverOptions, type ClusterNode, ConnectionMiddleware, EventAdapterInterface, InMemoryAdapter, LRUMap, LoggerLike, LoggingConfig, MiddlewareFunction, OCPPPlugin, type RPCError, RPCFormatViolationError, RPCFormationViolationError, RPCFrameworkError, RPCGenericError, RPCInternalError, RPCMessageTypeNotSupportedError, RPCNotImplementedError, RPCNotSupportedError, RPCOccurrenceConstraintViolationError, RPCPropertyConstraintViolationError, RPCProtocolError, RPCSecurityError, RPCTypeConstraintViolationError, TimeoutError, UnexpectedHttpResponse, Validator, WebsocketUpgradeError, combineAuth, createLoggingMiddleware, createPlugin, createRPCError, defineAdapter, defineAuth, defineMiddleware, defineRpcMiddleware, getErrorPlainObject, getPackageIdent, getStandardValidators };