@aloma.io/integration-sdk 3.8.67 → 3.8.69

package/src/testing/fake-aloma.mts

@@ -0,0 +1,306 @@
+import {randomUUID} from 'node:crypto';
+import http from 'node:http';
+import type {AddressInfo} from 'node:net';
+import * as jose from 'jose';
+import {WebSocket, WebSocketServer} from 'ws';
+
+type Packet = {id?: string; m?: string; c?: string; a?: any; e?: any};
+
+/**
+ * A fake ALOMA endpoint that speaks the connector protocol, in-process on a loopback port.
+ *
+ * Protocol (taken from src/internal/websocket and src/internal/dispatcher):
+ *  1. POST {url}connect with `Authorization: Connector <token>`. 401 means "register first", 200 + json means connected.
+ *  2. POST {url}register with `Authorization: Connector <registrationToken>` and
+ *     {name, version, id, publicKey, schema:{configSchema, introspect}, icon}; answer 200 {key: <token>}.
+ *  3. The connector opens a websocket at wsUrl (subprotocol "connector", same Authorization header).
+ *  4. Both sides exchange text frames {p: [packet, ...]}; a packet is {id, m: method, c: callback key, a: args}.
+ *  5. ALOMA sends connector.set-config {secrets} (no reply), then connector.query {query, variables} with a
+ *     callback key; the connector answers {c: key, a: result} or {c: key, a: {error}}.
+ *
+ * Anything that does not look like the real protocol is recorded in `protocolErrors`.
+ */
+export class FakeAloma {
+  readonly registrationToken = `fake-registration-${randomUUID()}`;
+  readonly sessionToken = `fake-session-${randomUUID()}`;
+
+  /** bodies of POST /register */
+  readonly registrations: any[] = [];
+  /** headers of POST /connect */
+  readonly connects: Array<{authorized: boolean; headers: http.IncomingHttpHeaders}> = [];
+  /** every packet the connector sent over the websocket, in order */
+  readonly received: Packet[] = [];
+  readonly protocolErrors: string[] = [];
+
+  private server!: http.Server;
+  private wss!: WebSocketServer;
+  private socket?: WebSocket;
+  private pending = new Map<string, (args: any) => void>();
+  private handlers = new Map<string, (args: any) => any | Promise<any>>();
+  private waiters: Array<() => void> = [];
+  private port = 0;
+  private id = '';
+  private version = '';
+
+  static async start(): Promise<FakeAloma> {
+    const fake = new FakeAloma();
+    await fake.listen();
+
+    return fake;
+  }
+
+  /** value for the connector's endpoint setting (env.DEVICE_ENDPOINT) */
+  get url() {
+    return `http://127.0.0.1:${this.port}/`;
+  }
+
+  /** value for the connector's websocket setting (env.WEBSOCKET_ENDPOINT) */
+  get wsUrl() {
+    return `ws://127.0.0.1:${this.port}/transport/`;
+  }
+
+  get connected() {
+    return this.socket?.readyState === WebSocket.OPEN;
+  }
+
+  get registration() {
+    return this.registrations[this.registrations.length - 1];
+  }
+
+  private async listen() {
+    this.server = http.createServer((req, res) => {
+      this.onHttp(req, res).catch((e) => {
+        this.protocolErrors.push(`http handler failed: ${e}`);
+        res.writeHead(500).end();
+      });
+    });
+
+    this.wss = new WebSocketServer({
+      noServer: true,
+      handleProtocols: (protocols) => (protocols.has('connector') ? 'connector' : false),
+    });
+
+    this.server.on('upgrade', (req, socket, head) => {
+      const problems: string[] = [];
+      if (req.headers.authorization !== `Connector ${this.sessionToken}`) problems.push('bad or missing Authorization on websocket');
+      if (!String(req.headers['sec-websocket-protocol'] || '').split(/,\s*/).includes('connector')) {
+        problems.push('websocket subprotocol "connector" not requested');
+      }
+
+      if (problems.length) {
+        this.protocolErrors.push(...problems);
+        socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+
+      this.wss.handleUpgrade(req, socket, head, (ws) => this.onSocket(ws));
+    });
+
+    await new Promise<void>((resolve) => this.server.listen(0, '127.0.0.1', () => resolve()));
+    this.port = (this.server.address() as AddressInfo).port;
+  }
+
+  private async readJson(req: http.IncomingMessage) {
+    let text = '';
+    for await (const chunk of req) text += chunk;
+
+    return text ? JSON.parse(text) : {};
+  }
+
+  private async onHttp(req: http.IncomingMessage, res: http.ServerResponse) {
+    const send = (status: number, body?: unknown) => {
+      res.writeHead(status, {'Content-Type': 'application/json'});
+      res.end(body === undefined ? '' : JSON.stringify(body));
+    };
+
+    const body = await this.readJson(req);
+    const auth = req.headers.authorization;
+
+    if (req.method === 'POST' && req.url === '/connect') {
+      const authorized = auth === `Connector ${this.sessionToken}`;
+      this.connects.push({authorized, headers: req.headers});
+
+      return authorized ? send(200, {}) : send(401);
+    }
+
+    if (req.method === 'POST' && req.url === '/register') {
+      if (auth !== `Connector ${this.registrationToken}`) {
+        this.protocolErrors.push('register called with a wrong registration token');
+        return send(401);
+      }
+
+      const missing = ['name', 'version', 'id', 'publicKey', 'schema'].filter((key) => body[key] == null);
+      if (missing.length) this.protocolErrors.push(`register body is missing: ${missing.join(', ')}`);
+
+      this.id = body.id;
+      this.version = body.version;
+      if (req.headers['user-agent'] !== `${body.id}/${body.version}`) {
+        this.protocolErrors.push(`register User-Agent should be id/version, got ${req.headers['user-agent']}`);
+      }
+
+      this.registrations.push(body);
+
+      return send(200, {key: this.sessionToken});
+    }
+
+    if (req.method === 'POST' && req.url === '/disconnect') return send(200, {});
+
+    this.protocolErrors.push(`unexpected request ${req.method} ${req.url}`);
+    send(404);
+  }
+
+  private onSocket(ws: WebSocket) {
+    this.socket = ws;
+
+    ws.on('message', (raw) => {
+      const frame = JSON.parse(raw.toString());
+      const packets: Packet[] = frame.p;
+
+      if (!Array.isArray(packets)) {
+        this.protocolErrors.push('frame without a "p" array');
+        return;
+      }
+
+      packets.forEach((packet) => this.onPacket(packet));
+    });
+
+    this.waiters.splice(0).forEach((fn) => fn());
+  }
+
+  private onPacket(packet: Packet) {
+    this.received.push(packet);
+
+    // an answer to something ALOMA sent
+    if (packet.c && !packet.m && this.pending.has(packet.c)) {
+      const done = this.pending.get(packet.c)!;
+      this.pending.delete(packet.c);
+      done(packet.a);
+      return;
+    }
+
+    // the connector asks ALOMA for something (blob, task, ...) and expects an answer on its callback key
+    if (packet.m && this.handlers.has(packet.m)) {
+      Promise.resolve(this.handlers.get(packet.m)!(packet.a)).then(
+        (answer) => packet.c && this.send({c: packet.c, a: answer}),
+        (e) => packet.c && this.send({c: packet.c, a: {error: String(e)}})
+      );
+    }
+  }
+
+  /** answer connector -> ALOMA requests such as connector.blob.get or connector.task.new */
+  handle(method: string, fn: (args: any) => any | Promise<any>) {
+    this.handlers.set(method, fn);
+    return this;
+  }
+
+  /** resolves when the connector's websocket is open (the handshake is finished) */
+  async waitForConnection(timeoutMs = 5000) {
+    if (this.connected) return;
+
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `connector did not connect within ${timeoutMs}ms. registrations=${this.registrations.length} ` +
+              `connects=${this.connects.length} protocolErrors=${JSON.stringify(this.protocolErrors)}`
+          )
+        );
+      }, timeoutMs);
+
+      this.waiters.push(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
+  /** resolves with the first packet the connector sent for `method` (e.g. connector.health.check), now or later */
+  async waitForPacket(method: string, timeoutMs = 5000): Promise<Packet> {
+    const deadline = Date.now() + timeoutMs;
+
+    for (;;) {
+      const found = this.received.find((packet) => packet.m === method);
+      if (found) return found;
+      if (Date.now() > deadline) throw new Error(`connector did not send ${method} within ${timeoutMs}ms`);
+
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+
+  /** send one raw packet to the connector */
+  send(packet: Packet) {
+    if (!this.connected) throw new Error('connector is not connected');
+
+    this.socket!.send(JSON.stringify({p: [{id: randomUUID(), ...packet}]}));
+  }
+
+  /** send a packet with a callback key and wait for the connector's answer (its `a` field) */
+  request(method: string, args: any, timeoutMs = 5000): Promise<any> {
+    const key = `_req-${randomUUID()}`;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(key);
+        reject(new Error(`no answer to ${method} within ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pending.set(key, (answer) => {
+        clearTimeout(timer);
+        resolve(answer);
+      });
+
+      this.send({m: method, c: key, a: args});
+    });
+  }
+
+  /** ask the connector for its schema and method list (connector.introspect) */
+  introspect() {
+    return this.request('connector.introspect', {});
+  }
+
+  /**
+   * Send the configuration the way ALOMA does: every field that is not `plain` is a JWE encrypted with the
+   * public key the connector registered, audience = connector id. Resolves after the packet is sent;
+   * the ConnectorHarness waits for the connector's start.
+   */
+  async setConfig(values: Record<string, any>) {
+    if (!this.registration) throw new Error('connector has not registered yet');
+
+    const fields = this.registration.schema?.configSchema?.fields || {};
+    const publicKey = await jose.importSPKI(Buffer.from(this.registration.publicKey, 'base64').toString(), 'RSA-OAEP-256');
+    const secrets: Record<string, any> = {};
+
+    for (const [key, value] of Object.entries(values)) {
+      if (fields[key]?.plain || key === 'endpointUrl') {
+        secrets[key] = value;
+        continue;
+      }
+
+      secrets[key] = await new jose.EncryptJWT({_data: value})
+        .setProtectedHeader({alg: 'RSA-OAEP-256', enc: 'A256GCM'})
+        .setIssuedAt()
+        .setIssuer('home.aloma.io')
+        .setAudience(this.id)
+        .encrypt(publicKey);
+    }
+
+    this.send({m: 'connector.set-config', a: {secrets}});
+  }
+
+  /**
+   * Call a connector method like ALOMA does (connector.query). Resolves with the connector's raw answer:
+   * an object result is passed through, any other value is wrapped as {[method]: value}, a failure is {error}.
+   */
+  call(method: string | string[], variables?: any, ctx: {taskId?: string; namespace?: string; sticky?: boolean} = {}) {
+    return this.request('connector.query', {query: method, variables, ...ctx});
+  }
+
+  async close() {
+    this.pending.clear();
+    this.wss.clients.forEach((client) => client.terminate());
+    this.wss.close();
+    this.server.closeAllConnections?.();
+    await new Promise<void>((resolve) => this.server.close(() => resolve()));
+  }
+}

package/src/testing/harness.mts

@@ -0,0 +1,172 @@
+import {Config} from '../internal/websocket/config.mjs';
+import {WebsocketConnector} from '../internal/websocket/index.mjs';
+import {onConnect} from '../internal/connector/server/on-connect/index.mjs';
+import {onMessage} from '../internal/connector/server/on-message.mjs';
+import type {Connector} from '../internal/connector/index.mjs';
+import {FakeAloma} from './fake-aloma.mjs';
+import {testKeyPair} from './keys.mjs';
+import {VendorMock} from './vendor-mock.mjs';
+
+export type HarnessOptions = {
+  /**
+   * The connector under test, already configured:
+   * `const c = new Connector({id, version, name}); c.configure().types(...).resolvers(...).main(...)`
+   */
+  connector: Connector;
+  /** vendor mock; a fresh one is created when omitted */
+  vendor?: VendorMock;
+  /**
+   * configuration values ALOMA sends after the handshake (encrypted unless the field is `plain`).
+   * `null` skips sending any configuration (the connector then never starts its main()).
+   */
+  config?: Record<string, any> | null;
+  /** how long to wait for each step, ms */
+  timeoutMs?: number;
+};
+
+/**
+ * Runs a real connector against a fake ALOMA, in-process.
+ *
+ * It wires the same SDK parts as Connector.run() and makeServer(): Config, WebsocketConnector (connection,
+ * registration, transport), onConnect (config decryption, main()), onMessage (dispatch and reply).
+ * Left out on purpose: the Prometheus metrics server (fixed port 4050), process signal handlers and
+ * env-var configuration, which are global side effects that cannot run once per test.
+ */
+export class ConnectorHarness {
+
+  private constructor(
+    readonly aloma: FakeAloma,
+    readonly vendor: VendorMock,
+    private readonly server: WebsocketConnector,
+    private readonly started: Promise<void> | null
+  ) {}
+
+  static async start(options: HarnessOptions): Promise<ConnectorHarness> {
+    const {connector, timeoutMs = 5000} = options;
+    const dispatcher: any = connector.dispatcher;
+    if (!dispatcher) throw new Error('call connector.configure() before starting the harness');
+
+    const vendor = options.vendor || new VendorMock();
+    const aloma = await FakeAloma.start();
+    vendor.allowPassthrough((url) => url.origin === new URL(aloma.url).origin);
+    vendor.install();
+
+    // main() is what a connector runs once ALOMA has sent its configuration; observe it
+    let mainDone!: () => void;
+    let mainFailed!: (e: unknown) => void;
+    const started = new Promise<void>((resolve, reject) => {
+      mainDone = resolve;
+      mainFailed = reject;
+    });
+    started.catch(() => {});
+
+    const originalMain = dispatcher._main;
+    dispatcher.main(async (arg) => {
+      try {
+        await originalMain?.(arg);
+        mainDone();
+      } catch (e) {
+        mainFailed(e);
+        throw e;
+      }
+    });
+
+    let server: WebsocketConnector | undefined;
+
+    try {
+      const {processPacket, start, introspect, configSchema} = dispatcher.build();
+      const keys = await testKeyPair();
+
+      const config = new Config({
+        id: connector.id,
+        version: connector.version,
+        name: connector.name,
+        registrationToken: aloma.registrationToken,
+        endpoint: aloma.url,
+        wsEndpoint: aloma.wsUrl,
+        privateKey: keys.privateKey,
+        publicKey: keys.publicKey,
+        introspect,
+        configSchema,
+        icon: connector.icon,
+      });
+
+      server = new WebsocketConnector({
+        config,
+        onConnect: onConnect({config, configSchema, dispatcher, start}),
+        onMessage: onMessage(processPacket),
+      });
+
+      const harness = new ConnectorHarness(aloma, vendor, server, options.config === null ? null : started);
+
+      await server.start();
+      await aloma.waitForConnection(timeoutMs);
+
+      if (options.config !== null) {
+        await aloma.setConfig(options.config || {});
+        await withTimeout(started, timeoutMs, 'connector main() did not finish after the configuration was sent');
+      }
+
+      return harness;
+    } catch (e) {
+      await ConnectorHarness.shutdown(server, vendor, aloma);
+      throw e;
+    }
+  }
+
+  private static async shutdown(server: WebsocketConnector | undefined, vendor: VendorMock, aloma: FakeAloma) {
+    try {
+      if (server) {
+        const anyServer: any = server;
+
+        await anyServer.leaving();
+        await anyServer.close();
+
+        // the SDK leaves a 45s ping watchdog timer behind; clear it so a test run can exit
+        clearTimeout(anyServer.transport?.ws?.pingTimeout);
+      }
+    } finally {
+      vendor.uninstall();
+      await aloma.close();
+    }
+  }
+
+  /** call a connector method and return the raw answer (`{error}` when it failed) */
+  call(method: string | string[], variables?: any, ctx?: {taskId?: string; namespace?: string; sticky?: boolean}) {
+    return this.aloma.call(method, variables, ctx);
+  }
+
+  /** call a connector method; throws when the connector answered with an error */
+  async callOk(method: string | string[], variables?: any) {
+    const answer = await this.call(method, variables);
+    if (answer?.error) throw new Error(`${method} failed: ${answer.error}`);
+
+    return answer;
+  }
+
+  /**
+   * Shut down the connector and the fake endpoint, restore fetch and the network guard.
+   * Then fails if the connector made any request that was not mocked or the fake endpoint saw a protocol error.
+   */
+  async stop({verify = true}: {verify?: boolean} = {}) {
+    await ConnectorHarness.shutdown(this.server, this.vendor, this.aloma);
+
+    if (verify) {
+      this.vendor.verify();
+      if (this.aloma.protocolErrors.length) {
+        throw new Error(`protocol errors seen by the fake ALOMA: ${JSON.stringify(this.aloma.protocolErrors)}`);
+      }
+    }
+  }
+}
+
+const withTimeout = <T,>(promise: Promise<T>, ms: number, message: string): Promise<T> => {
+  let timer: NodeJS.Timeout;
+
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error(message)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+};

package/src/testing/index.mts

@@ -0,0 +1,15 @@
+/**
+ * Test harness for connectors built on the ALOMA integration SDK.
+ *
+ *   import {ConnectorHarness, VendorMock} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+ *
+ * Test tooling only: nothing in the SDK runtime imports this folder.
+ */
+export {ConnectorHarness} from './harness.mjs';
+export type {HarnessOptions} from './harness.mjs';
+export {FakeAloma} from './fake-aloma.mjs';
+export {VendorMock} from './vendor-mock.mjs';
+export type {VendorRequest, VendorResponse, VendorResponder, UrlMatcher} from './vendor-mock.mjs';
+export {installNetworkGuard, uninstallNetworkGuard} from './network-guard.mjs';
+export {testKeyPair} from './keys.mjs';
+export {connectorFromRuntimeContext} from './runtime-connector.mjs';

package/src/testing/keys.mts

@@ -0,0 +1,19 @@
+import JWE from '../internal/util/jwe/index.mjs';
+
+let pair: Promise<{privateKey: string; publicKey: string}> | undefined;
+
+/**
+ * One throwaway RSA key pair per process, generated at test time.
+ * Never committed, never a real key. Same encoding the connector expects in
+ * env.PRIVATE_KEY / env.PUBLIC_KEY (base64 of the PEM).
+ */
+export const testKeyPair = () => {
+  pair ||= (async () => {
+    const jwe = new JWE({algorithm: 'RSA-OAEP-256'});
+    await jwe.newPair();
+
+    return {privateKey: await jwe.exportPrivateAsBase64(), publicKey: await jwe.exportPublicAsBase64()};
+  })();
+
+  return pair;
+};

package/src/testing/network-guard.mts

@@ -0,0 +1,57 @@
+import net from 'node:net';
+
+/**
+ * Test-only network guard.
+ *
+ * While installed, any TCP connection to a host that is not loopback throws
+ * immediately. fetch (undici), http, https, ws and axios all end up in
+ * net.Socket.prototype.connect, so this is the safety net behind the vendor mock:
+ * even code that bypasses global fetch cannot reach the network from a test.
+ */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+let original: typeof net.Socket.prototype.connect | undefined;
+let installs = 0;
+export const blocked: string[] = [];
+
+const targetOf = (args: any[]): {host: string; local: boolean} => {
+  // net.connect hands over a normalized [options, callback] array
+  const first = Array.isArray(args[0]) ? args[0][0] : args[0];
+
+  if (first && typeof first === 'object' && !Array.isArray(first)) {
+    if (first.path) return {host: String(first.path), local: true};
+    return {host: String(first.host ?? 'localhost'), local: false};
+  }
+  if (typeof first === 'number' || (typeof first === 'string' && !Number.isNaN(Number(first)))) {
+    return {host: typeof args[1] === 'string' ? args[1] : 'localhost', local: false};
+  }
+
+  // unix socket path
+  return {host: String(first), local: true};
+};
+
+export const installNetworkGuard = () => {
+  if (installs++ > 0) return;
+
+  original = net.Socket.prototype.connect;
+
+  (net.Socket.prototype as any).connect = function (this: net.Socket, ...args: any[]) {
+    const {host, local} = targetOf(args);
+
+    if (!local && !LOOPBACK.has(host)) {
+      const message = `NETWORK BLOCKED by connector test harness: connection to ${host} is not allowed in tests`;
+      blocked.push(host);
+      throw new Error(message);
+    }
+
+    return (original as any).apply(this, args);
+  };
+};
+
+export const uninstallNetworkGuard = () => {
+  if (installs === 0) return;
+  if (--installs > 0) return;
+
+  (net.Socket.prototype as any).connect = original;
+  original = undefined;
+};

package/src/testing/runtime-connector.mts

@@ -0,0 +1,50 @@
+import {AbstractController} from '../controller/index.mjs';
+import {buildResolvers} from '../builder/runtime-context.mjs';
+import type RuntimeContext from '../builder/runtime-context.mjs';
+import {Connector} from '../internal/connector/index.mjs';
+
+/**
+ * Turn what a connector repo builds (`await new Builder()...build()` gives a RuntimeContext) into a configured
+ * `Connector` that the ConnectorHarness can run, without calling `connector.run()` (which starts a metrics
+ * server on a fixed port and installs process signal handlers).
+ *
+ * This repeats the wiring of RuntimeContext.start(): methods become resolvers, config/oauth/endpoint are applied,
+ * main() starts the controller and sends a health check. If RuntimeContext.start() changes, change this too.
+ */
+export const connectorFromRuntimeContext = (context: RuntimeContext): Connector => {
+  const {controller, data} = context as any as {controller: AbstractController; data: any};
+
+  if (!(controller instanceof AbstractController)) {
+    throw new Error('the controller needs to extend AbstractController');
+  }
+
+  const connector = new Connector({
+    id: data.id,
+    version: data.version,
+    name: `${data.id}/${data.version}`,
+    icon: undefined,
+  });
+
+  const configuration = connector.configure().config(data.config || {});
+  const methods: string[] = [...data.methods, '__autocomplete', '__endpoint', '__default'];
+
+  configuration.types(data.types).resolvers(buildResolvers(methods, controller));
+
+  if (data.options?.endpoint?.enabled) {
+    configuration.endpoint((arg) => (controller as any).__endpoint(arg), data.options?.endpoint?.required);
+  }
+
+  if (data.auth?.oauth) {
+    configuration.oauth(data.auth?.oauth);
+  }
+
+  configuration.main(
+    async ({newTask, updateTask, config, oauth, getClient, getBlob, getBlobContent, createBlob, healthCheck}) => {
+      await (controller as any)._doStop();
+      await (controller as any)._doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob);
+      await healthCheck(controller);
+    }
+  );
+
+  return connector;
+};