@aloma.io/integration-sdk 3.8.67 → 3.8.68

package/build/testing/network-guard.mjs

@@ -0,0 +1,49 @@
+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;
+let installs = 0;
+export const blocked = [];
+const targetOf = (args) => {
+    // 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.connect = function (...args) {
+        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.apply(this, args);
+    };
+};
+export const uninstallNetworkGuard = () => {
+    if (installs === 0)
+        return;
+    if (--installs > 0)
+        return;
+    net.Socket.prototype.connect = original;
+    original = undefined;
+};

package/build/testing/runtime-connector.d.mts

@@ -0,0 +1,11 @@
+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 declare const connectorFromRuntimeContext: (context: RuntimeContext) => Connector;

package/build/testing/runtime-connector.mjs

@@ -0,0 +1,38 @@
+import { AbstractController } from '../controller/index.mjs';
+import { buildResolvers } 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) => {
+    const { controller, data } = context;
+    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 = [...data.methods, '__autocomplete', '__endpoint', '__default'];
+    configuration.types(data.types).resolvers(buildResolvers(methods, controller));
+    if (data.options?.endpoint?.enabled) {
+        configuration.endpoint((arg) => controller.__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._doStop();
+        await controller._doStart(config, oauth, newTask, updateTask, getClient, getBlob, getBlobContent, createBlob);
+        await healthCheck(controller);
+    });
+    return connector;
+};

package/build/testing/vendor-mock.d.mts

