@dxos/functions 0.5.3-main.6f2dfea → 0.5.3-main.79e0565

package/src/runtime/scheduler.ts

@@ -2,30 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { CronJob } from 'cron';
-import { getPort } from 'get-port-please';
-import http from 'node:http';
 import path from 'node:path';
-import WebSocket from 'ws';
 
-import { TextV0Type } from '@braneframe/types';
-import { debounce, DeferredTask, sleep, Trigger } from '@dxos/async';
-import { type Client, type PublicKey } from '@dxos/client';
-import { createSubscription, Filter, getAutomergeObjectCore, type Query, type Space } from '@dxos/client/echo';
+import { Mutex } from '@dxos/async';
+import { type Space } from '@dxos/client/echo';
 import { Context } from '@dxos/context';
-import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
-import { ComplexMap } from '@dxos/util';
 
-import {
-  type FunctionDef,
-  type FunctionManifest,
-  type FunctionTrigger,
-  type SubscriptionTrigger,
-  type TimerTrigger,
-  type WebhookTrigger,
-  type WebsocketTrigger,
-} from '../types';
+import { type FunctionRegistry } from '../function';
+import { type FunctionEventMeta } from '../handler';
+import { type TriggerRegistry } from '../trigger';
+import { type FunctionDef, type FunctionManifest, type FunctionTrigger } from '../types';
 
 export type Callback = (data: any) => Promise<void | number>;
 
