@dxos/functions 0.5.3-main.6f2dfea → 0.5.3-main.77c09ab

package/src/handler.ts

@@ -8,38 +8,61 @@ import { type EchoReactiveObject } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 import { nonNullable } from '@dxos/util';
 
-// Lambda-like function definitions.
+// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
+// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
 // https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/#functions
 // https://www.npmjs.com/package/aws-lambda
-// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
 
-// TODO(burdon): No response?
-export interface Response {
-  status(code: number): Response;
-}
+/**
+ * Function handler.
+ */
+export type FunctionHandler<TData = {}, TMeta = {}> = (params: {
+  context: FunctionContext;
+  event: FunctionEvent<TData, TMeta>;
+  response: FunctionResponse;
+}) => Promise<FunctionResponse | void>;
 
+/**
+ * Function context.
+ */
 export interface FunctionContext {
   // TODO(burdon): Limit access to individual space.
   client: Client;
   // TODO(burdon): Replace with storage service abstraction.
   dataDir?: string;
-  // Data passed to function invocation.
-  data?: any;
 }
 
-// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
-export type FunctionHandler<T extends {}> = (params: {
-  event: T;
-  context: FunctionContext;
-  response: Response;
-}) => Promise<Response | void>;
+/**
+ * Event payload.
+ */
+export type FunctionEvent<TData = {}, TMeta = {}> = {
+  data: FunctionEventMeta<TMeta> & TData;
+};
+
+/**
+ * Metadata from trigger.
+ */
+export type FunctionEventMeta<TMeta = {}> = {
+  meta: TMeta;
+};
+
+/**
+ * Function response.
+ */
+export interface FunctionResponse {
+  status(code: number): FunctionResponse;
+}
+
+//
+// Subscription utils.
+//
 
