@dxos/protocols 0.8.4-main.72ec0f3 → 0.8.4-main.7ace549

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/protocols",
-  "version": "0.8.4-main.72ec0f3",
+  "version": "0.8.4-main.7ace549",
   "description": "Protobuf definitions for DXOS protocols.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -60,19 +60,19 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "2.9.0",
-    "@dxos/codec-protobuf": "0.8.4-main.72ec0f3",
-    "@dxos/effect": "0.8.4-main.72ec0f3",
-    "@dxos/errors": "0.8.4-main.72ec0f3",
-    "@dxos/invariant": "0.8.4-main.72ec0f3",
-    "@dxos/keys": "0.8.4-main.72ec0f3",
-    "@dxos/util": "0.8.4-main.72ec0f3",
-    "@dxos/timeframe": "0.8.4-main.72ec0f3"
+    "@dxos/codec-protobuf": "0.8.4-main.7ace549",
+    "@dxos/effect": "0.8.4-main.7ace549",
+    "@dxos/errors": "0.8.4-main.7ace549",
+    "@dxos/invariant": "0.8.4-main.7ace549",
+    "@dxos/keys": "0.8.4-main.7ace549",
+    "@dxos/timeframe": "0.8.4-main.7ace549",
+    "@dxos/util": "0.8.4-main.7ace549"
   },
   "devDependencies": {
     "@bufbuild/buf": "1.43.0",
     "@bufbuild/protoc-gen-es": "2.9.0",
     "effect": "3.18.3",
-    "@dxos/protobuf-compiler": "0.8.4-main.72ec0f3"
+    "@dxos/protobuf-compiler": "0.8.4-main.7ace549"
   },
   "peerDependencies": {
     "effect": "^3.13.3"

package/src/edge/EdgeFunctionEnv.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type SpaceId } from '@dxos/keys';
+
+import { type QueryResult, type QueueQuery } from '../queue';
+
+/*
+
+API for the edge functions service.
+A function module should be a valid cloudflare worker module.
+
+# Fetching metadata (done on deploy)
+
+GET http://functions.dxos.internal/
+X-DXOS-Function-Route: meta
+
+Expected to return `FunctionMetadata` in JSON:
+
+{
+  key: string;
+  name?: string;
+  description?: string;
+  inputSchema?: JsonSchemaType;
+  outputSchema?: JsonSchemaType;
+}
+
+# Invoking the function
+
+POST http://functions.dxos.internal/
+Content-Type: application/json
+X-Trace-Queue-Dxn: dxn:queue:trace:AAAAAA:BBBBBB
+X-Invocation-Id: XXXXXXX
+X-Edge-Env: production
+
+{input_data}
+
+Expected to return `EdgeEnvelope` with the output data:
+
+{
+  success: true,
+  data: unknown
+}
+
+On Error returns `EdgeEnvelope` with error:
+
+{
+  success: false,
+  message: string
+  error: EncodedError
+}
+
+*/
+
+/**
+ * Environment available to the function running on Cloudflare.
+ */
+export interface Env {
+  QUEUE_SERVICE: QueueService;
+  DATA_SERVICE: DataService;
+}
+
+/**
+ * Use to trace the execution across multiple services.
+ *
+ * NOTE: Currently unused in functions.
+ */
+export interface ExecutionContext {}
+
+/**
+ * Database API for other CF services like functions.
+ */
+export interface DataService {
+  getSpaceMeta(ctx: ExecutionContext, spaceId: SpaceId): Promise<SpaceMeta | undefined>;
+  getDocument(ctx: ExecutionContext, spaceId: SpaceId, documentId: string): Promise<RawDocument | undefined>;
+
+  query(ctx: ExecutionContext, request: QueryRequest): Promise<QueryResponse>;
+  queryDocuments(ctx: ExecutionContext, request: QueryRequest): Promise<QueryDocumentsResponse>;
+  queryReferences(ctx: ExecutionContext, request: QueryReferencesRequest): Promise<QueryReferencesResponse>;
+
+  // TODO(burdon): Update? Return DocumentEntry?
+  changeDocument(ctx: ExecutionContext, spaceId: SpaceId, documentId: string, changes: Uint8Array): Promise<void>;
+}
+
+export interface QueueService {
+  query(ctx: ExecutionContext, queueDXN: string, query: Omit<QueueQuery, 'queueId'>): Promise<QueryResult>;
+  append(ctx: ExecutionContext, queueDXN: string, objects: unknown[]): Promise<void>;
+}
+
+export type ObjectDocumentJson = {
+  type?: string;
+  objectId: string;
+  documentId: string;
+  /** Base64 encoding of a document. */
+  document: string;
+};
+
+export type SpaceMeta = {
+  spaceKey: string;
+  rootDocumentId: string;
+};
+
+export type QueryRequest = {
+  spaceId: string;
+  type?: string;
+  where?: Record<string, any>;
+  objectIds?: string[];
+  cursor?: string;
+  limit?: number;
+};
+
+export type QueryResponse = {
+  results: ObjectSnapshot[];
+  cursor?: string;
+};
+
+/**
+ * TODO(yaroslav): make Indexer return EchoObject after create() can properly reconstruct an object
+ *   from this structure (meta, id and type aren't handled properly)
+ */
+export type ObjectSnapshot = {
+  type?: string;
+  documentId: string;
+  objectId: string;
+  // TODO(mykola): Use ObjectStructure from @dxos/echo-protocol.
+  object: unknown;
+};
+
+export type ObjectReference = {
+  fromId: string;
+  toId: string;
+  fieldName: string;
+};
+
+export type QueryDocumentsResponse = {
+  results: RawObject[];
+  cursor?: string;
+};
+
+export type RawDocument = {
+  documentId: string;
+  data: Uint8Array;
+};
+
+export type RawObject = {
+  type?: string;
+  objectId: string;
+  document: RawDocument;
+};
+
+export type QueryReferencesRequest = {
+  spaceId: string;
+  objectId: string;
+  referenceType: 'from' | 'to';
+};
+
+export type QueryReferencesResponse = {
+  references: ObjectReference[];
+};
+
+export type CreateDocumentResponse = {
+  /** Automerge document ID. */
+  documentId: string;
+};

