@dxos/functions 0.8.1 → 0.8.2-main.10c050d

package/src/handler.ts

@@ -2,17 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema as S } from 'effect';
-import { type Effect } from 'effect';
+import { Schema, type Context, type Effect } from 'effect';
 
-import { type Client, PublicKey } from '@dxos/client';
-import { type Space, type SpaceId } from '@dxos/client/echo';
-import type { CoreDatabase, EchoDatabase, ReactiveEchoObject } from '@dxos/echo-db';
+import { type AIServiceClient } from '@dxos/ai';
+// import { type Space } from '@dxos/client/echo';
+import type { CoreDatabase, EchoDatabase } from '@dxos/echo-db';
 import { type HasId } from '@dxos/echo-schema';
-import { type DXN } from '@dxos/keys';
-import { log } from '@dxos/log';
+import { type SpaceId, type DXN } from '@dxos/keys';
 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
@@ -22,19 +19,30 @@ 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>;
 
 /**
  * Function context.
  */
 export interface FunctionContext {
+  /**
+   * Resolves a service available to the function.
+   * @throws if the service is not available.
+   */
+  getService: <T extends Context.Tag<any, any>>(tag: T) => Context.Tag.Service<T>;
+
   getSpace: (spaceId: SpaceId) => Promise<SpaceAPI>;
 
   /**
@@ -42,18 +50,7 @@ export interface FunctionContext {
    */
   space: SpaceAPI | undefined;
 
-  ai: FunctionContextAi;
-
-  /**
-   * @deprecated
-   */
-  // TODO(burdon): Limit access to individual space.
-  client: Client;
-  /**
-   * @deprecated
-   */
-  // TODO(burdon): Replace with storage service abstraction.
-  dataDir?: string;
+  ai: AIServiceClient;
 }
 
 export interface FunctionContextAi {
@@ -61,28 +58,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.
 //
@@ -108,28 +83,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 = {
+export type FunctionDefinition<T = {}, O = any> = {
   description?: string;
-  inputSchema: S.Schema.AnyNoContext;
-  outputSchema?: S.Schema.AnyNoContext;
-  handler: FunctionHandler<any>;
-};
-
-export type DefineFunctionParams<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') {
@@ -139,71 +107,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,13 @@
 //
-// 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';
+export * from './services';
+export * from './executor';
+
+// Blow up cache

package/src/schema.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { EchoObject, JsonSchemaType, LabelAnnotation, 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),
+}).pipe(
+  EchoObject({
+    typename: 'dxos.org/type/Script',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+);
+
+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/services/ai.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context } from 'effect';
+
+import type { AIServiceClient } from '@dxos/ai';
+
+// TODO(burdon): Move to @dxos/ai.
+export class AiService extends Context.Tag('AiService')<
+  AiService,
+  {
+    readonly client: AIServiceClient;
+  }
+>() {}

package/src/services/credentials.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context } from 'effect';
+
+type CredentialQuery = {
+  service?: string;
+};
+
+// TODO(dmaretskyi): Unify with other apis.
+// packages/sdk/schema/src/common/access-token.ts
+type ServiceCredential = {
+  service: string;
+
+  // TODO(dmaretskyi): Build out.
+  apiKey?: string;
+};
+
+export class CredentialsService extends Context.Tag('CredentialsService')<
+  CredentialsService,
+  {
+    /**
+     * Query all.
+     */
+    queryCredentials: (query: CredentialQuery) => Promise<ServiceCredential[]>;
+
+    /**
+     * Get a single credential.
+     * @throws {Error} If no credential is found.
+     */
+    getCredential: (query: CredentialQuery) => Promise<ServiceCredential>;
+  }
+>() {}
+
+export class ConfiguredCredentialsService implements Context.Tag.Service<CredentialsService> {
+  constructor(private readonly credentials: ServiceCredential[] = []) {}
+
+  addCredentials(credentials: ServiceCredential[]): ConfiguredCredentialsService {
+    this.credentials.push(...credentials);
+    return this;
+  }
+
+  async queryCredentials(query: CredentialQuery): Promise<ServiceCredential[]> {
+    return this.credentials.filter((credential) => credential.service === query.service);
+  }
+
+  async getCredential(query: CredentialQuery): Promise<ServiceCredential> {
+    const credential = this.credentials.find((credential) => credential.service === query.service);
+    if (!credential) {
+      throw new Error(`Credential not found for service: ${query.service}`);
+    }
+    return credential;
+  }
+}

