@dxos/functions 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/process/StorageService.ts

@@ -0,0 +1,99 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema from 'effect/Schema';
+
+export interface Service {
+  /** Read a value by key. Returns `None` if key does not exist. */
+  get<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+  ): Effect.Effect<Option.Option<Schema.Schema.Type<S>>, never, Schema.Schema.Context<S>>;
+
+  /** Write a value for the given key. */
+  set<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+    value: Schema.Schema.Type<S>,
+  ): Effect.Effect<void, never, Schema.Schema.Context<S>>;
+
+  /** Remove a key. */
+  delete(key: string): Effect.Effect<void>;
+
+  /** List all keys, optionally filtered by prefix. */
+  list(prefix?: string): Effect.Effect<readonly string[]>;
+
+  /** Remove all keys managed by this scoped store. */
+  clear(): Effect.Effect<void>;
+}
+
+/**
+ * Scoped key-value storage service for processes.
+ * Each process receives its own namespaced instance via the process manager.
+ * Construct a live implementation with `StorageService.layer` from `@dxos/functions-runtime`.
+ */
+export class StorageService extends Context.Tag('@dxos/functions/StorageService')<StorageService, Service>() {}
+
+export const get = Effect.serviceFunctionEffect(StorageService, (_) => _.get);
+export const set = Effect.serviceFunctionEffect(StorageService, (_) => _.set);
+export const deleteKey = Effect.serviceFunctionEffect(StorageService, (_) => _.delete);
+export const list = Effect.serviceFunctionEffect(StorageService, (_) => _.list);
+export const clear = Effect.serviceFunctionEffect(StorageService, (_) => _.clear);
+
+/**
+ * Typed key in a storage service.
+ */
+export interface Key<T> extends Pipeable.Pipeable {
+  readonly key: string;
+
+  get: Effect.Effect<Option.Option<T>, never, StorageService>;
+  set(value: T): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Create a typed key in a storage service.
+ */
+export const key = <S extends Schema.Schema<any, string, any>>(schema: S, key: string): Key<Schema.Schema.Type<S>> => {
+  return {
+    key,
+    get: get(schema, key),
+    set: (value: Schema.Schema.Type<S>) => set(schema, key, value),
+    delete: () => deleteKey(key),
+    pipe(...args: any) {
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  };
+};
+
+/**
+ * Typed key in a storage service with a default value.
+ */
+export interface KeyWithDefault<T, U> extends Pipeable.Pipeable {
+  readonly key: string;
+  get: Effect.Effect<T | U, never, StorageService>;
+  set(value: U): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Assign a default value to a key if it is not present.
+ */
+export const withDefault =
+  <T>(getDefault: () => NoInfer<T>) =>
+  (key: Key<T>): KeyWithDefault<T, T> => {
+    return {
+      key: key.key,
+      get: key.get.pipe(Effect.map(Option.getOrElse(() => getDefault()))),
+      set: (value) => key.set(value),
+      delete: () => key.delete(),
+      pipe(...args: any) {
+        return Pipeable.pipeArguments(this, arguments);
+      },
+    };
+  };

package/src/protocol/functions-ai-http-client.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Headers from '@effect/platform/Headers';
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientError from '@effect/platform/HttpClientError';
+import * as HttpClientResponse from '@effect/platform/HttpClientResponse';
+import * as Effect from 'effect/Effect';
+import * as FiberRef from 'effect/FiberRef';
+import * as Layer from 'effect/Layer';
+import * as Stream from 'effect/Stream';
+
+import { log } from '@dxos/log';
+import { type EdgeFunctionEnv, ErrorCodec } from '@dxos/protocols';
+/**
+ * Copy pasted from https://github.com/Effect-TS/effect/blob/main/packages/platform/src/internal/fetchHttpClient.ts
+ */
+export const requestInitTagKey = '@effect/platform/FetchHttpClient/FetchOptions';
+
+export class FunctionsAiHttpClient {
+  static make = (service: EdgeFunctionEnv.FunctionsAiService) =>
+    HttpClient.make((request, url, signal, fiber) => {
+      const context = fiber.getFiberRef(FiberRef.currentContext);
+      const options: RequestInit = context.unsafeMap.get(requestInitTagKey) ?? {};
+      const headers = options.headers
+        ? Headers.merge(Headers.fromInput(options.headers), request.headers)
+        : request.headers;
+
+      const send = (body: BodyInit | undefined) =>
+        Effect.tryPromise({
+          try: () =>
+            service.fetch(
+              new Request(url, {
+                ...options,
+                method: request.method,
+                headers,
+                body,
+                // Note: Don't pass signal - it can't be serialized through RPC
+              }),
+            ),
+          catch: (cause) => {
+            log.error('Failed to fetch', { errorSerialized: ErrorCodec.encode(cause as Error) });
+            return new HttpClientError.RequestError({
+              request,
+              reason: 'Transport',
+              cause,
+            });
+          },
+        }).pipe(Effect.map((response) => HttpClientResponse.fromWeb(request, response)));
+
+      switch (request.body._tag) {
+        case 'Raw':
+        case 'Uint8Array':
+          return send(request.body.body as any);
+        case 'FormData':
+          return send(request.body.formData);
+        case 'Stream':
+          return Stream.toReadableStreamEffect(request.body.stream).pipe(Effect.flatMap(send));
+      }
+
+      return send(undefined);
+    });
+
+  static layer = (service: EdgeFunctionEnv.FunctionsAiService) =>
+    Layer.succeed(HttpClient.HttpClient, FunctionsAiHttpClient.make(service));
+}

package/src/{executor → protocol}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './executor';
+export * from './protocol';

package/src/protocol/protocol.test.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { FunctionError } from '../errors';
+import fibFunc from '../example/fib';
+import replyFunc from '../example/reply';
+import { wrapFunctionHandler } from './protocol';
+
+describe('wrapFunctionHandler', () => {
+  test('wraps reply function and executes handler', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(replyFunc);
+
+    expect(wrapped.meta.key).toBe('example.org/function/reply');
+    expect(wrapped.meta.name).toBe('Reply');
+
+    const testData = { message: 'hello' };
+    const result = await wrapped.handler({
+      data: testData,
+      context: {
+        services: {},
+      },
+    });
+
+    expect(result).toEqual(testData);
+  });
+
+  test('wraps fibonacci function with valid input', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(fibFunc);
+
+    expect(wrapped.meta.key).toBe('example.org/function/fib');
+    expect(wrapped.meta.name).toBe('Fibonacci');
+
+    const result = await wrapped.handler({
+      data: { iterations: 10 },
+      context: {
+        services: {},
+      },
+    });
+
+    expect(result).toEqual({ result: '55' });
+  });
+
+  test('throws FunctionError on invalid input schema for fibonacci', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(fibFunc);
+
+    await expect(
+      wrapped.handler({
+        data: { iterations: 'invalid' },
+        context: {
+          services: {},
+        },
+      }),
+    ).rejects.toThrow(FunctionError);
+  });
+});

