@dxos/protocols 0.8.4-main.28f8d3d → 0.8.4-main.2c6827d

package/src/buf/proto/gen/dxos/type_pb.ts

@@ -2,14 +2,14 @@
 // Copyright 2022 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.9.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/type.proto (package dxos.type, syntax proto3)
 /* eslint-disable */
 
 // TODO(burdon): Rename `dxos.registry.type`.
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import { file_google_protobuf_struct } from "@bufbuild/protobuf/wkt";
 import type { Record_Extension } from "./registry_pb.js";
 import { file_dxos_registry } from "./registry_pb.js";

package/src/buf/proto/gen/dxos/value_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2021 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.9.0 with parameter "target=ts,import_extension=js"
 // @generated from file dxos/value.proto (package dxos.value, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
 
 /**

package/src/buf/proto/gen/example/testing/data_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2020 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.9.0 with parameter "target=ts,import_extension=js"
 // @generated from file example/testing/data.proto (package example.testing.data, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
 import type { Message } from "@bufbuild/protobuf";
 
 /**

package/src/buf/proto/gen/example/testing/rpc_pb.ts

@@ -2,12 +2,12 @@
 // Copyright 2020 DXOS.org
 //
 
-// @generated by protoc-gen-es v2.1.0 with parameter "target=ts,import_extension=js"
+// @generated by protoc-gen-es v2.9.0 with parameter "target=ts,import_extension=js"
 // @generated from file example/testing/rpc.proto (package example.testing.rpc, syntax proto3)
 /* eslint-disable */
 
-import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv1";
-import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv1";
+import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
 import type { Any, EmptySchema } from "@bufbuild/protobuf/wkt";
 import { file_google_protobuf_any, file_google_protobuf_empty } from "@bufbuild/protobuf/wkt";
 import type { Message } from "@bufbuild/protobuf";

package/src/edge-error.ts

@@ -2,31 +2,44 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type EdgeErrorData, type EdgeHttpFailure } from './edge';
+import { type EdgeErrorData, type EdgeFailure, EdgeHttpErrorCodec, ErrorCodec } from './edge.js';
 
