ocpp-ws-io 1.0.0-alpha

package/src/types.ts

@@ -0,0 +1,316 @@
+import type { IncomingMessage } from "node:http";
+import type { TLSSocket } from "node:tls";
+import type { Duplex } from "node:stream";
+import type { Validator } from "./validator.js";
+
+// ─── OCPP Protocol ───────────────────────────────────────────────
+
+export type OCPPProtocol = "ocpp1.6" | "ocpp2.0.1" | "ocpp2.1";
+
+// ─── Connection State ────────────────────────────────────────────
+
+export const ConnectionState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;
+
+export type ConnectionState =
+  (typeof ConnectionState)[keyof typeof ConnectionState];
+
+// ─── Security Profiles (OCPP Spec) ──────────────────────────────
+
+export enum SecurityProfile {
+  /** No security — plain WS, no auth (dev/testing only) */
+  NONE = 0,
+  /** Profile 1: Basic Auth over unsecured WS (ws://) — password-based */
+  BASIC_AUTH = 1,
+  /** Profile 2: TLS + Basic Auth (wss://) — server cert + password */
+  TLS_BASIC_AUTH = 2,
+  /** Profile 3: Mutual TLS (wss://) — client + server certificates */
+  TLS_CLIENT_CERT = 3,
+}
+
+// ─── Message Types ───────────────────────────────────────────────
+
+export const MessageType = {
+  CALL: 2,
+  CALLRESULT: 3,
+  CALLERROR: 4,
+} as const;
+
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+
+// ─── OCPP Message Tuples ─────────────────────────────────────────
+
+export type OCPPCall<T = unknown> = [2, string, string, T];
+export type OCPPCallResult<T = unknown> = [3, string, T];
+export type OCPPCallError = [
+  4,
+  string,
+  string,
+  string,
+  Record<string, unknown>,
+];
+export type OCPPMessage<T = unknown> =
+  | OCPPCall<T>
+  | OCPPCallResult<T>
+  | OCPPCallError;
+
+// ─── TLS Options ─────────────────────────────────────────────────
+
+export interface TLSOptions {
+  /** Server/client certificate (PEM) */
+  cert?: string | Buffer;
+  /** Private key (PEM) */
+  key?: string | Buffer;
+  /** CA certificate(s) for verification */
+  ca?: string | Buffer | Array<string | Buffer>;
+  /** Reject unauthorized certs (default: true) */
+  rejectUnauthorized?: boolean;
+  /** Passphrase for encrypted private key */
+  passphrase?: string;
+}
+
+// ─── Handler Types ───────────────────────────────────────────────
+
+export interface HandlerContext<T = unknown> {
+  messageId: string;
+  method: string;
+  params: T;
+  signal: AbortSignal;
+}
+
+export type CallHandler<TParams = unknown, TResult = unknown> = (
+  context: HandlerContext<TParams>,
+) => TResult | Promise<TResult>;
+
+export type WildcardHandler = (
+  method: string,
+  context: HandlerContext,
+) => unknown | Promise<unknown>;
+
+// ─── Call Options ────────────────────────────────────────────────
+
+export interface CallOptions {
+  /** Timeout in milliseconds for this specific call */
+  timeoutMs?: number;
+  /** Abort signal */
+  signal?: AbortSignal;
+  /** Suppress sending a response (server-side, NOREPLY) */
+  noReply?: boolean;
+}
+
+// ─── Close Options ───────────────────────────────────────────────
+
+export interface CloseOptions {
+  /** WebSocket close code (default: 1000) */
+  code?: number;
+  /** Close reason string */
+  reason?: string;
+  /** Wait for pending calls to complete before closing */
+  awaitPending?: boolean;
+  /** Force-close without waiting */
+  force?: boolean;
+}
+
+// ─── Handshake Info ──────────────────────────────────────────────
+
+export interface HandshakeInfo {
+  /** Charging station identity (from URL path) */
+  identity: string;
+  /** Remote IP address */
+  remoteAddress: string;
+  /** Request headers */
+  headers: Record<string, string | string[] | undefined>;
+  /** Negotiated subprotocols */
+  protocols: Set<string>;
+  /** Request endpoint URL path */
+  endpoint: string;
+  /** URL query parameters */
+  query: URLSearchParams;
+  /** Original HTTP request */
+  request: IncomingMessage;
+  /** Password from Basic Auth (Profile 1 & 2) */
+  password?: Buffer;
+  /** Client certificate (Profile 3 — mTLS) */
+  clientCertificate?: ReturnType<TLSSocket["getPeerCertificate"]>;
+  /** Active security profile */
+  securityProfile: SecurityProfile;
+}
+
+// ─── Session Data ────────────────────────────────────────────────
+
+export type SessionData<T = Record<string, unknown>> = T;
+
+// ─── Client Options ──────────────────────────────────────────────
+
+export interface ClientOptions {
+  /** Unique identity for this client (charging station ID) */
+  identity: string;
+  /** WebSocket endpoint URL (ws:// or wss://) */
+  endpoint: string;
+  /** OCPP Security Profile (default: NONE) */
+  securityProfile?: SecurityProfile;
+  /** Password for Basic Auth (Profile 1 & 2) */
+  password?: string | Buffer;
+  /** TLS options (Profile 2 & 3) */
+  tls?: TLSOptions;
+  /** OCPP subprotocols to negotiate */
+  protocols?: string[];
+  /** Additional WebSocket headers */
+  headers?: Record<string, string>;
+  /** Additional query parameters */
+  query?: Record<string, string>;
+  /** Enable automatic reconnection (default: true) */
+  reconnect?: boolean;
+  /** Maximum reconnection attempts (default: Infinity) */
+  maxReconnects?: number;
+  /** Back-off base delay in ms (default: 1000) */
+  backoffMin?: number;
+  /** Back-off max delay in ms (default: 30000) */
+  backoffMax?: number;
+  /** Call timeout in ms (default: 30000) */
+  callTimeoutMs?: number;
+  /** Ping interval in ms (default: 30000, 0 to disable) */
+  pingIntervalMs?: number;
+  /** Defer pings if activity detected (default: false) */
+  deferPingsOnActivity?: boolean;
+  /** Maximum concurrent outbound calls (default: 1) */
+  callConcurrency?: number;
+  /** Enable strict mode validation (default: false) */
+  strictMode?: boolean | string[];
+  /** Custom validators for strict mode */
+  strictModeValidators?: Validator[];
+  /** Max number of bad messages before closing (default: Infinity) */
+  maxBadMessages?: number;
+  /** Include error details in responses (default: false) */
+  respondWithDetailedErrors?: boolean;
+}
+
+// ─── Server Options ──────────────────────────────────────────────
+
+export interface ServerOptions {
+  /** OCPP Security Profile (default: NONE) */
+  securityProfile?: SecurityProfile;
+  /** TLS options for HTTPS server (Profile 2 & 3) */
+  tls?: TLSOptions;
+  /** Accepted OCPP subprotocols */
+  protocols?: string[];
+  /** Call timeout in ms — inherited by server clients (default: 30000) */
+  callTimeoutMs?: number;
+  /** Ping interval in ms — inherited by server clients (default: 30000) */
+  pingIntervalMs?: number;
+  /** Defer pings if activity detected — inherited (default: false) */
+  deferPingsOnActivity?: boolean;
+  /** Max concurrent outbound calls — inherited (default: 1) */
+  callConcurrency?: number;
+  /** Enable strict mode — inherited (default: false) */
+  strictMode?: boolean | string[];
+  /** Custom validators — inherited */
+  strictModeValidators?: Validator[];
+  /** Max bad messages — inherited (default: Infinity) */
+  maxBadMessages?: number;
+  /** Include error details in responses — inherited (default: false) */
+  respondWithDetailedErrors?: boolean;
+}
+
+// ─── Listen Options ──────────────────────────────────────────────
+
+export interface ListenOptions {
+  /** Existing HTTP/HTTPS server to attach to */
+  server?: import("node:http").Server | import("node:https").Server;
+  /** Hostname to bind to */
+  host?: string;
+  /** Signal to abort the listen */
+  signal?: AbortSignal;
+}
+
+// ─── Auth Callback ───────────────────────────────────────────────
+
+export interface AuthAccept<TSession = Record<string, unknown>> {
+  /** Subprotocol to use for this client */
+  protocol?: string;
+  /** Session data attached to the client */
+  session?: TSession;
+}
+
+export type AuthCallback<TSession = Record<string, unknown>> = (
+  accept: (options?: AuthAccept<TSession>) => void,
+  reject: (code?: number, message?: string) => void,
+  handshake: HandshakeInfo,
+  signal: AbortSignal,
+) => void | Promise<void>;
+
+// ─── Event Types ─────────────────────────────────────────────────
+
+export interface ClientEvents {
+  open: [{ response: IncomingMessage }];
+  close: [{ code: number; reason: string }];
+  error: [Error];
+  connecting: [{ url: string }];
+  reconnect: [{ attempt: number; delay: number }];
+  message: [OCPPMessage];
+  call: [OCPPCall];
+  callResult: [OCPPCallResult];
+  callError: [OCPPCallError];
+  badMessage: [{ message: string; error: Error }];
+  ping: [];
+  pong: [];
+  strictValidationFailure: [{ message: unknown; error: Error }];
+}
+
+export interface ServerEvents<TSession = Record<string, unknown>> {
+  client: [ServerClientInstance<TSession>];
+  error: [Error];
+  upgradeError: [{ error: Error; socket: Duplex }];
+}
+
+// Forward reference for ServerClient (resolved at runtime)
+export type ServerClientInstance<TSession = Record<string, unknown>> = {
+  readonly identity: string;
+  readonly protocol: string | undefined;
+  readonly session: TSession;
+  readonly handshake: HandshakeInfo;
+  readonly state: ConnectionState;
+  close(options?: CloseOptions): Promise<{ code: number; reason: string }>;
+  handle<TParams, TResult>(
+    method: string,
+    handler: CallHandler<TParams, TResult>,
+  ): void;
+  handle(handler: WildcardHandler): void;
+  call<TResult>(
+    method: string,
+    params?: unknown,
+    options?: CallOptions,
+  ): Promise<TResult>;
+  removeHandler(method?: string): void;
+  removeAllHandlers(): void;
+  reconfigure(options: Partial<ClientOptions>): void;
+  on<K extends keyof ClientEvents>(
+    event: K,
+    listener: (...args: ClientEvents[K]) => void,
+  ): void;
+  once<K extends keyof ClientEvents>(
+    event: K,
+    listener: (...args: ClientEvents[K]) => void,
+  ): void;
+  off<K extends keyof ClientEvents>(
+    event: K,
+    listener: (...args: ClientEvents[K]) => void,
+  ): void;
+};
+
+// ─── Event Adapter Interface ─────────────────────────────────────
+
+export interface EventAdapterInterface {
+  publish(channel: string, data: unknown): Promise<void>;
+  subscribe(channel: string, handler: (data: unknown) => void): Promise<void>;
+  unsubscribe(channel: string): Promise<void>;
+  disconnect(): Promise<void>;
+}
+
+// ─── Symbols ─────────────────────────────────────────────────────
+
+export const NOREPLY: unique symbol = Symbol("NOREPLY");

