ocpp-ws-io 1.0.0-alpha

package/src/ws-util.ts

@@ -0,0 +1,186 @@
+/**
+ * WebSocket utility functions for OCPP handshake handling.
+ *
+ * Subprotocol parsing follows RFC 6455 Section 4.1 and
+ * HTTP token rules from RFC 7230 Section 3.2.6.
+ * Close code validation per RFC 6455 Section 7.4.
+ */
+
+import http from "node:http";
+import type { Duplex } from "node:stream";
+
+// ─── Subprotocol Parsing ────────────────────────────────────────
+
+/**
+ * Determine if a character code is a valid HTTP token character.
+ * RFC 7230 Section 3.2.6: tchar = "!" / "#" / "$" / "%" / "&" / "'" /
+ * "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+ */
+function isTChar(c: number): boolean {
+  // ALPHA (A-Z, a-z)
+  if ((c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a)) return true;
+  // DIGIT (0-9)
+  if (c >= 0x30 && c <= 0x39) return true;
+  // Special tchar symbols
+  switch (c) {
+    case 0x21: // !
+    case 0x23: // #
+    case 0x24: // $
+    case 0x25: // %
+    case 0x26: // &
+    case 0x27: // '
+    case 0x2a: // *
+    case 0x2b: // +
+    case 0x2d: // -
+    case 0x2e: // .
+    case 0x5e: // ^
+    case 0x5f: // _
+    case 0x60: // `
+    case 0x7c: // |
+    case 0x7e: // ~
+      return true;
+  }
+  return false;
+}
+
+/**
+ * Parse the `Sec-WebSocket-Protocol` header into a Set of protocol names.
+ *
+ * Implements RFC 6455 Section 4.2.1 grammar for the header value:
+ *   protocol-list = 1#token
+ *   (see RFC 7230 Section 7 for the #rule list extension)
+ *
+ * Whitespace (SP/HTAB) is allowed around commas as per HTTP list rules.
+ * Duplicate protocol names and invalid token characters cause a SyntaxError.
+ */
+export function parseSubprotocols(header: string): Set<string> {
+  if (header.length === 0) {
+    throw new SyntaxError("Unexpected end of input");
+  }
+
+  const protocols = new Set<string>();
+  let cursor = 0;
+
+  while (cursor < header.length) {
+    // Skip leading whitespace before token
+    while (
+      cursor < header.length &&
+      (header.charCodeAt(cursor) === 0x20 || header.charCodeAt(cursor) === 0x09)
+    ) {
+      cursor++;
+    }
+
+    // Expect at least one token character
+    const tokenStart = cursor;
+    while (cursor < header.length && isTChar(header.charCodeAt(cursor))) {
+      cursor++;
+    }
+
+    if (cursor === tokenStart) {
+      throw new SyntaxError(`Unexpected character at index ${cursor}`);
+    }
+
+    const token = header.substring(tokenStart, cursor);
+
+    if (protocols.has(token)) {
+      throw new SyntaxError(`The "${token}" subprotocol is duplicated`);
+    }
+    protocols.add(token);
+
+    // Skip trailing whitespace after token
+    while (
+      cursor < header.length &&
+      (header.charCodeAt(cursor) === 0x20 || header.charCodeAt(cursor) === 0x09)
+    ) {
+      cursor++;
+    }
+
+    // Expect end of string or comma separator
+    if (cursor >= header.length) break;
+
+    if (header.charCodeAt(cursor) !== 0x2c /* , */) {
+      throw new SyntaxError(`Unexpected character at index ${cursor}`);
+    }
+    cursor++; // consume comma
+
+    // After a comma, there must be another token — trailing comma is invalid
+    // (We'll check at the start of the next iteration)
+    // Peek ahead: if only whitespace remains, it's a trailing comma
+    let peek = cursor;
+    while (
+      peek < header.length &&
+      (header.charCodeAt(peek) === 0x20 || header.charCodeAt(peek) === 0x09)
+    ) {
+      peek++;
+    }
+    if (peek >= header.length || !isTChar(header.charCodeAt(peek))) {
+      throw new SyntaxError("Unexpected end of input");
+    }
+  }
+
+  // Ensure we actually got at least one protocol
+  if (protocols.size === 0) {
+    throw new SyntaxError("Unexpected end of input");
+  }
+
+  return protocols;
+}
+
+// ─── Close Code Validation ──────────────────────────────────────
+
+/**
+ * Reserved close codes that MUST NOT be set in a Close frame.
+ * Per RFC 6455 Section 7.4.1.
+ */
+const RESERVED_CLOSE_CODES = new Set([1004, 1005, 1006]);
+
+/**
+ * Check if a WebSocket close status code is valid for use in a Close frame.
+ *
+ * Per RFC 6455 Section 7.4:
+ * - 1000–1014 are valid (except 1004, 1005, 1006 which are reserved)
+ * - 3000–4999 are available for application/library/framework use
+ */
+export function isValidStatusCode(code: number): boolean {
+  if (code >= 1000 && code <= 1014 && !RESERVED_CLOSE_CODES.has(code)) {
+    return true;
+  }
+  if (code >= 3000 && code <= 4999) {
+    return true;
+  }
+  return false;
+}
+
+// ─── Handshake Abort ────────────────────────────────────────────
+
+/**
+ * Reject a WebSocket upgrade by sending an HTTP error response
+ * to the raw socket and closing the connection.
+ */
+export function abortHandshake(
+  socket: Duplex,
+  statusCode: number,
+  reason?: string,
+  extraHeaders?: Record<string, string>,
+): void {
+  if (!socket.writable) return;
+
+  const statusText = http.STATUS_CODES[statusCode] ?? "Unknown";
+  const body = reason ?? statusText;
+  const bodyBytes = Buffer.byteLength(body, "utf8");
+
+  const allHeaders: Record<string, string | number> = {
+    Connection: "close",
+    "Content-Type": "text/plain; charset=utf-8",
+    "Content-Length": bodyBytes,
+    ...extraHeaders,
+  };
+
+  const headerBlock = Object.entries(allHeaders)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join("\r\n");
+
+  socket.end(
+    `HTTP/1.1 ${statusCode} ${statusText}\r\n${headerBlock}\r\n\r\n${body}`,
+  );
+}