@@ -38,111 +25,99 @@ export type SchedulerOptions = {
  * The scheduler triggers function execution based on various triggers.
  */
 export class Scheduler {
-  // Map of mounted functions.
-  private readonly _mounts = new ComplexMap<
-    { spaceKey: PublicKey; id: string },
-    { ctx: Context; trigger: FunctionTrigger }
-  >(({ spaceKey, id }) => `${spaceKey.toHex()}:${id}`);
+  private _ctx = createContext();
+
+  private readonly _callMutex = new Mutex();
 
   constructor(
-    private readonly _client: Client,
-    private readonly _manifest: FunctionManifest,
+    public readonly functions: FunctionRegistry,
+    public readonly triggers: TriggerRegistry,
     private readonly _options: SchedulerOptions = {},
-  ) {}
-
-  get mounts() {
-    return Array.from(this._mounts.values()).reduce<FunctionTrigger[]>((acc, { trigger }) => {
-      acc.push(trigger);
-      return acc;
-    }, []);
+  ) {
+    this.functions.registered.on(async ({ space, added }) => {
+      await this._safeActivateTriggers(space, this.triggers.getInactiveTriggers(space), added);
+    });
+    this.triggers.registered.on(async ({ space, triggers }) => {
+      await this._safeActivateTriggers(space, triggers, this.functions.getFunctions(space));
+    });
   }
 
   async start() {
-    this._client.spaces.subscribe(async (spaces) => {
-      for (const space of spaces) {
-        await space.waitUntilReady();
-        for (const trigger of this._manifest.triggers ?? []) {
-          await this.mount(new Context(), space, trigger);
-        }
-      }
-    });
+    await this._ctx.dispose();
+    this._ctx = createContext();
+    await this.functions.open(this._ctx);
+    await this.triggers.open(this._ctx);
   }
 
   async stop() {
-    for (const { id, spaceKey } of this._mounts.keys()) {
-      await this.unmount(id, spaceKey);
-    }
+    await this._ctx.dispose();
+    await this.functions.close();
+    await this.triggers.close();
   }
 
-  /**
-   * Mount trigger.
-   */
-  private async mount(ctx: Context, space: Space, trigger: FunctionTrigger) {
-    const key = { spaceKey: space.key, id: trigger.function };
-    const def = this._manifest.functions.find((config) => config.id === trigger.function);
-    invariant(def, `Function not found: ${trigger.function}`);
-
-    // TODO(burdon): Currently supports only one trigger declaration per function.
-    const exists = this._mounts.get(key);
-    if (!exists) {
-      this._mounts.set(key, { ctx, trigger });
-      log('mount', { space: space.key, trigger });
-      if (ctx.disposed) {
-        return;
-      }
-
-      //
-      // Triggers types.
-      //
-
-      if (trigger.timer) {
-        await this._createTimer(ctx, space, def, trigger.timer);
-      }
-
-      if (trigger.webhook) {
-        await this._createWebhook(ctx, space, def, trigger.webhook);
-      }
-
-      if (trigger.websocket) {
-        await this._createWebsocket(ctx, space, def, trigger.websocket);
-      }
+  // TODO(burdon): Remove and update registries directly.
+  public async register(space: Space, manifest: FunctionManifest) {
+    await this.functions.register(space, manifest.functions);
+    await this.triggers.register(space, manifest);
+  }
 
-      if (trigger.subscription) {
-        await this._createSubscription(ctx, space, def, trigger.subscription);
-      }
-    }
+  private async _safeActivateTriggers(
+    space: Space,
+    triggers: FunctionTrigger[],
+    functions: FunctionDef[],
+  ): Promise<void> {
+    const mountTasks = triggers.map((trigger) => {
+      return this.activate(space, functions, trigger);
+    });
+    await Promise.all(mountTasks).catch(log.catch);
   }
 
-  private async unmount(id: string, spaceKey: PublicKey) {
-    const key = { id, spaceKey };
-    const { ctx } = this._mounts.get(key) ?? {};
-    if (ctx) {
-      this._mounts.delete(key);
-      await ctx.dispose();
+  private async activate(space: Space, functions: FunctionDef[], fnTrigger: FunctionTrigger) {
+    const definition = functions.find((def) => def.uri === fnTrigger.function);
+    if (!definition) {
+      log.info('function is not found for trigger', { fnTrigger });
+      return;
     }
+
+    await this.triggers.activate({ space }, fnTrigger, async (args) => {
+      return this._callMutex.executeSynchronized(() => {
+        return this._execFunction(definition, fnTrigger, {
+          meta: fnTrigger.meta,
+          data: { ...args, spaceKey: space.key },
+        });
+      });
+    });
+
+    log('activated trigger', { space: space.key, trigger: fnTrigger });
   }
 
-  // TODO(burdon): Pass in Space key (common context).
-  private async _execFunction(def: FunctionDef, data: any): Promise<number> {
+  private async _execFunction<TData, TMeta>(
+    def: FunctionDef,
+    trigger: FunctionTrigger,
+    { data, meta }: { data: TData; meta?: TMeta },
+  ): Promise<number> {
+    let status = 0;
     try {
-      let status = 0;
+      // TODO(burdon): Pass in Space key (common context)?
+      const payload = Object.assign({}, meta && ({ meta } satisfies FunctionEventMeta<TMeta>), data);
+
       const { endpoint, callback } = this._options;
       if (endpoint) {
         // TODO(burdon): Move out of scheduler (generalize as callback).
-        const url = path.join(endpoint, def.path);
-        log.info('exec', { function: def.id, url });
+        const url = path.join(endpoint, def.route);
+        log.info('exec', { function: def.uri, url, triggerType: trigger.spec.type });
         const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
           },
-          body: JSON.stringify(data),
+          body: JSON.stringify(payload),
         });
 
         status = response.status;
       } else if (callback) {
-        log.info('exec', { function: def.id });
-        status = (await callback(data)) ?? 200;
+        log.info('exec', { function: def.uri });
+        status = (await callback(payload)) ?? 200;
       }
 
       // Check errors.
@@ -151,214 +126,14 @@ export class Scheduler {
       }
 
       // const result = await response.json();
-      log.info('done', { function: def.id, status });
-      return status;
+      log.info('done', { function: def.uri, status });
     } catch (err: any) {
-      log.error('error', { function: def.id, error: err.message });
-      return 500;
-    }
-  }
-
-  //
-  // Triggers
-  //
-
-  /**
-   * Cron timer.
-   */
-  private async _createTimer(ctx: Context, space: Space, def: FunctionDef, trigger: TimerTrigger) {
-    log.info('timer', { space: space.key, trigger });
-    const { cron } = trigger;
-
-    const task = new DeferredTask(ctx, async () => {
-      await this._execFunction(def, { spaceKey: space.key });
-    });
-
-    let last = 0;
-    let run = 0;
-    // https://www.npmjs.com/package/cron#constructor
-    const job = CronJob.from({
-      cronTime: cron,
-      runOnInit: false,
-      onTick: () => {
-        // TODO(burdon): Check greater than 30s (use cron-parser).
-        const now = Date.now();
-        const delta = last ? now - last : 0;
-        last = now;
-
-        run++;
-        log.info('tick', { space: space.key.truncate(), count: run, delta });
-        task.schedule();
-      },
-    });
-
-    job.start();
-    ctx.onDispose(() => job.stop());
-  }
-
-  /**
-   * Webhook.
-   */
-  private async _createWebhook(ctx: Context, space: Space, def: FunctionDef, trigger: WebhookTrigger) {
-    log.info('webhook', { space: space.key, trigger });
-
-    // TODO(burdon): Enable POST hook with payload.
-    const server = http.createServer(async (req, res) => {
-      if (req.method !== trigger.method) {
-        res.statusCode = 405;
-        return res.end();
-      }
-
-      res.statusCode = await this._execFunction(def, { spaceKey: space.key });
-      res.end();
-    });
-
-    // TODO(burdon): Not used.
-    // const DEF_PORT_RANGE = { min: 7500, max: 7599 };
-    // const portRange = Object.assign({}, trigger.port, DEF_PORT_RANGE) as WebhookTrigger['port'];
-    const port = await getPort({
-      random: true,
-      // portRange: [portRange!.min, portRange!.max],
-    });
-
-    // TODO(burdon): Update trigger object with actual port.
-    server.listen(port, () => {
-      log.info('started webhook', { port });
-      trigger.port = port;
-    });
-
-    ctx.onDispose(() => {
-      server.close();
-    });
-  }
-
-  /**
-   * Websocket.
-   * NOTE: The port must be unique, so the same hook cannot be used for multiple spaces.
-   */
-  private async _createWebsocket(
-    ctx: Context,
-    space: Space,
-    def: FunctionDef,
-    trigger: WebsocketTrigger,
-    options: {
-      retryDelay: number;
-      maxAttempts: number;
-    } = {
-      retryDelay: 2,
-      maxAttempts: 5,
-    },
-  ) {
-    log.info('websocket', { space: space.key, trigger });
-    const { url } = trigger;
-
-    let ws: WebSocket;
-    for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
-      const open = new Trigger<boolean>();
-
-      ws = new WebSocket(url);
-      Object.assign(ws, {
-        onopen: () => {
-          log.info('opened', { url });
-          if (trigger.init) {
-            ws.send(new TextEncoder().encode(JSON.stringify(trigger.init)));
-          }
-
-          open.wake(true);
-        },
-
-        // TODO(burdon): Config retry if server closes?
-        onclose: (event) => {
-          log.info('closed', { url, code: event.code });
-          open.wake(false);
-        },
-
-        onerror: (event) => {
-          log.catch(event.error, { url });
-        },
-
-        onmessage: async (event) => {
-          try {
-            const data = JSON.parse(new TextDecoder().decode(event.data as Uint8Array));
-            await this._execFunction(def, { spaceKey: space.key, data });
-          } catch (err) {
-            log.catch(err, { url });
-          }
-        },
-      } satisfies Partial<WebSocket>);
-
-      const isOpen = await open.wait();
-      if (isOpen) {
-        break;
-      } else {
-        const wait = Math.pow(attempt, 2) * options.retryDelay;
-        if (attempt < options.maxAttempts) {
-          log.warn(`failed to connect; trying again in ${wait}s`, { attempt });
-          await sleep(wait * 1_000);
-        }
-      }
+      log.error('error', { function: def.uri, error: err.message });
+      status = 500;
     }
 
-    ctx.onDispose(() => {
-      ws?.close();
-    });
-  }
-
-  /**
-   * ECHO subscription.
-   */
-  private async _createSubscription(ctx: Context, space: Space, def: FunctionDef, trigger: SubscriptionTrigger) {
-    log.info('subscription', { space: space.key, trigger });
-    const objectIds = new Set<string>();
-    const task = new DeferredTask(ctx, async () => {
-      await this._execFunction(def, { spaceKey: space.key, objects: Array.from(objectIds) });
-    });
-
-    // TODO(burdon): Don't fire initially.
-    // TODO(burdon): Subscription is called THREE times.
-    const subscriptions: (() => void)[] = [];
-    const subscription = createSubscription(({ added, updated }) => {
-      log.info('updated', { added: added.length, updated: updated.length });
-      for (const object of added) {
-        objectIds.add(object.id);
-      }
-      for (const object of updated) {
-        objectIds.add(object.id);
-      }
-
-      task.schedule();
-    });
-
-    subscriptions.push(() => subscription.unsubscribe());
-
-    // TODO(burdon): Create queue. Only allow one invocation per trigger at a time?
-    // TODO(burdon): Disable trigger if keeps failing.
-    const { filter, options: { deep, delay } = {} } = trigger;
-    const update = ({ objects }: Query) => {
-      subscription.update(objects);
-
-      // TODO(burdon): Hack to monitor changes to Document's text object.
-      if (deep) {
-        log.info('update', { objects: objects.length });
-        for (const object of objects) {
-          const content = object.content;
-          if (content instanceof TextV0Type) {
-            subscriptions.push(
-              getAutomergeObjectCore(content).updates.on(debounce(() => subscription.update([object]), 1_000)),
-            );
-          }
-        }
-      }
-    };
-
-    // TODO(burdon): Is Filter.or implemented?
-    // TODO(burdon): [Bug]: all callbacks are fired on the first mutation.
-    // TODO(burdon): [Bug]: not updated when document is deleted (either top or hierarchically).
-    const query = space.db.query(Filter.or(filter.map(({ type, props }) => Filter.typename(type, props))));
-    subscriptions.push(query.subscribe(delay ? debounce(update, delay) : update));
-
-    ctx.onDispose(() => {
-      subscriptions.forEach((unsubscribe) => unsubscribe());
-    });
+    return status;
   }
 }
+
+const createContext = () => new Context({ name: 'FunctionScheduler' });

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

@@ -0,0 +1,99 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 { describe, test } from '@dxos/test';
+
+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 { FunctionDef, FunctionTrigger } from '../types';
+
+describe('functions e2e', () => {
+  let testBuilder: TestBuilder;
+  before(async () => {
+    testBuilder = new TestBuilder();
+  });
+  after(async () => {
+    await testBuilder.destroy();
+  });
+
+  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 app = (await createInitializedClients(testBuilder, 1))[0];
+    const space = await app.spaces.create();
+    await inviteMember(space, functionRuntime);
+
+    const uri = 'example.com/function/test';
+    space.db.add(create(FunctionDef, { uri, route: '/test', handler: 'test' }));
+    const triggerMeta: FunctionTrigger['meta'] = { name: 'DXOS' };
+    space.db.add(
+      create(FunctionTrigger, {
+        function: uri,
+        meta: triggerMeta,
+        spec: {
+          type: 'subscription',
+          filter: [{ type: TestType.typename }],
+        },
+      }),
+    );
+
+    const called = new Trigger<any>();
+    setTestCallHandler(async (args) => {
+      called.wake(args.event.data);
+      return args.response.status(200);
+    });
+
+    await waitTriggersReplicated(space, scheduler);
+    const addedObject = space.db.add(create(TestType, { title: '42' }));
+
+    const callArgs = await called.wait();
+    expect(callArgs.meta).to.deep.eq(triggerMeta);
+    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

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './setup';
+export * from './types';
+export * from './util';

package/src/testing/setup.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { FunctionsPlugin } from '@dxos/agent';
+import { Client, Config } from '@dxos/client';
+import { type TestBuilder } from '@dxos/client/testing';
+import { range } from '@dxos/util';
+
+import { TestType } from './types';
+import { FunctionDef, FunctionTrigger } from '../types';
+
+// TODO(burdon): Create new or extend existing TestBuilder.
+
+export const createInitializedClients = async (testBuilder: TestBuilder, count: number = 1, config?: Config) => {
+  const clients = range(count).map(() => new Client({ config, services: testBuilder.createLocalClientServices() }));
+  testBuilder.ctx.onDispose(() => Promise.all(clients.map((c) => c.destroy())));
+  return Promise.all(
+    clients.map(async (client, index) => {
+      await client.initialize();
+      await client.halo.createIdentity({ displayName: `Peer ${index}` });
+      client.addSchema(TestType, FunctionDef, FunctionTrigger);
+      return client;
+    }),
+  );
+};
+
+export const createFunctionRuntime = async (testBuilder: TestBuilder): Promise<Client> => {
+  const config = new Config({
+    runtime: {
+      agent: {
+        plugins: [{ id: 'dxos.org/agent/plugin/functions', config: { port: 8080 } }],
+      },
+    },
+  });
+
+  const client = (await createInitializedClients(testBuilder, 1, config))[0];
+
+  // TODO(burdon): Better way to configure plugin? (Rationalize chess.test).
+  const functionsPlugin = new FunctionsPlugin();
+  await functionsPlugin.initialize({ client, clientServices: client.services });
+  await functionsPlugin.open();
+  testBuilder.ctx.onDispose(() => functionsPlugin.close());
+  return client;
+};

package/src/testing/test/handler.ts

@@ -4,6 +4,12 @@
 
 import { type FunctionHandler } from '../../handler';
 
-export const handler: FunctionHandler<any> = async ({ response }) => {
-  return response.status(200);
+let callHandler: FunctionHandler<any> = async ({ response }) => response.status(200);
+
+export const setTestCallHandler = (handler: FunctionHandler<any>) => {
+  callHandler = handler;
+};
+
+export const handler: FunctionHandler<any> = async (args) => {
+  return callHandler(args);
 };

package/src/testing/types.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { S, TypedObject } from '@dxos/echo-schema';
+
+export class TestType extends TypedObject({ typename: 'example.com/type/Test', version: '0.1.0' })({
+  title: S.string,
+}) {}

package/src/testing/util.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Filter, type Space } from '@dxos/client/echo';
+import { invariant } from '@dxos/invariant';
+
+import { FunctionTrigger } from '../types';
+
+export const triggerWebhook = async (space: Space, uri: string) => {
+  const trigger = (
+    await space.db.query(Filter.schema(FunctionTrigger, (t: FunctionTrigger) => t.function === uri)).run()
+  ).objects[0];
+  invariant(trigger.spec.type === 'webhook');
+  void fetch(`http://localhost:${trigger.spec.port}`);
+};

package/src/trigger/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './trigger-registry';