package/src/{edge.ts → edge/edge.ts}

@@ -40,8 +40,8 @@ export type EdgeErrorData = { type: string } & Record<string, any>;
 // TODO(dmaretskyi): Refactor this type to just be { success: false, error: SerializedError }
 // reason -> error.message
 // cause -> error.cause
-// errorData.type -> error.code
-// ...errorData -> error.context
+// data.type -> error.code
+// ...data -> error.context
 export type EdgeFailure = {
   /**
    * Branded Type.
@@ -50,11 +50,11 @@ export type EdgeFailure = {
   /**
    * An explanation of why the call failed. Used mostly for logging and monitoring.
    */
-  reason: string;
+  message: string;
   /**
    * Cause Error captured on the EDGE service to aid debugging on the client.
    */
-  cause?: SerializedError;
+  error?: SerializedError;
   /**
    * Information that can be used to retry the request such that it will succeed, for example:
    * 1. { type: 'auth_required', challenge: string }
@@ -62,16 +62,16 @@ export type EdgeFailure = {
    * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
    *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
    *    if the user confirms.
-   * When errorData is returned simply retrying the request won't have any effect.
-   * EdgeHttpClient should parse well-known errorData into Error types and throw.
+   * When data is returned simply retrying the request won't have any effect.
+   * EdgeHttpClient should parse well-known data into Error types and throw.
    */
-  errorData?: EdgeErrorData;
+  data?: EdgeErrorData;
 };
 
 /**
  * Represents a body response from the Edge service.
  */
-export type EdgeBody<T> = EdgeSuccess<T> | EdgeFailure;
+export type EdgeEnvelope<T> = EdgeSuccess<T> | EdgeFailure;
 
 /**
  * Use this to create a response from the Edge service.
@@ -92,21 +92,32 @@ export const EdgeResponse = Object.freeze({
     );
   },
   failure: ({
-    reason,
-    cause,
-    errorData,
+    message,
+    error,
+    errorEncoded,
+    data,
     shouldRetryAfter,
     status = 500,
   }: {
     /**
      * An explanation of why the call failed. Used mostly for logging and monitoring.
      */
-    reason: string;
+    message: string;
     /**
      * Error that caused the failure.
      * Useful for debugging.
+     *
+     * Use only one of the fields `error` or `errorEncoded`.s
+     */
+    error?: Error;
+    /**
+     * Encoded Error that caused the failure.
+     * Useful for debugging.
+     *
+     * Use only one of the fields `error` or `errorEncoded`.
      */
-    cause?: Error;
+    errorEncoded?: SerializedError;
+
     /**
      * Information that can be used to retry the request such that it will succeed, for example:
      * 1. { type: 'auth_required', challenge: string }
@@ -114,10 +125,10 @@ export const EdgeResponse = Object.freeze({
      * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
      *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
      *    if the user confirms.
-     * When errorData is returned simply retrying the request won't have any effect.
-     * EdgeHttpClient should parse well-known errorData into Error types and throw.
+     * When data is returned simply retrying the request won't have any effect.
+     * EdgeHttpClient should parse well-known data into Error types and throw.
      */
