@aloma.io/integration-sdk 3.8.66 → 3.8.68

package/README.md

@@ -106,6 +106,66 @@ The SDK includes comprehensive scenario tests that verify:
 
 All tests use real OpenAPI specifications and compare generated output against fixtures to ensure deterministic, high-quality code generation.
 
+### Testing a connector: handshake smoke test
+
+The SDK ships a test harness (`build/testing/`, source in `src/testing/`). It runs your real connector in-process
+against a fake ALOMA endpoint on `127.0.0.1`, performs the real handshake (connect, 401, register, websocket,
+configuration), sends method calls like ALOMA does, and mocks the vendor HTTP API. Any request that is not
+mocked fails the test, and raw connections to non-loopback hosts are blocked, so a test never touches the network.
+No real token or key is needed: the harness generates a throwaway RSA key pair and fake tokens.
+
+A connector repo adds one dev dependency on the SDK (already a dependency) and one file, `test/handshake.smoke.test.mjs`
+(run it with `mocha --exit test/handshake.smoke.test.mjs` after `yarn build`):
+
+```js
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {Builder} from '@aloma.io/integration-sdk';
+import {ConnectorHarness, connectorFromRuntimeContext} from '@aloma.io/integration-sdk/build/testing/index.mjs';
+
+describe('handshake smoke test', function () {
+  this.timeout(15000);
+  let harness;
+
+  // stop() also fails the test if the connector made a request you did not mock
+  afterEach(async () => harness && (await harness.stop()));
+
+  it('registers, connects, starts and reports healthy', async () => {
+    // use the same Builder configuration as src/index.mts (config, options, auth)
+    const context = await new Builder().config({fields: {apiKey: {name: 'API Key', type: 'line'}}}).build();
+
+    harness = await ConnectorHarness.start({
+      connector: connectorFromRuntimeContext(context),
+      config: {apiKey: 'fake-api-key-not-real'}, // encrypted for the connector unless the field is `plain`
+    });
+
+    const health = await harness.aloma.waitForPacket('connector.health.check');
+    expect(health.a).to.deep.equal({ok: true, error: null});
+  });
+
+  it('calls a method against a mocked vendor API', async () => {
+    harness = await ConnectorHarness.start({/* same as above */});
+    harness.vendor.get('https://api.vendor.example/things/1', {json: {id: 1}});
+
+    expect(await harness.callOk('getThing', {id: 1})).to.deep.equal({id: 1});
+  });
+});
+```
+
+Useful pieces: `harness.call(method, variables, ctx)` (raw answer, `{error}` on failure), `harness.callOk(...)`,
+`harness.vendor.get/post/put/delete(url | RegExp | fn, {status, json, text, headers} | fn(request))`,
+`harness.vendor.requests` (what the connector sent), `harness.aloma.handle('connector.blob.create', fn)` to answer
+requests the connector makes to ALOMA, `harness.aloma.registration` (what the connector registered).
+`test/harness-connector-smoke.test.mjs` in this repo is a runnable version of the example.
+
+Not covered: the Prometheus metrics server (fixed port 4050), process signal handlers, configuration through
+environment variables and OAuth flows against a real provider. `connectorFromRuntimeContext` repeats the wiring of
+`RuntimeContext.start()`, so keep the two in step.
+
+SDK maintainers: `yarn test:harness` runs the harness tests (CI runs it on Node 18, 20, 22 and 24). `yarn test:mutation`
+applies 30+ deliberate bugs to the harness and the SDK handshake, dispatch and result paths and checks the tests
+catch each one; the result is recorded in `test/MUTATION.md`.
+
 ## 📚 Documentation
 
 - **[OPENAPI_TO_CONNECTOR.md](./OPENAPI_TO_CONNECTOR.md)** - OpenAPI generator details

package/build/builder/runtime-context.mjs

