@dxos/functions 0.5.3-main.37bbd91 → 0.5.3-main.3b535c7

package/schema/functions.json

@@ -1,24 +1,27 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
-  "required": [],
+  "required": [
+    "functions",
+    "triggers"
+  ],
   "properties": {
     "functions": {
       "type": "array",
       "items": {
         "type": "object",
         "required": [
-          "uri",
-          "route",
+          "id",
+          "name",
           "handler"
         ],
         "properties": {
-          "uri": {
+          "id": {
             "type": "string",
             "description": "a string",
             "title": "string"
           },
-          "route": {
+          "name": {
             "type": "string",
             "description": "a string",
             "title": "string"
@@ -42,165 +45,126 @@
       "items": {
         "type": "object",
         "required": [
-          "function",
-          "spec"
+          "function"
         ],
         "properties": {
           "function": {
             "type": "string",
-            "description": "Function URI.",
+            "description": "Function ID/URI.",
             "title": "string"
           },
-          "meta": {
-            "$ref": "#/$defs/object"
+          "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
           },
-          "spec": {
-            "anyOf": [
-              {
+          "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"
+                  "deep": {
+                    "type": "boolean",
+                    "description": "a boolean",
+                    "title": "boolean"
                   },
-                  "method": {
-                    "type": "string",
-                    "description": "a string",
-                    "title": "string"
-                  },
-                  "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
-// https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/#functions
+// 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
+// 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.
- */
+// TODO(burdon): Limit access to individual space?
 export interface FunctionContext {
-  // TODO(burdon): Limit access to individual space.
   client: Client;
-  // TODO(burdon): Replace with storage service abstraction.
   dataDir?: string;
 }
 
-/**
- * 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.
+// 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>;
 
-export type RawSubscriptionData = {
-  spaceKey?: string;
+export type FunctionSubscriptionEvent = {
+  space?: string; // TODO(burdon): Convert to PublicKey.
   objects?: string[];
 };
 
-export type SubscriptionData = {
+// TODO(burdon): ???
+export type FunctionSubscriptionEvent2 = {
   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<FunctionSubscriptionEvent2>,
+): FunctionHandler<FunctionSubscriptionEvent> => {
+  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.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);
 
-    if (!!data.spaceKey && !space) {
-      log.warn('invalid space', { data });
+    if (!!event.space && !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.ts

@@ -7,19 +7,18 @@ import { getPort } from 'get-port-please';
 import type http from 'http';
 import { join } from 'node:path';
 
-import { Event, Trigger } from '@dxos/async';
+import { 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 = {
-  baseDir: string;
   port?: number;
+  directory: string;
+  manifest: FunctionManifest;
   reload?: boolean;
   dataDir?: string;
 };
@@ -28,36 +27,20 @@ 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> }> = {};
 
   private _server?: http.Server;
   private _port?: number;
-  private _functionServiceRegistration?: string;
+  private _registrationId?: string;
   private _proxy?: string;
   private _seq = 0;
 
-  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 {
-      seq: this._seq,
-    };
-  }
+  ) {}
 
   get endpoint() {
     invariant(this._port);
@@ -72,26 +55,30 @@ export class DevServer {
     return Object.values(this._handlers);
   }
 
-  async start() {
-    invariant(!this._server);
-    log.info('starting...');
-    this._ctx = createContext();
+  async initialize() {
+    for (const def of this._options.manifest.functions) {
+      try {
+        await this._load(def);
+      } catch (err) {
+        log.error('parsing function (check manifest)', err);
+      }
+    }
+  }
 
-    // TODO(burdon): Move to hono.
+  async start() {
     const app = express();
     app.use(express.json());
 
-    app.post('/:path', async (req, res) => {
-      const { path } = req.params;
+    app.post('/:name', async (req, res) => {
+      const { name } = req.params;
       try {
-        log.info('calling', { path });
+        log.info('calling', { name });
         if (this._options.reload) {
-          const { def } = this._handlers['/' + path];
+          const { def } = this._handlers[name];
           await this._load(def, true);
         }
 
-        // TODO(burdon): Get function context.
-        res.statusCode = await this.invoke('/' + path, req.body);
+        res.statusCode = await this._invoke(name, req.body);
         res.end();
       } catch (err: any) {
         log.catch(err);
@@ -107,110 +94,72 @@ export class DevServer {
       // Register functions.
       const { registrationId, endpoint } = await this._client.services.services.FunctionRegistryService!.register({
         endpoint: this.endpoint,
+        functions: this.functions.map(({ def: { name } }) => ({ name })),
       });
 
-      log.info('registered', { endpoint });
+      log.info('registered', { registrationId, endpoint });
+      this._registrationId = registrationId;
       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).');
     }
-
-    log.info('started', { port: this._port });
   }
 
   async stop() {
-    invariant(this._server);
-    log.info('stopping...');
-
     const trigger = new Trigger();
-    this._server.close(async () => {
-      log.info('server stopped');
-      try {
-        if (this._functionServiceRegistration) {
-          invariant(this._client.services.services.FunctionRegistryService);
-          await this._client.services.services.FunctionRegistryService.unregister({
-            registrationId: this._functionServiceRegistration,
-          });
-
-          log.info('unregistered', { registrationId: this._functionServiceRegistration });
-          this._functionServiceRegistration = undefined;
-          this._proxy = undefined;
-        }
+    this._server?.close(async () => {
+      if (this._registrationId) {
+        await this._client.services.services.FunctionRegistryService!.unregister({
+          registrationId: this._registrationId,
+        });
 
-        trigger.wake();
-      } catch (err) {
-        trigger.throw(err as Error);
+        log.info('unregistered', { registrationId: this._registrationId });
+        this._registrationId = undefined;
+        this._proxy = undefined;
       }
+
+      trigger.wake();
     });
 
     await trigger.wait();
     this._port = undefined;
     this._server = undefined;
-    log.info('stopped');
   }
 
   /**
    * Load function.
    */
-  private async _load(def: FunctionDef, force?: boolean | undefined) {
-    const { uri, route, handler } = def;
-    const filePath = join(this._options.baseDir, handler);
-    log.info('loading', { uri, force });
+  private async _load(def: FunctionDef, flush = false) {
+    const { id, name, handler } = def;
+    const path = join(this._options.directory, handler);
+    log.info('loading', { id });
 
     // Remove from cache.
-    if (force) {
+    if (flush) {
       Object.keys(require.cache)
-        .filter((key) => key.startsWith(filePath))
-        .forEach((key) => {
-          delete require.cache[key];
-        });
+        .filter((key) => key.startsWith(path))
+        .forEach((key) => delete require.cache[key]);
     }
 
-    // TODO(burdon): Import types.
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const module = require(filePath);
+    const module = require(path);
     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[name] = { def, handler: module.default };
   }
 
   /**
-   * Invoke function.
+   * Invoke function handler.
    */
-  public async invoke(path: string, data: any): Promise<number> {
+  private async _invoke(name: string, event: any) {
     const seq = ++this._seq;
     const now = Date.now();
 
-    log.info('req', { seq, path });
-    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) {
-    const { handler } = this._handlers[path] ?? {};
-    invariant(handler, `invalid path: ${path}`);
+    log.info('req', { seq, name });
+    const { handler } = this._handlers[name];
 
     const context: FunctionContext = {
       client: this._client,
@@ -218,7 +167,7 @@ export class DevServer {
     };
 
     let statusCode = 200;
-    const response: FunctionResponse = {
+    const response: Response = {
       status: (code: number) => {
         statusCode = code;
         return response;
@@ -226,8 +175,8 @@ export class DevServer {
     };
 
     await handler({ context, event, response });
+    log.info('res', { seq, name, statusCode, duration: Date.now() - now });
+
     return statusCode;
   }
 }
-
-const createContext = () => new Context({ name: 'DevServer' });