@dxos/functions 0.5.3-main.2ad0afc → 0.5.3-main.3456876

package/schema/functions.json

@@ -1,24 +1,26 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
-  "required": [],
+  "required": [
+    "functions"
+  ],
   "properties": {
     "functions": {
       "type": "array",
       "items": {
         "type": "object",
         "required": [
-          "uri",
-          "route",
+          "id",
+          "path",
           "handler"
         ],
         "properties": {
-          "uri": {
+          "id": {
             "type": "string",
             "description": "a string",
             "title": "string"
           },
-          "route": {
+          "path": {
             "type": "string",
             "description": "a string",
             "title": "string"
@@ -42,165 +44,135 @@
       "items": {
         "type": "object",
         "required": [
-          "function",
-          "spec"
+          "function"
         ],
         "properties": {
           "function": {
             "type": "string",
-            "description": "Function URI.",
+            "description": "Function ID/URI.",
             "title": "string"
           },
-          "meta": {
-            "$ref": "#/$defs/object"
+          "context": {
+            "type": "object",
+            "required": [],
+            "properties": {},
+            "additionalProperties": {
+              "$id": "/schemas/any",
+              "title": "any"
+            }
           },
-          "spec": {
-            "anyOf": [
-              {
+          "timer": {
+            "type": "object",
+            "required": [
+              "cron"
+            ],
+            "properties": {
+              "cron": {
+                "type": "string",
+                "description": "a string",
+                "title": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "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": {
                 "type": "object",
-                "required": [
-                  "type",
-                  "cron"
-                ],
-                "properties": {
-                  "type": {
-                    "const": "timer"
+                "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"
+                      }
+                    }
                   },
-                  "cron": {
-                    "type": "string",
-                    "description": "a string",
-                    "title": "string"
-                  }
-                },
-                "additionalProperties": false
+                  "additionalProperties": false
+                }
               },
-              {
+              "options": {
                 "type": "object",
-                "required": [
-                  "type",
-                  "method"
-                ],
+                "required": [],
                 "properties": {
-                  "type": {
-                    "const": "webhook"
-                  },
-                  "method": {
-                    "type": "string",
-                    "description": "a string",
-                    "title": "string"
+                  "deep": {
+                    "type": "boolean",
+                    "description": "a boolean",
+                    "title": "boolean"
                   },
-                  "port": {
+                  "delay": {
                     "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
       }
     }
   },
-  "additionalProperties": false,
-  "$defs": {
-    "object": {
-      "$id": "/schemas/object",
-      "oneOf": [
-        {
-          "type": "object"
-        },
-        {
-          "type": "array"
-        }
-      ],
-      "description": "an object in the TypeScript meaning, i.e. the `object` type",
-      "title": "object"
-    }
-  }
+  "additionalProperties": false
 }

package/src/handler.ts

@@ -8,61 +8,38 @@ import { type EchoReactiveObject } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 import { nonNullable } from '@dxos/util';
 
-// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
-// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
+// Lambda-like function definitions.
 // 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
 
-/**
- * Function handler.
- */
-export type FunctionHandler<TData = {}, TMeta = {}> = (params: {
-  context: FunctionContext;
-  event: FunctionEvent<TData, TMeta>;
-  response: FunctionResponse;
-}) => Promise<FunctionResponse | void>;
+// TODO(burdon): No response?
+export interface Response {
+  status(code: number): Response;
+}
 
-/**
- * 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;
 }
 
-/**
- * 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.
-//
+// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
+export type FunctionHandler<T extends {}> = (params: {
+  event: T;
+  context: FunctionContext;
+  response: Response;
+}) => Promise<Response | void>;
 
-export type RawSubscriptionData = {
+export type RawSubscriptionEvent = {
   spaceKey?: string;
   objects?: string[];
 };
 
-export type SubscriptionData = {
+export type SubscriptionEvent = {
   space?: Space;
   objects?: EchoReactiveObject<any>[];
 };
@@ -77,22 +54,22 @@ export type SubscriptionData = {
  *
  * NOTE: Get space key from devtools or `dx space list --json`
  */
-export const subscriptionHandler = <TMeta>(
-  handler: FunctionHandler<SubscriptionData, TMeta>,
-): FunctionHandler<RawSubscriptionData, TMeta> => {
-  return ({ event: { data }, context, ...rest }) => {
+export const subscriptionHandler = (
+  handler: FunctionHandler<SubscriptionEvent>,
+): FunctionHandler<RawSubscriptionEvent> => {
+  return ({ event, context, ...rest }) => {
     const { client } = context;
-    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)
-      : [];
+    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);
 
-    if (!!data.spaceKey && !space) {
-      log.warn('invalid space', { data });
+    if (!!event.spaceKey && !space) {
+      log.warn('invalid space', { event });
     } else {
       log.info('handler', { space: space?.key.truncate(), objects: objects?.length });
     }
 
-    return handler({ event: { data: { ...data, space, objects } }, context, ...rest });
+    return handler({ event: { space, objects }, context, ...rest });
   };
 };

package/src/index.ts

@@ -2,8 +2,6 @@
 // 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,14 +5,12 @@
 import { expect } from 'chai';
 import path from 'path';
 
-import { waitForCondition } from '@dxos/async';
-import { type Client } from '@dxos/client';
+import { FunctionsPlugin } from '@dxos/agent';
+import { Client, Config } from '@dxos/client';
 import { TestBuilder } from '@dxos/client/testing';
-import { describe, test } from '@dxos/test';
+import { describe, openAndClose, 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', () => {
@@ -20,10 +18,35 @@ describe('dev server', () => {
   let testBuilder: TestBuilder;
   before(async () => {
     testBuilder = new TestBuilder();
-    client = await createFunctionRuntime(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);
+
     expect(client.services.services.FunctionRegistryService).to.exist;
   });
-
   after(async () => {
     await testBuilder.destroy();
   });
@@ -32,19 +55,18 @@ describe('dev server', () => {
     const manifest: FunctionManifest = {
       functions: [
         {
-          uri: 'example.com/function/test',
-          route: 'test',
+          id: 'example.com/function/test',
+          path: 'test',
           handler: 'test',
         },
       ],
     };
 
-    const registry = new FunctionRegistry(client);
-    const server = new DevServer(client, registry, {
+    const server = new DevServer(client, {
+      manifest,
       baseDir: path.join(__dirname, '../testing'),
     });
-    const space = await client.spaces.create();
-    await registry.register(space, manifest.functions);
+    await server.initialize();
     await server.start();
 
     // TODO(burdon): Doesn't shut down cleanly.
@@ -52,8 +74,6 @@ 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,15 +9,14 @@ 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 FunctionRegistry } from '../function';
-import { type FunctionContext, type FunctionEvent, type FunctionHandler, type FunctionResponse } from '../handler';
-import { type FunctionDef } from '../types';
+import { type FunctionContext, type FunctionHandler, type Response } from '../handler';
+import { type FunctionDef, type FunctionManifest } from '../types';
 
 export type DevServerOptions = {
+  manifest: FunctionManifest;
   baseDir: string;
   port?: number;
   reload?: boolean;
@@ -28,8 +27,6 @@ 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> }> = {};
 
@@ -41,17 +38,11 @@ export class DevServer {
 
   public readonly update = new Event<number>();
 
+  // prettier-ignore
   constructor(
     private readonly _client: Client,
-    private readonly _functionsRegistry: FunctionRegistry,
     private readonly _options: DevServerOptions,
-  ) {
-    this._functionsRegistry.registered.on(async ({ added }) => {
-      added.forEach((def) => this._load(def));
-      await this._safeUpdateRegistration();
-      log('new functions loaded', { added });
-    });
-  }
+  ) {}
 
   get stats() {
     return {
@@ -72,10 +63,19 @@ 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,14 +107,12 @@ 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).');
@@ -157,10 +155,10 @@ export class DevServer {
   /**
    * Load function.
    */
-  private async _load(def: FunctionDef, force?: boolean | undefined) {
-    const { uri, route, handler } = def;
+  private async _load(def: FunctionDef, force = false) {
+    const { id, path, handler } = def;
     const filePath = join(this._options.baseDir, handler);
-    log.info('loading', { uri, force });
+    log.info('loading', { id, force });
 
     // Remove from cache.
     if (force) {
@@ -171,26 +169,13 @@ 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: ${uri}`);
+      throw new Error(`Handler must export default function: ${id}`);
     }
 
-    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 (e) {
-      log.catch(e);
-    }
+    this._handlers[path] = { def, handler: module.default };
   }
 
   /**
@@ -201,14 +186,14 @@ 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: FunctionEvent) {
+  private async _invoke(path: string, event: any) {
     const { handler } = this._handlers[path] ?? {};
     invariant(handler, `invalid path: ${path}`);
 
@@ -218,7 +203,7 @@ export class DevServer {
     };
 
     let statusCode = 200;
-    const response: FunctionResponse = {
+    const response: Response = {
       status: (code: number) => {
         statusCode = code;
         return response;
@@ -229,5 +214,3 @@ export class DevServer {
     return statusCode;
   }
 }
-
-const createContext = () => new Context({ name: 'DevServer' });