@dxos/edge-client 0.6.13 → 0.6.14-main.1366248

package/src/edge-client.ts

@@ -2,34 +2,33 @@
 // Copyright 2024 DXOS.org
 //
 
-import WebSocket from 'isomorphic-ws';
-
-import { Trigger, Event, scheduleTaskInterval, scheduleTask, TriggerState } from '@dxos/async';
-import { Context, LifecycleState, Resource, type Lifecycle } from '@dxos/context';
-import { invariant } from '@dxos/invariant';
-import { log } from '@dxos/log';
-import { buf } from '@dxos/protocols/buf';
-import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { Trigger, scheduleMicroTask, TriggerState } from '@dxos/async';
+import { Resource, type Lifecycle } from '@dxos/context';
+import { log, logInfo } from '@dxos/log';
+import { type Message } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';
-import { WebsocketClosedError } from './errors';
+import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
+import { EdgeWsConnection } from './edge-ws-connection';
+import { EdgeConnectionClosedError, EdgeIdentityChangedError } from './errors';
 import { PersistentLifecycle } from './persistent-lifecycle';
-import { type Protocol, toUint8Array } from './protocol';
+import { type Protocol } from './protocol';
+import { getEdgeUrlWithProtocol } from './utils';
 
 const DEFAULT_TIMEOUT = 10_000;
-const SIGNAL_KEEPALIVE_INTERVAL = 5_000;
 
-export type MessageListener = (message: Message) => void | Promise<void>;
+export type MessageListener = (message: Message) => void;
+export type ReconnectListener = () => void;
 
 export interface EdgeConnection extends Required<Lifecycle> {
-  reconnect: Event;
-
   get info(): any;
   get identityKey(): string;
   get peerKey(): string;
   get isOpen(): boolean;
-  setIdentity(params: { peerKey: string; identityKey: string }): void;
-  addListener(listener: MessageListener): () => void;
+  get isConnected(): boolean;
+  setIdentity(identity: EdgeIdentity): void;
+  onMessage(listener: MessageListener): () => void;
+  onReconnected(listener: ReconnectListener): () => void;
   send(message: Message): Promise<void>;
 }
 