@@ -14,10 +14,10 @@ import { Connector } from '../internal/index.mjs';
 export function buildResolvers(methods, controller) {
     const resolvers = {};
     methods.forEach((method) => {
-        const handler = async (args) => {
+        const handler = async (args, ctx) => {
             if (!methods.includes(method))
                 throw new Error(`${method} not found`);
-            return controller[method](args);
+            return controller[method](args, ctx);
         };
         if (method.includes('.')) {
             // Register nested tree for array-based resolution: ["crm", "contacts", "getPage"]

package/build/controller/index.d.mts

@@ -44,8 +44,9 @@ export declare 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>;
     /**
      * will be invoked, when the connector has an endpoint enabled
      * will receive the data and can e.g. create a new task from it
@@ -134,7 +135,7 @@ export declare abstract class AbstractController {
     /**
      * @ignore
      **/
-    __default(arg: any): Promise<any | null>;
+    __default(arg: any, ctx?: any): Promise<any | null>;
     /**
      * @ignore
      **/

package/build/controller/index.mjs

@@ -41,8 +41,9 @@ export class AbstractController {
     /**
      * called, when the remote public method is not found on the controller
      * @param arg
+     * @param ctx optional invocation context (taskId, namespace, sticky)
      */
-    fallback(arg) {
+    fallback(arg, ctx) {
         throw new Error('method not found');
     }
     /**
@@ -136,8 +137,8 @@ export class AbstractController {
     /**
      * @ignore
      **/
-    async __default(arg) {
-        return this.fallback(arg);
+    async __default(arg, ctx) {
+        return this.fallback(arg, ctx);
     }
     /**
      * @ignore

package/build/internal/dispatcher/index.d.mts

@@ -26,10 +26,7 @@ export default class Dispatcher {
     build(): {
         introspect: () => any;
         configSchema: () => any;
-        execute: ({ query, variables }: {
-            query: any;
-            variables: any;
-        }) => Promise<any>;
+        execute: ({ query, variables, taskId, namespace, sticky }: any) => Promise<any>;
         processPacket: (packet: any) => Promise<any>;
         start: (arg: any) => Promise<void>;
     };

package/build/internal/dispatcher/index.mjs

@@ -133,7 +133,8 @@ ${arg.configurableClientScope}
             }
             return current;
         };
-        const execute = async ({ query, variables }) => {
+        const execute = async ({ query, variables, taskId, namespace, sticky }) => {
+            const ctx = { taskId, namespace, sticky };
             if (!Array.isArray(query))
                 query = [query];
             query = query
@@ -143,7 +144,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;
         const configSchema = () => local._config;

package/build/testing/fake-aloma.d.mts

@@ -0,0 +1,87 @@
+/// <reference types="node" resolution-mode="require"/>
+import http from 'node:http';
+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 declare class FakeAloma {
+    readonly registrationToken: string;
+    readonly sessionToken: string;
+    /** 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;
+    private wss;
+    private socket?;
+    private pending;
+    private handlers;
+    private waiters;
+    private port;
+    private id;
+    private version;
+    static start(): Promise<FakeAloma>;
+    /** value for the connector's endpoint setting (env.DEVICE_ENDPOINT) */
+    get url(): string;
+    /** value for the connector's websocket setting (env.WEBSOCKET_ENDPOINT) */
+    get wsUrl(): string;
+    get connected(): boolean;
+    get registration(): any;
+    private listen;
+    private readJson;
+    private onHttp;
+    private onSocket;
+    private onPacket;
+    /** answer connector -> ALOMA requests such as connector.blob.get or connector.task.new */
+    handle(method: string, fn: (args: any) => any | Promise<any>): this;
+    /** resolves when the connector's websocket is open (the handshake is finished) */
+    waitForConnection(timeoutMs?: number): Promise<void>;
+    /** resolves with the first packet the connector sent for `method` (e.g. connector.health.check), now or later */
+    waitForPacket(method: string, timeoutMs?: number): Promise<Packet>;
+    /** send one raw packet to the connector */
+    send(packet: Packet): void;
+    /** send a packet with a callback key and wait for the connector's answer (its `a` field) */
+    request(method: string, args: any, timeoutMs?: number): Promise<any>;
+    /** ask the connector for its schema and method list (connector.introspect) */
+    introspect(): Promise<any>;
+    /**
+     * 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.
+     */
+    setConfig(values: Record<string, any>): Promise<void>;
+    /**
+     * 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;
+    }): Promise<any>;
+    close(): Promise<void>;
+}
+export {};

package/build/testing/fake-aloma.mjs

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import http from 'node:http';
+import * as jose from 'jose';
+import { WebSocket, WebSocketServer } from 'ws';
+/**
+ * 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 {
+    registrationToken = `fake-registration-${randomUUID()}`;
+    sessionToken = `fake-session-${randomUUID()}`;
+    /** bodies of POST /register */
+    registrations = [];
+    /** headers of POST /connect */
+    connects = [];
+    /** every packet the connector sent over the websocket, in order */
+    received = [];
+    protocolErrors = [];
+    server;
+    wss;
+    socket;
+    pending = new Map();
+    handlers = new Map();
+    waiters = [];
+    port = 0;
+    id = '';
+    version = '';
+    static async start() {
+        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];
+    }
+    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 = [];
+            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((resolve) => this.server.listen(0, '127.0.0.1', () => resolve()));
+        this.port = this.server.address().port;
+    }
+    async readJson(req) {
+        let text = '';
+        for await (const chunk of req)
+            text += chunk;
+        return text ? JSON.parse(text) : {};
+    }
+    async onHttp(req, res) {
+        const send = (status, body) => {
+            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);
+    }
+    onSocket(ws) {
+        this.socket = ws;
+        ws.on('message', (raw) => {
+            const frame = JSON.parse(raw.toString());
+            const packets = 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());
+    }
+    onPacket(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, fn) {
+        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((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, timeoutMs = 5000) {
+        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) {
+        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, args, timeoutMs = 5000) {
+        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) {
+        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 = {};
+        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, variables, ctx = {}) {
+        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((resolve) => this.server.close(() => resolve()));
+    }
+}

package/build/testing/harness.d.mts

@@ -0,0 +1,51 @@
+import type { Connector } from '../internal/connector/index.mjs';
+import { FakeAloma } from './fake-aloma.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 declare class ConnectorHarness {
+    readonly aloma: FakeAloma;
+    readonly vendor: VendorMock;
+    private readonly server;
+    private readonly started;
+    private constructor();
+    static start(options: HarnessOptions): Promise<ConnectorHarness>;
+    private static shutdown;
+    /** 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;
+    }): Promise<any>;
+    /** call a connector method; throws when the connector answered with an error */
+    callOk(method: string | string[], variables?: any): Promise<any>;
+    /**
+     * 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.
+     */
+    stop({ verify }?: {
+        verify?: boolean;
+    }): Promise<void>;
+}