package/src/util.ts

@@ -0,0 +1,119 @@
+import * as errors from "./errors.js";
+import type { RPCError } from "./errors.js";
+
+// ─── RPC Error Factory ──────────────────────────────────────────
+
+/**
+ * Registry mapping OCPP-J RPC error code strings to their corresponding
+ * error constructors. Organized by OCPP spec error category.
+ */
+const RPC_ERROR_REGISTRY = new Map<
+  string,
+  new (message?: string, details?: Record<string, unknown>) => RPCError
+>([
+  // Generic / framework errors
+  ["GenericError", errors.RPCGenericError],
+  ["RpcFrameworkError", errors.RPCFrameworkError],
+  ["MessageTypeNotSupported", errors.RPCMessageTypeNotSupportedError],
+
+  // Action-level errors
+  ["NotImplemented", errors.RPCNotImplementedError],
+  ["NotSupported", errors.RPCNotSupportedError],
+  ["InternalError", errors.RPCInternalError],
+
+  // Protocol / security errors
+  ["ProtocolError", errors.RPCProtocolError],
+  ["SecurityError", errors.RPCSecurityError],
+
+  // Payload validation errors
+  ["FormatViolation", errors.RPCFormatViolationError],
+  ["FormationViolation", errors.RPCFormationViolationError],
+  ["PropertyConstraintViolation", errors.RPCPropertyConstraintViolationError],
+  [
+    "OccurrenceConstraintViolation",
+    errors.RPCOccurrenceConstraintViolationError,
+  ],
+  ["TypeConstraintViolation", errors.RPCTypeConstraintViolationError],
+]);
+
+/**
+ * Instantiate a typed RPCError from a string error code.
+ * Returns an RPCGenericError if the code is not recognized.
+ */
+export function createRPCError(
+  code: string,
+  message?: string,
+  details: Record<string, unknown> = {},
+): RPCError {
+  const Ctor = RPC_ERROR_REGISTRY.get(code) ?? errors.RPCGenericError;
+  return new Ctor(message, details);
+}
+
+// ─── Error Serialization ────────────────────────────────────────
+
+/**
+ * Known error properties to extract, in a defined order.
+ * This covers standard Error fields plus common OCPP RPC fields.
+ */
+const ERROR_PROPERTIES = [
+  "name",
+  "message",
+  "stack",
+  "code",
+  "rpcErrorCode",
+  "rpcErrorMessage",
+  "details",
+] as const;
+
+/**
+ * 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.
+ */
+export function getErrorPlainObject(err: Error): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const prop of ERROR_PROPERTIES) {
+    const value = (err as unknown as Record<string, unknown>)[prop];
+    if (value !== undefined) {
+      // Skip functions and symbols — they aren't JSON-serializable
+      if (typeof value === "function" || typeof value === "symbol") continue;
+
+      // Test serializability for complex values
+      if (typeof value === "object" && value !== null) {
+        try {
+          JSON.stringify(value);
+          result[prop] = value;
+        } catch {
+          // Skip non-serializable properties (circular refs, etc.)
+        }
+      } else {
+        result[prop] = value;
+      }
+    }
+  }
+
+  // Ensure we always have at least name and message
+  if (!result.name) result.name = err.name;
+  if (!result.message) result.message = err.message;
+
+  return result;
+}
+
+// ─── Package Identity ───────────────────────────────────────────
+
+const PKG_NAME = "ocpp-ws-io";
+const PKG_VERSION = "1.0.0";
+
+/**
+ * Get the package identifier string used in HTTP headers and logging.
+ * Format: `ocpp-ws-io/1.0.0`
+ */
+export function getPackageIdent(): string {
+  return `${PKG_NAME}/${PKG_VERSION}`;
+}