package/test/adapter.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { InMemoryAdapter } from "../src/adapters/adapter.js";
+
+describe("InMemoryAdapter", () => {
+  it("should publish and receive messages", async () => {
+    const adapter = new InMemoryAdapter();
+    let received: unknown;
+
+    await adapter.subscribe("test", (data) => {
+      received = data;
+    });
+
+    await adapter.publish("test", { hello: "world" });
+    expect(received).toEqual({ hello: "world" });
+  });
+
+  it("should support multiple subscribers", async () => {
+    const adapter = new InMemoryAdapter();
+    const received: unknown[] = [];
+
+    await adapter.subscribe("ch", (data) => received.push(`a:${data}`));
+    await adapter.subscribe("ch", (data) => received.push(`b:${data}`));
+
+    await adapter.publish("ch", "msg1");
+    expect(received).toEqual(["a:msg1", "b:msg1"]);
+  });
+
+  it("should not deliver to unrelated channels", async () => {
+    const adapter = new InMemoryAdapter();
+    let received = false;
+
+    await adapter.subscribe("channelA", () => {
+      received = true;
+    });
+    await adapter.publish("channelB", "data");
+
+    expect(received).toBe(false);
+  });
+
+  it("should unsubscribe from a channel", async () => {
+    const adapter = new InMemoryAdapter();
+    let count = 0;
+
+    await adapter.subscribe("ch", () => {
+      count++;
+    });
+    await adapter.publish("ch", "msg1");
+    expect(count).toBe(1);
+
+    await adapter.unsubscribe("ch");
+    await adapter.publish("ch", "msg2");
+    expect(count).toBe(1); // Still 1 after unsubscribe
+  });
+
+  it("should clear all channels on disconnect", async () => {
+    const adapter = new InMemoryAdapter();
+    let count = 0;
+
+    await adapter.subscribe("ch1", () => {
+      count++;
+    });
+    await adapter.subscribe("ch2", () => {
+      count++;
+    });
+
+    await adapter.disconnect();
+
+    await adapter.publish("ch1", "x");
+    await adapter.publish("ch2", "x");
+    expect(count).toBe(0);
+  });
+
+  it("should swallow handler errors silently", async () => {
+    const adapter = new InMemoryAdapter();
+    let secondCalled = false;
+
+    await adapter.subscribe("ch", () => {
+      throw new Error("oops");
+    });
+    await adapter.subscribe("ch", () => {
+      secondCalled = true;
+    });
+
+    // Should not throw
+    await adapter.publish("ch", "data");
+    expect(secondCalled).toBe(true);
+  });
+});