@@ -37,61 +36,90 @@ export type MessengerConfig = {
   socketEndpoint: string;
   timeout?: number;
   protocol?: Protocol;
+  disableAuth?: boolean;
 };
 
 /**
- * Messenger client.
+ * Messenger client for EDGE:
+ *  - While open, uses PersistentLifecycle to keep an open EdgeWsConnection, reconnecting on failures.
+ *  - Manages identity and re-create EdgeWsConnection when identity changes.
+ *  - Dispatches connection state and message notifications.
  */
 export class EdgeClient extends Resource implements EdgeConnection {
-  public reconnect = new Event();
-  private readonly _persistentLifecycle = new PersistentLifecycle({
-    start: async () => this._openWebSocket(),
-    stop: async () => this._closeWebSocket(),
-    onRestart: async () => this.reconnect.emit(),
+  private readonly _persistentLifecycle = new PersistentLifecycle<EdgeWsConnection>({
+    start: async () => this._connect(),
+    stop: async (state: EdgeWsConnection) => this._disconnect(state),
   });
 
-  private readonly _listeners = new Set<MessageListener>();
-  private readonly _protocol: Protocol;
+  private readonly _messageListeners = new Set<MessageListener>();
+  private readonly _reconnectListeners = new Set<ReconnectListener>();
+
+  private readonly _baseWsUrl: string;
+  private readonly _baseHttpUrl: string;
+
+  private _currentConnection?: EdgeWsConnection = undefined;
   private _ready = new Trigger();
-  private _ws?: WebSocket = undefined;
-  private _keepaliveCtx?: Context = undefined;
-  private _heartBeatContext?: Context = undefined;
 
   constructor(
-    private _identityKey: string,
-    private _peerKey: string,
+    private _identity: EdgeIdentity,
     private readonly _config: MessengerConfig,
   ) {
     super();
-    this._protocol = this._config.protocol ?? protocol;
+    this._baseWsUrl = getEdgeUrlWithProtocol(_config.socketEndpoint, 'ws');
+    this._baseHttpUrl = getEdgeUrlWithProtocol(_config.socketEndpoint, 'http');
   }
 
-  // TODO(burdon): Attach logging.
+  @logInfo
   public get info() {
     return {
       open: this.isOpen,
-      identity: this._identityKey,
-      device: this._peerKey,
+      identity: this._identity.identityKey,
+      device: this._identity.peerKey,
     };
   }
 
+  get isConnected() {
+    return Boolean(this._currentConnection) && this._ready.state === TriggerState.RESOLVED;
+  }
+
   get identityKey() {
-    return this._identityKey;
+    return this._identity.identityKey;
   }
 
   get peerKey() {
-    return this._peerKey;
+    return this._identity.peerKey;
   }
 
-  setIdentity({ peerKey, identityKey }: { peerKey: string; identityKey: string }) {
-    this._peerKey = peerKey;
-    this._identityKey = identityKey;
-    this._persistentLifecycle.scheduleRestart();
+  setIdentity(identity: EdgeIdentity) {
+    if (identity.identityKey !== this._identity.identityKey || identity.peerKey !== this._identity.peerKey) {
+      log('Edge identity changed', { identity, oldIdentity: this._identity });
+      this._identity = identity;
+      this._closeCurrentConnection(new EdgeIdentityChangedError());
+      this._persistentLifecycle.scheduleRestart();
+    }
   }
 
-  public addListener(listener: MessageListener): () => void {
-    this._listeners.add(listener);
-    return () => this._listeners.delete(listener);
+  public onMessage(listener: MessageListener): () => void {
+    this._messageListeners.add(listener);
+    return () => this._messageListeners.delete(listener);
+  }
+
+  public onReconnected(listener: () => void): () => void {
+    this._reconnectListeners.add(listener);
+    if (this._ready.state === TriggerState.RESOLVED) {
+      // Microtask so that listener is always called asynchronously, no matter the state of the ready trigger
+      // at the moment of registration.
+      scheduleMicroTask(this._ctx, () => {
+        if (this._reconnectListeners.has(listener)) {
+          try {
+            listener();
+          } catch (error) {
+            log.catch(error);
+          }
+        }
+      });
+    }
+    return () => this._reconnectListeners.delete(listener);
   }
 
   /**
@@ -108,86 +136,97 @@ export class EdgeClient extends Resource implements EdgeConnection {
    * Close connection and free resources.
    */
   protected override async _close() {
-    log('closing...', { peerKey: this._peerKey });
+    log('closing...', { peerKey: this._identity.peerKey });
+    this._closeCurrentConnection();
     await this._persistentLifecycle.close();
   }
 
-  private async _openWebSocket() {
-    const url = new URL(`/ws/${this._identityKey}/${this._peerKey}`, this._config.socketEndpoint);
-    this._ws = new WebSocket(url);
+  private async _connect(): Promise<EdgeWsConnection | undefined> {
+    if (this._ctx.disposed) {
+      return undefined;
+    }
 
-    this._ws.onopen = () => {
-      log('opened', this.info);
-      this._ready.wake();
-    };
-    this._ws.onclose = () => {
-      log('closed', this.info);
-      this._persistentLifecycle.scheduleRestart();
-    };
-    this._ws.onerror = (event) => {
-      log.warn('EdgeClient socket error', { error: event.error, info: event.message });
-      this._persistentLifecycle.scheduleRestart();
-    };
-    /**
-     * https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/data
-     */
-    this._ws.onmessage = async (event) => {
-      if (event.data === '__pong__') {
-        this._onHeartbeat();
-        return;
-      }
-      const data = await toUint8Array(event.data);
-      const message = buf.fromBinary(MessageSchema, data);
-      log('received', { peerKey: this._peerKey, payload: protocol.getPayloadType(message) });
-      if (message) {
-        for (const listener of this._listeners) {
-          try {
-            await listener(message);
-          } catch (err) {
-            log.error('processing', { err, payload: protocol.getPayloadType(message) });
-          }
-        }
-      }
-    };
+    const identity = this._identity;
+    const path = `/ws/${identity.identityKey}/${identity.peerKey}`;
+    const protocolHeader = this._config.disableAuth ? undefined : await this._createAuthHeader(path);
+    if (this._identity !== identity) {
+      log('identity changed during auth header request');
+      return undefined;
+    }
 
-    await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
-    this._keepaliveCtx = new Context();
-    scheduleTaskInterval(
-      this._keepaliveCtx,
-      async () => {
-        // TODO(mykola): use RFC6455 ping/pong once implemented in the browser?
-        // Cloudflare's worker responds to this `without interrupting hibernation`. https://developers.cloudflare.com/durable-objects/api/websockets/#setwebsocketautoresponse
-        this._ws?.send('__ping__');
+    const restartRequired = new Trigger();
+    const url = new URL(path, this._baseWsUrl);
+    log('Opening websocket', { url: url.toString(), protocolHeader });
+    const connection = new EdgeWsConnection(
+      identity,
+      { url, protocolHeader },
+      {
+        onConnected: () => {
+          if (this._isActive(connection)) {
+            this._ready.wake();
+            this._notifyReconnected();
+          } else {
+            log.verbose('connected callback ignored, because connection is not active');
+          }
+        },
+        onRestartRequired: () => {
+          if (this._isActive(connection)) {
+            this._closeCurrentConnection();
+            this._persistentLifecycle.scheduleRestart();
+          } else {
+            log.verbose('restart requested by inactive connection');
+          }
+          restartRequired.wake();
+        },
+        onMessage: (message) => {
+          if (this._isActive(connection)) {
+            this._notifyMessageReceived(message);
+          } else {
+            log.verbose('ignored a message on inactive connection', {
+              from: message.source,
+              type: message.payload?.typeUrl,
+            });
+          }
+        },
       },
-      SIGNAL_KEEPALIVE_INTERVAL,
     );
-    this._ws.send('__ping__');
-    this._onHeartbeat();
+    this._currentConnection = connection;
+
+    await connection.open();
+    // Race with restartRequired so that restart is not blocked by _connect execution.
+    // Wait on ready to attempt a reconnect if it times out.
+    await Promise.race([this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT }), restartRequired]);
+
+    return connection;
+  }
+
+  private async _disconnect(state: EdgeWsConnection) {
+    await state.close();
   }
 
-  private async _closeWebSocket() {
-    if (!this._ws) {
-      return;
+  private _closeCurrentConnection(error: Error = new EdgeConnectionClosedError()) {
+    this._currentConnection = undefined;
+    this._ready.throw(error);
+    this._ready.reset();
+  }
+
+  private _notifyReconnected() {
+    for (const listener of this._reconnectListeners) {
+      try {
+        listener();
+      } catch (err) {
+        log.error('ws reconnect listener failed', { err });
+      }
     }
-    try {
-      this._ready.throw(new WebsocketClosedError());
-      this._ready.reset();
-      void this._keepaliveCtx?.dispose();
-      this._keepaliveCtx = undefined;
-      void this._heartBeatContext?.dispose();
-      this._heartBeatContext = undefined;
-
-      // NOTE: Remove event handlers to avoid scheduling restart.
-      this._ws.onopen = () => {};
-      this._ws.onclose = () => {};
-      this._ws.onerror = () => {};
-      this._ws.close();
-      this._ws = undefined;
-    } catch (err) {
-      if (err instanceof Error && err.message.includes('WebSocket is closed before the connection is established.')) {
-        return;
+  }
+
+  private _notifyMessageReceived(message: Message) {
+    for (const listener of this._messageListeners) {
+      try {
+        listener(message);
+      } catch (err) {
+        log.error('ws incoming message processing failed', { err, payload: protocol.getPayloadType(message) });
       }
-      log.warn('Error closing websocket', { err });
     }
   }
 
@@ -197,26 +236,41 @@ export class EdgeClient extends Resource implements EdgeConnection {
    */
   public async send(message: Message): Promise<void> {
     if (this._ready.state !== TriggerState.RESOLVED) {
+      log('waiting for websocket to become ready');
       await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
     }
-    invariant(this._ws);
-    invariant(!message.source || message.source.peerKey === this._peerKey);
-    log('sending...', { peerKey: this._peerKey, payload: protocol.getPayloadType(message) });
-    this._ws.send(buf.toBinary(MessageSchema, message));
+
+    if (!this._currentConnection) {
+      throw new EdgeConnectionClosedError();
+    }
+
+    if (
+      message.source &&
+      (message.source.peerKey !== this._identity.peerKey || message.source.identityKey !== this.identityKey)
+    ) {
+      throw new EdgeIdentityChangedError();
+    }
+
+    this._currentConnection.send(message);
   }
 
-  private _onHeartbeat() {
-    if (this._lifecycleState !== LifecycleState.OPEN) {
-      return;
+  private async _createAuthHeader(path: string): Promise<string | undefined> {
+    const httpUrl = new URL(path, this._baseHttpUrl);
+    httpUrl.protocol = getEdgeUrlWithProtocol(this._baseWsUrl.toString(), 'http');
+    const response = await fetch(httpUrl, { method: 'GET' });
+    if (response.status === 401) {
+      return encodePresentationWsAuthHeader(await handleAuthChallenge(response, this._identity));
+    } else {
+      log.warn('no auth challenge from edge', { status: response.status, statusText: response.statusText });
+      return undefined;
     }
-    void this._heartBeatContext?.dispose();
-    this._heartBeatContext = new Context();
-    scheduleTask(
-      this._heartBeatContext,
-      () => {
-        this._persistentLifecycle.scheduleRestart();
-      },
-      2 * SIGNAL_KEEPALIVE_INTERVAL,
-    );
   }
+
+  private _isActive = (connection: EdgeWsConnection) => connection === this._currentConnection;
 }
+
+const encodePresentationWsAuthHeader = (encodedPresentation: Uint8Array): string => {
+  // = and / characters are not allowed in the WebSocket subprotocol header.
+  const encodedToken = Buffer.from(encodedPresentation).toString('base64').replace(/=*$/, '').replaceAll('/', '|');
+  return `base64url.bearer.authorization.dxos.org.${encodedToken}`;
+};

package/src/edge-http-client.ts

@@ -0,0 +1,213 @@
+//
+// 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) {
+    if (this._edgeIdentity?.identityKey !== identity.identityKey || this._edgeIdentity?.peerKey !== identity.peerKey) {
+      this._edgeIdentity = identity;
+      this._authHeader = undefined;
+    }
+  }
+
+  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);
+};