@dxos/edge-client 0.6.13 → 0.6.14-main.69511f5

package/src/edge-http-client.ts

@@ -0,0 +1,210 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { sleep } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { type PublicKey, type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import {
+  EdgeCallFailedError,
+  type EdgeHttpResponse,
+  type GetNotarizationResponseBody,
+  type PostNotarizationRequestBody,
+  type JoinSpaceRequest,
+  type JoinSpaceResponseBody,
+  EdgeAuthChallengeError,
+  type CreateAgentResponseBody,
+  type CreateAgentRequestBody,
+  type GetAgentStatusResponseBody,
+  type RecoverIdentityRequest,
+  type RecoverIdentityResponseBody,
+} from '@dxos/protocols';
+
+import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
+import { getEdgeUrlWithProtocol } from './utils';
+
+const DEFAULT_RETRY_TIMEOUT = 1500;
+const DEFAULT_RETRY_JITTER = 500;
+const DEFAULT_MAX_RETRIES_COUNT = 3;
+
+export class EdgeHttpClient {
+  private readonly _baseUrl: string;
+
+  private _edgeIdentity: EdgeIdentity | undefined;
+  /**
+   * Auth header is cached until receiving the next 401 from EDGE, at which point it gets refreshed.
+   */
+  private _authHeader: string | undefined;
+
+  constructor(baseUrl: string) {
+    this._baseUrl = getEdgeUrlWithProtocol(baseUrl, 'http');
+    log('created', { url: this._baseUrl });
+  }
+
+  setIdentity(identity: EdgeIdentity) {
+    this._edgeIdentity = identity;
+  }
+
+  public createAgent(body: CreateAgentRequestBody, args?: EdgeHttpGetArgs): Promise<CreateAgentResponseBody> {
+    return this._call('/agents/create', { ...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' });
+  }
+
+  public getCredentialsForNotarization(spaceId: SpaceId, args?: EdgeHttpGetArgs): Promise<GetNotarizationResponseBody> {
+    return this._call(`/spaces/${spaceId}/notarization`, { ...args, method: 'GET' });
+  }
+
+  public async notarizeCredentials(
+    spaceId: SpaceId,
+    body: PostNotarizationRequestBody,
+    args?: EdgeHttpGetArgs,
+  ): Promise<void> {
+    await this._call(`/spaces/${spaceId}/notarization`, { ...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' });
+  }
+
+  public async recoverIdentity(
+    body: RecoverIdentityRequest,
+    args?: EdgeHttpGetArgs,
+  ): Promise<RecoverIdentityResponseBody> {
+    return this._call('/identity/recover', { ...args, body, method: 'POST' });
+  }
+
+  private async _call<T>(path: string, args: EdgeHttpCallArgs): Promise<T> {
+    const requestContext = args.context ?? new Context();
+    const shouldRetry = createRetryHandler(args);
+    const url = `${this._baseUrl}${path.startsWith('/') ? path.slice(1) : path}`;
+
+    log.info('call', { method: args.method, path, 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 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.info('unsuccessful edge response', { path, 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);
+          handledAuth = true;
+          continue;
+        } else {
+          processingError = EdgeCallFailedError.fromHttpFailure(response);
+        }
+      } catch (error: any) {
+        processingError = EdgeCallFailedError.fromProcessingFailureCause(error);
+      }
+
+      if (processingError.isRetryable && (await shouldRetry(requestContext, retryAfterHeaderValue))) {
+        log.info('retrying edge request', { path, processingError });
+      } else {
+        throw processingError;
+      }
+    }
+  }
+
+  private async _handleUnauthorized(response: Response) {
+    if (!this._edgeIdentity) {
+      log.warn('edge 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;
+  }
+}
+
+const createRetryHandler = (args: EdgeHttpCallArgs) => {
+  if (!args.retry || args.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;
+  return async (ctx: Context, retryAfter: number) => {
+    if (++retries > maxRetries || ctx.disposed) {
+      return false;
+    }
+
+    if (retryAfter) {
+      await sleep(retryAfter);
+    } else {
+      const timeout = baseTimeout + Math.random() * jitter;
+      await sleep(timeout);
+    }
+
+    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;
+};
+
+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-identity.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+import { schema } from '@dxos/protocols/proto';
+import { type Presentation } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+export interface EdgeIdentity {
+  peerKey: string;
+  identityKey: string;
+  /**
+   * Returns credential presentation issued by the identity key.
+   * Presentation must have the provided challenge.
+   * Presentation may include ServiceAccess credentials.
+   */
+  presentCredentials({ challenge }: { challenge: Uint8Array }): Promise<Presentation>;
+}
+
+export const handleAuthChallenge = async (failedResponse: Response, identity: EdgeIdentity): Promise<Uint8Array> => {
+  invariant(failedResponse.status === 401);
+
+  const headerValue = failedResponse.headers.get('Www-Authenticate');
+  invariant(headerValue?.startsWith('VerifiablePresentation challenge='));
+
+  const challenge = headerValue?.slice('VerifiablePresentation challenge='.length);
+  invariant(challenge);
+
+  const presentation = await identity.presentCredentials({ challenge: Buffer.from(challenge, 'base64') });
+  return schema.getCodecForType('dxos.halo.credentials.Presentation').encode(presentation);
+};

package/src/errors.ts

@@ -2,8 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-export class WebsocketClosedError extends Error {
+export class EdgeConnectionClosedError extends Error {
   constructor() {
-    super('WebSocket connection closed');
+    super('Edge connection closed.');
+  }
+}
+
+export class EdgeIdentityChangedError extends Error {
+  constructor() {
+    super('Edge identity changed.');
   }
 }

package/src/index.ts

@@ -7,3 +7,7 @@ export * from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 export * from './edge-client';
 export * from './defs';
 export * from './protocol';
+export * from './errors';
+export * from './auth';
+export * from './edge-http-client';
+export * from './edge-identity';

package/src/persistent-lifecycle.test.ts

@@ -2,11 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
+import { describe, expect, test } from 'vitest';
 
 import { sleep, Trigger } from '@dxos/async';
 import { log } from '@dxos/log';
-import { describe, openAndClose, test } from '@dxos/test';
+import { openAndClose } from '@dxos/test-utils';
 
 import { PersistentLifecycle } from './persistent-lifecycle';
 

package/src/protocol.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
+import { describe, expect, test } from 'vitest';
 
 import { buf } from '@dxos/protocols/buf';
 import {
@@ -11,7 +11,6 @@ import {
   SwarmRequestSchema,
   SwarmResponseSchema,
 } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
-import { describe, test } from '@dxos/test';
 
 import { Protocol } from './protocol';
 

package/src/protocol.ts

@@ -4,10 +4,10 @@
 
 import { invariant } from '@dxos/invariant';
 import { buf, bufWkt } from '@dxos/protocols/buf';
-import { type Message, MessageSchema, type Peer as PeerProto } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { type Message, MessageSchema, type PeerSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 import { bufferToArray } from '@dxos/util';
 
-export type PeerData = Partial<PeerProto>;
+export type PeerData = buf.MessageInitShape<typeof PeerSchema>;
 
 export const getTypename = (typeName: string) => `type.googleapis.com/${typeName}`;
 

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './test-utils';

package/src/testing/test-utils.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import WebSocket from 'isomorphic-ws';
+
+import { Trigger } from '@dxos/async';
+import { log } from '@dxos/log';
+import { buf } from '@dxos/protocols/buf';
+import { MessageSchema, TextMessageSchema, type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+
+import { protocol } from '../defs';
+import { toUint8Array } from '../protocol';
+
+export const DEFAULT_PORT = 8080;
+
+type TestEdgeWsServerParams = {
+  admitConnection?: Trigger;
+  payloadDecoder?: (payload: Uint8Array) => any;
+  messageHandler?: (payload: any) => Promise<Uint8Array | undefined>;
+};
+
+export const createTestEdgeWsServer = async (port = DEFAULT_PORT, params?: TestEdgeWsServerParams) => {
+  const server = new WebSocket.Server({ port, verifyClient: createConnectionDelayHandler(params) });
+
+  let connection: WebSocket | undefined;
+
+  const messageSink: any[] = [];
+  const closeTrigger = new Trigger();
+  const sendResponseMessage = createResponseSender(() => connection!);
+
+  server.on('connection', (ws) => {
+    connection = ws;
+    ws.on('error', (err) => log.catch(err));
+    ws.on('message', async (data) => {
+      if (String(data) === '__ping__') {
+        ws.send('__pong__');
+        return;
+      }
+      const { request, requestPayload } = await decodeRequest(params, data);
+      if (params?.messageHandler) {
+        const responsePayload = await params.messageHandler(requestPayload);
+        if (responsePayload && connection) {
+          sendResponseMessage(request, responsePayload);
+        }
+      }
+      log('message', { payload: requestPayload });
+      messageSink.push(requestPayload);
+    });
+
+    ws.on('close', () => {
+      connection = undefined;
+      closeTrigger.wake();
+    });
+  });
+
+  return {
+    server,
+    messageSink,
+    endpoint: `ws://localhost:${port}`,
+    cleanup: () => server.close(),
+    currentConnection: () => connection,
+    sendResponseMessage,
+    sendMessage: (msg: Message) => {
+      connection!.send(buf.toBinary(MessageSchema, msg));
+    },
+    closeConnection: () => {
+      closeTrigger.reset();
+      connection!.close(1011);
+      return closeTrigger.wait();
+    },
+  };
+};
+
+const createConnectionDelayHandler = (params: TestEdgeWsServerParams | undefined) => {
+  return (_: any, callback: (admit: boolean) => void) => {
+    if (params?.admitConnection) {
+      log('delaying edge connection admission');
+      void params.admitConnection.wait().then(() => {
+        callback(true);
+        log('edge connection admitted');
+      });
+    } else {
+      callback(true);
+    }
+  };
+};
+
+const createResponseSender = (connection: () => WebSocket) => {
+  return (request: Message, responsePayload: Uint8Array) => {
+    const recipient = request.source!;
+    connection().send(
+      buf.toBinary(
+        MessageSchema,
+        buf.create(MessageSchema, {
+          source: {
+            identityKey: recipient.identityKey,
+            peerKey: recipient.peerKey,
+          },
+          serviceId: request.serviceId!,
+          payload: { value: responsePayload },
+        }),
+      ),
+    );
+  };
+};
+
+const decodeRequest = async (params: TestEdgeWsServerParams | undefined, data: any) => {
+  const request = buf.fromBinary(MessageSchema, await toUint8Array(data));
+  const requestPayload = params?.payloadDecoder
+    ? params.payloadDecoder(request.payload!.value!)
+    : protocol.getPayload(request, TextMessageSchema);
+  return { request, requestPayload };
+};

package/src/utils.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export const getEdgeUrlWithProtocol = (baseUrl: string, protocol: 'http' | 'ws') => {
+  const isSecure = baseUrl.startsWith('https') || baseUrl.startsWith('wss');
+  const url = new URL(baseUrl);
+  url.protocol = protocol + (isSecure ? 's' : '');
+  return url.toString();
+};

package/src/websocket.test.ts

@@ -2,17 +2,18 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
 import WebSocket from 'isomorphic-ws';
+import { describe, expect, test, onTestFinished } from 'vitest';
 
 import { Trigger, TriggerState } from '@dxos/async';
-import { describe, test } from '@dxos/test';
 
-import { createTestWsServer } from './test-utils';
+import { createTestEdgeWsServer } from './testing';
 
 describe('WebSocket', () => {
   test('swap `onclose` handler ', async () => {
-    const { endpoint } = await createTestWsServer();
+    const { endpoint, cleanup } = await createTestEdgeWsServer(8003);
+    onTestFinished(cleanup);
+
     const ws = new WebSocket(endpoint);
     const opened = new Trigger();
     ws.onopen = () => {

package/dist/types/src/test-utils.d.ts

@@ -1,11 +0,0 @@
-import WebSocket from 'isomorphic-ws';
-export declare const DEFAULT_PORT = 8080;
-export declare const createTestWsServer: (port?: number) => Promise<{
-    server: WebSocket.Server;
-    /**
-     * Close the server connection.
-     */
-    error: () => Promise<void>;
-    endpoint: string;
-}>;
-//# sourceMappingURL=test-utils.d.ts.map

package/dist/types/src/test-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-utils.d.ts","sourceRoot":"","sources":["../../../src/test-utils.ts"],"names":[],"mappings":"AAIA,OAAO,SAAS,MAAM,eAAe,CAAC;AAWtC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,eAAO,MAAM,kBAAkB;;IAsB3B;;OAEG;;;EAON,CAAC"}

package/src/test-utils.ts

@@ -1,49 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import WebSocket from 'isomorphic-ws';
-
-import { Trigger } from '@dxos/async';
-import { log } from '@dxos/log';
-import { buf } from '@dxos/protocols/buf';
-import { MessageSchema, TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
-import { afterTest } from '@dxos/test';
-
-import { protocol } from './defs';
-import { toUint8Array } from './protocol';
-
-export const DEFAULT_PORT = 8080;
-
-export const createTestWsServer = async (port = DEFAULT_PORT) => {
-  const server = new WebSocket.Server({ port });
-  let connection: WebSocket;
-  const closeTrigger = new Trigger();
-  server.on('connection', (ws) => {
-    connection = ws;
-    ws.on('error', (err) => log.catch(err));
-    ws.on('message', async (data) => {
-      if (String(data) === '__ping__') {
-        ws.send('__pong__');
-        return;
-      }
-      log('message', {
-        payload: protocol.getPayload(buf.fromBinary(MessageSchema, await toUint8Array(data)), TextMessageSchema),
-      });
-    });
-    ws.on('close', () => closeTrigger.wake());
-  });
-
-  afterTest(() => server.close());
-  return {
-    server,
-    /**
-     * Close the server connection.
-     */
-    error: async () => {
-      connection.close(1011);
-      await closeTrigger.wait();
-    },
-    endpoint: `ws://localhost:${port}`,
-  };
-};