@dxos/functions 0.5.3-main.f752aaa → 0.5.3-main.f9b873d

package/schema/functions.json

@@ -1,27 +1,24 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
-  "required": [
-    "functions",
-    "triggers"
-  ],
+  "required": [],
   "properties": {
     "functions": {
       "type": "array",
       "items": {
         "type": "object",
         "required": [
-          "id",
-          "name",
+          "uri",
+          "route",
           "handler"
         ],
         "properties": {
-          "id": {
+          "uri": {
             "type": "string",
             "description": "a string",
             "title": "string"
           },
-          "name": {
+          "route": {
             "type": "string",
             "description": "a string",
             "title": "string"
@@ -45,7 +42,8 @@
       "items": {
         "type": "object",
         "required": [
-          "function"
+          "function",
+          "spec"
         ],
         "properties": {
           "function": {
@@ -53,113 +51,142 @@
             "description": "Function ID/URI.",
             "title": "string"
           },
-          "timer": {
+          "meta": {
             "type": "object",
-            "required": [
-              "cron"
-            ],
-            "properties": {
-              "cron": {
-                "type": "string",
-                "description": "a string",
-                "title": "string"
-              }
-            },
-            "additionalProperties": false
+            "required": [],
+            "properties": {},
+            "additionalProperties": {
+              "$id": "/schemas/any",
+              "title": "any"
+            }
           },
-          "webhook": {
-            "type": "object",
-            "required": [
-              "port"
-            ],
-            "properties": {
-              "port": {
-                "type": "number",
-                "description": "a number",
-                "title": "number"
-              }
-            },
-            "additionalProperties": false
-          },
-          "websocket": {
-            "type": "object",
-            "required": [
-              "url"
-            ],
-            "properties": {
-              "url": {
-                "type": "string",
-                "description": "a string",
-                "title": "string"
-              },
-              "init": {
+          "spec": {
+            "anyOf": [
+              {
                 "type": "object",
-                "required": [],
-                "properties": {},
-                "additionalProperties": {
-                  "$id": "/schemas/any",
-                  "title": "any"
-                }
-              }
-            },
-            "additionalProperties": false
-          },
-          "subscription": {
-            "type": "object",
-            "required": [
-              "filter"
-            ],
-            "properties": {
-              "spaceKey": {
-                "type": "string",
-                "description": "a string",
-                "title": "string"
-              },
-              "filter": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "required": [
-                    "type"
-                  ],
-                  "properties": {
-                    "type": {
-                      "type": "string",
-                      "description": "a string",
-                      "title": "string"
-                    },
-                    "props": {
-                      "type": "object",
-                      "required": [],
-                      "properties": {},
-                      "additionalProperties": {
-                        "$id": "/schemas/any",
-                        "title": "any"
-                      }
-                    }
+                "required": [
+                  "type",
+                  "cron"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "timer"
                   },
-                  "additionalProperties": false
-                }
+                  "cron": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  }
+                },
+                "additionalProperties": false
               },
-              "options": {
+              {
                 "type": "object",
-                "required": [],
+                "required": [
+                  "type",
+                  "method"
+                ],
                 "properties": {
-                  "deep": {
-                    "type": "boolean",
-                    "description": "a boolean",
-                    "title": "boolean"
+                  "type": {
+                    "const": "webhook"
                   },
-                  "delay": {
+                  "method": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  },
+                  "port": {
                     "type": "number",
                     "description": "a number",
                     "title": "number"
                   }
                 },
                 "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "url"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "websocket"
+                  },
+                  "url": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  },
+                  "init": {
+                    "type": "object",
+                    "required": [],
+                    "properties": {},
+                    "additionalProperties": {
+                      "$id": "/schemas/any",
+                      "title": "any"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "filter"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "subscription"
+                  },
+                  "filter": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "type"
+                      ],
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "description": "a string",
+                          "title": "string"
+                        },
+                        "props": {
+                          "type": "object",
+                          "required": [],
+                          "properties": {},
+                          "additionalProperties": {
+                            "$id": "/schemas/any",
+                            "title": "any"
+                          }
+                        }
+                      },
+                      "additionalProperties": false
+                    }
+                  },
+                  "options": {
+                    "type": "object",
+                    "required": [],
+                    "properties": {
+                      "deep": {
+                        "type": "boolean",
+                        "description": "a boolean",
+                        "title": "boolean"
+                      },
+                      "delay": {
+                        "type": "number",
+                        "description": "a number",
+                        "title": "number"
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "additionalProperties": false
               }
-            },
-            "additionalProperties": false
+            ]
           }
         },
         "additionalProperties": false

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';
 
-// TODO(burdon): Context?
-// Lambda-like function definitions.
-// See: https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/#functions
-// https://www.npmjs.com/package/aws-lambda
+// 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
 
-// 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>;
 
-// TODO(burdon): Limit access to individual space?
+/**
+ * Function context.
+ */
 export interface FunctionContext {
+  // TODO(burdon): Limit access to individual space.
   client: Client;
+  // TODO(burdon): Replace with storage service abstraction.
   dataDir?: string;
 }
 
-// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
-// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
-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 FunctionSubscriptionEvent = {
-  space?: string; // TODO(burdon): Convert to PublicKey.
+export type RawSubscriptionData = {
+  spaceKey?: string;
   objects?: string[];
 };
 
-// TODO(burdon): ???
-export type FunctionSubscriptionEvent2 = {
+export type SubscriptionData = {
   space?: Space;
   objects?: EchoReactiveObject<any>[];
 };
@@ -54,22 +77,22 @@ export type FunctionSubscriptionEvent2 = {
  *
  * NOTE: Get space key from devtools or `dx space list --json`
  */
-export const subscriptionHandler = (
-  handler: FunctionHandler<FunctionSubscriptionEvent2>,
-): FunctionHandler<FunctionSubscriptionEvent> => {
-  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.space ? client.spaces.get(PublicKey.from(event.space)) : 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.space && !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

@@ -3,5 +3,7 @@
 //
 
 export * from './handler';
+export * from './registry';
 export * from './runtime';
+export * from './trigger';
 export * from './types';

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

@@ -0,0 +1,105 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { expect } from 'chai';
+
+import { Trigger } from '@dxos/async';
+import { type Client } from '@dxos/client';
+import { TestBuilder } from '@dxos/client/testing';
+import { Context } from '@dxos/context';
+import { Filter } from '@dxos/echo-db';
+import { create } from '@dxos/echo-schema';
+import { describe, test } from '@dxos/test';
+import { range } from '@dxos/util';
+
+import { FunctionRegistry } from './function-registry';
+import { createInitializedClients } from '../testing';
+import { FunctionDef, type FunctionManifest } from '../types';
+
+const testManifest: FunctionManifest = {
+  functions: [
+    {
+      uri: 'dxos.functions.test/hello',
+      route: '/hello',
+      handler: 'test',
+    },
+  ],
+};
+
+describe('function registry', () => {
+  let ctx: Context;
+  let testBuilder: TestBuilder;
+  beforeEach(async () => {
+    ctx = new Context();
+    testBuilder = new TestBuilder();
+  });
+  afterEach(async () => {
+    await ctx.dispose();
+    await testBuilder.destroy();
+  });
+
+  describe('register', () => {
+    test('creates new functions', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      await registry.register(space, testManifest);
+      const { objects: definitions } = await space.db.query(Filter.schema(FunctionDef)).run();
+      expect(definitions.length).to.eq(1);
+      expect(definitions[0].uri).to.eq(testManifest.functions?.[0]?.uri);
+    });
+
+    test('de-duplicates by function URI', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      const existing = space.db.add(create(FunctionDef, { ...testManifest.functions![0] }));
+      await registry.register(space, testManifest);
+      const { objects: definitions } = await space.db.query(Filter.schema(FunctionDef)).run();
+      expect(definitions.length).to.eq(1);
+      expect(definitions[0].uri).to.eq(existing.uri);
+    });
+  });
+
+  describe('onFunctionsRegistered', () => {
+    test('called with all registered when opened', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      const definitions = range(3, () => create(FunctionDef, { ...testManifest.functions![0] }));
+      definitions.forEach((def) => space.db.add(def));
+
+      const functionRegistered = new Trigger<FunctionDef[]>();
+      registry.onFunctionsRegistered.on((fn) => {
+        functionRegistered.wake(fn.newFunctions);
+      });
+      void registry.open(ctx);
+      const functions = await functionRegistered.wait();
+      const expected = definitions.map((def) => def.uri).sort();
+      expect(functions.map((fn) => fn.uri).sort()).to.deep.eq(expected);
+    });
+
+    test('called when a new functions is added', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+
+      const functionRegistered = new Trigger<FunctionDef>();
+      registry.onFunctionsRegistered.on((fn) => {
+        expect(fn.newFunctions.length).to.eq(1);
+        functionRegistered.wake(fn.newFunctions[0]);
+      });
+      await registry.open(ctx);
+      await registry.register(space, testManifest);
+      const registered = await functionRegistered.wait();
+      expect(registered.uri).to.eq(testManifest.functions![0].uri);
+    });
+  });
+
+  const createRegistry = (client: Client) => {
+    const registry = new FunctionRegistry(client);
+    ctx.onDispose(() => registry.close());
+    return registry;
+  };
+});

package/src/registry/function-registry.ts

@@ -0,0 +1,84 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Event } from '@dxos/async';
+import { type Client } from '@dxos/client';
+import { create, Filter, type Space } from '@dxos/client/echo';
+import { type Context, Resource } from '@dxos/context';
+import { PublicKey } from '@dxos/keys';
+import { ComplexMap } from '@dxos/util';
+
+import { FunctionDef, type FunctionManifest } from '../types';
+
+export type FunctionsRegisteredEvent = {
+  space: Space;
+  newFunctions: FunctionDef[];
+};
+
+export class FunctionRegistry extends Resource {
+  private readonly _functionBySpaceKey = new ComplexMap<PublicKey, FunctionDef[]>(PublicKey.hash);
+
+  public readonly onFunctionsRegistered = new Event<FunctionsRegisteredEvent>();
+
+  constructor(private readonly _client: Client) {
+    super();
+  }
+
+  public getFunctions(space: Space): FunctionDef[] {
+    return this._functionBySpaceKey.get(space.key) ?? [];
+  }
+
+  /**
+   * The method loads function definitions from the manifest into the space.
+   * We first load all the definitions from the space to deduplicate by functionId.
+   */
+  // TODO(burdon): This should not be space specific (they are static for the agent).
+  public async register(space: Space, manifest: FunctionManifest): Promise<void> {
+    if (!manifest.functions?.length) {
+      return;
+    }
+    if (!space.db.graph.runtimeSchemaRegistry.isSchemaRegistered(FunctionDef)) {
+      space.db.graph.runtimeSchemaRegistry.registerSchema(FunctionDef);
+    }
+
+    const { objects: existingDefinitions } = await space.db.query(Filter.schema(FunctionDef)).run();
+    const newDefinitions = getNewDefinitions(manifest.functions, existingDefinitions);
+    const reactiveObjects = newDefinitions.map((template) => create(FunctionDef, { ...template }));
+    reactiveObjects.forEach((obj) => space.db.add(obj));
+  }
+
+  protected override async _open(): Promise<void> {
+    const spaceListSubscription = this._client.spaces.subscribe(async (spaces) => {
+      for (const space of spaces) {
+        if (this._functionBySpaceKey.has(space.key)) {
+          continue;
+        }
+        const registered: FunctionDef[] = [];
+        this._functionBySpaceKey.set(space.key, registered);
+        await space.waitUntilReady();
+        if (this._ctx.disposed) {
+          break;
+        }
+
+        const functionsSubscription = space.db.query(Filter.schema(FunctionDef)).subscribe((definitions) => {
+          const newFunctions = getNewDefinitions(definitions.objects, registered);
+          if (newFunctions.length > 0) {
+            registered.push(...newFunctions);
+            this.onFunctionsRegistered.emit({ space, newFunctions });
+          }
+        });
+        this._ctx.onDispose(functionsSubscription);
+      }
+    });
+    this._ctx.onDispose(() => spaceListSubscription.unsubscribe());
+  }
+
+  protected override async _close(_: Context): Promise<void> {
+    this._functionBySpaceKey.clear();
+  }
+}
+
+const getNewDefinitions = <T extends { uri: string }>(candidateList: T[], existing: FunctionDef[]): T[] => {
+  return candidateList.filter((candidate) => existing.find((def) => def.uri === candidate.uri) == null);
+};

package/src/registry/index.ts

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

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

@@ -0,0 +1,60 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { expect } from 'chai';
+import path from 'path';
+
+import { 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 '../registry';
+import { createFunctionRuntime } from '../testing';
+import { type FunctionManifest } from '../types';
+
+describe('dev server', () => {
+  let client: Client;
+  let testBuilder: TestBuilder;
+  before(async () => {
+    testBuilder = new TestBuilder();
+    client = await createFunctionRuntime(testBuilder);
+    expect(client.services.services.FunctionRegistryService).to.exist;
+  });
+
+  after(async () => {
+    await testBuilder.destroy();
+  });
+
+  test('start/stop', async () => {
+    const manifest: FunctionManifest = {
+      functions: [
+        {
+          uri: 'example.com/function/test',
+          route: 'test',
+          handler: 'test',
+        },
+      ],
+    };
+
+    const registry = new FunctionRegistry(client);
+    const server = new DevServer(client, registry, {
+      baseDir: path.join(__dirname, '../testing'),
+    });
+    const space = await client.spaces.create();
+    await registry.register(space, manifest);
+    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);
+  });
+});