@@ -0,0 +1,59 @@
+/// <reference types="node" resolution-mode="require"/>
+export type VendorRequest = {
+    method: string;
+    url: string;
+    /** the url exactly as the connector passed it to fetch */
+    rawUrl: string;
+    headers: Record<string, string>;
+    body?: string;
+};
+export type VendorResponse = {
+    status?: number;
+    headers?: Record<string, string>;
+    /** sent as JSON with a json content-type */
+    json?: unknown;
+    /** sent as is */
+    text?: string;
+};
+export type VendorResponder = VendorResponse | ((request: VendorRequest) => VendorResponse | Promise<VendorResponse>);
+export type UrlMatcher = string | RegExp | ((url: string) => boolean);
+/**
+ * Mock for the HTTP calls a connector makes to its vendor API.
+ *
+ * - intercepts global fetch (what the SDK Fetcher and OAuth code use)
+ * - answers from routes you register with on()/get()/post()...
+ * - any request without a route is recorded in `unmocked` and rejected,
+ *   verify() then fails the test even if the connector swallowed the error
+ * - also installs the network guard, so nothing can reach a non-loopback host
+ */
+export declare class VendorMock {
+    readonly requests: VendorRequest[];
+    readonly unmocked: VendorRequest[];
+    private routes;
+    private originalFetch?;
+    private passthrough;
+    /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+    allowPassthrough(fn: (url: URL) => boolean): this;
+    on(method: string, matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    get(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    post(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    put(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    delete(matcher: UrlMatcher, respond: VendorResponder, options?: {
+        times?: number;
+    }): this;
+    install(): this;
+    uninstall(): void;
+    /** throws if the connector made a request that had no mock, even if it caught the error */
+    verify(): void;
+    /** throws if a registered route was never used */
+    verifyAllRoutesUsed(): void;
+    private handle;
+}

package/build/testing/vendor-mock.mjs

@@ -0,0 +1,121 @@
+import { installNetworkGuard, uninstallNetworkGuard } from './network-guard.mjs';
+// "https:/host/x" (one slash, which the SDK Fetcher produces) and "https://host/x" are the same URL to fetch
+const canonical = (url) => {
+    try {
+        return new URL(url).href;
+    }
+    catch (e) {
+        return url;
+    }
+};
+const matches = (matcher, url) => {
+    if (typeof matcher === 'string')
+        return canonical(matcher) === url;
+    if (matcher instanceof RegExp)
+        return matcher.test(url);
+    return matcher(url);
+};
+/**
+ * Mock for the HTTP calls a connector makes to its vendor API.
+ *
+ * - intercepts global fetch (what the SDK Fetcher and OAuth code use)
+ * - answers from routes you register with on()/get()/post()...
+ * - any request without a route is recorded in `unmocked` and rejected,
+ *   verify() then fails the test even if the connector swallowed the error
+ * - also installs the network guard, so nothing can reach a non-loopback host
+ */
+export class VendorMock {
+    requests = [];
+    unmocked = [];
+    routes = [];
+    originalFetch;
+    passthrough = () => false;
+    /** urls for which the real fetch is used (the fake ALOMA endpoint); everything else is mocked */
+    allowPassthrough(fn) {
+        this.passthrough = fn;
+        return this;
+    }
+    on(method, matcher, respond, options = {}) {
+        this.routes.push({ method: method.toUpperCase(), matcher, respond, times: options.times ?? Infinity, used: 0 });
+        return this;
+    }
+    get(matcher, respond, options) {
+        return this.on('GET', matcher, respond, options);
+    }
+    post(matcher, respond, options) {
+        return this.on('POST', matcher, respond, options);
+    }
+    put(matcher, respond, options) {
+        return this.on('PUT', matcher, respond, options);
+    }
+    delete(matcher, respond, options) {
+        return this.on('DELETE', matcher, respond, options);
+    }
+    install() {
+        if (this.originalFetch)
+            return this;
+        installNetworkGuard();
+        this.originalFetch = globalThis.fetch;
+        globalThis.fetch = ((input, init) => this.handle(input, init));
+        return this;
+    }
+    uninstall() {
+        if (!this.originalFetch)
+            return;
+        globalThis.fetch = this.originalFetch;
+        this.originalFetch = undefined;
+        uninstallNetworkGuard();
+    }
+    /** throws if the connector made a request that had no mock, even if it caught the error */
+    verify() {
+        if (this.unmocked.length) {
+            const list = this.unmocked.map((r) => `${r.method} ${r.url}`).join('\n  ');
+            throw new Error(`UNMOCKED vendor requests were made (no network is allowed in tests):\n  ${list}`);
+        }
+    }
+    /** throws if a registered route was never used */
+    verifyAllRoutesUsed() {
+        const unused = this.routes.filter((r) => r.used === 0);
+        if (unused.length) {
+            throw new Error(`mocked routes never called: ${unused.map((r) => `${r.method} ${String(r.matcher)}`).join(', ')}`);
+        }
+    }
+    async handle(input, init = {}) {
+        const rawUrl = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+        const url = canonical(rawUrl);
+        const method = String(init.method || (typeof input === 'object' && input.method) || 'GET').toUpperCase();
+        const headers = {};
+        new Headers(init.headers || (typeof input === 'object' && input.headers) || {}).forEach((value, key) => {
+            headers[key] = value;
+        });
+        const request = { method, url, rawUrl, headers };
+        if (init.body != null)
+            request.body = typeof init.body === 'string' ? init.body : String(init.body);
+        const route = this.routes.find((r) => r.method === method && r.used < r.times && matches(r.matcher, url));
+        if (route) {
+            route.used++;
+            this.requests.push(request);
+            const spec = typeof route.respond === 'function' ? await route.respond(request) : route.respond;
+            const responseHeaders = { ...spec.headers };
+            let body = null;
+            if (spec.json !== undefined) {
+                body = JSON.stringify(spec.json);
+                responseHeaders['content-type'] ||= 'application/json';
+            }
+            else if (spec.text !== undefined) {
+                body = spec.text;
+            }
+            const status = spec.status ?? 200;
+            return new Response([204, 205, 304].includes(status) ? null : body, { status, headers: responseHeaders });
+        }
+        if (this.originalFetch && this.passthrough(new URL(url))) {
+            return this.originalFetch(input, init);
+        }
+        this.unmocked.push(request);
+        // status 400 makes the SDK Fetcher give up at once instead of retrying for seconds
+        const error = new Error(`UNMOCKED vendor request: ${method} ${url} (add a route with vendor.on(...))`);
+        error.status = 400;
+        error.alomaHarnessUnmocked = true;
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloma.io/integration-sdk",
-  "version": "3.8.67",
+  "version": "3.8.68",
   "description": "",
   "author": "aloma.io",
   "license": "Apache-2.0",
@@ -11,7 +11,9 @@
   "scripts": {
     "dev": "./node_modules/typescript/bin/tsc --watch",
     "build": "./node_modules/typescript/bin/tsc",
-    "test": "./node_modules/mocha/bin/_mocha --recursive test/ --loader ts-node/esm",
+    "test": "node tools/run-tests.mjs",
+    "test:harness": "./node_modules/mocha/bin/_mocha --exit \"test/harness*.test.mjs\"",
+    "test:mutation": "node tools/mutation-run.mjs",
     "test:scenarios": "node test/verify-scenarios.mjs",
     "test:all": "npm run test:scenarios",
     "format": "yarn prettier --write src/",
@@ -55,7 +57,9 @@
     "ts-node": "^10.9.2"
   },
   "resolutions": {
-    "path-to-regexp": "0.1.13"
+    "path-to-regexp": "0.1.13",
+    "qs": ">=6.15.2",
+    "serialize-javascript": ">=7.0.5"
   },
   "repository": {
     "type": "git",

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()));
+  }
+}