-export type RawSubscriptionEvent = {
+export type RawSubscriptionData = {
   spaceKey?: string;
   objects?: string[];
 };
 
-export type SubscriptionEvent = {
+export type SubscriptionData = {
   space?: Space;
   objects?: EchoReactiveObject<any>[];
 };
@@ -54,22 +77,22 @@ export type SubscriptionEvent = {
  *
  * NOTE: Get space key from devtools or `dx space list --json`
  */
-export const subscriptionHandler = (
-  handler: FunctionHandler<SubscriptionEvent>,
-): FunctionHandler<RawSubscriptionEvent> => {
-  return ({ event, context, ...rest }) => {
+export const subscriptionHandler = <TMeta>(
+  handler: FunctionHandler<SubscriptionData, TMeta>,
+): FunctionHandler<RawSubscriptionData, TMeta> => {
+  return ({ event: { data }, context, ...rest }) => {
     const { client } = context;
-    const space = event.spaceKey ? client.spaces.get(PublicKey.from(event.spaceKey)) : undefined;
-    const objects =
-      space &&
-      event.objects?.map<EchoReactiveObject<any> | undefined>((id) => space!.db.getObjectById(id)).filter(nonNullable);
+    const space = data.spaceKey ? client.spaces.get(PublicKey.from(data.spaceKey)) : undefined;
+    const objects = space
+      ? data.objects?.map<EchoReactiveObject<any> | undefined>((id) => space!.db.getObjectById(id)).filter(nonNullable)
+      : [];
 
-    if (!!event.spaceKey && !space) {
-      log.warn('invalid space', { event });
+    if (!!data.spaceKey && !space) {
+      log.warn('invalid space', { data });
     } else {
       log.info('handler', { space: space?.key.truncate(), objects: objects?.length });
     }
 
-    return handler({ event: { space, objects }, context, ...rest });
+    return handler({ event: { data: { ...data, space, objects } }, context, ...rest });
   };
 };

package/src/index.ts

@@ -2,6 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './function';
 export * from './handler';
 export * from './runtime';
+export * from './trigger';
 export * from './types';

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

@@ -5,12 +5,14 @@
 import { expect } from 'chai';
 import path from 'path';
 
-import { FunctionsPlugin } from '@dxos/agent';
-import { Client, Config } from '@dxos/client';
+import { waitForCondition } from '@dxos/async';
+import { type Client } from '@dxos/client';
 import { TestBuilder } from '@dxos/client/testing';
-import { describe, openAndClose, test } from '@dxos/test';
+import { describe, test } from '@dxos/test';
 
 import { DevServer } from './dev-server';
+import { FunctionRegistry } from '../function';
+import { createFunctionRuntime } from '../testing';
 import { type FunctionManifest } from '../types';
 
 describe('dev server', () => {
@@ -18,35 +20,10 @@ describe('dev server', () => {
   let testBuilder: TestBuilder;
   before(async () => {
     testBuilder = new TestBuilder();
-    const config = new Config({
-      runtime: {
-        agent: {
-          plugins: [
-            {
-              id: 'dxos.org/agent/plugin/functions',
-              config: {
-                port: 8080,
-              },
-            },
-          ],
-        },
-      },
-    });
-
-    const services = testBuilder.createLocalClientServices();
-    client = new Client({ config, services });
-
-    await client.initialize();
-    await client.halo.createIdentity();
-    testBuilder.ctx.onDispose(() => client.destroy());
-
-    // TODO(burdon): Better way to configure plugin? (Rationalize chess.test).
-    const functionsPlugin = new FunctionsPlugin();
-    await functionsPlugin.initialize({ client, clientServices: services });
-    await openAndClose(functionsPlugin);
-
+    client = await createFunctionRuntime(testBuilder);
     expect(client.services.services.FunctionRegistryService).to.exist;
   });
+
   after(async () => {
     await testBuilder.destroy();
   });
@@ -55,18 +32,19 @@ describe('dev server', () => {
     const manifest: FunctionManifest = {
       functions: [
         {
-          id: 'example.com/function/test',
-          path: 'test',
+          uri: 'example.com/function/test',
+          route: 'test',
           handler: 'test',
         },
       ],
     };
 
-    const server = new DevServer(client, {
-      manifest,
+    const registry = new FunctionRegistry(client);
+    const server = new DevServer(client, registry, {
       baseDir: path.join(__dirname, '../testing'),
     });
-    await server.initialize();
+    const space = await client.spaces.create();
+    await registry.register(space, manifest.functions);
     await server.start();
 
     // TODO(burdon): Doesn't shut down cleanly.
@@ -74,6 +52,8 @@ describe('dev server', () => {
     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);
   });

package/src/runtime/dev-server.ts

@@ -9,14 +9,15 @@ import { join } from 'node:path';
 
 import { Event, Trigger } from '@dxos/async';
 import { type Client } from '@dxos/client';
+import { Context } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 
-import { type FunctionContext, type FunctionHandler, type Response } from '../handler';
-import { type FunctionDef, type FunctionManifest } from '../types';
+import { type FunctionRegistry } from '../function';
+import { type FunctionContext, type FunctionEvent, type FunctionHandler, type FunctionResponse } from '../handler';
+import { type FunctionDef } from '../types';
 
 export type DevServerOptions = {
-  manifest: FunctionManifest;
   baseDir: string;
   port?: number;
   reload?: boolean;
@@ -27,6 +28,8 @@ export type DevServerOptions = {
  * Functions dev server provides a local HTTP server for testing functions.
  */
 export class DevServer {
+  private _ctx = createContext();
+
   // Function handlers indexed by name (URL path).
   private readonly _handlers: Record<string, { def: FunctionDef; handler: FunctionHandler<any> }> = {};
 
@@ -38,11 +41,18 @@ export class DevServer {
 
   public readonly update = new Event<number>();
 
-  // prettier-ignore
   constructor(
     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 {
@@ -63,19 +73,10 @@ export class DevServer {
     return Object.values(this._handlers);
   }
 
-  async initialize() {
-    for (const def of this._options.manifest.functions) {
-      try {
-        await this._load(def);
-      } catch (err) {
-        log.error('parsing function (check manifest)', err);
-      }
-    }
-  }
-
   async start() {
     invariant(!this._server);
     log.info('starting...');
+    this._ctx = createContext();
 
     // TODO(burdon): Move to hono.
     const app = express();
@@ -107,12 +108,14 @@ export class DevServer {
       // Register functions.
       const { registrationId, endpoint } = await this._client.services.services.FunctionRegistryService!.register({
         endpoint: this.endpoint,
-        functions: this.functions.map(({ def: { id, path } }) => ({ id, path })),
       });
 
       log.info('registered', { endpoint });
       this._proxy = endpoint;
       this._functionServiceRegistration = registrationId;
+
+      // Open after registration, so that it can be updated with the list of function definitions.
+      await this._functionsRegistry.open(this._ctx);
     } catch (err: any) {
       await this.stop();
       throw new Error('FunctionRegistryService not available (check plugin is configured).');
@@ -155,10 +158,10 @@ export class DevServer {
   /**
    * Load function.
    */
-  private async _load(def: FunctionDef, force = false) {
-    const { id, path, handler } = def;
+  private async _load(def: FunctionDef, force?: boolean | undefined) {
+    const { uri, route, handler } = def;
     const filePath = join(this._options.baseDir, handler);
-    log.info('loading', { id, force });
+    log.info('loading', { uri, force });
 
     // Remove from cache.
     if (force) {
@@ -169,13 +172,26 @@ export class DevServer {
         });
     }
 
+    // TODO(burdon): Import types.
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const module = require(filePath);
     if (typeof module.default !== 'function') {
-      throw new Error(`Handler must export default function: ${id}`);
+      throw new Error(`Handler must export default function: ${uri}`);
     }
 
-    this._handlers[path] = { def, handler: module.default };
+    this._handlers[route] = { def, handler: module.default };
+  }
+
+  private async _safeUpdateRegistration(): Promise<void> {
+    invariant(this._functionServiceRegistration);
+    try {
+      await this._client.services.services.FunctionRegistryService!.updateRegistration({
+        registrationId: this._functionServiceRegistration,
+        functions: this.functions.map(({ def: { id, route } }) => ({ id, route })),
+      });
+    } catch (err) {
+      log.catch(err);
+    }
   }
 
   /**
@@ -186,24 +202,23 @@ export class DevServer {
     const now = Date.now();
 
     log.info('req', { seq, path });
-    const statusCode = await this._invoke(path, data);
+    const statusCode = await this._invoke(path, { data });
 
     log.info('res', { seq, path, statusCode, duration: Date.now() - now });
     this.update.emit(statusCode);
     return statusCode;
   }
 
-  private async _invoke(path: string, event: any) {
+  private async _invoke(path: string, event: FunctionEvent) {
     const { handler } = this._handlers[path] ?? {};
     invariant(handler, `invalid path: ${path}`);
-
     const context: FunctionContext = {
       client: this._client,
       dataDir: this._options.dataDir,
     };
 
     let statusCode = 200;
-    const response: Response = {
+    const response: FunctionResponse = {
       status: (code: number) => {
         statusCode = code;
         return response;
@@ -214,3 +229,5 @@ export class DevServer {
     return statusCode;
   }
 }
+
+const createContext = () => new Context({ name: 'DevServer' });

package/src/runtime/scheduler.test.ts

@@ -6,40 +6,53 @@ import { expect } from 'chai';
 import WebSocket from 'ws';
 
 import { Trigger } from '@dxos/async';
-import { Client } from '@dxos/client';
+import { type Client } from '@dxos/client';
 import { TestBuilder } from '@dxos/client/testing';
-import { create, S, TypedObject } from '@dxos/echo-schema';
+import { create } from '@dxos/echo-schema';
 import { describe, test } from '@dxos/test';
 
-import { Scheduler } from './scheduler';
-import { type FunctionManifest, type WebhookTrigger } from '../types';
+import { Scheduler, type SchedulerOptions } from './scheduler';
+import { FunctionRegistry } from '../function';
+import { createInitializedClients, TestType, triggerWebhook } from '../testing';
+import { TriggerRegistry } from '../trigger';
+import { type FunctionManifest } from '../types';
 
 // TODO(burdon): Test we can add and remove triggers.
 describe('scheduler', () => {
+  let testBuilder: TestBuilder;
   let client: Client;
   before(async () => {
-    const testBuilder = new TestBuilder();
-    client = new Client({ services: testBuilder.createLocalClientServices() });
-    await client.initialize();
-    await client.halo.createIdentity();
+    testBuilder = new TestBuilder();
+    client = (await createInitializedClients(testBuilder, 1))[0];
   });
   after(async () => {
-    await client.destroy();
+    await testBuilder.destroy();
   });
 
+  const createScheduler = (callback: SchedulerOptions['callback']) => {
+    const scheduler = new Scheduler(new FunctionRegistry(client), new TriggerRegistry(client), { callback });
+    after(async () => {
+      await scheduler.stop();
+    });
+
+    return scheduler;
+  };
+
   test('timer', async () => {
     const manifest: FunctionManifest = {
       functions: [
         {
-          id: 'example.com/function/test',
-          path: '/test',
+          uri: 'example.com/function/test',
+          route: '/test',
           handler: 'test',
         },
       ],
       triggers: [
         {
           function: 'example.com/function/test',
-          timer: {
+          enabled: true,
+          spec: {
+            type: 'timer',
             cron: '0/1 * * * * *', // Every 1s.
           },
         },
@@ -48,18 +61,13 @@ describe('scheduler', () => {
 
     let count = 0;
     const done = new Trigger();
-    const scheduler = new Scheduler(client, manifest, {
-      callback: async () => {
-        if (++count === 3) {
-          done.wake();
-        }
-      },
+    const scheduler = createScheduler(async () => {
+      if (++count === 3) {
+        done.wake();
+      }
     });
-
+    await scheduler.register(client.spaces.default, manifest);
     await scheduler.start();
-    after(async () => {
-      await scheduler.stop();
-    });
 
     await done.wait({ timeout: 5_000 });
     expect(count).to.equal(3);
@@ -69,15 +77,17 @@ describe('scheduler', () => {
     const manifest: FunctionManifest = {
       functions: [
         {
-          id: 'example.com/function/test',
-          path: '/test',
+          uri: 'example.com/function/test',
+          route: '/test',
           handler: 'test',
         },
       ],
       triggers: [
         {
           function: 'example.com/function/test',
-          webhook: {
+          enabled: true,
+          spec: {
+            type: 'webhook',
             method: 'GET',
           },
         },
@@ -85,23 +95,14 @@ describe('scheduler', () => {
     };
 
     const done = new Trigger();
-    const scheduler = new Scheduler(client, manifest, {
-      callback: async () => {
-        done.wake();
-      },
+    const scheduler = createScheduler(async () => {
+      done.wake();
     });
-
+    const space = await client.spaces.create();
+    await scheduler.register(space, manifest);
     await scheduler.start();
-    after(async () => {
-      await scheduler.stop();
-    });
 
-    setTimeout(() => {
-      const mount: WebhookTrigger = scheduler.mounts.find(
-        (mount) => mount.function === 'example.com/function/test',
-      )!.webhook!;
-      void fetch(`http://localhost:${mount.port}`);
-    });
+    setTimeout(async () => triggerWebhook(space, manifest.functions![0].uri));
 
     await done.wait();
   });
@@ -110,15 +111,17 @@ describe('scheduler', () => {
     const manifest: FunctionManifest = {
       functions: [
         {
-          id: 'example.com/function/test',
-          path: '/test',
+          uri: 'example.com/function/test',
+          route: '/test',
           handler: 'test',
         },
       ],
       triggers: [
         {
           function: 'example.com/function/test',
-          websocket: {
+          enabled: true,
+          spec: {
+            type: 'websocket',
             // url: 'https://hub.dxos.network/api/mailbox/test',
             url: 'http://localhost:8081',
             init: {
@@ -130,16 +133,11 @@ describe('scheduler', () => {
     };
 
     const done = new Trigger();
-    const scheduler = new Scheduler(client, manifest, {
-      callback: async (data) => {
-        done.wake();
-      },
+    const scheduler = createScheduler(async () => {
+      done.wake();
     });
-
+    await scheduler.register(client.spaces.default, manifest);
     await scheduler.start();
-    after(async () => {
-      await scheduler.stop();
-    });
 
     // Test server.
     setTimeout(() => {
@@ -157,29 +155,21 @@ describe('scheduler', () => {
   });
 
   test('subscription', async () => {
-    class TestType extends TypedObject({ typename: 'example.com/type/Test', version: '0.1.0' })({
-      title: S.string,
-    }) {}
-    client.addSchema(TestType);
-
     const manifest: FunctionManifest = {
       functions: [
         {
-          id: 'example.com/function/test',
-          path: '/test',
+          uri: 'example.com/function/test',
+          route: '/test',
           handler: 'test',
         },
       ],
       triggers: [
         {
           function: 'example.com/function/test',
-          subscription: {
-            spaceKey: client.spaces.default.key.toHex(),
-            filter: [
-              {
-                type: TestType.typename,
-              },
-            ],
+          enabled: true,
+          spec: {
+            type: 'subscription',
+            filter: [{ type: TestType.typename }],
           },
         },
       ],
@@ -187,20 +177,14 @@ describe('scheduler', () => {
 
     let count = 0;
     const done = new Trigger();
-    const scheduler = new Scheduler(client, manifest, {
-      callback: async () => {
-        if (++count === 2) {
-          done.wake();
-        }
-      },
+    const scheduler = createScheduler(async () => {
+      if (++count === 1) {
+        done.wake();
+      }
     });
-
+    await scheduler.register(client.spaces.default, manifest);
     await scheduler.start();
-    after(async () => {
-      await scheduler.stop();
-    });
 
-    // TODO(burdon): Query for Expando?
     setTimeout(() => {
       const space = client.spaces.default;
       const object = create(TestType, { title: 'Hello world!' });