ocpp-ws-io 2.1.3

package/dist/index.d.mts

@@ -0,0 +1,449 @@
+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 CloseOptions, o as CallOptions, V as Validator } from './index-BixJj_yJ.mjs';
+export { p as AnyOCPPProtocol, q as AuthAccept, r as CallHandler, s as ClientEvents, t as ClientOptions, u as ConnectionContext, v as ConnectionState, H as HandlerContext, w as HandshakeInfo, x as MessageType, y as MiddlewareNext, z as MiddlewareStack, N as NOREPLY, B as OCPP16Methods, D as OCPP201Methods, F as OCPP21Methods, G as OCPPCall, I as OCPPCallError, J as OCPPCallResult, K as OCPPClient, P as OCPPMessage, Q as OCPPMethodMap, U as OCPPProtocolKey, W as RedisAdapter, X as SecurityProfile, Y as SessionData, Z as TLSOptions, _ as WildcardHandler, $ as createValidator } from './index-BixJj_yJ.mjs';
+import { Server, IncomingMessage } from 'node:http';
+import { Duplex } from 'node:stream';
+import 'ws';
+import 'node:https';
+import 'node:events';
+import 'node:tls';
+import 'voltlog-io';
+import 'ajv';
+
+/**
+ * In-memory event adapter for single-process use.
+ * Events are dispatched synchronously within the same process.
+ */
+declare class InMemoryAdapter implements EventAdapterInterface {
+    private _channels;
+    publish(channel: string, data: unknown): Promise<void>;
+    publishBatch(messages: {
+        channel: string;
+        data: unknown;
+    }[]): Promise<void>;
+    subscribe(channel: string, handler: (data: unknown) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    disconnect(): Promise<void>;
+    private _presence;
+    setPresence(identity: string, nodeId: string, _ttl: number): Promise<void>;
+    getPresence(identity: string): Promise<string | null>;
+    getPresenceBatch(identities: string[]): Promise<(string | null)[]>;
+    removePresence(identity: string): Promise<void>;
+}
+/**
+ * Helper function to create a custom EventAdapter without needing to define a rigid Class.
+ * Provides full TypeScript inference for the `EventAdapterInterface`.
+ *
+ * @example
+ * ```typescript
+ * const myAdapter = defineAdapter({
+ *   publish: async (channel, data) => { ... },
+ *   subscribe: async (channel, handler) => { ... },
+ *   unsubscribe: async (channel) => { ... },
+ *   disconnect: async () => { ... }
+ * });
+ * server.setAdapter(myAdapter);
+ * ```
+ */
+declare function defineAdapter(adapter: EventAdapterInterface): EventAdapterInterface;
+
+declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+declare class UnexpectedHttpResponse extends Error {
+    readonly statusCode: number;
+    readonly headers: Record<string, string | string[] | undefined>;
+    constructor(message: string, statusCode: number, headers?: Record<string, string | string[] | undefined>);
+}
+declare class WebsocketUpgradeError extends Error {
+    constructor(message?: string);
+}
+interface RPCError extends Error {
+    readonly rpcErrorCode: string;
+    readonly rpcErrorMessage: string;
+    readonly details: Record<string, unknown>;
+}
+declare class RPCGenericError extends Error implements RPCError {
+    readonly rpcErrorCode: string;
+    readonly rpcErrorMessage: string;
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCNotImplementedError extends RPCGenericError {
+    readonly rpcErrorCode = "NotImplemented";
+    readonly rpcErrorMessage = "Requested method is not known";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCNotSupportedError extends RPCGenericError {
+    readonly rpcErrorCode = "NotSupported";
+    readonly rpcErrorMessage = "Requested method is recognised but not supported";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCInternalError extends RPCGenericError {
+    readonly rpcErrorCode = "InternalError";
+    readonly rpcErrorMessage = "An internal error occurred and the receiver was not able to process the requested action successfully";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCProtocolError extends RPCGenericError {
+    readonly rpcErrorCode = "ProtocolError";
+    readonly rpcErrorMessage = "Payload for action is incomplete";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCSecurityError extends RPCGenericError {
+    readonly rpcErrorCode = "SecurityError";
+    readonly rpcErrorMessage = "During the processing of action a security issue occurred preventing receiver from completing the action successfully";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCFormationViolationError extends RPCGenericError {
+    readonly rpcErrorCode = "FormationViolation";
+    readonly rpcErrorMessage = "Payload for action is syntactically incorrect or not conform the PDU structure for action";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCFormatViolationError extends RPCGenericError {
+    readonly rpcErrorCode = "FormatViolation";
+    readonly rpcErrorMessage = "Payload is syntactically correct but at least one field contains an invalid value";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCPropertyConstraintViolationError extends RPCGenericError {
+    readonly rpcErrorCode = "PropertyConstraintViolation";
+    readonly rpcErrorMessage = "Payload is syntactically correct but at least one of the fields violates data type constraints";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCOccurrenceConstraintViolationError extends RPCGenericError {
+    readonly rpcErrorCode = "OccurrenceConstraintViolation";
+    readonly rpcErrorMessage = "Payload for action is syntactically correct but at least one of the fields violates occurrence constraints";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCTypeConstraintViolationError extends RPCGenericError {
+    readonly rpcErrorCode = "TypeConstraintViolation";
+    readonly rpcErrorMessage = "Payload for action is syntactically correct but at least one of the fields violates type constraints";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCMessageTypeNotSupportedError extends RPCGenericError {
+    readonly rpcErrorCode = "MessageTypeNotSupported";
+    readonly rpcErrorMessage = "A message with a Message Type Number received that is not supported by this implementation";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RPCFrameworkError extends RPCGenericError {
+    readonly rpcErrorCode = "RpcFrameworkError";
+    readonly rpcErrorMessage = "Content of the call is not a valid RPC request";
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+
+/**
+ * Utility to define and strongly-type a ConnectionMiddleware function.
+ * This provides immediate IDE autocomplete for the `ConnectionContext`.
+ */
+declare function defineMiddleware(mw: ConnectionMiddleware): ConnectionMiddleware;
+/**
+ * Utility to define and strongly-type an RPC Middleware function.
+ * This provides immediate IDE autocomplete for the `MiddlewareContext`
+ * used when passing middleware to `client.use()`.
+ */
+declare function defineRpcMiddleware<TContext = MiddlewareContext>(mw: MiddlewareFunction<TContext>): MiddlewareFunction<TContext>;
+/**
+ * Utility to define and strongly-type an AuthCallback function.
+ * This provides immediate IDE autocomplete for the handshake and arguments.
+ */
+declare function defineAuth<TSession = Record<string, unknown>>(cb: AuthCallback<TSession>): AuthCallback<TSession>;
+/**
+ * Combines multiple AuthCallback functions sequentially.
+ *
+ * Flow matching standard middleware logic:
+ * - If one callback `reject(err)` is called, the loop drops the connection instantly.
+ * - If one callback `accept(opts)` is called, the loop terminates and grants the connection.
+ * - If the loop finishes without anyone calling accept, it rejects with 401 Unauthorized.
+ */
+declare function combineAuth(...cbs: AuthCallback[]): AuthCallback;
+/**
+ * Creates a middleware that logs all RPC exchanges using the provided logger.
+ * Logs start/end of calls and results with duration.
+ */
+declare function createLoggingMiddleware(logger: LoggerLike, identity: string, config?: LoggingConfig | boolean): MiddlewareFunction<MiddlewareContext, any>;
+
+/**
+ * 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 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>;
+    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>;
+}
+
+/**
+ * Pre-built validators for all supported OCPP protocol versions.
+ * These are automatically registered when strict mode is enabled.
+ */
+declare const standardValidators: 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.
+ *
+ * Extracts well-known properties explicitly rather than relying on
+ * Object.getOwnPropertyNames to avoid exposing internal fields and
+ * to guarantee a stable output shape.
+ *
+ * If a property holds a non-serializable value (functions, symbols,
+ * circular references), it is silently skipped.
+ */
+declare function getErrorPlainObject(err: Error): Record<string, unknown>;
+/**
+ * Get the package identifier string used in HTTP headers and logging.
+ * Format: `ocpp-ws-io/1.0.0`
+ */
+declare function getPackageIdent(): string;
+
+export { AllMethodNames, AuthCallback, CORSOptions, CallOptions, CloseOptions, ConnectionMiddleware, EventAdapterInterface, InMemoryAdapter, 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, TimeoutError, TypedEventEmitter, UnexpectedHttpResponse, Validator, WebsocketUpgradeError, combineAuth, createLoggingMiddleware, createRPCError, createRouter, defineAdapter, defineAuth, defineMiddleware, defineRpcMiddleware, getErrorPlainObject, getPackageIdent, standardValidators };