@dxos/functions 0.5.2 → 0.5.3-main.088a2c8

package/dist/types/src/types.d.ts

@@ -0,0 +1,182 @@
+import * as S from '@effect/schema/Schema';
+declare const TimerTriggerSchema: S.struct<{
+    cron: S.$string;
+}>;
+declare const WebhookTriggerSchema: S.mutable<S.struct<{
+    method: S.$string;
+    port: S.PropertySignature<"?:", number | undefined, never, "?:", number | undefined, never>;
+}>>;
+declare const WebsocketTriggerSchema: S.struct<{
+    url: S.$string;
+    init: S.PropertySignature<"?:", {
+        readonly [x: string]: any;
+    } | undefined, never, "?:", {
+        readonly [x: string]: any;
+    } | undefined, never>;
+}>;
+declare const SubscriptionTriggerSchema: S.struct<{
+    spaceKey: S.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>;
+    filter: S.array<S.struct<{
+        type: S.$string;
+        props: S.PropertySignature<"?:", {
+            readonly [x: string]: any;
+        } | undefined, never, "?:", {
+            readonly [x: string]: any;
+        } | undefined, never>;
+    }>>;
+    options: S.PropertySignature<"?:", {
+        readonly deep?: boolean | undefined;
+        readonly delay?: number | undefined;
+    } | undefined, never, "?:", {
+        readonly deep?: boolean | undefined;
+        readonly delay?: number | undefined;
+    } | undefined, never>;
+}>;
+declare const FunctionTriggerSchema: S.struct<{
+    function: S.$string;
+    meta: S.PropertySignature<"?:", {
+        readonly [x: string]: any;
+    } | undefined, never, "?:", {
+        readonly [x: string]: any;
+    } | undefined, never>;
+    timer: S.PropertySignature<"?:", {
+        readonly cron: string;
+    } | undefined, never, "?:", {
+        readonly cron: string;
+    } | undefined, never>;
+    webhook: S.PropertySignature<"?:", {
+        port?: number | undefined;
+        method: string;
+    } | undefined, never, "?:", {
+        method: string;
+        port?: number | undefined;
+    } | undefined, never>;
+    websocket: S.PropertySignature<"?:", {
+        readonly url: string;
+        readonly init?: {
+            readonly [x: string]: any;
+        } | undefined;
+    } | undefined, never, "?:", {
+        readonly url: string;
+        readonly init?: {
+            readonly [x: string]: any;
+        } | undefined;
+    } | undefined, never>;
+    subscription: S.PropertySignature<"?:", {
+        readonly filter: readonly {
+            readonly type: string;
+            readonly props?: {
+                readonly [x: string]: any;
+            } | undefined;
+        }[];
+        readonly spaceKey?: string | undefined;
+        readonly options?: {
+            readonly deep?: boolean | undefined;
+            readonly delay?: number | undefined;
+        } | undefined;
+    } | undefined, never, "?:", {
+        readonly filter: readonly {
+            readonly type: string;
+            readonly props?: {
+                readonly [x: string]: any;
+            } | undefined;
+        }[];
+        readonly spaceKey?: string | undefined;
+        readonly options?: {
+            readonly deep?: boolean | undefined;
+            readonly delay?: number | undefined;
+        } | undefined;
+    } | undefined, never>;
+}>;
+export type FunctionTrigger = S.Schema.Type<typeof FunctionTriggerSchema>;
+export type TimerTrigger = S.Schema.Type<typeof TimerTriggerSchema>;
+export type WebhookTrigger = S.Schema.Type<typeof WebhookTriggerSchema>;
+export type WebsocketTrigger = S.Schema.Type<typeof WebsocketTriggerSchema>;
+export type SubscriptionTrigger = S.Schema.Type<typeof SubscriptionTriggerSchema>;
+/**
+ * Function definition.
+ */
+declare const FunctionDefSchema: S.struct<{
+    id: S.$string;
+    description: S.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>;
+    path: S.$string;
+    handler: S.$string;
+}>;
+export type FunctionDef = S.Schema.Type<typeof FunctionDefSchema>;
+/**
+ * Function manifest file.
+ */
+export declare const FunctionManifestSchema: S.struct<{
+    functions: S.mutable<S.array<S.struct<{
+        id: S.$string;
+        description: S.PropertySignature<"?:", string | undefined, never, "?:", string | undefined, never>;
+        path: S.$string;
+        handler: S.$string;
+    }>>>;
+    triggers: S.PropertySignature<"?:", {
+        readonly function: string;
+        readonly meta?: {
+            readonly [x: string]: any;
+        } | undefined;
+        readonly timer?: {
+            readonly cron: string;
+        } | undefined;
+        readonly webhook?: {
+            port?: number | undefined;
+            method: string;
+        } | undefined;
+        readonly websocket?: {
+            readonly url: string;
+            readonly init?: {
+                readonly [x: string]: any;
+            } | undefined;
+        } | undefined;
+        readonly subscription?: {
+            readonly filter: readonly {
+                readonly type: string;
+                readonly props?: {
+                    readonly [x: string]: any;
+                } | undefined;
+            }[];
+            readonly spaceKey?: string | undefined;
+            readonly options?: {
+                readonly deep?: boolean | undefined;
+                readonly delay?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }[] | undefined, never, "?:", {
+        readonly function: string;
+        readonly meta?: {
+            readonly [x: string]: any;
+        } | undefined;
+        readonly timer?: {
+            readonly cron: string;
+        } | undefined;
+        readonly webhook?: {
+            method: string;
+            port?: number | undefined;
+        } | undefined;
+        readonly websocket?: {
+            readonly url: string;
+            readonly init?: {
+                readonly [x: string]: any;
+            } | undefined;
+        } | undefined;
+        readonly subscription?: {
+            readonly filter: readonly {
+                readonly type: string;
+                readonly props?: {
+                    readonly [x: string]: any;
+                } | undefined;
+            }[];
+            readonly spaceKey?: string | undefined;
+            readonly options?: {
+                readonly deep?: boolean | undefined;
+                readonly delay?: number | undefined;
+            } | undefined;
+        } | undefined;
+    }[] | undefined, never>;
+}>;
+export type FunctionManifest = S.Schema.Type<typeof FunctionManifestSchema>;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,CAAC,MAAM,uBAAuB,CAAC;AAE3C,QAAA,MAAM,kBAAkB;;EAEtB,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;GAMzB,CAAC;AAEF,QAAA,MAAM,sBAAsB;;;;;;;EAG1B,CAAC;AAEH,QAAA,MAAM,yBAAyB;;;;;;;;;;;;;;;;;EAiB7B,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWzB,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,kBAAkB,CAAC,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAC5E,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAElF;;GAEG;AAEH,QAAA,MAAM,iBAAiB;;;;;EAQrB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/types/tools/schema.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/types/tools/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../tools/schema.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/functions",
-  "version": "0.5.2",
+  "version": "0.5.3-main.088a2c8",
   "description": "Functions SDK and runtime.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,27 +16,36 @@
   "types": "dist/types/src/index.d.ts",
   "files": [
     "dist",
+    "schema",
     "src"
   ],
   "dependencies": {
+    "@effect/schema": "^0.64.20",
     "@preact/signals-core": "^1.6.0",
     "cron": "^3.1.6",
+    "effect": "^2.4.19",
     "express": "^4.19.2",
     "get-port-please": "^3.1.1",
-    "@braneframe/types": "0.5.2",
-    "@dxos/async": "0.5.2",
-    "@dxos/client": "0.5.2",
-    "@dxos/context": "0.5.2",
-    "@dxos/echo-schema": "0.5.2",
-    "@dxos/invariant": "0.5.2",
-    "@dxos/log": "0.5.2",
-    "@dxos/node-std": "0.5.2",
-    "@dxos/util": "0.5.2"
+    "ws": "^8.14.2",
+    "@braneframe/types": "0.5.3-main.088a2c8",
+    "@dxos/async": "0.5.3-main.088a2c8",
+    "@dxos/context": "0.5.3-main.088a2c8",
+    "@dxos/echo-schema": "0.5.3-main.088a2c8",
+    "@dxos/invariant": "0.5.3-main.088a2c8",
+    "@dxos/client": "0.5.3-main.088a2c8",
+    "@dxos/node-std": "0.5.3-main.088a2c8",
+    "@dxos/log": "0.5.3-main.088a2c8",
+    "@dxos/util": "0.5.3-main.088a2c8"
   },
   "devDependencies": {
-    "@types/express": "^4.17.17"
+    "@types/express": "^4.17.17",
+    "@types/ws": "^7.4.0",
+    "@dxos/agent": "0.5.3-main.088a2c8"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "gen-schema": "ts-node ./tools/schema.ts"
   }
 }

package/schema/functions.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "functions"
+  ],
+  "properties": {
+    "functions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "path",
+          "handler"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "path": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "handler": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "description": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "function"
+        ],
+        "properties": {
+          "function": {
+            "type": "string",
+            "description": "Function ID/URI.",
+            "title": "string"
+          },
+          "meta": {
+            "type": "object",
+            "required": [],
+            "properties": {},
+            "additionalProperties": {
+              "$id": "/schemas/any",
+              "title": "any"
+            }
+          },
+          "timer": {
+            "type": "object",
+            "required": [
+              "cron"
+            ],
+            "properties": {
+              "cron": {
+                "type": "string",
+                "description": "a string",
+                "title": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "webhook": {
+            "type": "object",
+            "required": [
+              "method"
+            ],
+            "properties": {
+              "method": {
+                "type": "string",
+                "description": "a string",
+                "title": "string"
+              },
+              "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": [],
+                "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"
+                      }
+                    }
+                  },
+                  "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,31 +8,61 @@ import { type EchoReactiveObject } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 import { nonNullable } from '@dxos/util';
 
-// TODO(burdon): No response?
-export interface Response {
-  status(code: number): Response;
-}
+// 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
+
+/**
+ * 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[];
 };
 
-export type FunctionSubscriptionEvent2 = {
+export type SubscriptionData = {
   space?: Space;
   objects?: EchoReactiveObject<any>[];
 };
@@ -47,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,5 @@
 //
 
 export * from './handler';
-export * from './manifest';
 export * from './runtime';
+export * from './types';

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

@@ -0,0 +1,80 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { expect } from 'chai';
+import path from 'path';
+
+import { FunctionsPlugin } from '@dxos/agent';
+import { Client, Config } from '@dxos/client';
+import { TestBuilder } from '@dxos/client/testing';
+import { describe, openAndClose, test } from '@dxos/test';
+
+import { DevServer } from './dev-server';
+import { type FunctionManifest } from '../types';
+
+describe('dev server', () => {
+  let client: Client;
+  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);
+
+    expect(client.services.services.FunctionRegistryService).to.exist;
+  });
+  after(async () => {
+    await testBuilder.destroy();
+  });
+
+  test('start/stop', async () => {
+    const manifest: FunctionManifest = {
+      functions: [
+        {
+          id: 'example.com/function/test',
+          path: 'test',
+          handler: 'test',
+        },
+      ],
+    };
+
+    const server = new DevServer(client, {
+      manifest,
+      baseDir: path.join(__dirname, '../testing'),
+    });
+    await server.initialize();
+    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 server.invoke('test', {});
+    expect(server.stats.seq).to.eq(1);
+  });
+});