package/src/protocol/protocol.ts

@@ -0,0 +1,273 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as AnthropicClient from '@effect/ai-anthropic/AnthropicClient';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { AiModelResolver, AiService } from '@dxos/ai';
+import { AnthropicResolver } from '@dxos/ai/resolvers';
+import { LifecycleState, Resource } from '@dxos/context';
+import { Database, Feed, JsonSchema, Ref, type Type } from '@dxos/echo';
+import { EchoClient, type EchoDatabaseImpl, type QueueFactory, createFeedServiceLayer } from '@dxos/echo-db';
+import { refFromEncodedReference } from '@dxos/echo/internal';
+import { runAndForwardErrors } from '@dxos/effect';
+import { assertState, failedInvariant, invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { Operation } from '@dxos/operation';
+import { type FunctionProtocol } from '@dxos/protocols';
+
+import { FunctionError } from '../errors';
+import { type FunctionServices } from '../sdk';
+import { CredentialsService, FunctionInvocationService, QueueService } from '../services';
+import * as Trace from '../Trace';
+import { FunctionsAiHttpClient } from './functions-ai-http-client';
+
+/**
+ * Wraps a function handler made with `defineFunction` to a protocol that the functions-runtime expects.
+ */
+export const wrapFunctionHandler = (func: Operation.WithHandler<Operation.Definition.Any>): FunctionProtocol.Func => {
+  if (!Operation.isOperationWithHandler(func)) {
+    throw new TypeError('Expected operation with handler');
+  }
+
+  const serviceTags = func.services.map((service) => service.key);
+
+  return {
+    meta: {
+      key: func.meta.key,
+      name: func.meta.name,
+      description: func.meta.description,
+      inputSchema: JsonSchema.toJsonSchema(func.input),
+      outputSchema: func.output === undefined ? undefined : JsonSchema.toJsonSchema(func.output),
+      services: func.services.map((service) => service.key),
+    },
+    handler: async ({ data, context }) => {
+      if (
+        (serviceTags.includes(Database.Service.key) ||
+          serviceTags.includes(QueueService.key) ||
+          serviceTags.includes(Feed.FeedService.key)) &&
+        (!context.services.dataService || !context.services.queryService)
+      ) {
+        throw new FunctionError({
+          message: 'Services not provided: dataService, queryService',
+        });
+      }
+
+      // eslint-disable-next-line no-useless-catch
+      try {
+        if (!SchemaAST.isAnyKeyword(func.input.ast)) {
+          try {
+            Schema.validateSync(func.input)(data);
+          } catch (error) {
+            throw new FunctionError({ message: 'Invalid input schema', cause: error });
+          }
+        }
+
+        await using funcContext = await new FunctionContext(context).open();
+
+        if (func.types.length > 0) {
+          invariant(funcContext.db, 'Database is required for functions with types');
+          await funcContext.db.graph.schemaRegistry.register(func.types as Type.AnyEntity[]);
+        }
+
+        const dataWithDecodedRefs =
+          funcContext.db && !SchemaAST.isAnyKeyword(func.input.ast)
+            ? decodeRefsFromSchema(func.input.ast, data, funcContext.db)
+            : data;
+
+        let result: any = await func.handler(dataWithDecodedRefs);
+
+        if (Effect.isEffect(result)) {
+          result = await runAndForwardErrors(
+            (result as Effect.Effect<unknown, unknown, FunctionServices>).pipe(
+              Effect.orDie,
+              Effect.provide(funcContext.createLayer()),
+            ),
+          );
+        }
+
+        if (func.output && !SchemaAST.isAnyKeyword(func.output.ast)) {
+          Schema.validateSync(func.output)(result);
+        }
+
+        return result;
+      } catch (error) {
+        // TODO(dmaretskyi): We might do error wrapping here and add extra context.
+        throw error;
+      }
+    },
+  };
+};
+
+/**
+ * Container for services and context for a function.
+ */
+class FunctionContext extends Resource {
+  readonly context: FunctionProtocol.Context;
+  readonly client: EchoClient | undefined;
+  db: EchoDatabaseImpl | undefined;
+  queues: QueueFactory | undefined;
+
+  constructor(context: FunctionProtocol.Context) {
+    super();
+    this.context = context;
+    if (context.services.dataService && context.services.queryService) {
+      this.client = new EchoClient().connectToService({
+        dataService: context.services.dataService,
+        queryService: context.services.queryService,
+        queueService: context.services.queueService,
+      });
+    }
+  }
+
+  override async _open() {
+    await this.client?.open();
+    this.db =
+      this.client && this.context.spaceId
+        ? this.client.constructDatabase({
+            spaceId: this.context.spaceId ?? failedInvariant(),
+            spaceKey: PublicKey.fromHex(this.context.spaceKey ?? failedInvariant('spaceKey missing in context')),
+            reactiveSchemaQuery: false,
+            preloadSchemaOnOpen: false,
+          })
+        : undefined;
+
+    await this.db?.setSpaceRoot(this.context.spaceRootUrl ?? failedInvariant('spaceRootUrl missing in context'));
+    await this.db?.open();
+    this.queues =
+      this.client && this.context.spaceId ? this.client.constructQueueFactory(this.context.spaceId) : undefined;
+  }
+
+  override async _close() {
+    await this.db?.close();
+    await this.client?.close();
+  }
+
+  createLayer(): Layer.Layer<FunctionServices> {
+    assertState(this._lifecycleState === LifecycleState.OPEN, 'FunctionContext is not open');
+
+    const dbLayer = this.db ? Database.layer(this.db) : Database.notAvailable;
+    const queuesLayer = this.queues ? QueueService.layer(this.queues) : QueueService.notAvailable;
+    const feedLayer = this.queues ? createFeedServiceLayer(this.queues) : Feed.notAvailable;
+    const credentials = dbLayer
+      ? CredentialsService.layerFromDatabase({ caching: true }).pipe(Layer.provide(dbLayer))
+      : CredentialsService.configuredLayer([]);
+    const functionInvocationService = MockedFunctionInvocationService;
+    const operationServiceLayer = MockedOperationServiceLayer;
+
+    const aiLayer = this.context.services.functionsAiService
+      ? AiModelResolver.AiModelResolver.buildAiService.pipe(
+          Layer.provide(
+            AnthropicResolver.make().pipe(
+              Layer.provide(
+                AnthropicClient.layer({
+                  // Note: It doesn't matter what is base url here, it will be proxied to ai gateway in edge.
+                  apiUrl: 'http://internal/provider/anthropic',
+                }).pipe(Layer.provide(FunctionsAiHttpClient.layer(this.context.services.functionsAiService))),
+              ),
+            ),
+          ),
+        )
+      : AiService.notAvailable;
+
+    return Layer.mergeAll(
+      dbLayer,
+      queuesLayer,
+      feedLayer,
+      credentials,
+      functionInvocationService,
+      operationServiceLayer,
+      aiLayer,
+      // TODO(dmaretskyi): Forward trace events.
+      Trace.writerLayerNoop,
+    );
+  }
+}
+
+const MockedFunctionInvocationService = Layer.succeed(FunctionInvocationService, {
+  invokeFunction: () => Effect.die('Calling functions from functions is not implemented yet.'),
+  resolveFunction: () => Effect.die('Not implemented.'),
+});
+
+const MockedOperationServiceLayer = Layer.succeed(Operation.Service, {
+  invoke: () => Effect.die('Calling operations from functions is not implemented yet.'),
+  schedule: () => Effect.die('Not implemented.'),
+  invokePromise: async () => ({ error: new Error('Not implemented') }),
+} as any);
+
+const decodeRefsFromSchema = (ast: SchemaAST.AST, value: unknown, db: EchoDatabaseImpl): unknown => {
+  if (value == null) {
+    return value;
+  }
+
+  const encoded = SchemaAST.encodedBoundAST(ast);
+  if (Ref.isRefType(encoded)) {
+    if (Ref.isRef(value)) {
+      return value;
+    }
+
+    if (typeof value === 'object' && value !== null && typeof (value as any)['/'] === 'string') {
+      const resolver = db.graph.createRefResolver({ context: { space: db.spaceId } });
+      return refFromEncodedReference(value as any, resolver);
+    }
+
+    return value;
+  }
+
+  switch (encoded._tag) {
+    case 'TypeLiteral': {
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value;
+      }
+      const result: Record<string, unknown> = { ...(value as any) };
+      for (const prop of SchemaAST.getPropertySignatures(encoded)) {
+        const key = prop.name.toString();
+        if (key in result) {
+          result[key] = decodeRefsFromSchema(prop.type, (result as any)[key], db);
+        }
+      }
+      return result;
+    }
+
+    case 'TupleType': {
+      if (!Array.isArray(value)) {
+        return value;
+      }
+
+      // For arrays, effect uses TupleType with empty elements and a single rest element.
+      if (encoded.elements.length === 0 && encoded.rest.length === 1) {
+        const elementType = encoded.rest[0].type;
+        return (value as unknown[]).map((item) => decodeRefsFromSchema(elementType, item, db));
+      }
+
+      return value;
+    }
+
+    case 'Union': {
+      // Optional values are represented as union with undefined.
+      const nonUndefined = encoded.types.filter((t) => !SchemaAST.isUndefinedKeyword(t));
+      if (nonUndefined.length === 1) {
+        return decodeRefsFromSchema(nonUndefined[0], value, db);
+      }
+
+      // For other unions we can't safely pick a branch without validating.
+      return value;
+    }
+
+    case 'Suspend': {
+      return decodeRefsFromSchema(encoded.f(), value, db);
+    }
+
+    case 'Refinement': {
+      return decodeRefsFromSchema(encoded.from, value, db);
+    }
+
+    default: {
+      return value;
+    }
+  }
+};