package/test/client.test.ts

@@ -0,0 +1,297 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { OCPPServer } from "../src/server.js";
+import { OCPPClient } from "../src/client.js";
+import { SecurityProfile } from "../src/types.js";
+import type { OCPPServerClient } from "../src/server-client.js";
+
+let server: OCPPServer;
+let client: OCPPClient;
+let port: number;
+
+const getPort = (srv: import("node:http").Server): number => {
+  const addr = srv.address();
+  if (addr && typeof addr !== "string") return addr.port;
+  return 0;
+};
+
+describe("OCPPClient", () => {
+  beforeEach(async () => {
+    server = new OCPPServer({ protocols: ["ocpp1.6"] });
+    server.auth((accept, _reject, _handshake) => {
+      accept({ protocol: "ocpp1.6" });
+    });
+    const httpServer = await server.listen(0);
+    port = getPort(httpServer);
+  });
+
+  afterEach(async () => {
+    if (client) await client.close({ force: true }).catch(() => {});
+    await server.close({ force: true });
+  });
+
+  it("should throw if identity is missing", () => {
+    expect(
+      () =>
+        new OCPPClient({
+          identity: "",
+          endpoint: "ws://localhost:9999",
+        }),
+    ).toThrow("identity is required");
+  });
+
+  it("should be in CLOSED state initially", () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+    expect(client.state).toBe(OCPPClient.CLOSED);
+  });
+
+  it("should connect successfully", async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    await client.connect();
+    expect(client.state).toBe(OCPPClient.OPEN);
+    expect(client.protocol).toBe("ocpp1.6");
+  });
+
+  it('should emit "open" event on connect', async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    let opened = false;
+    client.on("open", () => {
+      opened = true;
+    });
+    await client.connect();
+    expect(opened).toBe(true);
+  });
+
+  it("should reject connect when already connected", async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    await client.connect();
+    await expect(client.connect()).rejects.toThrow("Cannot connect");
+  });
+
+  it("should close gracefully", async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    await client.connect();
+    const result = await client.close();
+    expect(result.code).toBe(1000);
+    expect(client.state).toBe(OCPPClient.CLOSED);
+  });
+
+  it("should handle RPC call and response", async () => {
+    // Set up server handler BEFORE client connects
+    server.on("client", (serverClient: OCPPServerClient) => {
+      serverClient.handle("BootNotification", async () => {
+        return {
+          status: "Accepted",
+          currentTime: new Date().toISOString(),
+          interval: 300,
+        };
+      });
+    });
+
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    await client.connect();
+
+    const result = await client.call<{ status: string }>("BootNotification", {
+      chargePointModel: "TestModel",
+      chargePointVendor: "TestVendor",
+    });
+
+    expect(result.status).toBe("Accepted");
+  });
+
+  it("should receive NotImplemented for unhandled calls", async () => {
+    // Server has no handler for UnhandledAction, so it returns NotImplemented
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+      callTimeoutMs: 2000,
+    });
+
+    await client.connect();
+
+    await expect(client.call("UnhandledAction", {})).rejects.toThrow(
+      /not known|NotImplemented/,
+    );
+  });
+
+  it("should support abort signal on calls", async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    await client.connect();
+
+    const ac = new AbortController();
+    const callPromise = client.call("SlowAction", {}, { signal: ac.signal });
+    ac.abort();
+
+    await expect(callPromise).rejects.toThrow();
+  });
+
+  it("should receive calls from server", async () => {
+    let receivedMethod = "";
+
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    client.handle("Reset", async (ctx) => {
+      receivedMethod = ctx.method;
+      return { status: "Accepted" };
+    });
+
+    // Set up server handler BEFORE connecting
+    const serverCallPromise = new Promise<void>((resolve, reject) => {
+      server.on("client", async (serverClient: OCPPServerClient) => {
+        try {
+          const result = await serverClient.call<{ status: string }>("Reset", {
+            type: "Hard",
+          });
+          expect(result.status).toBe("Accepted");
+          resolve();
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+
+    await client.connect();
+    await serverCallPromise;
+    expect(receivedMethod).toBe("Reset");
+  });
+
+  it("should handle wildcard handlers", async () => {
+    let wildcardMethod = "";
+
+    client = new OCPPClient({
+      identity: "CS002",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    client.handle((method, _ctx) => {
+      wildcardMethod = method;
+      return { status: "Accepted" };
+    });
+
+    const serverCallPromise = new Promise<void>((resolve, reject) => {
+      server.on("client", async (serverClient: OCPPServerClient) => {
+        try {
+          await serverClient.call("AnyMethod", {});
+          resolve();
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+
+    await client.connect();
+    await serverCallPromise;
+    expect(wildcardMethod).toBe("AnyMethod");
+  });
+
+  it("should remove specific handlers", async () => {
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      reconnect: false,
+    });
+
+    client.handle("Test", async () => ({ result: "ok" }));
+    client.removeHandler("Test");
+
+    const serverCallPromise = new Promise<void>((resolve, reject) => {
+      server.on("client", async (serverClient: OCPPServerClient) => {
+        try {
+          await serverClient.call("Test", {});
+          reject(new Error("Should have thrown"));
+        } catch {
+          resolve();
+        }
+      });
+    });
+
+    await client.connect();
+    await serverCallPromise;
+  });
+});
+
+describe("OCPPClient - Security Profiles", () => {
+  afterEach(async () => {
+    if (client) await client.close({ force: true }).catch(() => {});
+    if (server) await server.close({ force: true });
+  });
+
+  it("should include Basic Auth header for Profile 1", async () => {
+    let receivedPassword: Buffer | undefined;
+
+    server = new OCPPServer({ protocols: ["ocpp1.6"] });
+    server.auth((accept, _reject, handshake) => {
+      receivedPassword = handshake.password;
+      accept({ protocol: "ocpp1.6" });
+    });
+    const httpServer = await server.listen(0);
+    port = getPort(httpServer);
+
+    client = new OCPPClient({
+      identity: "CS001",
+      endpoint: `ws://localhost:${port}`,
+      protocols: ["ocpp1.6"],
+      securityProfile: SecurityProfile.BASIC_AUTH,
+      password: "myPassword123",
+      reconnect: false,
+    });
+
+    await client.connect();
+
+    // Give the server a moment to process
+    await new Promise((r) => setTimeout(r, 100));
+
+    expect(receivedPassword).toBeDefined();
+    expect(receivedPassword!.toString()).toBe("myPassword123");
+  });
+});

package/test/errors.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import {
+  RPCGenericError,
+  RPCNotImplementedError,
+  RPCNotSupportedError,
+  RPCInternalError,
+  RPCProtocolError,
+  RPCSecurityError,
+  RPCFormationViolationError,
+  RPCFormatViolationError,
+  RPCPropertyConstraintViolationError,
+  RPCOccurrenceConstraintViolationError,
+  RPCTypeConstraintViolationError,
+  RPCMessageTypeNotSupportedError,
+  RPCFrameworkError,
+  TimeoutError,
+  UnexpectedHttpResponse,
+  WebsocketUpgradeError,
+} from "../src/errors.js";
+
+describe("Error Classes", () => {
+  it("TimeoutError should have correct properties", () => {
+    const err = new TimeoutError("custom timeout");
+    expect(err.name).toBe("TimeoutError");
+    expect(err.message).toBe("custom timeout");
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it("TimeoutError should have default message", () => {
+    const err = new TimeoutError();
+    expect(err.message).toBe("Operation timed out");
+  });
+
+  it("UnexpectedHttpResponse should include status code and headers", () => {
+    const err = new UnexpectedHttpResponse("bad response", 401, {
+      "www-authenticate": "Basic",
+    });
+    expect(err.name).toBe("UnexpectedHttpResponse");
+    expect(err.statusCode).toBe(401);
+    expect(err.headers["www-authenticate"]).toBe("Basic");
+  });
+
+  it("WebsocketUpgradeError should have default message", () => {
+    const err = new WebsocketUpgradeError();
+    expect(err.name).toBe("WebsocketUpgradeError");
+    expect(err.message).toBe("WebSocket upgrade failed");
+  });
+
+  it("RPCGenericError should have correct code", () => {
+    const err = new RPCGenericError("test");
+    expect(err.rpcErrorCode).toBe("GenericError");
+    expect(err.name).toBe("RPCGenericError");
+  });
+
+  it("RPCNotImplementedError should have correct code and message", () => {
+    const err = new RPCNotImplementedError("test");
+    expect(err.rpcErrorCode).toBe("NotImplemented");
+    expect(err.rpcErrorMessage).toBe("Requested method is not known");
+  });
+
+  it("RPCNotSupportedError should have correct code", () => {
+    const err = new RPCNotSupportedError();
+    expect(err.rpcErrorCode).toBe("NotSupported");
+  });
+
+  it("RPCInternalError should have correct code", () => {
+    const err = new RPCInternalError();
+    expect(err.rpcErrorCode).toBe("InternalError");
+  });
+
+  it("RPCProtocolError should have correct code", () => {
+    const err = new RPCProtocolError();
+    expect(err.rpcErrorCode).toBe("ProtocolError");
+  });
+
+  it("RPCSecurityError should have correct code", () => {
+    const err = new RPCSecurityError();
+    expect(err.rpcErrorCode).toBe("SecurityError");
+  });
+
+  it("RPCFormationViolationError should have correct code", () => {
+    const err = new RPCFormationViolationError();
+    expect(err.rpcErrorCode).toBe("FormationViolation");
+  });
+
+  it("RPCFormatViolationError should have correct code", () => {
+    const err = new RPCFormatViolationError();
+    expect(err.rpcErrorCode).toBe("FormatViolation");
+  });
+
+  it("RPCPropertyConstraintViolationError should have correct code", () => {
+    const err = new RPCPropertyConstraintViolationError();
+    expect(err.rpcErrorCode).toBe("PropertyConstraintViolation");
+  });
+
+  it("RPCOccurrenceConstraintViolationError should have correct code", () => {
+    const err = new RPCOccurrenceConstraintViolationError();
+    expect(err.rpcErrorCode).toBe("OccurrenceConstraintViolation");
+  });
+
+  it("RPCTypeConstraintViolationError should have correct code", () => {
+    const err = new RPCTypeConstraintViolationError();
+    expect(err.rpcErrorCode).toBe("TypeConstraintViolation");
+  });
+
+  it("RPCMessageTypeNotSupportedError should have correct code", () => {
+    const err = new RPCMessageTypeNotSupportedError();
+    expect(err.rpcErrorCode).toBe("MessageTypeNotSupported");
+  });
+
+  it("RPCFrameworkError should have correct code", () => {
+    const err = new RPCFrameworkError();
+    expect(err.rpcErrorCode).toBe("RpcFrameworkError");
+  });
+
+  it("all RPC errors should extend RPCGenericError chain", () => {
+    const errors = [
+      new RPCGenericError(),
+      new RPCNotImplementedError(),
+      new RPCInternalError(),
+      new RPCFormatViolationError(),
+    ];
+    for (const err of errors) {
+      expect(err).toBeInstanceOf(Error);
+    }
+  });
+
+  it("RPC errors should carry details", () => {
+    const err = new RPCGenericError("msg", { foo: "bar" });
+    expect(err.details).toEqual({ foo: "bar" });
+  });
+});