@aloma.io/integration-sdk 3.8.66 → 3.8.68

package/build/testing/harness.mjs

@@ -0,0 +1,139 @@
+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 { FakeAloma } from './fake-aloma.mjs';
+import { testKeyPair } from './keys.mjs';
+import { VendorMock } from './vendor-mock.mjs';
+/**
+ * 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 {
+    aloma;
+    vendor;
+    server;
+    started;
+    constructor(aloma, vendor, server, started) {
+        this.aloma = aloma;
+        this.vendor = vendor;
+        this.server = server;
+        this.started = started;
+    }
+    static async start(options) {
+        const { connector, timeoutMs = 5000 } = options;
+        const dispatcher = 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;
+        let mainFailed;
+        const started = new Promise((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;
+        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;
+        }
+    }
+    static async shutdown(server, vendor, aloma) {
+        try {
+            if (server) {
+                const anyServer = 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, variables, ctx) {
+        return this.aloma.call(method, variables, ctx);
+    }
+    /** call a connector method; throws when the connector answered with an error */
+    async callOk(method, variables) {
+        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 } = {}) {
+        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 = (promise, ms, message) => {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(message)), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+};

package/build/testing/index.d.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/build/testing/index.mjs

@@ -0,0 +1,13 @@
+/**
+ * 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 { FakeAloma } from './fake-aloma.mjs';
+export { VendorMock } from './vendor-mock.mjs';
+export { installNetworkGuard, uninstallNetworkGuard } from './network-guard.mjs';
+export { testKeyPair } from './keys.mjs';
+export { connectorFromRuntimeContext } from './runtime-connector.mjs';

package/build/testing/keys.d.mts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const testKeyPair: () => Promise<{
+    privateKey: string;
+    publicKey: string;
+}>;

package/build/testing/keys.mjs

@@ -0,0 +1,15 @@
+import JWE from '../internal/util/jwe/index.mjs';
+let pair;
+/**
+ * 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/build/testing/network-guard.d.mts

@@ -0,0 +1,3 @@
+export declare const blocked: string[];
+export declare const installNetworkGuard: () => void;
+export declare const uninstallNetworkGuard: () => void;

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.66",
+  "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,11 +57,13 @@
     "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",
-    "url": "https://github.com/aloma-io/integration.git",
+    "url": "git+https://github.com/aloma-io/integration.git",
     "directory": "integration-sdk"
   },
   "publishConfig": {

package/src/builder/runtime-context.mts

@@ -16,9 +16,9 @@ export function buildResolvers(methods: string[], controller: any): any {
   const resolvers: any = {};
 
   methods.forEach((method) => {
-    const handler = async (args: any) => {
+    const handler = async (args: any, ctx?: any) => {
       if (!methods.includes(method)) throw new Error(`${method} not found`);
-      return controller[method](args);
+      return controller[method](args, ctx);
     };
 
     if (method.includes('.')) {

package/src/controller/index.mts

@@ -51,8 +51,9 @@ export abstract class AbstractController {
   /**
    * called, when the remote public method is not found on the controller
    * @param arg
+   * @param ctx optional invocation context (taskId, namespace, sticky)
    */
-  protected fallback(arg: any): Promise<any> {
+  protected fallback(arg: any, ctx?: any): Promise<any> {
     throw new Error('method not found');
   }
 
@@ -186,8 +187,8 @@ export abstract class AbstractController {
   /**
    * @ignore
    **/
-  async __default(arg: any): Promise<any | null> {
-    return this.fallback(arg);
+  async __default(arg: any, ctx?: any): Promise<any | null> {
+    return this.fallback(arg, ctx);
   }
 
   /**

package/src/internal/dispatcher/index.mts

@@ -163,7 +163,8 @@ ${arg.configurableClientScope}
       return current;
     };
 
-    const execute = async ({query, variables}) => {
+    const execute = async ({query, variables, taskId, namespace, sticky}: any) => {
+      const ctx = {taskId, namespace, sticky};
       if (!Array.isArray(query)) query = [query];
 
       query = query
@@ -177,7 +178,7 @@ ${arg.configurableClientScope}
       const method = resolveMethod(query);
       if (!method && !_resolvers.__default) throw new Error(`${originalQuery} not found`);
 
-      return method ? method(variables) : _resolvers.__default(variables ? {...variables, __method: originalQuery} : variables);
+      return method ? method(variables, ctx) : _resolvers.__default(variables ? {...variables, __method: originalQuery} : variables, ctx);
     };
 
     const introspect = () => local._types;