@dxos/edge-client 0.8.3 → 0.8.4-main.28f8d3d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.8.3",
+  "version": "0.8.4-main.28f8d3d",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,16 +10,19 @@
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
     },
     "./muxer": {
+      "source": "./src/edge-ws-muxer.ts",
       "types": "./dist/types/src/edge-ws-muxer.d.ts",
       "browser": "./dist/lib/browser/edge-ws-muxer.mjs",
       "node": "./dist/lib/node-esm/edge-ws-muxer.mjs"
     },
     "./testing": {
+      "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
@@ -39,23 +42,27 @@
     "README.md"
   ],
   "dependencies": {
+    "@effect/platform": "^0.90.2",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.14.2",
-    "@dxos/async": "0.8.3",
-    "@dxos/context": "0.8.3",
-    "@dxos/credentials": "0.8.3",
-    "@dxos/debug": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/keys": "0.8.3",
-    "@dxos/keyring": "0.8.3",
-    "@dxos/log": "0.8.3",
-    "@dxos/crypto": "0.8.3",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/protocols": "0.8.3",
-    "@dxos/util": "0.8.3"
+    "@dxos/async": "0.8.4-main.28f8d3d",
+    "@dxos/context": "0.8.4-main.28f8d3d",
+    "@dxos/credentials": "0.8.4-main.28f8d3d",
+    "@dxos/crypto": "0.8.4-main.28f8d3d",
+    "@dxos/debug": "0.8.4-main.28f8d3d",
+    "@dxos/invariant": "0.8.4-main.28f8d3d",
+    "@dxos/keyring": "0.8.4-main.28f8d3d",
+    "@dxos/keys": "0.8.4-main.28f8d3d",
+    "@dxos/node-std": "0.8.4-main.28f8d3d",
+    "@dxos/log": "0.8.4-main.28f8d3d",
+    "@dxos/protocols": "0.8.4-main.28f8d3d",
+    "@dxos/util": "0.8.4-main.28f8d3d"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.8.3"
+    "@dxos/test-utils": "0.8.4-main.28f8d3d"
+  },
+  "peerDependencies": {
+    "effect": "^3.13.3"
   },
   "publishConfig": {
     "access": "public"

package/src/edge-client.ts

@@ -2,8 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Trigger, scheduleMicroTask, TriggerState, PersistentLifecycle, Event } from '@dxos/async';
-import { Resource, type Lifecycle } from '@dxos/context';
+import { Event, PersistentLifecycle, Trigger, TriggerState, scheduleMicroTask } from '@dxos/async';
+import { type Lifecycle, Resource } from '@dxos/context';
 import { log, logInfo } from '@dxos/log';
 import { type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 import { EdgeStatus } from '@dxos/protocols/proto/dxos/client/services';

package/src/edge-http-client.test.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from 'vitest';
+
+import { createEphemeralEdgeIdentity } from './auth';
+import { EdgeHttpClient } from './edge-http-client';
+
+// TODO(burdon): Factor out config.
+const DEV_SERVER = 'https://edge.dxos.workers.dev';
+
+describe.skipIf(process.env.CI)('EdgeHttpClient', () => {
+  it.only('should get status', async ({ expect }) => {
+    const client = new EdgeHttpClient(DEV_SERVER);
+    const identity = await createEphemeralEdgeIdentity();
+    client.setIdentity(identity);
+
+    const result = await client.getStatus();
+    expect(result).toBeDefined();
+  });
+});

package/src/edge-http-client.ts

@@ -2,42 +2,73 @@
 // Copyright 2024 DXOS.org
 //
 
+import { FetchHttpClient, HttpClient } from '@effect/platform';
+import { Effect, pipe } from 'effect';
+
 import { sleep } from '@dxos/async';
 import { Context } from '@dxos/context';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import {
+  type CreateAgentRequestBody,
+  type CreateAgentResponseBody,
+  type CreateSpaceRequest,
+  type CreateSpaceResponseBody,
+  EdgeAuthChallengeError,
   EdgeCallFailedError,
   type EdgeHttpResponse,
+  type EdgeStatus,
+  type ExecuteWorkflowResponseBody,
+  type GetAgentStatusResponseBody,
   type GetNotarizationResponseBody,
-  type PostNotarizationRequestBody,
+  type InitiateOAuthFlowRequest,
+  type InitiateOAuthFlowResponse,
   type JoinSpaceRequest,
   type JoinSpaceResponseBody,
-  EdgeAuthChallengeError,
-  type CreateAgentResponseBody,
-  type CreateAgentRequestBody,
-  type GetAgentStatusResponseBody,
+  type ObjectId,
+  type PostNotarizationRequestBody,
+  type QueryResult,
+  type QueueQuery,
   type RecoverIdentityRequest,
   type RecoverIdentityResponseBody,
   type UploadFunctionRequest,
   type UploadFunctionResponseBody,
-  type ObjectId,
-  type ExecuteWorkflowResponseBody,
-  type QueueQuery,
-  type QueryResult,
-  type InitiateOAuthFlowRequest,
-  type InitiateOAuthFlowResponse,
-  type CreateSpaceRequest,
-  type CreateSpaceResponseBody,
 } from '@dxos/protocols';
+import { createUrl } from '@dxos/util';
 
 import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
+import { HttpConfig, encodeAuthHeader, withLogging, withRetryConfig } from './http-client';
 import { getEdgeUrlWithProtocol } from './utils';
 
 const DEFAULT_RETRY_TIMEOUT = 1500;
 const DEFAULT_RETRY_JITTER = 500;
 const DEFAULT_MAX_RETRIES_COUNT = 3;
 
+export type RetryConfig = {
+  /**
+   * A number of call retries, not counting the initial request.
+   */
+  count: number;
+  /**
+   * Delay before retries in ms.
+   */
+  timeout?: number;
+  /**
+   * A random amount of time before retrying to help prevent large bursts of requests.
+   */
+  jitter?: number;
+};
+
+type EdgeHttpRequestArgs = {
+  method: string;
+  context?: Context;
+  retry?: RetryConfig;
+  body?: any;
+};
+
+export type EdgeHttpGetArgs = Pick<EdgeHttpRequestArgs, 'context' | 'retry'>;
+export type EdgeHttpPostArgs = Pick<EdgeHttpRequestArgs, 'context' | 'retry' | 'body'>;
+
 export class EdgeHttpClient {
   private readonly _baseUrl: string;
 
@@ -64,19 +95,38 @@ export class EdgeHttpClient {
     }
   }
 
+  //
+  // Status
+  //
+
+  public async getStatus(args?: EdgeHttpGetArgs): Promise<EdgeStatus> {
+    return this._call(new URL('/status', this.baseUrl), { ...args, method: 'GET' });
+  }
+
+  //
+  // Agents
+  //
+
   public createAgent(body: CreateAgentRequestBody, args?: EdgeHttpGetArgs): Promise<CreateAgentResponseBody> {
-    return this._call('/agents/create', { ...args, method: 'POST', body });
+    return this._call(new URL('/agents/create', this.baseUrl), { ...args, method: 'POST', body });
   }
 
   public getAgentStatus(
     request: { ownerIdentityKey: PublicKey },
     args?: EdgeHttpGetArgs,
   ): Promise<GetAgentStatusResponseBody> {
-    return this._call(`/users/${request.ownerIdentityKey.toHex()}/agent/status`, { ...args, method: 'GET' });
+    return this._call(new URL(`/users/${request.ownerIdentityKey.toHex()}/agent/status`, this.baseUrl), {
+      ...args,
+      method: 'GET',
+    });
   }
 
+  //
+  // Credentials
+  //
+
   public getCredentialsForNotarization(spaceId: SpaceId, args?: EdgeHttpGetArgs): Promise<GetNotarizationResponseBody> {
-    return this._call(`/spaces/${spaceId}/notarization`, { ...args, method: 'GET' });
+    return this._call(new URL(`/spaces/${spaceId}/notarization`, this.baseUrl), { ...args, method: 'GET' });
   }
 
   public async notarizeCredentials(
@@ -84,49 +134,59 @@ export class EdgeHttpClient {
     body: PostNotarizationRequestBody,
     args?: EdgeHttpGetArgs,
   ): Promise<void> {
-    await this._call(`/spaces/${spaceId}/notarization`, { ...args, body, method: 'POST' });
+    await this._call(new URL(`/spaces/${spaceId}/notarization`, this.baseUrl), { ...args, body, method: 'POST' });
   }
 
-  public async joinSpaceByInvitation(
-    spaceId: SpaceId,
-    body: JoinSpaceRequest,
-    args?: EdgeHttpGetArgs,
-  ): Promise<JoinSpaceResponseBody> {
-    return this._call(`/spaces/${spaceId}/join`, { ...args, body, method: 'POST' });
-  }
+  //
+  // Identity
+  //
 
   public async recoverIdentity(
     body: RecoverIdentityRequest,
     args?: EdgeHttpGetArgs,
   ): Promise<RecoverIdentityResponseBody> {
-    return this._call('/identity/recover', { ...args, body, method: 'POST' });
+    return this._call(new URL('/identity/recover', this.baseUrl), { ...args, body, method: 'POST' });
   }
 
-  public async executeWorkflow(
+  //
+  // Invitations
+  //
+
+  public async joinSpaceByInvitation(
     spaceId: SpaceId,
-    graphId: ObjectId,
-    input: any,
+    body: JoinSpaceRequest,
     args?: EdgeHttpGetArgs,
-  ): Promise<ExecuteWorkflowResponseBody> {
-    return this._call(`/workflows/${spaceId}/${graphId}`, { ...args, body: input, method: 'POST' });
+  ): Promise<JoinSpaceResponseBody> {
+    return this._call(new URL(`/spaces/${spaceId}/join`, this.baseUrl), { ...args, body, method: 'POST' });
   }
 
-  public async uploadFunction(
-    pathParts: { functionId?: string },
-    body: UploadFunctionRequest,
-    args?: EdgeHttpGetArgs,
-  ): Promise<UploadFunctionResponseBody> {
-    const path = ['functions', ...(pathParts.functionId ? [pathParts.functionId] : [])].join('/');
-    return this._call(path, { ...args, body, method: 'PUT' });
+  //
+  // OAuth and credentials
+  //
+
+  public async listFunctions(args?: EdgeHttpGetArgs): Promise<any> {
+    return this._call(new URL('/functions', this.baseUrl), { ...args, method: 'GET' });
   }
 
   public async initiateOAuthFlow(
     body: InitiateOAuthFlowRequest,
     args?: EdgeHttpGetArgs,
   ): Promise<InitiateOAuthFlowResponse> {
-    return this._call('/oauth/initiate', { ...args, body, method: 'POST' });
+    return this._call(new URL('/oauth/initiate', this.baseUrl), { ...args, body, method: 'POST' });
   }
 
+  //
+  // Spaces
+  //
+
+  async createSpace(body: CreateSpaceRequest, args?: EdgeHttpGetArgs): Promise<CreateSpaceResponseBody> {
+    return this._call(new URL('/spaces/create', this.baseUrl), { ...args, body, method: 'POST' });
+  }
+
+  //
+  // Queues
+  //
+
   public async queryQueue(
     subspaceTag: string,
     spaceId: SpaceId,
@@ -134,26 +194,19 @@ export class EdgeHttpClient {
     args?: EdgeHttpGetArgs,
   ): Promise<QueryResult> {
     const { queueId } = query;
-    const queryParams = new URLSearchParams();
-    if (query.after != null) {
-      queryParams.set('after', query.after);
-    }
-    if (query.before != null) {
-      queryParams.set('before', query.before);
-    }
-    if (query.limit != null) {
-      queryParams.set('limit', query.limit.toString());
-    }
-    if (query.reverse != null) {
-      queryParams.set('reverse', query.reverse.toString());
-    }
-    if (query.objectIds != null) {
-      queryParams.set('objectIds', query.objectIds.join(','));
-    }
-    return this._call(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}/query?${queryParams.toString()}`, {
-      ...args,
-      method: 'GET',
-    });
+    return this._call(
+      createUrl(new URL(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}/query`, this.baseUrl), {
+        after: query.after,
+        before: query.before,
+        limit: query.limit,
+        reverse: query.reverse,
+        objectIds: query.objectIds?.join(','),
+      }),
+      {
+        ...args,
+        method: 'GET',
+      },
+    );
   }
 
   public async insertIntoQueue(
@@ -163,72 +216,105 @@ export class EdgeHttpClient {
     objects: unknown[],
     args?: EdgeHttpGetArgs,
   ): Promise<void> {
-    return this._call(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}`, {
+    return this._call(new URL(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}`, this.baseUrl), {
       ...args,
       body: { objects },
       method: 'POST',
     });
   }
 
-  async deleteFromQueue(
+  public async deleteFromQueue(
     subspaceTag: string,
     spaceId: SpaceId,
     queueId: ObjectId,
     objectIds: ObjectId[],
     args?: EdgeHttpGetArgs,
   ): Promise<void> {
-    return this._call(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}`, {
+    return this._call(
+      createUrl(new URL(`/spaces/${subspaceTag}/${spaceId}/queue/${queueId}`, this.baseUrl), {
+        ids: objectIds.join(','),
+      }),
+      {
+        ...args,
+        method: 'DELETE',
+      },
+    );
+  }
+
+  //
+  // Functions
+  //
+
+  public async uploadFunction(
+    pathParts: { functionId?: string },
+    body: UploadFunctionRequest,
+    args?: EdgeHttpGetArgs,
+  ): Promise<UploadFunctionResponseBody> {
+    const path = ['functions', ...(pathParts.functionId ? [pathParts.functionId] : [])].join('/');
+    return this._call(new URL(path, this.baseUrl), { ...args, body, method: 'PUT' });
+  }
+
+  //
+  // Workflows
+  //
+
+  public async executeWorkflow(
+    spaceId: SpaceId,
+    graphId: ObjectId,
+    input: any,
+    args?: EdgeHttpGetArgs,
+  ): Promise<ExecuteWorkflowResponseBody> {
+    return this._call(new URL(`/workflows/${spaceId}/${graphId}`, this.baseUrl), {
       ...args,
-      query: { ids: objectIds.join(',') },
-      method: 'DELETE',
+      body: input,
+      method: 'POST',
     });
   }
 
-  async createSpace(body: CreateSpaceRequest, args?: EdgeHttpGetArgs): Promise<CreateSpaceResponseBody> {
-    return this._call('/spaces/create', { ...args, body, method: 'POST' });
+  //
+  // Internal
+  //
+
+  private async _fetch<T>(url: URL, args: EdgeHttpRequestArgs): Promise<T> {
+    return pipe(
+      HttpClient.get(url),
+      withLogging,
+      withRetryConfig,
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(HttpConfig.default),
+      Effect.withSpan('EdgeHttpClient'),
+      Effect.runPromise,
+    ) as T;
   }
 
-  private async _call<T>(path: string, args: EdgeHttpCallArgs): Promise<T> {
-    const requestContext = args.context ?? new Context();
+  // TODO(burdon): Refactor with effect (see edge-http-client.test.ts).
+  private async _call<T>(url: URL, args: EdgeHttpRequestArgs): Promise<T> {
     const shouldRetry = createRetryHandler(args);
-    let url = `${this._baseUrl}${path.startsWith('/') ? path.slice(1) : path}`;
-
-    if (args.query) {
-      const queryParams = new URLSearchParams();
-      for (const [key, value] of Object.entries(args.query)) {
-        queryParams.set(key, value.toString());
-      }
-      url += `?${queryParams.toString()}`;
-    }
-
-    log('call', { method: args.method, path, request: args.body });
+    const requestContext = args.context ?? new Context();
+    log('fetch', { url, request: args.body });
 
     let handledAuth = false;
-    let authHeader = this._authHeader;
     while (true) {
       let processingError: EdgeCallFailedError;
       let retryAfterHeaderValue: number = Number.NaN;
       try {
-        const request = createRequest(args, authHeader);
+        const request = createRequest(args, this._authHeader);
         const response = await fetch(url, request);
-
         retryAfterHeaderValue = Number(response.headers.get('Retry-After'));
-
         if (response.ok) {
           const body = (await response.json()) as EdgeHttpResponse<T>;
           if (body.success) {
             return body.data;
           }
 
-          log('unsuccessful edge response', { path, body });
-
+          log.warn('unsuccessful edge response', { url, body });
           if (body.errorData?.type === 'auth_challenge' && typeof body.errorData?.challenge === 'string') {
             processingError = new EdgeAuthChallengeError(body.errorData.challenge, body.errorData);
           } else {
             processingError = EdgeCallFailedError.fromUnsuccessfulResponse(response, body);
           }
         } else if (response.status === 401 && !handledAuth) {
-          authHeader = await this._handleUnauthorized(response);
+          this._authHeader = await this._handleUnauthorized(response);
           handledAuth = true;
           continue;
         } else {
@@ -239,7 +325,7 @@ export class EdgeHttpClient {
       }
 
       if (processingError.isRetryable && (await shouldRetry(requestContext, retryAfterHeaderValue))) {
-        log('retrying edge request', { path, processingError });
+        log('retrying edge request', { url, processingError });
       } else {
         throw processingError;
       }
@@ -248,24 +334,35 @@ export class EdgeHttpClient {
 
   private async _handleUnauthorized(response: Response): Promise<string> {
     if (!this._edgeIdentity) {
-      log.warn('edge unauthorized response received before identity was set');
+      log.warn('unauthorized response received before identity was set');
       throw EdgeCallFailedError.fromHttpFailure(response);
     }
+
     const challenge = await handleAuthChallenge(response, this._edgeIdentity);
-    this._authHeader = encodeAuthHeader(challenge);
-    log('auth header updated');
-    return this._authHeader;
+    return encodeAuthHeader(challenge);
   }
 }
 
-const createRetryHandler = (args: EdgeHttpCallArgs) => {
-  if (!args.retry || args.retry.count < 1) {
+const createRequest = ({ method, body }: EdgeHttpRequestArgs, authHeader: string | undefined): RequestInit => {
+  return {
+    method,
+    body: body && JSON.stringify(body),
+    headers: authHeader ? { Authorization: authHeader } : undefined,
+  };
+};
+
+/**
+ * @deprecated
+ */
+const createRetryHandler = ({ retry }: EdgeHttpRequestArgs) => {
+  if (!retry || retry.count < 1) {
     return async () => false;
   }
+
   let retries = 0;
-  const maxRetries = args.retry.count ?? DEFAULT_MAX_RETRIES_COUNT;
-  const baseTimeout = args.retry.timeout ?? DEFAULT_RETRY_TIMEOUT;
-  const jitter = args.retry.jitter ?? DEFAULT_RETRY_JITTER;
+  const maxRetries = retry.count ?? DEFAULT_MAX_RETRIES_COUNT;
+  const baseTimeout = retry.timeout ?? DEFAULT_RETRY_TIMEOUT;
+  const jitter = retry.jitter ?? DEFAULT_RETRY_JITTER;
   return async (ctx: Context, retryAfter: number) => {
     if (++retries > maxRetries || ctx.disposed) {
       return false;
@@ -281,43 +378,3 @@ const createRetryHandler = (args: EdgeHttpCallArgs) => {
     return true;
   };
 };
-
-export type RetryConfig = {
-  /**
-   * A number of call retries, not counting the initial request.
-   */
-  count: number;
-  /**
-   * Delay before retries in ms.
-   */
-  timeout?: number;
-  /**
-   * A random amount of time before retrying to help prevent large bursts of requests.
-   */
-  jitter?: number;
-};
-
-export type EdgeHttpGetArgs = { context?: Context; retry?: RetryConfig };
-
-export type EdgeHttpPostArgs = { context?: Context; body?: any; retry?: RetryConfig };
-
-type EdgeHttpCallArgs = {
-  method: string;
-  body?: any;
-  context?: Context;
-  retry?: RetryConfig;
-  query?: Record<string, string>;
-};
-
-const createRequest = (args: EdgeHttpCallArgs, authHeader: string | undefined): RequestInit => {
-  return {
-    method: args.method,
-    body: args.body && JSON.stringify(args.body),
-    headers: authHeader ? { Authorization: authHeader } : undefined,
-  };
-};
-
-const encodeAuthHeader = (challenge: Uint8Array) => {
-  const encodedChallenge = Buffer.from(challenge).toString('base64');
-  return `VerifiablePresentation pb;base64,${encodedChallenge}`;
-};

package/src/edge-ws-connection.ts

@@ -10,7 +10,7 @@ import { invariant } from '@dxos/invariant';
 import { log, logInfo } from '@dxos/log';
 import { EdgeWebsocketProtocol } from '@dxos/protocols';
 import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';
 import { type EdgeIdentity } from './edge-identity';
@@ -30,6 +30,7 @@ export class EdgeWsConnection extends Resource {
   private _inactivityTimeoutCtx: Context | undefined;
   private _ws: WebSocket | undefined;
   private _wsMuxer: WebSocketMuxer | undefined;
+  private _lastReceivedMessageTimestamp = Date.now();
 
   constructor(
     private readonly _identity: EdgeIdentity,
@@ -111,6 +112,7 @@ export class EdgeWsConnection extends Resource {
         log.verbose('message ignored on closed connection', { event: event.type });
         return;
       }
+      this._lastReceivedMessageTimestamp = Date.now();
       if (event.data === '__pong__') {
         this._rescheduleHeartbeatTimeout();
         return;
@@ -172,8 +174,14 @@ export class EdgeWsConnection extends Resource {
       this._inactivityTimeoutCtx,
       () => {
         if (this.isOpen) {
-          log.warn('restart due to inactivity timeout');
-          this._callbacks.onRestartRequired();
+          if (Date.now() - this._lastReceivedMessageTimestamp > SIGNAL_KEEPALIVE_TIMEOUT) {
+            log.warn('restart due to inactivity timeout', {
+              lastReceivedMessageTimestamp: this._lastReceivedMessageTimestamp,
+            });
+            this._callbacks.onRestartRequired();
+          } else {
+            this._rescheduleHeartbeatTimeout();
+          }
         }
       },
       SIGNAL_KEEPALIVE_TIMEOUT,

package/src/edge-ws-muxer.ts

@@ -5,7 +5,7 @@
 import { Trigger } from '@dxos/async';
 import { log } from '@dxos/log';
 import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';