@dxos/functions 0.5.4 → 0.5.5-main.23d7ea6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/functions",
-  "version": "0.5.4",
+  "version": "0.5.5-main.23d7ea6",
   "description": "Functions API and runtime.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -18,6 +18,12 @@
       "node": "./dist/lib/node/types.cjs",
       "default": "./dist/lib/node/types.cjs",
       "types": "./dist/types/src/types.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/lib/browser/testing/index.mjs",
+      "require": "./dist/lib/node/testing/index.cjs",
+      "node": "./dist/lib/node/testing/index.cjs",
+      "types": "./dist/types/src/testing/index.d.ts"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -25,6 +31,9 @@
     "*": {
       "types": [
         "dist/types/src/types.d.ts"
+      ],
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
       ]
     }
   },
@@ -40,23 +49,23 @@
     "express": "^4.19.2",
     "get-port-please": "^3.1.1",
     "ws": "^8.14.2",
-    "@braneframe/types": "0.5.4",
-    "@dxos/async": "0.5.4",
-    "@dxos/client": "0.5.4",
-    "@dxos/echo-db": "0.5.4",
-    "@dxos/echo-schema": "0.5.4",
-    "@dxos/keys": "0.5.4",
-    "@dxos/context": "0.5.4",
-    "@dxos/invariant": "0.5.4",
-    "@dxos/log": "0.5.4",
-    "@dxos/node-std": "0.5.4",
-    "@dxos/protocols": "0.5.4",
-    "@dxos/util": "0.5.4"
+    "@braneframe/types": "0.5.5-main.23d7ea6",
+    "@dxos/client": "0.5.5-main.23d7ea6",
+    "@dxos/async": "0.5.5-main.23d7ea6",
+    "@dxos/echo-schema": "0.5.5-main.23d7ea6",
+    "@dxos/context": "0.5.5-main.23d7ea6",
+    "@dxos/echo-db": "0.5.5-main.23d7ea6",
+    "@dxos/invariant": "0.5.5-main.23d7ea6",
+    "@dxos/keys": "0.5.5-main.23d7ea6",
+    "@dxos/log": "0.5.5-main.23d7ea6",
+    "@dxos/protocols": "0.5.5-main.23d7ea6",
+    "@dxos/node-std": "0.5.5-main.23d7ea6",
+    "@dxos/util": "0.5.5-main.23d7ea6"
   },
   "devDependencies": {
     "@types/express": "^4.17.17",
     "@types/ws": "^7.4.0",
-    "@dxos/agent": "0.5.4"
+    "@dxos/agent": "0.5.5-main.23d7ea6"
   },
   "publishConfig": {
     "access": "public"

package/src/function/function-registry.test.ts

@@ -4,7 +4,7 @@
 
 import { expect } from 'chai';
 
-import { Trigger } from '@dxos/async';
+import { sleep, Trigger } from '@dxos/async';
 import { type Client } from '@dxos/client';
 import { TestBuilder } from '@dxos/client/testing';
 import { Context } from '@dxos/context';
@@ -39,6 +39,19 @@ describe('function registry', () => {
     await testBuilder.destroy();
   });
 
+  test('getUniqueByUri', async () => {
+    const client = (await createInitializedClients(testBuilder))[0];
+    const registry = createRegistry(client);
+    await registry.open();
+    for (let i = 0; i < 2; i++) {
+      const space = await client.spaces.create();
+      await registry.register(space, testManifest.functions);
+    }
+    await sleep(10);
+    const definitions = registry.getUniqueByUri();
+    expect(definitions.length).to.eq(testManifest.functions?.length);
+  });
+
   describe('register', () => {
     test('creates new functions', async () => {
       const client = (await createInitializedClients(testBuilder))[0];

package/src/function/function-registry.ts

@@ -30,6 +30,16 @@ export class FunctionRegistry extends Resource {
     return this._functionBySpaceKey.get(space.key) ?? [];
   }
 
+  public getUniqueByUri(): FunctionDef[] {
+    const uniqueByUri = [...this._functionBySpaceKey.values()]
+      .flatMap((defs) => defs)
+      .reduce((acc, v) => {
+        acc.set(v.uri, v);
+        return acc;
+      }, new Map<string, FunctionDef>());
+    return [...uniqueByUri.values()];
+  }
+
   /**
    * Loads function definitions from the manifest into the space.
    * We first load all the definitions from the space to deduplicate by functionId.

package/src/runtime/dev-server.test.ts

@@ -3,24 +3,25 @@
 //
 
 import { expect } from 'chai';
+import { getRandomPort } from 'get-port-please';
 import path from 'path';
 
-import { waitForCondition } from '@dxos/async';
+import { sleep, waitForCondition } from '@dxos/async';
 import { type Client } from '@dxos/client';
 import { TestBuilder } from '@dxos/client/testing';
 import { describe, test } from '@dxos/test';
 
 import { DevServer } from './dev-server';
 import { FunctionRegistry } from '../function';
-import { createFunctionRuntime } from '../testing';
-import { type FunctionManifest } from '../types';
+import { createFunctionRuntime, testFunctionManifest } from '../testing';
+import { initFunctionsPlugin } from '../testing/plugin-init';
 
 describe('dev server', () => {
   let client: Client;
   let testBuilder: TestBuilder;
   before(async () => {
     testBuilder = new TestBuilder();
-    client = await createFunctionRuntime(testBuilder);
+    client = await createFunctionRuntime(testBuilder, initFunctionsPlugin);
     expect(client.services.services.FunctionRegistryService).to.exist;
   });
 
@@ -28,33 +29,50 @@ describe('dev server', () => {
     await testBuilder.destroy();
   });
 
-  test('start/stop', async () => {
-    const manifest: FunctionManifest = {
-      functions: [
-        {
-          uri: 'example.com/function/test',
-          route: 'test',
-          handler: 'test',
-        },
-      ],
-    };
+  test('function registry open after dev server started', async () => {
+    const { registry, server, space } = await setupTest();
+    await registry.register(space, testFunctionManifest.functions);
+    await server.start();
+    await registry.open();
+    await waitForCondition({ condition: () => server.functions.length > 0 });
+    await expectTestFunctionInvocable(server);
+  });
+
+  test('function registry open before dev server started', async () => {
+    const { registry, server, space } = await setupTest();
+    await registry.register(space, testFunctionManifest.functions);
+    await registry.open();
+    await server.start();
+    await waitForCondition({ condition: () => server.functions.length > 0 });
+    await expectTestFunctionInvocable(server);
+  });
+
+  test('unsubscribes from functions after stopped', async () => {
+    const { registry, server, space } = await setupTest();
+    await registry.register(space, testFunctionManifest.functions);
+    await server.start();
+    await server.stop();
+    await registry.open();
+    await sleep(20);
+    expect(server.functions.length).to.eq(0);
+  });
 
+  const expectTestFunctionInvocable = async (server: DevServer) => {
+    const seq = server.stats.seq;
+    await server.invoke('test', {});
+    expect(server.stats.seq).to.eq(seq + 1);
+  };
+
+  const setupTest = async () => {
     const registry = new FunctionRegistry(client);
     const server = new DevServer(client, registry, {
       baseDir: path.join(__dirname, '../testing'),
+      port: await getRandomPort('127.0.0.1'),
     });
     const space = await client.spaces.create();
-    await registry.register(space, manifest.functions);
-    await server.start();
-
     // TODO(burdon): Doesn't shut down cleanly.
     //  Error: invariant violation [this._client.services.services.FunctionRegistryService]
     testBuilder.ctx.onDispose(() => server.stop());
-    expect(server).to.exist;
-
-    await waitForCondition({ condition: () => server.functions.length > 0 });
-
-    await server.invoke('test', {});
-    expect(server.stats.seq).to.eq(1);
-  });
+    return { registry, server, space };
+  };
 });

package/src/runtime/dev-server.ts

@@ -7,7 +7,7 @@ import { getPort } from 'get-port-please';
 import type http from 'http';
 import { join } from 'node:path';
 
-import { Event, Trigger } from '@dxos/async';
+import { asyncTimeout, Event, Trigger } from '@dxos/async';
 import { type Client } from '@dxos/client';
 import { Context } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
@@ -45,14 +45,7 @@ export class DevServer {
     private readonly _client: Client,
     private readonly _functionsRegistry: FunctionRegistry,
     private readonly _options: DevServerOptions,
-  ) {
-    // TODO(burdon): Add/remove listener in start/stop.
-    this._functionsRegistry.registered.on(async ({ added }) => {
-      added.forEach((def) => this._load(def));
-      await this._safeUpdateRegistration();
-      log('new functions loaded', { added });
-    });
-  }
+  ) {}
 
   get stats() {
     return {
@@ -92,7 +85,7 @@ export class DevServer {
         }
 
         // TODO(burdon): Get function context.
-        res.statusCode = await this.invoke('/' + path, req.body);
+        res.statusCode = await asyncTimeout(this.invoke('/' + path, req.body), 20_000);
         res.end();
       } catch (err: any) {
         log.catch(err);
@@ -101,7 +94,7 @@ export class DevServer {
       }
     });
 
-    this._port = await getPort({ host: 'localhost', port: 7200, portRange: [7200, 7299] });
+    this._port = this._options.port ?? (await getPort({ host: 'localhost', port: 7200, portRange: [7200, 7299] }));
     this._server = app.listen(this._port);
 
     try {
@@ -115,7 +108,8 @@ export class DevServer {
       this._functionServiceRegistration = registrationId;
 
       // Open after registration, so that it can be updated with the list of function definitions.
-      await this._functionsRegistry.open(this._ctx);
+      await this._handleNewFunctions(this._functionsRegistry.getUniqueByUri());
+      this._ctx.onDispose(this._functionsRegistry.registered.on(({ added }) => this._handleNewFunctions(added)));
     } catch (err: any) {
       await this.stop();
       throw new Error('FunctionRegistryService not available (check plugin is configured).');
@@ -125,8 +119,12 @@ export class DevServer {
   }
 
   async stop() {
-    invariant(this._server);
+    if (!this._server) {
+      return;
+    }
+
     log.info('stopping...');
+    await this._ctx.dispose();
 
     const trigger = new Trigger();
     this._server.close(async () => {
@@ -155,6 +153,12 @@ export class DevServer {
     log.info('stopped');
   }
 
+  private async _handleNewFunctions(newFunctions: FunctionDef[]) {
+    newFunctions.forEach((def) => this._load(def));
+    await this._safeUpdateRegistration();
+    log('new functions loaded', { newFunctions });
+  }
+
   /**
    * Load function.
    */

package/src/runtime/scheduler.test.ts

@@ -3,6 +3,7 @@
 //
 
 import { expect } from 'chai';
+import { getRandomPort } from 'get-port-please';
 import WebSocket from 'ws';
 
 import { Trigger } from '@dxos/async';
@@ -108,6 +109,7 @@ describe('scheduler', () => {
   });
 
   test('websocket', async () => {
+    const port = await getRandomPort('127.0.0.1');
     const manifest: FunctionManifest = {
       functions: [
         {
@@ -123,7 +125,7 @@ describe('scheduler', () => {
           spec: {
             type: 'websocket',
             // url: 'https://hub.dxos.network/api/mailbox/test',
-            url: 'http://localhost:8081',
+            url: `http://localhost:${port}`,
             init: {
               type: 'sync',
             },
@@ -141,7 +143,7 @@ describe('scheduler', () => {
 
     // Test server.
     setTimeout(() => {
-      const wss = new WebSocket.Server({ port: 8081 });
+      const wss = new WebSocket.Server({ port });
       wss.on('connection', (ws: WebSocket) => {
         ws.on('message', (data) => {
           const info = JSON.parse(new TextDecoder().decode(data as ArrayBuffer));

package/src/testing/functions-integration.test.ts

@@ -3,20 +3,15 @@
 //
 
 import { expect } from 'chai';
-import path from 'path';
 
-import { Trigger, waitForCondition } from '@dxos/async';
-import { type Client } from '@dxos/client';
-import { create, type Space } from '@dxos/client/echo';
-import { performInvitation, TestBuilder } from '@dxos/client/testing';
-import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+import { Trigger } from '@dxos/async';
+import { create } from '@dxos/client/echo';
+import { TestBuilder } from '@dxos/client/testing';
 import { describe, test } from '@dxos/test';
 
+import { initFunctionsPlugin } from './plugin-init';
 import { setTestCallHandler } from './test/handler';
-import { FunctionRegistry } from '../function';
-import { DevServer, Scheduler } from '../runtime';
-import { createFunctionRuntime, createInitializedClients, TestType } from '../testing';
-import { TriggerRegistry } from '../trigger';
+import { createInitializedClients, inviteMember, startFunctionsHost, TestType } from '../testing';
 import { FunctionDef, FunctionTrigger } from '../types';
 
 describe('functions e2e', () => {
@@ -30,13 +25,11 @@ describe('functions e2e', () => {
 
   test('a function gets triggered in response to another peer object creations', async () => {
     // TODO(burdon): Create builder pattern.
-    const functionRuntime = await createFunctionRuntime(testBuilder);
-    const devServer = await startDevServer(functionRuntime);
-    const scheduler = await startScheduler(functionRuntime, devServer);
+    const functionRuntime = await startFunctionsHost(testBuilder, initFunctionsPlugin);
 
     const app = (await createInitializedClients(testBuilder, 1))[0];
     const space = await app.spaces.create();
-    await inviteMember(space, functionRuntime);
+    await inviteMember(space, functionRuntime.client);
 
     const uri = 'example.com/function/test';
     space.db.add(create(FunctionDef, { uri, route: '/test', handler: 'test' }));
@@ -59,7 +52,7 @@ describe('functions e2e', () => {
       return args.response.status(200);
     });
 
-    await waitTriggersReplicated(space, scheduler);
+    await functionRuntime.waitHasActiveTriggers(space);
     const addedObject = space.db.add(create(TestType, { title: '42' }));
 
     const callArgs = await called.wait();
@@ -67,34 +60,4 @@ describe('functions e2e', () => {
     expect(callArgs.objects).to.deep.eq([addedObject.id]);
     expect(callArgs.spaceKey).to.eq(space.key.toHex());
   });
-
-  const waitTriggersReplicated = async (space: Space, scheduler: Scheduler) => {
-    await waitForCondition({ condition: () => scheduler.triggers.getActiveTriggers(space).length > 0 });
-  };
-
-  // TODO(burdon): Factor out utils to builder pattern.
-
-  const startScheduler = async (client: Client, devServer: DevServer) => {
-    const functionRegistry = new FunctionRegistry(client);
-    const triggerRegistry = new TriggerRegistry(client);
-    const scheduler = new Scheduler(functionRegistry, triggerRegistry, { endpoint: devServer.endpoint });
-    await scheduler.start();
-    testBuilder.ctx.onDispose(() => scheduler.stop());
-    return scheduler;
-  };
-
-  const startDevServer = async (client: Client) => {
-    const functionRegistry = new FunctionRegistry(client);
-    const server = new DevServer(client, functionRegistry, {
-      baseDir: path.join(__dirname, '../testing'),
-    });
-    await server.start();
-    testBuilder.ctx.onDispose(() => server.stop());
-    return server;
-  };
-
-  const inviteMember = async (host: Space, guest: Client) => {
-    const [{ invitation: hostInvitation }] = await Promise.all(performInvitation({ host, guest: guest.spaces }));
-    expect(hostInvitation?.state).to.eq(Invitation.State.SUCCESS);
-  };
 });

package/src/testing/index.ts

@@ -5,3 +5,4 @@
 export * from './setup';
 export * from './types';
 export * from './util';
+export * from './manifest';

package/src/testing/manifest.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type { FunctionManifest } from '../types';
+
+export const testFunctionManifest: FunctionManifest = {
+  functions: [
+    {
+      uri: 'example.com/function/test',
+      route: 'test',
+      handler: 'test',
+    },
+  ],
+};

package/src/testing/plugin-init.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { FunctionsPlugin } from '@dxos/agent';
+import { type Client } from '@dxos/client';
+
+import { type FunctionsPluginInitializer } from './setup';
+
+/**
+ * Deliberately in a non-exported file to keep @dxos/agent as a devDependency.
+ */
+export const initFunctionsPlugin: FunctionsPluginInitializer = async (client: Client) => {
+  const plugin = new FunctionsPlugin();
+  await plugin.initialize({ client, clientServices: client.services });
+  await plugin.open();
+  return {
+    close: () => plugin.close(),
+  };
+};

package/src/testing/setup.ts

@@ -2,14 +2,23 @@
 // Copyright 2024 DXOS.org
 //
 
-import { FunctionsPlugin } from '@dxos/agent';
+import { getRandomPort } from 'get-port-please';
+import path from 'node:path';
+
+import { waitForCondition } from '@dxos/async';
 import { Client, Config } from '@dxos/client';
+import { type Space } from '@dxos/client/echo';
 import { type TestBuilder } from '@dxos/client/testing';
 import { range } from '@dxos/util';
 
 import { TestType } from './types';
+import { FunctionRegistry } from '../function';
+import { DevServer, type DevServerOptions, Scheduler } from '../runtime';
+import { TriggerRegistry } from '../trigger';
 import { FunctionDef, FunctionTrigger } from '../types';
 
+export type FunctionsPluginInitializer = (client: Client) => Promise<{ close: () => Promise<void> }>;
+
 // TODO(burdon): Extend/wrap TestBuilder.
 
 export const createInitializedClients = async (testBuilder: TestBuilder, count: number = 1, config?: Config) => {
@@ -25,19 +34,68 @@ export const createInitializedClients = async (testBuilder: TestBuilder, count:
   );
 };
 
-export const createFunctionRuntime = async (testBuilder: TestBuilder): Promise<Client> => {
+export const createFunctionRuntime = async (
+  testBuilder: TestBuilder,
+  pluginInitializer: FunctionsPluginInitializer,
+): Promise<Client> => {
+  const functionsPort = await getRandomPort('127.0.0.1');
   const config = new Config({
     runtime: {
       agent: {
-        plugins: [{ id: 'dxos.org/agent/plugin/functions', config: { port: 8080 } }],
+        plugins: [{ id: 'dxos.org/agent/plugin/functions', config: { port: functionsPort } }],
       },
     },
   });
 
   const [client] = await createInitializedClients(testBuilder, 1, config);
-  const plugin = new FunctionsPlugin();
-  await plugin.initialize({ client, clientServices: client.services });
-  await plugin.open();
+  const plugin = await pluginInitializer(client);
   testBuilder.ctx.onDispose(() => plugin.close());
   return client;
 };
+
+export const startFunctionsHost = async (
+  testBuilder: TestBuilder,
+  pluginInitializer: FunctionsPluginInitializer,
+  options?: DevServerOptions,
+) => {
+  const functionRuntime = await createFunctionRuntime(testBuilder, pluginInitializer);
+  const functionsRegistry = new FunctionRegistry(functionRuntime);
+  const devServer = await startDevServer(testBuilder, functionRuntime, functionsRegistry, options);
+  const scheduler = await startScheduler(testBuilder, functionRuntime, devServer, functionsRegistry);
+  return {
+    scheduler,
+    client: functionRuntime,
+    waitHasActiveTriggers: async (space: Space) => {
+      await waitForCondition({ condition: () => scheduler.triggers.getActiveTriggers(space).length > 0 });
+    },
+  };
+};
+
+const startScheduler = async (
+  testBuilder: TestBuilder,
+  client: Client,
+  devServer: DevServer,
+  functionRegistry: FunctionRegistry,
+) => {
+  const triggerRegistry = new TriggerRegistry(client);
+  const scheduler = new Scheduler(functionRegistry, triggerRegistry, { endpoint: devServer.endpoint });
+  await scheduler.start();
+  testBuilder.ctx.onDispose(() => scheduler.stop());
+  return scheduler;
+};
+
+const startDevServer = async (
+  testBuilder: TestBuilder,
+  client: Client,
+  functionRegistry: FunctionRegistry,
+  options?: { baseDir?: string },
+) => {
+  const server = new DevServer(client, functionRegistry, {
+    baseDir: path.join(__dirname, '../testing'),
+    port: await getRandomPort('127.0.0.1'),
+    ...options,
+  });
+  await server.start();
+  testBuilder.ctx.onDispose(() => server.stop());
+  return server;
+};

package/src/testing/util.ts

@@ -2,8 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
+import type { Client } from '@dxos/client';
 import { Filter, type Space } from '@dxos/client/echo';
+import { performInvitation } from '@dxos/client/testing';
 import { invariant } from '@dxos/invariant';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 
 import { FunctionTrigger } from '../types';
 
@@ -14,3 +17,10 @@ export const triggerWebhook = async (space: Space, uri: string) => {
   invariant(trigger.spec.type === 'webhook');
   void fetch(`http://localhost:${trigger.spec.port}`);
 };
+
+export const inviteMember = async (host: Space, guest: Client) => {
+  const [{ invitation: hostInvitation }] = await Promise.all(performInvitation({ host, guest: guest.spaces }));
+  if (hostInvitation?.state !== Invitation.State.SUCCESS) {
+    throw new Error(`Expected ${hostInvitation?.state} to be ${Invitation.State.SUCCESS}.`);
+  }
+};