package/src/validator.ts

@@ -0,0 +1,148 @@
+import Ajv, { type ValidateFunction } from "ajv";
+import addFormats from "ajv-formats";
+import { createRPCError } from "./util.js";
+
+// ─── Validation Error Mapping ───────────────────────────────────
+
+/**
+ * Maps AJV validation keywords to OCPP-J RPC error codes.
+ *
+ * Rather than listing each keyword individually, this is organized
+ * by the OCPP error category that best describes the validation failure.
+ * The mapping is derived from the OCPP-J specification sections on error codes.
+ */
+
+/** Keywords indicating the data type itself is wrong */
+const TYPE_VIOLATIONS = new Set(["type"]);
+
+/** Keywords indicating a value falls outside allowed bounds or format */
+const FORMAT_VIOLATIONS = new Set([
+  "maximum",
+  "minimum",
+  "maxLength",
+  "minLength",
+  "pattern",
+  "format",
+  "anyOf",
+  "oneOf",
+  "not",
+  "if",
+]);
+
+/** Keywords indicating cardinality / presence constraints are broken */
+const OCCURRENCE_VIOLATIONS = new Set([
+  "required",
+  "maxItems",
+  "minItems",
+  "maxProperties",
+  "minProperties",
+  "additionalProperties",
+  "additionalItems",
+  "exclusiveMaximum",
+  "exclusiveMinimum",
+  "multipleOf",
+]);
+
+/** Keywords indicating a property value is not in the allowed set */
+const PROPERTY_VIOLATIONS = new Set(["enum", "const"]);
+
+/**
+ * Resolve an AJV keyword to the appropriate OCPP RPC error code.
+ */
+function keywordToOCPPError(keyword: string): string {
+  if (TYPE_VIOLATIONS.has(keyword)) return "TypeConstraintViolation";
+  if (OCCURRENCE_VIOLATIONS.has(keyword))
+    return "OccurrenceConstraintViolation";
+  if (PROPERTY_VIOLATIONS.has(keyword)) return "PropertyConstraintViolation";
+  if (FORMAT_VIOLATIONS.has(keyword)) return "FormatViolation";
+  // Fallback for any unknown keywords
+  return "FormatViolation";
+}
+
+// ─── Validator Class ────────────────────────────────────────────
+
+export interface ValidatorSchema {
+  $schema?: string;
+  $id?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Schema validator using AJV for OCPP message validation.
+ * Each validator is bound to a specific subprotocol version.
+ */
+export class Validator {
+  readonly subprotocol: string;
+  /** @internal */
+  _ajv: Ajv;
+
+  constructor(subprotocol: string, schemas: ValidatorSchema[]) {
+    this.subprotocol = subprotocol;
+    this._ajv = new Ajv({
+      allErrors: true,
+      strict: false,
+      multipleOfPrecision: 4,
+    });
+    addFormats(this._ajv);
+
+    // OCPP schemas use non-standard URN $id values like "urn:Authorize.req"
+    // that fast-uri can't serialize. Normalize $id to simple path-based form.
+    for (const schema of schemas) {
+      const normalized = { ...schema };
+      if (normalized.$id && normalized.$id.startsWith("urn:")) {
+        normalized.$id = normalized.$id.replace("urn:", "urn/");
+      }
+      this._ajv.addSchema(normalized);
+    }
+  }
+
+  /**
+   * Normalize a schema ID from OCPP URN format to internal path format.
+   */
+  private _normalizeSchemaId(schemaId: string): string {
+    return schemaId.startsWith("urn:")
+      ? schemaId.replace("urn:", "urn/")
+      : schemaId;
+  }
+
+  /**
+   * Validate a payload against a schema identified by its $id.
+   * Throws a typed RPCError if validation fails.
+   */
+  validate(schemaId: string, params: unknown): void {
+    const resolvedId = this._normalizeSchemaId(schemaId);
+    const validateFn: ValidateFunction | undefined =
+      this._ajv.getSchema(resolvedId);
+
+    if (!validateFn) {
+      // Schema not found — skip validation (not all actions have schemas)
+      return;
+    }
+
+    const isValid = validateFn(params);
+    if (!isValid && validateFn.errors && validateFn.errors.length > 0) {
+      const primaryError = validateFn.errors[0];
+      const ocppErrorCode = keywordToOCPPError(primaryError.keyword);
+      const description = this._ajv.errorsText(validateFn.errors);
+
+      throw createRPCError(ocppErrorCode, description);
+    }
+  }
+
+  /**
+   * Check if a schema exists for the given $id.
+   */
+  hasSchema(schemaId: string): boolean {
+    return !!this._ajv.getSchema(this._normalizeSchemaId(schemaId));
+  }
+}
+
+/**
+ * Create a validator for a specific subprotocol version.
+ */
+export function createValidator(
+  subprotocol: string,
+  schemas: ValidatorSchema[],
+): Validator {
+  return new Validator(subprotocol, schemas);
+}