+// TODO(burdon): Reconcile with @dxos/errors.
+/**
+ * Error thrown when a call to the Edge service fails.
+ * There 3 possible sources of failure:
+ * 1. EdgeFailure (JSON body with { success: false }) -> Processing the request failed and was gracefully handled by EDGE service.
+ * 2. Http failure (non-ok code) -> The HTTP request failed (e.g. timeout, network error).
+ *                               -> Unhandled exception on EDGE side, EDGE would provide serialized error in the response body.
+ * 3. Processing failure -> Unhandled exception on client side while processing the response.
+ */
 export class EdgeCallFailedError extends Error {
-  public static fromProcessingFailureCause(cause: Error): EdgeCallFailedError {
-    return new EdgeCallFailedError({
-      reason: 'Error processing request.',
-      isRetryable: true,
-      cause,
+  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'),
+      retryAfterMs: getRetryAfterMillis(response),
+      cause: body.cause ? ErrorCodec.decode(body.cause) : undefined,
     });
+
+    return error;
   }
 
-  public static fromHttpFailure(response: Response): EdgeCallFailedError {
+  public static async fromHttpFailure(response: Response): Promise<EdgeCallFailedError> {
     return new EdgeCallFailedError({
       reason: `HTTP code ${response.status}: ${response.statusText}.`,
       isRetryable: isRetryableCode(response.status),
       retryAfterMs: getRetryAfterMillis(response),
+      cause: await EdgeHttpErrorCodec.decode(response),
     });
   }
 
-  public static fromUnsuccessfulResponse(response: Response, body: EdgeHttpFailure): EdgeCallFailedError {
+  public static fromProcessingFailureCause(cause: Error): EdgeCallFailedError {
     return new EdgeCallFailedError({
-      reason: body.reason,
-      errorData: body.errorData,
-      isRetryable: body.errorData == null && response.headers.has('Retry-After'),
-      retryAfterMs: getRetryAfterMillis(response),
+      reason: 'Error processing request.',
+      isRetryable: true,
+      cause,
     });
   }
 
@@ -64,12 +77,6 @@ const getRetryAfterMillis = (response: Response) => {
   return Number.isNaN(retryAfter) || retryAfter === 0 ? undefined : retryAfter * 1000;
 };
 
-export const createRetryableHttpFailure = (args: { reason: any; retryAfterSeconds: number }) => {
-  return new Response(JSON.stringify({ success: false, reason: args.reason }), {
-    headers: { 'Retry-After': String(args.retryAfterSeconds) },
-  });
-};
-
 const isRetryableCode = (status: number) => {
   if (status === 501) {
     // Not Implemented

package/src/edge.ts

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
+import { BaseError } from '@dxos/errors';
+import { invariant } from '@dxos/invariant';
 import { SpaceId } from '@dxos/keys';
 
 // TODO(burdon): Rename EdgerRouterEndpoint.
@@ -16,20 +18,43 @@ export enum EdgeService {
   STATUS = 'status',
 }
 
-export type EdgeHttpSuccess<T> = {
+export type EdgeSuccess<T> = {
   success: true;
   data: T;
 };
 
+export type SerializedError = {
+  code?: string;
+  message?: string;
+  context?: Record<string, unknown>;
+  stack?: string;
+  cause?: SerializedError;
+};
+
 export type EdgeErrorData = { type: string } & Record<string, any>;
 
-export type EdgeHttpFailure = {
-  // TODO(burdon): Why is this required?
+/**
+ * This is the shape of the error response from the Edge service,
+ * when the error is gracefully handled, the Response will be an object with this shape and have status code 200.
+ */
+// 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
+export type EdgeFailure = {
+  /**
+   * Branded Type.
+   */
   success: false;
   /**
    * An explanation of why the call failed. Used mostly for logging and monitoring.
    */
   reason: string;
+  /**
+   * Cause Error captured on the EDGE service to aid debugging on the client.
+   */
+  cause?: SerializedError;
   /**
    * Information that can be used to retry the request such that it will succeed, for example:
    * 1. { type: 'auth_required', challenge: string }
@@ -43,7 +68,87 @@ export type EdgeHttpFailure = {
   errorData?: EdgeErrorData;
 };
 
-export type EdgeHttpResponse<T> = EdgeHttpSuccess<T> | EdgeHttpFailure;
+/**
+ * Represents a body response from the Edge service.
+ */
+export type EdgeBody<T> = EdgeSuccess<T> | EdgeFailure;
+
+/**
+ * Use this to create a response from the Edge service.
+ */
+export const EdgeResponse = Object.freeze({
+  success: <T>(data: T, status: number = 200): Response => {
+    invariant(status >= 200 && status < 300, 'Status code must be in the 2xx range');
+    const headers = new Headers({ 'Content-Type': 'application/json' });
+    return new Response(
+      JSON.stringify({
+        success: true,
+        data,
+      } satisfies EdgeSuccess<T>),
+      {
+        status,
+        headers,
+      },
+    );
+  },
+  failure: ({
+    reason,
+    cause,
+    errorData,
+    shouldRetryAfter,
+    status = 500,
+  }: {
+    /**
+     * An explanation of why the call failed. Used mostly for logging and monitoring.
+     */
+    reason: string;
+    /**
+     * Error that caused the failure.
+     * Useful for debugging.
+     */
+    cause?: Error;
+    /**
+     * Information that can be used to retry the request such that it will succeed, for example:
+     * 1. { type: 'auth_required', challenge: string }
+     *    Requires retrying the request with challenge signature included.
+     * 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.
+     */
+    errorData?: 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.
+     */
+    shouldRetryAfter?: number;
+
+    /**
+     * Status code of the response.
+     * @default 500
+     */
+    status?: number;
+  }): Response => {
+    const headers = new Headers({ 'Content-Type': 'application/json' });
+    if (shouldRetryAfter) {
+      headers.set('Retry-After', String(shouldRetryAfter));
+    }
+
+    return new Response(
+      JSON.stringify({
+        success: false,
+        reason,
+        errorData,
+        cause: cause ? ErrorCodec.encode(cause) : undefined,
+      } satisfies EdgeFailure),
+      {
+        status,
+        headers,
+      },
+    );
+  },
+});
 
 export type GetNotarizationResponseBody = {
   awaitingNotarization: { credentials: string[] };
@@ -118,15 +223,36 @@ export type GetAgentStatusResponseBody = {
 
 export type UploadFunctionRequest = {
   name?: string;
-  script: string;
   version: string;
   ownerPublicKey: string;
+  entryPoint: string;
+  assets: Record<string, Uint8Array>;
+  /**
+   * Runtime in Edge that will be used to run the function.
+   * Runtime cannot be changed once the function was deployed.
+   * @default Runtime.WORKERS_FOR_PLATFORMS
+   */
+  runtime?: Runtime;
 };
 
+/**
+ * Note: Do not change the values of these enums, this values are stored in the FunctionVersions database.
+ */
+export enum Runtime {
+  // https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/
+  WORKERS_FOR_PLATFORMS = 'WORKERS_FOR_PLATFORMS',
+  // https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/
+  WORKER_LOADER = 'WORKER_LOADER',
+  // Local worker dispatcher for testing.
+  TEST = 'TEST',
+}
+
 export type UploadFunctionResponseBody = {
   functionId: string;
   version: string;
   meta: {
+    key?: string;
+    name?: string;
     description?: string;
     /**
      * JSON Schema for the input of the function.
@@ -270,7 +396,82 @@ export type ExportBundleResponse = {
   }[];
 };
 
-export const DocumentCodec = {
+export const DocumentCodec = Object.freeze({
   encode: (doc: Uint8Array) => Buffer.from(doc).toString('base64'),
   decode: (doc: string) => new Uint8Array(Buffer.from(doc, 'base64')),
-};
+});
+
+const MAX_ERROR_DEPTH = 3;
+
+/**
+ * Codec for serializing and deserializing Edge Errors.
+ */
+export const ErrorCodec = Object.freeze({
+  encode: (err: Error, depth: number = 0): SerializedError => ({
+    code: 'code' in err ? (err as any).code : undefined,
+    message: err.message,
+    stack: err.stack,
+    cause: err.cause instanceof Error && depth < MAX_ERROR_DEPTH ? ErrorCodec.encode(err.cause, depth + 1) : undefined,
+  }),
+  decode: (serializedError: SerializedError, depth: number = 0): Error => {
+    let err: Error;
+    if (typeof serializedError.code === 'string') {
+      err = new BaseError(serializedError.code, {
+        message: serializedError.message ?? 'Unknown error',
+        cause:
+          serializedError.cause && depth < MAX_ERROR_DEPTH
+            ? ErrorCodec.decode(serializedError.cause, depth + 1)
+            : undefined,
+        context: serializedError.context,
+      });
+
+      if (serializedError.stack) {
+        Object.defineProperty(err, 'stack', {
+          value: serializedError.stack,
+        });
+      }
+    } else {
+      err = new Error(serializedError.message ?? 'Unknown error', {
+        cause:
+          serializedError.cause && depth < MAX_ERROR_DEPTH
+            ? ErrorCodec.decode(serializedError.cause, depth + 1)
+            : undefined,
+      });
+
+      if (serializedError.stack) {
+        Object.defineProperty(err, 'stack', {
+          value: serializedError.stack,
+        });
+      }
+    }
+
+    return err;
+  },
+});
+
+/**
+ * Codec for serializing and deserializing Edge unhandled HTTP errors.
+ */
+export const EdgeHttpErrorCodec = Object.freeze({
+  encode: (err: Error): Response =>
+    new Response(
+      JSON.stringify({
+        error: ErrorCodec.encode(err),
+      }),
+      { status: 500 },
+    ),
+
+  decode: async (response: Response): Promise<Error | undefined> => {
+    if (response.headers.get('Content-Type') !== 'application/json') {
+      const body = await response.clone().text();
+      return new Error(body.slice(0, 256));
+    }
+
+    const body = await response.clone().json();
+    if (!('error' in body)) {
+      return undefined;
+    }
+
+    return ErrorCodec.decode(body.error);
+  },
+});

package/src/errors/base-errors.ts

@@ -2,6 +2,8 @@
 // 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.

package/src/index.ts

@@ -2,15 +2,16 @@
 // Copyright 2021 DXOS.org
 //
 
+export * from './automerge.js';
+export * from './edge-error.js';
+export * from './edge.js';
 export * from './errors/index.js';
 export * from './indexing.js';
+export * from './profile-archive.js';
+export * from './query.js';
+export * from './queue.js';
+export * from './space-archive.js';
 export * from './storage.js';
 export * from './tracing.js';
 export type * from './types.js';
-export * from './query.js';
-export * from './profile-archive.js';
-export * from './automerge.js';
-export * from './edge.js';
-export type * from './queue.js';
-export * from './space-archive.js';
-export * from './edge-error.js';
+export * as FunctionProtocol from './FunctionProtocol.js';

package/src/indexing.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 export type ObjectPointerDecoded = {
   spaceKey: string | undefined;

package/src/invitation.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { ParamKeyAnnotation } from '@dxos/effect';
 

package/src/proto/dxos/client/services.proto

@@ -596,9 +596,26 @@ service EdgeAgentService {
   rpc QueryAgentStatus(google.protobuf.Empty) returns (stream QueryAgentStatusResponse);
 }
 
-enum EdgeStatus {
-  NOT_CONNECTED = 0;
-  CONNECTED = 1;
+message EdgeStatus {
+  enum ConnectionState {
+    NOT_CONNECTED = 0;
+    CONNECTED = 1;
+  }
+
+  ConnectionState state = 1;
+  /** Latency in ms */
+  int32 rtt = 2;
+
+  /** How long the connection has been up */
+  int32 uptime = 3;
+
+  /** Upload rate in bytes per second */
+  int32 rate_bytes_up = 4;
+  /** Download rate in bytes per second */
+  int32 rate_bytes_down = 5;
+
+  int32 messages_sent = 6;
+  int32 messages_received = 7;
 }
 
 message QueryEdgeStatusResponse {

package/src/proto/dxos/config.proto

@@ -12,9 +12,7 @@ package dxos.config;
 
 option go_package = "github.com/dxos/dxos/proto/def/dxos/config";
 
-extend google.protobuf.FieldOptions {
-  optional string env_var = 1000;
-}
+extend google.protobuf.FieldOptions { optional string env_var = 1000; }
 
 message Config {
   optional int32 version = 1;
@@ -58,9 +56,10 @@ message Module {
     optional google.protobuf.Struct env = 10;
   }
 
-  optional string id = 8;     // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
-  optional string name = 1;   // TODO(burdon): Replace with id (or key?)
-  optional string type = 2;   // TODO(burdon): Define namespace (e.g., 'dxos.org/type/frame' vs. 'dxos.type.frame')
+  optional string id = 8;   // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
+  optional string name = 1; // TODO(burdon): Replace with id (or key?)
+  optional string type = 2; // TODO(burdon): Define namespace (e.g.,
+                            // 'dxos.org/type/frame' vs. 'dxos.type.frame')
 
   // TODO(burdon): Developer info message.
 
@@ -74,7 +73,7 @@ message Module {
   optional bool tunnel = 7;
 
   // TODO(burdon): Start at 100.
-  repeated Module deps = 10;  // TODO(burdon): E.g., types.
+  repeated Module deps = 10; // TODO(burdon): E.g., types.
   optional Build build = 100;
   repeated Repo repos = 101;
 
@@ -111,8 +110,8 @@ message Runtime {
     }
 
     message Log {
-      optional string filter = 1 [(env_var) = "LOG_FILTER"];
-      optional string prefix = 2 [(env_var) = "LOG_PREFIX"];
+      optional string filter = 1 [ (env_var) = "LOG_FILTER" ];
+      optional string prefix = 2 [ (env_var) = "LOG_PREFIX" ];
     }
 
     message EdgeFeatures {
@@ -136,7 +135,8 @@ message Runtime {
     optional int32 invitation_expiration = 5;
 
     /// Location of the remote client host.
-    // TODO(burdon): Rename vault_endpoint (generalize http/ws; drop vault.html).
+    // TODO(burdon): Rename vault_endpoint (generalize http/ws; drop
+    // vault.html).
     optional string remote_source = 6;
 
     // Authenticate via `Sec-WebSocket-Protocol` header hack.
@@ -145,7 +145,8 @@ message Runtime {
     /// Connect to and serve client services to a remote proxy.
     optional string devtools_proxy = 7;
 
-    /// Spaces will stay in SpaceState.CLOSED until explicitly opened. Speeds up client-services initialization.
+    /// Spaces will stay in SpaceState.CLOSED until explicitly opened. Speeds up
+    /// client-services initialization.
     optional bool lazy_space_open = 9;
 
     /// Disabled automerge & hypercore replication through P2P connections.
@@ -169,7 +170,7 @@ message Runtime {
     optional string org = 1;
     optional string theme = 2;
     optional string website = 3;
-    optional string public_url = 4 [(env_var) = "PUBLIC_URL"];
+    optional string public_url = 4 [ (env_var) = "PUBLIC_URL" ];
 
     optional BuildInfo build = 100;
     optional google.protobuf.Struct env = 101;
@@ -214,13 +215,9 @@ message Runtime {
     optional string channel = 7;
   }
 
-  message Props {
-    optional string title = 1;
-  }
+  message Props { optional string title = 1; }
 
-  message System {
-    optional string debug = 1;
-  }
+  message System { optional string debug = 1; }
 
   //
   // KUBE
@@ -255,9 +252,7 @@ message Runtime {
       int32 interval = 3;
     }
 
-    message Trace {
-      bool disabled = 1;
-    }
+    message Trace { bool disabled = 1; }
 
     message Telemetry {
       bool disabled = 1;
@@ -285,10 +280,10 @@ message Runtime {
 
     /// https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
     message KuboApiAuthorization {
-        /// Just for organizational purposes.
-        string name = 1;
-        string auth_secret = 2;
-        repeated string allowed_paths = 3;
+      /// Just for organizational purposes.
+      string name = 1;
+      string auth_secret = 2;
+      repeated string allowed_paths = 3;
     }
 
     // TODO(burdon): Needs documentation/
@@ -359,8 +354,9 @@ message Runtime {
     message Ipfs {
       optional string server = 1;
       optional string gateway = 2;
-      /// Used for IPFS API authentication, regardless if server is direct KUBO API (e.g. path of '/api/v0') or a reverse proxy
-      /// Same secret format as https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
+      /// Used for IPFS API authentication, regardless if server is direct KUBO
+      /// API (e.g. path of '/api/v0') or a reverse proxy Same secret format as
+      /// https://github.com/ipfs/kubo/blob/master/docs/config.md#apiauthorizations
       optional string server_auth_secret = 3;
     }
 
@@ -376,9 +372,7 @@ message Runtime {
       optional string credential = 3;
     }
 
-    message IceProvider {
-      string urls = 1;
-    }
+    message IceProvider { string urls = 1; }
 
     message Machine {
       optional string do_access_token = 1;
@@ -396,9 +390,7 @@ message Runtime {
       optional string server = 1;
     }
 
-    message Tunneling {
-      optional string server = 1;
-    }
+    message Tunneling { optional string server = 1; }
 
     message Supervisor { // TODO(burdon): Is this a service?
       optional string server = 1;
@@ -416,14 +408,13 @@ message Runtime {
       optional string type = 2;
     }
 
-    message Edge {
-      optional string url = 1;
-    }
+    message Edge { optional string url = 1; }
 
-    message Ai {
-      optional string server = 1;
-    }
+    message Ai { optional string server = 1; }
+
+    message Hub { optional string url = 1; }
 
+    /** Deprecated */
     optional Kube kube = 1;
     optional AppServer app = 2;
     optional Dxns dxns = 3;
@@ -434,12 +425,17 @@ message Runtime {
     optional Machine machine = 7;
     optional BotHost bot = 8;
     optional Publisher publisher = 9;
-    optional Supervisor supervisor = 10; // TODO(burdon): Promote to 1; start others at 10.
+    /** Deprecated */
+    optional Supervisor supervisor = 10;
+    /** Deprecated */
     optional Tunneling tunneling = 11;
+    /** Deprecated */
     optional Faasd faasd = 12;
+    /** Deprecated */
     optional AgentHosting agent_hosting = 13;
     optional Edge edge = 15;
     optional Ai ai = 16;
+    optional Hub hub = 17;
   }
 
   message Keys {