@dxos/functions 0.8.2-main.12df754 → 0.8.2-main.30e4dbb

package/src/handler.ts

@@ -2,18 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema as S } from 'effect';
+import { Schema } from 'effect';
 import { type Effect } from 'effect';
 
 import { type AIServiceClient } from '@dxos/assistant';
-import { type Client, PublicKey } from '@dxos/client';
-import { type Space } from '@dxos/client/echo';
-import type { CoreDatabase, EchoDatabase, ReactiveEchoObject } from '@dxos/echo-db';
+// import { type Space } from '@dxos/client/echo';
+import type { CoreDatabase, EchoDatabase } from '@dxos/echo-db';
 import { type HasId } from '@dxos/echo-schema';
 import { type SpaceId, type DXN } from '@dxos/keys';
-import { log } from '@dxos/log';
 import { type QueryResult } from '@dxos/protocols';
-import { isNonNullable } from '@dxos/util';
 
 // TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
 // https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
@@ -23,13 +20,18 @@ import { isNonNullable } from '@dxos/util';
 /**
  * Function handler.
  */
-export type FunctionHandler<TData = {}, TMeta = {}, TOutput = any> = (params: {
+export type FunctionHandler<TData = {}, TOutput = any> = (params: {
+  /**
+   * Services and context available to the function.
+   */
   context: FunctionContext;
-  event: FunctionEvent<TData, TMeta>;
+
   /**
-   * @deprecated
+   * Data passed as the input to the function.
+   * Must match the function's input schema.
+   * This will be the payload from the trigger or other data passed into the function in a workflow.
    */
-  response: FunctionResponse;
+  data: TData;
 }) => TOutput | Promise<TOutput> | Effect.Effect<TOutput, any>;
 
 /**
@@ -44,17 +46,6 @@ export interface FunctionContext {
   space: SpaceAPI | undefined;
 
   ai: AIServiceClient;
-
-  /**
-   * @deprecated
-   */
-  // TODO(burdon): Limit access to individual space.
-  client: Client;
-  /**
-   * @deprecated
-   */
-  // TODO(burdon): Replace with storage service abstraction.
-  dataDir?: string;
 }
 
 export interface FunctionContextAi {
@@ -62,28 +53,6 @@ export interface FunctionContextAi {
   run(model: string, inputs: any, options?: any): Promise<any>;
 }
 
-/**
- * Event payload.
- */
-// TODO(dmaretskyi): Update type definitions to match the actual payload.
-export type FunctionEvent<TData = {}, TMeta = {}> = {
-  data: FunctionEventMeta<TMeta> & TData;
-};
-
-/**
- * Metadata from trigger.
- */
-export type FunctionEventMeta<TMeta = {}> = {
-  meta: TMeta;
-};
-
-/**
- * Function response.
- */
-export type FunctionResponse = {
-  status(code: number): FunctionResponse;
-};
-
 //
 // API.
 //
@@ -109,28 +78,21 @@ export interface SpaceAPI {
   get queues(): QueuesAPI;
 }
 
-// TODO(wittjosiah): Fix this.
+// TODO(wittjosiah): Queues are incompatible.
 const __assertFunctionSpaceIsCompatibleWithTheClientSpace = () => {
   // const _: SpaceAPI = {} as Space;
 };
 
-export type FunctionDefinition = {
-  description?: string;
-  inputSchema: S.Schema.AnyNoContext;
-  outputSchema?: S.Schema.AnyNoContext;
-  handler: FunctionHandler<any>;
-};
-
-export type DefineFunctionParams<T, O = any> = {
+export type FunctionDefinition<T = {}, O = any> = {
   description?: string;
-  inputSchema: S.Schema<T, any>;
-  outputSchema?: S.Schema<O, any>;
-  handler: FunctionHandler<T, any, O>;
+  inputSchema: Schema.Schema<T, any>;
+  outputSchema?: Schema.Schema<O, any>;
+  handler: FunctionHandler<T, O>;
 };
 
 // TODO(dmaretskyi): Bind input type to function handler.
-export const defineFunction = <T, O>(params: DefineFunctionParams<T, O>): FunctionDefinition => {
-  if (!S.isSchema(params.inputSchema)) {
+export const defineFunction = <T, O>(params: FunctionDefinition<T, O>): FunctionDefinition<T, O> => {
+  if (!Schema.isSchema(params.inputSchema)) {
     throw new Error('Input schema must be a valid schema');
   }
   if (typeof params.handler !== 'function') {
@@ -140,71 +102,7 @@ export const defineFunction = <T, O>(params: DefineFunctionParams<T, O>): Functi
   return {
     description: params.description,
     inputSchema: params.inputSchema,
-    outputSchema: params.outputSchema ?? S.Any,
+    outputSchema: params.outputSchema ?? Schema.Any,
     handler: params.handler,
   };
 };
-
-//
-// Subscription utils.
-//
-
-export type RawSubscriptionData = {
-  spaceKey?: string;
-  objects?: string[];
-};
-
-export type SubscriptionData = {
-  space?: Space;
-  objects?: ReactiveEchoObject<any>[];
-};
-
-/**
- * Handler wrapper for subscription events; extracts space and objects.
- *
- * To test:
- * ```
- * curl -s -X POST -H "Content-Type: application/json" --data '{"space": "0446...1cbb"}' http://localhost:7100/dev/email-extractor
- * ```
- *
- * NOTE: Get space key from devtools or `dx space list --json`
- */
-// TODO(burdon): Evolve into plugin definition like Composer.
-export const subscriptionHandler = <TMeta>(
-  handler: FunctionHandler<SubscriptionData, TMeta>,
-  types?: S.Schema.AnyNoContext[],
-): FunctionHandler<RawSubscriptionData, TMeta> => {
-  return async ({ event: { data }, context, response, ...rest }) => {
-    const { client } = context;
-    const space = data.spaceKey ? client.spaces.get(PublicKey.from(data.spaceKey)) : undefined;
-    if (!space) {
-      log.error('Invalid space');
-      return response.status(500);
-    }
-
-    registerTypes(space, types);
-    const objects = space
-      ? data.objects
-          ?.map<ReactiveEchoObject<any> | undefined>((id) => space!.db.getObjectById(id))
-          .filter(isNonNullable)
-      : [];
-
-    if (!!data.spaceKey && !space) {
-      log.warn('invalid space', { data });
-    } else {
-      log.info('handler', { space: space?.key.truncate(), objects: objects?.length });
-    }
-
-    return handler({ event: { data: { ...data, space, objects } }, context, response, ...rest });
-  };
-};
-
-// TODO(burdon): Evolve types as part of function metadata.
-const registerTypes = (space: Space, types: S.Schema.AnyNoContext[] = []) => {
-  const registry = space.db.graph.schemaRegistry;
-  for (const type of types) {
-    if (!registry.hasSchema(type)) {
-      registry.addSchema([type]);
-    }
-  }
-};

package/src/index.ts

@@ -1,10 +1,9 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2024 DXOS.org
 //
 
-export * from './edge';
-export * from './function';
 export * from './handler';
-// export * from './runtime';
-export * from './trigger';
+export * from './schema';
+export * from './trace';
 export * from './types';
+export * from './url';

package/src/schema.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { EchoObject, JsonSchemaType, LabelAnnotationId, Ref, TypedObject } from '@dxos/echo-schema';
+import { DataType } from '@dxos/schema';
+
+/**
+ * Source script.
+ */
+export const ScriptType = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String),
+  // TODO(burdon): Change to hash of deployed content.
+  // Whether source has changed since last deploy.
+  changed: Schema.optional(Schema.Boolean),
+  source: Ref(DataType.Text),
+})
+  .annotations({ [LabelAnnotationId]: 'name' })
+  .pipe(
+    EchoObject({
+      typename: 'dxos.org/type/Script',
+      version: '0.1.0',
+    }),
+  );
+
+export type ScriptType = Schema.Schema.Type<typeof ScriptType>;
+
+/**
+ * Function deployment.
+ */
+export class FunctionType extends TypedObject({
+  typename: 'dxos.org/type/Function',
+  version: '0.1.0',
+})({
+  // TODO(burdon): Rename to id/uri?
+  name: Schema.NonEmptyString,
+  version: Schema.String,
+
+  description: Schema.optional(Schema.String),
+
+  // Reference to a source script if it exists within ECHO.
+  // TODO(burdon): Don't ref ScriptType directly (core).
+  source: Schema.optional(Ref(ScriptType)),
+
+  inputSchema: Schema.optional(JsonSchemaType),
+  outputSchema: Schema.optional(JsonSchemaType),
+
+  // Local binding to a function name.
+  binding: Schema.optional(Schema.String),
+}) {}

package/src/{types/trace.ts → trace.ts}

@@ -2,7 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { EchoObject, Expando, ObjectId, Ref, S } from '@dxos/echo-schema';
+import { Schema } from 'effect';
+
+import { EchoObject, Expando, ObjectId, Ref } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 
 import { FunctionTrigger, type FunctionTriggerType } from './types';
@@ -19,20 +21,20 @@ export enum InvocationTraceEventType {
   END = 'end',
 }
 
-export const TraceEventException = S.Struct({
-  timestampMs: S.Number,
-  message: S.String,
-  name: S.String,
-  stack: S.optional(S.String),
+export const TraceEventException = Schema.Struct({
+  timestampMs: Schema.Number,
+  message: Schema.String,
+  name: Schema.String,
+  stack: Schema.optional(Schema.String),
 });
-export type TraceEventException = S.Schema.Type<typeof TraceEventException>;
+export type TraceEventException = Schema.Schema.Type<typeof TraceEventException>;
 
-export const InvocationTraceStartEvent = S.Struct({
+export const InvocationTraceStartEvent = Schema.Struct({
   /**
    * Queue message id.
    */
   id: ObjectId,
-  type: S.Literal(InvocationTraceEventType.START),
+  type: Schema.Literal(InvocationTraceEventType.START),
   /**
    * Invocation id, the same for invocation start and end events.
    */
@@ -40,12 +42,12 @@ export const InvocationTraceStartEvent = S.Struct({
   /**
    * Event generation time.
    */
-  timestampMs: S.Number,
+  timestampMs: Schema.Number,
   /**
    * Data passed to function / workflow as an argument.
    */
   // TODO(burdon): Input schema?
-  input: S.Object,
+  input: Schema.Object,
   /**
    * Queue DXN for function/workflow invocation events.
    */
@@ -58,17 +60,17 @@ export const InvocationTraceStartEvent = S.Struct({
   /**
    * Present for automatic invocations.
    */
-  trigger: S.optional(Ref(FunctionTrigger)),
+  trigger: Schema.optional(Ref(FunctionTrigger)),
 }).pipe(EchoObject({ typename: 'dxos.org/type/InvocationTraceStart', version: '0.1.0' }));
 
-export type InvocationTraceStartEvent = S.Schema.Type<typeof InvocationTraceStartEvent>;
+export type InvocationTraceStartEvent = Schema.Schema.Type<typeof InvocationTraceStartEvent>;
 
-export const InvocationTraceEndEvent = S.Struct({
+export const InvocationTraceEndEvent = Schema.Struct({
   /**
    * Trace event id.
    */
   id: ObjectId,
-  type: S.Literal(InvocationTraceEventType.END),
+  type: Schema.Literal(InvocationTraceEventType.END),
   /**
    * Invocation id, will be the same for invocation start and end.
    */
@@ -77,36 +79,36 @@ export const InvocationTraceEndEvent = S.Struct({
    * Event generation time.
    */
   // TODO(burdon): Remove ms suffix.
-  timestampMs: S.Number,
-  outcome: S.Enums(InvocationOutcome),
-  exception: S.optional(TraceEventException),
+  timestampMs: Schema.Number,
+  outcome: Schema.Enums(InvocationOutcome),
+  exception: Schema.optional(TraceEventException),
 }).pipe(EchoObject({ typename: 'dxos.org/type/InvocationTraceEnd', version: '0.1.0' }));
 
-export type InvocationTraceEndEvent = S.Schema.Type<typeof InvocationTraceEndEvent>;
+export type InvocationTraceEndEvent = Schema.Schema.Type<typeof InvocationTraceEndEvent>;
 
 export type InvocationTraceEvent = InvocationTraceStartEvent | InvocationTraceEndEvent;
 
-export const TraceEventLog = S.Struct({
-  timestampMs: S.Number,
-  level: S.String,
-  message: S.String,
-  context: S.optional(S.Object),
+export const TraceEventLog = Schema.Struct({
+  timestampMs: Schema.Number,
+  level: Schema.String,
+  message: Schema.String,
+  context: Schema.optional(Schema.Object),
 });
 
-export const TraceEvent = S.Struct({
+export const TraceEvent = Schema.Struct({
   id: ObjectId,
   // TODO(burdon): Need enum/numeric result (not string).
-  outcome: S.String,
-  truncated: S.Boolean,
+  outcome: Schema.String,
+  truncated: Schema.Boolean,
   /**
    * Time when the event was persisted.
    */
-  ingestionTimestampMs: S.Number,
-  logs: S.Array(TraceEventLog),
-  exceptions: S.Array(TraceEventException),
+  ingestionTimestampMs: Schema.Number,
+  logs: Schema.Array(TraceEventLog),
+  exceptions: Schema.Array(TraceEventException),
 }).pipe(EchoObject({ typename: 'dxos.org/type/TraceEvent', version: '0.1.0' }));
 
-export type TraceEvent = S.Schema.Type<typeof TraceEvent>;
+export type TraceEvent = Schema.Schema.Type<typeof TraceEvent>;
 
 /**
  * Deprecated InvocationTrace event format.

package/src/translations.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { ScriptType } from './types';
+import { ScriptType } from './schema';
 
 export default [
   {

package/src/types.ts

@@ -0,0 +1,210 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema, SchemaAST } from 'effect';
+
+import { Expando, OptionsAnnotationId, TypedObject, DXN, Ref, RawObject } from '@dxos/echo-schema';
+
+import { FunctionType } from './schema';
+
+/**
+ * Type discriminator for TriggerType.
+ * Every spec has a type field of type TriggerKind that we can use to understand which type we're working with.
+ * https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions
+ */
+export enum TriggerKind {
+  Timer = 'timer',
+  Webhook = 'webhook',
+  Subscription = 'subscription',
+  Email = 'email',
+  Queue = 'queue',
+}
+
+const kindLiteralAnnotations = { [SchemaAST.TitleAnnotationId]: 'Kind' };
+
+/**
+ * Cron timer.
+ */
+const TimerTriggerSchema = Schema.Struct({
+  kind: Schema.Literal(TriggerKind.Timer).annotations(kindLiteralAnnotations),
+  cron: Schema.String.annotations({
+    [SchemaAST.TitleAnnotationId]: 'Cron',
+    [SchemaAST.ExamplesAnnotationId]: ['0 0 * * *'],
+  }),
+}).pipe(Schema.mutable);
+export type TimerTrigger = Schema.Schema.Type<typeof TimerTriggerSchema>;
+
+const EmailTriggerSchema = Schema.Struct({
+  kind: Schema.Literal(TriggerKind.Email).annotations(kindLiteralAnnotations),
+}).pipe(Schema.mutable);
+export type EmailTrigger = Schema.Schema.Type<typeof EmailTriggerSchema>;
+
+const QueueTriggerSchema = Schema.Struct({
+  kind: Schema.Literal(TriggerKind.Queue).annotations(kindLiteralAnnotations),
+  queue: DXN,
+}).pipe(Schema.mutable);
+export type QueueTrigger = Schema.Schema.Type<typeof QueueTriggerSchema>;
+
+/**
+ * Webhook.
+ */
+const WebhookTriggerSchema = Schema.Struct({
+  kind: Schema.Literal(TriggerKind.Webhook).annotations(kindLiteralAnnotations),
+  method: Schema.optional(
+    Schema.String.annotations({
+      [SchemaAST.TitleAnnotationId]: 'Method',
+      [OptionsAnnotationId]: ['GET', 'POST'],
+    }),
+  ),
+  port: Schema.optional(
+    Schema.Number.annotations({
+      [SchemaAST.TitleAnnotationId]: 'Port',
+    }),
+  ),
+}).pipe(Schema.mutable);
+export type WebhookTrigger = Schema.Schema.Type<typeof WebhookTriggerSchema>;
+
+// TODO(burdon): Use ECHO definition (from https://github.com/dxos/dxos/pull/8233).
+const QuerySchema = Schema.Struct({
+  type: Schema.optional(Schema.String.annotations({ [SchemaAST.TitleAnnotationId]: 'Type' })),
+  props: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+}).annotations({ [SchemaAST.TitleAnnotationId]: 'Query' });
+
+/**
+ * Subscription.
+ */
+const SubscriptionTriggerSchema = Schema.Struct({
+  kind: Schema.Literal(TriggerKind.Subscription).annotations(kindLiteralAnnotations),
+  // TODO(burdon): Define query DSL (from ECHO). Reconcile with Table.Query.
+  filter: QuerySchema,
+  options: Schema.optional(
+    Schema.Struct({
+      // Watch changes to object (not just creation).
+      deep: Schema.optional(Schema.Boolean.annotations({ [SchemaAST.TitleAnnotationId]: 'Nested' })),
+      // Debounce changes (delay in ms).
+      delay: Schema.optional(Schema.Number.annotations({ [SchemaAST.TitleAnnotationId]: 'Delay' })),
+    }).annotations({ [SchemaAST.TitleAnnotationId]: 'Options' }),
+  ),
+}).pipe(Schema.mutable);
+export type SubscriptionTrigger = Schema.Schema.Type<typeof SubscriptionTriggerSchema>;
+
+/**
+ * Trigger schema (discriminated union).
+ */
+export const TriggerSchema = Schema.Union(
+  TimerTriggerSchema,
+  WebhookTriggerSchema,
+  SubscriptionTriggerSchema,
+  EmailTriggerSchema,
+  QueueTriggerSchema,
+).annotations({
+  [SchemaAST.TitleAnnotationId]: 'Trigger',
+});
+export type TriggerType = Schema.Schema.Type<typeof TriggerSchema>;
+
+export type EventType =
+  | EmailTriggerOutput
+  | WebhookTriggerOutput
+  | QueueTriggerOutput
+  | SubscriptionTriggerOutput
+  | TimerTriggerOutput;
+
+// TODO(burdon): Reuse trigger schema from @dxos/functions (TriggerType).
+export const EmailTriggerOutput = Schema.mutable(
+  Schema.Struct({
+    from: Schema.String,
+    to: Schema.String,
+    subject: Schema.String,
+    created: Schema.String,
+    body: Schema.String,
+  }),
+);
+export type EmailTriggerOutput = Schema.Schema.Type<typeof EmailTriggerOutput>;
+
+export const WebhookTriggerOutput = Schema.mutable(
+  Schema.Struct({
+    url: Schema.String,
+    method: Schema.Literal('GET', 'POST'),
+    headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+    bodyText: Schema.String,
+  }),
+);
+export type WebhookTriggerOutput = Schema.Schema.Type<typeof WebhookTriggerOutput>;
+
+export const QueueTriggerOutput = Schema.mutable(
+  Schema.Struct({
+    queue: DXN,
+    item: Schema.Any,
+    cursor: Schema.String,
+  }),
+);
+export type QueueTriggerOutput = Schema.Schema.Type<typeof QueueTriggerOutput>;
+
+export const SubscriptionTriggerOutput = Schema.mutable(
+  Schema.Struct({ type: Schema.String, changedObjectId: Schema.String }),
+);
+export type SubscriptionTriggerOutput = Schema.Schema.Type<typeof SubscriptionTriggerOutput>;
+
+export const TimerTriggerOutput = Schema.mutable(Schema.Struct({ tick: Schema.Number }));
+export type TimerTriggerOutput = Schema.Schema.Type<typeof TimerTriggerOutput>;
+
+/**
+ * Function trigger.
+ * Function is invoked with the `payload` passed as input data.
+ * The event that triggers the function is available in the function context.
+ */
+export const FunctionTriggerSchema = Schema.Struct({
+  /**
+   * Function or workflow to invoke.
+   */
+  // TODO(dmaretskyi): Can be a Ref(FunctionType) or Ref(ComputeGraphType).
+  function: Schema.optional(Ref(Expando).annotations({ [SchemaAST.TitleAnnotationId]: 'Function' })),
+
+  /**
+   * Only used for workflowSchema.
+   * Specifies the input node in the circuit.
+   * @deprecated Remove and enforce a single input node in all compute graphSchema.
+   */
+  inputNodeId: Schema.optional(Schema.String.annotations({ [SchemaAST.TitleAnnotationId]: 'Input Node ID' })),
+
+  enabled: Schema.optional(Schema.Boolean.annotations({ [SchemaAST.TitleAnnotationId]: 'Enabled' })),
+
+  spec: Schema.optional(TriggerSchema),
+
+  /**
+   * Passed as the input data to the function.
+   * Must match the function's input schema.
+   *
+   * @example
+   * {
+   *   item: '{{$.trigger.event}}',
+   *   instructions: 'Summarize and perform entity-extraction'
+   *   mailbox: { '/': 'dxn:echo:AAA:ZZZ' }
+   * }
+   */
+  input: Schema.optional(Schema.mutable(Schema.Record({ key: Schema.String, value: Schema.Any }))),
+});
+
+export type FunctionTriggerType = Schema.Schema.Type<typeof FunctionTriggerSchema>;
+
+/**
+ * Function trigger.
+ */
+export class FunctionTrigger extends TypedObject({
+  typename: 'dxos.org/type/FunctionTrigger',
+  version: '0.2.0',
+})(FunctionTriggerSchema.fields) {}
+
+// TODO(wittjosiah): Remove?
+
+/**
+ * Function manifest file.
+ */
+export const FunctionManifestSchema = Schema.Struct({
+  functions: Schema.optional(Schema.mutable(Schema.Array(RawObject(FunctionType)))),
+  triggers: Schema.optional(Schema.mutable(Schema.Array(RawObject(FunctionTrigger)))),
+});
+export type FunctionManifest = Schema.Schema.Type<typeof FunctionManifestSchema>;
+
+export const FUNCTION_TYPES = [FunctionType, FunctionTrigger];

package/src/{types/url.ts → url.ts}

@@ -32,7 +32,7 @@ export const setUserFunctionUrlInMetadata = (meta: ObjectMeta, functionUrl: stri
 /**
  * NOTE: functionId is backend ID, not ECHO object id.
  */
-export const makeFunctionUrl = (spaceId: SpaceId, fn: { functionId: string }) => `/${spaceId}/${fn.functionId}`;
+export const makeFunctionUrl = (fn: { functionId: string }) => `/${fn.functionId}`;
 
 export const getInvocationUrl = (functionUrl: string, edgeUrl: string, options: InvocationOptions = {}) => {
   const baseUrl = new URL('functions/', edgeUrl);