package/src/sdk.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type AiService } from '@dxos/ai';
+import { type Database, type Feed } from '@dxos/echo';
+import { type Trace } from '@dxos/functions';
+import type { Operation } from '@dxos/operation';
+
+import { type CredentialsService, type FunctionInvocationService, type QueueService } from './services';
+
+// 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
+
+/**
+ * Services that are available to invoked functions.
+ * @deprecated
+ */
+export type FunctionServices =
+  | AiService.AiService
+  | CredentialsService
+  | Database.Service
+  // TODO(wittjosiah): Remove QueueService — use Feed.FeedService instead.
+  | QueueService
+  | Feed.FeedService
+  | Trace.TraceService
+  | FunctionInvocationService
+  | Operation.Service;

package/src/services/credentials.ts

@@ -2,9 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import type * as Config from 'effect/Config';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
 
-type CredentialQuery = {
+import { Query } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { AccessToken } from '@dxos/types';
+
+export type CredentialQuery = {
   service?: string;
 };
 
@@ -17,7 +27,7 @@ export type ServiceCredential = {
   apiKey?: string;
 };
 
-export class CredentialsService extends Context.Tag('CredentialsService')<
+export class CredentialsService extends Context.Tag('@dxos/functions/CredentialsService')<
   CredentialsService,
   {
     /**
@@ -31,7 +41,91 @@ export class CredentialsService extends Context.Tag('CredentialsService')<
      */
     getCredential: (query: CredentialQuery) => Promise<ServiceCredential>;
   }
->() {}
+>() {
+  static getCredential = (query: CredentialQuery): Effect.Effect<ServiceCredential, never, CredentialsService> =>
+    Effect.gen(function* () {
+      const credentials = yield* CredentialsService;
+      return yield* Effect.promise(() => credentials.getCredential(query));
+    });
+
+  static getApiKey = (query: CredentialQuery): Effect.Effect<Redacted.Redacted<string>, never, CredentialsService> =>
+    Effect.gen(function* () {
+      const credential = yield* CredentialsService.getCredential(query);
+      if (!credential.apiKey) {
+        throw new Error(`API key not found for service: ${query.service}`);
+      }
+      return Redacted.make(credential.apiKey);
+    });
+
+  static configuredLayer = (credentials: ServiceCredential[]) =>
+    Layer.succeed(CredentialsService, new ConfiguredCredentialsService(credentials));
+
+  static layerConfig = (
+    credentials: {
+      service: string;
+      apiKey: Config.Config<Redacted.Redacted<string>>;
+    }[],
+  ) =>
+    Layer.effect(
+      CredentialsService,
+      Effect.gen(function* () {
+        const serviceCredentials = yield* Effect.forEach(credentials, ({ service, apiKey }) =>
+          Effect.gen(function* () {
+            return {
+              service,
+              apiKey: Redacted.value(yield* apiKey),
+            };
+          }),
+        );
+
+        return new ConfiguredCredentialsService(serviceCredentials);
+      }),
+    );
+
+  static layerFromDatabase = ({ caching = false }: { caching?: boolean } = {}) =>
+    Layer.effect(
+      CredentialsService,
+      Effect.gen(function* () {
+        const dbService = yield* Database.Service;
+        const cache = new Map<string, ServiceCredential[]>();
+
+        const queryCredentials = async (query: CredentialQuery): Promise<ServiceCredential[]> => {
+          const cacheKey = JSON.stringify(query);
+          if (caching && cache.has(cacheKey)) {
+            return cache.get(cacheKey)!;
+          }
+
+          const accessTokens = await dbService.db.query(Query.type(AccessToken.AccessToken)).run();
+          const credentials = accessTokens
+            .filter((accessToken) => accessToken.source === query.service)
+            .map((accessToken) => ({
+              service: accessToken.source,
+              apiKey: accessToken.token,
+            }));
+
+          if (caching) {
+            cache.set(cacheKey, credentials);
+          }
+
+          return credentials;
+        };
+
+        return {
+          getCredential: async (query) => {
+            const credentials = await queryCredentials(query);
+            if (credentials.length === 0) {
+              throw new Error(`Credential not found for service: ${query.service}`);
+            }
+
+            return credentials[0];
+          },
+          queryCredentials: async (query) => {
+            return queryCredentials(query);
+          },
+        };
+      }),
+    );
+}
 
 export class ConfiguredCredentialsService implements Context.Tag.Service<CredentialsService> {
   constructor(private readonly credentials: ServiceCredential[] = []) {}
@@ -50,6 +144,16 @@ export class ConfiguredCredentialsService implements Context.Tag.Service<Credent
     if (!credential) {
       throw new Error(`Credential not found for service: ${query.service}`);
     }
+
     return credential;
   }
 }
+
+/**
+ * Maps the request to include the given token in the Authorization header.
+ */
+export const withAuthorization = (token: string, kind?: 'Bearer' | 'Basic') =>
+  HttpClient.mapRequest((request) => {
+    const authorization = kind ? `${kind} ${token}` : token;
+    return HttpClientRequest.setHeader(request, 'Authorization', authorization);
+  });