@dxos/protocols 0.8.4-main.a4bbb77 → 0.8.4-main.ae835ea

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,38 @@ 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.
+ */
+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 +63,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[] };
@@ -273,7 +373,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/index.ts

@@ -2,15 +2,15 @@
 // 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 './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 * from './query.js';
 export * from './queue.js';
 export * from './space-archive.js';
-export * from './edge-error.js';
+export * from './storage.js';
+export * from './tracing.js';
+export type * from './types.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/gen/dxos/client/services.ts

@@ -1399,9 +1399,36 @@ export interface EdgeAgentService {
  * Defined in:
  *   {@link file://./../../../dxos/client/services.proto}
  */
-export enum EdgeStatus {
-    NOT_CONNECTED = 0,
-    CONNECTED = 1
+export interface EdgeStatus {
+    state: EdgeStatus.ConnectionState;
+    /**
+     * Latency in ms
+     */
+    rtt: number;
+    /**
+     * How long the connection has been up
+     */
+    uptime: number;
+    /**
+     * Upload rate in bytes per second
+     */
+    rateBytesUp: number;
+    /**
+     * Download rate in bytes per second
+     */
+    rateBytesDown: number;
+    messagesSent: number;
+    messagesReceived: number;
+}
+export namespace EdgeStatus {
+    /**
+     * Defined in:
+     *   {@link file://./../../../dxos/client/services.proto}
+     */
+    export enum ConnectionState {
+        NOT_CONNECTED = 0,
+        CONNECTED = 1
+    }
 }
 /**
  * Defined in:

package/src/proto/gen/google/protobuf.ts

@@ -84,14 +84,14 @@ export enum NullValue {
 export interface ListValue {
     values?: Value[];
 }
-export interface Any {
-    type_url: string;
-    value: Uint8Array;
-}
 export interface Timestamp {
     seconds: string;
     nanos: number;
 }
+export interface Any {
+    type_url: string;
+    value: Uint8Array;
+}
 export interface FileDescriptorSet {
     file?: FileDescriptorProto[];
 }