-    errorData?: EdgeErrorData;
+    data?: EdgeErrorData;
     /**
      * If provided, this request will be marked as retryable and the client will wait for the specified number of milliseconds before retrying.
      * If not provided, the client will not retry the request.
@@ -138,9 +149,9 @@ export const EdgeResponse = Object.freeze({
     return new Response(
       JSON.stringify({
         success: false,
-        reason,
-        errorData,
-        cause: cause ? ErrorCodec.encode(cause) : undefined,
+        message,
+        data,
+        error: error ? ErrorCodec.encode(error) : errorEncoded,
       } satisfies EdgeFailure),
       {
         status,

package/src/{edge-error.ts → edge/errors.ts}

@@ -16,11 +16,11 @@ import { type EdgeErrorData, type EdgeFailure, EdgeHttpErrorCodec, ErrorCodec }
 export class EdgeCallFailedError extends Error {
   public static fromUnsuccessfulResponse(response: Response, body: EdgeFailure): EdgeCallFailedError {
     const error = new EdgeCallFailedError({
-      reason: body.reason,
-      errorData: body.errorData,
-      isRetryable: body.errorData == null && response.headers.has('Retry-After'),
+      message: body.message,
+      data: body.data,
+      isRetryable: body.data == null && response.headers.has('Retry-After'),
       retryAfterMs: getRetryAfterMillis(response),
-      cause: body.cause ? ErrorCodec.decode(body.cause) : undefined,
+      cause: body.error ? ErrorCodec.decode(body.error) : undefined,
     });
 
     return error;
@@ -28,7 +28,7 @@ export class EdgeCallFailedError extends Error {
 
   public static async fromHttpFailure(response: Response): Promise<EdgeCallFailedError> {
     return new EdgeCallFailedError({
-      reason: `HTTP code ${response.status}: ${response.statusText}.`,
+      message: `HTTP code ${response.status}: ${response.statusText}.`,
       isRetryable: isRetryableCode(response.status),
       retryAfterMs: getRetryAfterMillis(response),
       cause: await EdgeHttpErrorCodec.decode(response),
@@ -37,27 +37,26 @@ export class EdgeCallFailedError extends Error {
 
   public static fromProcessingFailureCause(cause: Error): EdgeCallFailedError {
     return new EdgeCallFailedError({
-      reason: 'Error processing request.',
+      message: 'Error processing request.',
       isRetryable: true,
       cause,
     });
   }
 
-  readonly reason: string;
-  readonly errorData?: EdgeErrorData;
+  readonly data?: EdgeErrorData;
   readonly isRetryable?: boolean;
   readonly retryAfterMs?: number;
 
   constructor(args: {
-    reason: string;
+    message: string;
     isRetryable?: boolean;
-    errorData?: EdgeErrorData;
+    data?: EdgeErrorData;
     retryAfterMs?: number;
     cause?: Error;
   }) {
-    super(args.reason, { cause: args.cause });
-    this.reason = args.reason;
-    this.errorData = args.errorData;
+    super(args.message, { cause: args.cause });
+    this.message = args.message;
+    this.data = args.data;
     this.retryAfterMs = args.retryAfterMs;
     this.isRetryable = Boolean(args.isRetryable);
   }
@@ -66,9 +65,9 @@ export class EdgeCallFailedError extends Error {
 export class EdgeAuthChallengeError extends EdgeCallFailedError {
   constructor(
     public readonly challenge: string,
-    errorData: EdgeErrorData,
+    data: EdgeErrorData,
   ) {
-    super({ reason: 'Auth challenge.', errorData, isRetryable: false });
+    super({ message: 'Auth challenge.', data, isRetryable: false });
   }
 }
 

package/src/edge/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './edge.js';
+export * as EdgeFunctionEnv from './EdgeFunctionEnv.js';
+export * from './errors.js';

package/src/errors/base-errors.ts

@@ -2,43 +2,25 @@
 // Copyright 2021 DXOS.org
 //
 
-// TODO(dmaretskyi): Reconcile with @dxos/errors
-
 /**
  * NOTE: Messages should be sentences (Start with a capital letter and end with a period).
  * Errors can optionally include a JSON context object.
  */
-export class BaseError extends Error {
-  constructor(
-    readonly code: string,
-    message?: string,
-    readonly context?: Record<string, any>,
-  ) {
-    // TODO(dmaretskyi): Error.cause.
-    super(message ?? code);
-    this.name = code;
-    // NOTE: Restores prototype chain (https://stackoverflow.com/a/48342359).
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-// TODO(dmaretskyi): Consider common error classes with error codes:
-// throw new SystemError(ERROR_CODE_OUT_OF_MEMORY, 'Out of memory', { a: 1, b: 2 });
+import { BaseError } from '@dxos/errors';
 
 /**
  * User facing API Errors.
  * E.g., something was misconfigured.
  */
-export class ApiError extends BaseError {}
+export class ApiError extends BaseError.extend('API') {}
 
 /**
  * Internal system errors.
  * E.g., unexpected/unrecoverable runtime error.
  */
-export class SystemError extends BaseError {}
+export class SystemError extends BaseError.extend('SYSTEM') {}
 
 /**
  * Database errors.
  */
-// TODO(wittjosiah): Same as ApiError?
-export class DatabaseError extends BaseError {}
+export class DatabaseError extends BaseError.extend('DATABASE') {}

package/src/errors/errors.test.ts

@@ -9,7 +9,7 @@ import { ApiError } from './base-errors.js';
 describe('Errors', () => {
   test('test', async () => {
     const runTest = async () => {
-      throw new ApiError('Test error');
+      throw new ApiError({ message: 'Test error' });
     };
 
     await expect(runTest()).rejects.toThrowError('Test error');