package/src/services/database.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context } from 'effect';
+
+import type { EchoDatabase } from '@dxos/echo-db';
+
+export class DatabaseService extends Context.Tag('DatabaseService')<
+  DatabaseService,
+  {
+    readonly db: EchoDatabase;
+  }
+>() {}

package/src/services/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './ai';
+export * from './database';
+export * from './queues';
+export * from './service-container';
+export * from './credentials';
+export * from './tracing';

package/src/services/queues.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context } from 'effect';
+
+import type { Queue, QueueFactory } from '@dxos/echo-db';
+
+export class QueuesService extends Context.Tag('QueuesService')<
+  QueuesService,
+  {
+    readonly contextQueue: Queue | undefined;
+
+    readonly queues: QueueFactory;
+  }
+>() {}

package/src/services/service-container.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context } from 'effect';
+
+import { AiService } from './ai';
+import { CredentialsService } from './credentials';
+import { DatabaseService } from './database';
+import { QueuesService } from './queues';
+import { TracingService } from './tracing';
+
+export interface Services {
+  database: Context.Tag.Service<DatabaseService>;
+  ai: Context.Tag.Service<AiService>;
+  queues: Context.Tag.Service<QueuesService>;
+  credentials: Context.Tag.Service<CredentialsService>;
+  tracing: Context.Tag.Service<TracingService>;
+}
+
+const SERVICE_MAPPING: Record<string, keyof Services> = {
+  [DatabaseService.key]: 'database',
+  [AiService.key]: 'ai',
+  [QueuesService.key]: 'queues',
+  [CredentialsService.key]: 'credentials',
+  [TracingService.key]: 'tracing',
+};
+
+const DEFAULT_SERVICES: Partial<Services> = {
+  tracing: TracingService.noop,
+};
+
+export class ServiceContainer {
+  private _services: Partial<Services> = { ...DEFAULT_SERVICES };
+
+  /**
+   * Set services.
+   * @param services - Services to set.
+   * @returns The container instance.
+   */
+  setServices(services: Partial<Services>): this {
+    this._services = { ...this._services, ...services };
+    return this;
+  }
+
+  getService<T extends Context.Tag<any, any>>(tag: T): Context.Tag.Service<T> {
+    const serviceKey = SERVICE_MAPPING[tag.key];
+    const service = serviceKey != null ? this._services[serviceKey] : undefined;
+    if (!service) {
+      throw new Error(`Service not available: ${tag.key}`);
+    }
+    return service as Context.Tag.Service<T>;
+  }
+
+  clone(): ServiceContainer {
+    return new ServiceContainer().setServices({ ...this._services });
+  }
+}

package/src/services/tracing.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context } from 'effect';
+
+import type { AnyEchoObject } from '@dxos/echo-schema';
+
+export class TracingService extends Context.Tag('TracingService')<
+  TracingService,
+  {
+    /**
+     * Write an event to the tracing queue.
+     * @param event - The event to write. Must be an a typed object.
+     */
+    write(event: AnyEchoObject): void;
+  }
+>() {
+  static noop: Context.Tag.Service<TracingService> = { write: () => {} };
+
+  static console: Context.Tag.Service<TracingService> = {
+    write: (event) => {
+      // eslint-disable-next-line no-console
+      console.log(event);
+    },
+  };
+}

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

@@ -2,7 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { EchoObject, Expando, ObjectId, Ref, S } from '@dxos/echo-schema';
+import { Schema } from 'effect';
+
+import { Queue } from '@dxos/echo-db';
+import { EchoObject, Expando, ObjectId, Ref } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 
 import { FunctionTrigger, type FunctionTriggerType } from './types';
@@ -19,20 +22,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,17 +43,16 @@ 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.
+   * Queue  for function/workflow invocation events.
    */
-  // TODO(burdon): Need reference type for queue. vs. string?
-  invocationTraceQueue: Ref(Expando),
+  invocationTraceQueue: Ref(Queue),
   /**
    * DXN of the invoked function/workflow.
    */
@@ -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.
@@ -119,7 +121,7 @@ export type InvocationSpan = {
   outcome: InvocationOutcome;
   input: object;
   durationMs: number;
-  invocationTraceQueue: Ref<Expando>;
+  invocationTraceQueue: Ref<Queue>;
   invocationTarget: Ref<Expando>;
   trigger?: Ref<FunctionTriggerType>;
   exception?: TraceEventException;

package/src/translations.ts

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