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

package/src/packlets/invitations/edge-invitation-handler.ts

@@ -0,0 +1,185 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type MutexGuard, scheduleMicroTask, scheduleTask } from '@dxos/async';
+import { type Context } from '@dxos/context';
+import { sign } from '@dxos/crypto';
+import { type EdgeHttpClient } from '@dxos/edge-client';
+import { invariant } from '@dxos/invariant';
+import { SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import {
+  EdgeAuthChallengeError,
+  EdgeCallFailedError,
+  type JoinSpaceRequest,
+  type JoinSpaceResponseBody,
+} from '@dxos/protocols';
+import { schema } from '@dxos/protocols/proto';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+import { type DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
+import {
+  type AdmissionResponse,
+  type AdmissionRequest,
+  type SpaceAdmissionRequest,
+} from '@dxos/protocols/proto/dxos/halo/invitations';
+
+import { type InvitationProtocol } from './invitation-protocol';
+import { type FlowLockHolder, type GuardedInvitationState } from './invitation-state';
+import { tryAcquireBeforeContextDisposed } from './utils';
+
+export interface EdgeInvitationHandlerCallbacks {
+  onInvitationSuccess(response: AdmissionResponse, request: AdmissionRequest): Promise<void>;
+}
+
+export const DEFAULT_REQUEST_RETRY_INTERVAL_MS = 3000;
+export const DEFAULT_REQUEST_RETRY_JITTER_MS = 500;
+
+export type EdgeInvitationConfig = {
+  retryInterval?: number;
+  retryJitter?: number;
+};
+
+export class EdgeInvitationHandler implements FlowLockHolder {
+  private _flowLock: MutexGuard | undefined;
+
+  private readonly _retryInterval: number;
+  private readonly _retryJitter: number;
+
+  constructor(
+    config: EdgeInvitationConfig | undefined,
+    private readonly _client: EdgeHttpClient | undefined,
+    private readonly _callbacks: EdgeInvitationHandlerCallbacks,
+  ) {
+    this._retryInterval = config?.retryInterval ?? DEFAULT_REQUEST_RETRY_INTERVAL_MS;
+    this._retryJitter = config?.retryJitter ?? DEFAULT_REQUEST_RETRY_JITTER_MS;
+  }
+
+  public handle(
+    ctx: Context,
+    guardedState: GuardedInvitationState,
+    protocol: InvitationProtocol,
+    deviceProfile?: DeviceProfileDocument,
+  ) {
+    if (!this._client) {
+      log('edge disabled');
+      return;
+    }
+
+    const invitation = guardedState.current;
+    const spaceId = invitation.spaceId;
+    const canBeHandledByEdge =
+      invitation.authMethod !== Invitation.AuthMethod.SHARED_SECRET &&
+      invitation.type === Invitation.Type.DELEGATED &&
+      invitation.kind === Invitation.Kind.SPACE &&
+      spaceId != null &&
+      SpaceId.isValid(spaceId);
+
+    if (!canBeHandledByEdge) {
+      log('invitation could not be handled by edge', { invitation });
+      return;
+    }
+
+    ctx.onDispose(() => {
+      this._flowLock?.release();
+      this._flowLock = undefined;
+    });
+
+    const tryHandleInvitation = async () => {
+      const admissionRequest = await protocol.createAdmissionRequest(deviceProfile);
+      if (admissionRequest.space) {
+        try {
+          await this._handleSpaceInvitationFlow(ctx, guardedState, admissionRequest.space, spaceId);
+        } catch (error) {
+          if (error instanceof EdgeCallFailedError) {
+            log.info('join space with edge unsuccessful', {
+              reason: error.message,
+              retryable: error.isRetryable,
+              after: error.retryAfterMs ?? this._calculateNextRetryMs(),
+            });
+            if (error.isRetryable) {
+              scheduleTask(ctx, tryHandleInvitation, error.retryAfterMs ?? this._calculateNextRetryMs());
+            }
+          } else {
+            log.info('failed to handle invitation with edge', { error });
+            scheduleTask(ctx, tryHandleInvitation, this._calculateNextRetryMs());
+          }
+        }
+      }
+    };
+    scheduleMicroTask(ctx, tryHandleInvitation);
+  }
+
+  private async _handleSpaceInvitationFlow(
+    ctx: Context,
+    guardedState: GuardedInvitationState,
+    admissionRequest: SpaceAdmissionRequest,
+    spaceId: SpaceId,
+  ) {
+    try {
+      log('edge invitation flow');
+      this._flowLock = await tryAcquireBeforeContextDisposed(ctx, guardedState.mutex);
+      log('edge invitation flow acquired the lock');
+
+      guardedState.set(this, Invitation.State.CONNECTING);
+
+      const response = await this._joinSpaceByInvitation(guardedState, spaceId, {
+        identityKey: admissionRequest.identityKey.toHex(),
+        invitationId: guardedState.current.invitationId,
+      });
+
+      const admissionResponse = await this._mapToAdmissionResponse(response);
+      await this._callbacks.onInvitationSuccess(admissionResponse, { space: admissionRequest });
+    } catch (error) {
+      guardedState.set(this, Invitation.State.ERROR);
+      throw error;
+    } finally {
+      this._flowLock?.release();
+      this._flowLock = undefined;
+    }
+  }
+
+  private async _mapToAdmissionResponse(edgeResponse: JoinSpaceResponseBody): Promise<AdmissionResponse> {
+    const credentialBytes = Buffer.from(edgeResponse.spaceMemberCredential, 'base64');
+    const codec = schema.getCodecForType('dxos.halo.credentials.Credential');
+    return {
+      space: {
+        credential: codec.decode(credentialBytes),
+      },
+    };
+  }
+
+  private async _joinSpaceByInvitation(
+    guardedState: GuardedInvitationState,
+    spaceId: SpaceId,
+    request: JoinSpaceRequest,
+  ): Promise<JoinSpaceResponseBody> {
+    invariant(this._client);
+    try {
+      return await this._client.joinSpaceByInvitation(spaceId, request);
+    } catch (error: any) {
+      if (error instanceof EdgeAuthChallengeError) {
+        const publicKey = guardedState.current.guestKeypair?.publicKey;
+        const privateKey = guardedState.current.guestKeypair?.privateKey;
+        if (!privateKey || !publicKey) {
+          throw error;
+        }
+        const signature = sign(Buffer.from(error.challenge, 'base64'), privateKey);
+        return this._client.joinSpaceByInvitation(spaceId, {
+          ...request,
+          signature: Buffer.from(signature).toString('base64'),
+        });
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  public hasFlowLock(): boolean {
+    return this._flowLock != null;
+  }
+
+  private _calculateNextRetryMs() {
+    return this._retryInterval + Math.random() * this._retryJitter;
+  }
+}

package/src/packlets/invitations/invitation-guest-extenstion.ts

@@ -12,6 +12,7 @@ import { type Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type InvitationHostService, InvitationOptions } from '@dxos/protocols/proto/dxos/halo/invitations';
 import { type ExtensionContext, RpcExtension } from '@dxos/teleport';
 
+import { type FlowLockHolder } from './invitation-state';
 import { tryAcquireBeforeContextDisposed } from './utils';
 
 const OPTIONS_TIMEOUT = 10_000;
@@ -27,10 +28,13 @@ type InvitationGuestExtensionCallbacks = {
 /**
  * Guest's side for a connection to a concrete peer in p2p network during invitation.
  */
-export class InvitationGuestExtension extends RpcExtension<
-  { InvitationHostService: InvitationHostService },
-  { InvitationHostService: InvitationHostService }
-> {
+export class InvitationGuestExtension
+  extends RpcExtension<
+    { InvitationHostService: InvitationHostService },
+    { InvitationHostService: InvitationHostService }
+  >
+  implements FlowLockHolder
+{
   private _ctx = new Context();
   private _remoteOptions?: InvitationOptions;
   private _remoteOptionsTrigger = new Trigger();

package/src/packlets/invitations/invitation-host-extension.ts

@@ -21,6 +21,7 @@ import {
 } from '@dxos/protocols/proto/dxos/halo/invitations';
 import { type ExtensionContext, RpcExtension } from '@dxos/teleport';
 
+import type { FlowLockHolder } from './invitation-state';
 import { stateToString, tryAcquireBeforeContextDisposed } from './utils';
 
 /// Timeout for the options exchange.
@@ -43,10 +44,13 @@ type InvitationHostExtensionCallbacks = {
 /**
  * Host's side for a connection to a concrete peer in p2p network during invitation.
  */
-export class InvitationHostExtension extends RpcExtension<
-  { InvitationHostService: InvitationHostService },
-  { InvitationHostService: InvitationHostService }
-> {
+export class InvitationHostExtension
+  extends RpcExtension<
+    { InvitationHostService: InvitationHostService },
+    { InvitationHostService: InvitationHostService }
+  >
+  implements FlowLockHolder
+{
   /**
    * @internal
    */
@@ -106,13 +110,11 @@ export class InvitationHostExtension extends RpcExtension<
 
         introduce: async (request) => {
           const { profile, invitationId } = request;
-
           const traceId = PublicKey.random().toHex();
           log.trace('dxos.sdk.invitation-handler.host.introduce', trace.begin({ id: traceId }));
 
           const invitation = this._requireActiveInvitation();
           this._assertInvitationState(Invitation.State.CONNECTED);
-
           if (invitationId !== invitation?.invitationId) {
             log.warn('incorrect invitationId', { expected: invitation.invitationId, actual: invitationId });
             this._callbacks.onError(new Error('Incorrect invitationId.'));
@@ -126,7 +128,6 @@ export class InvitationHostExtension extends RpcExtension<
           log('guest introduced themselves', { guestProfile: profile });
           this.guestProfile = profile;
           this._callbacks.onStateUpdate(Invitation.State.READY_FOR_AUTHENTICATION);
-
           this._challenge =
             invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? randomBytes(32) : undefined;
 

package/src/packlets/invitations/invitation-state.ts

@@ -0,0 +1,112 @@
+/**
+ * A utility object for serializing invitation state changes by multiple concurrent
+ * invitation flow connections.
+ */
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Mutex, type PushStream } from '@dxos/async';
+import { type Context } from '@dxos/context';
+import { log } from '@dxos/log';
+import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
+
+import { stateToString } from './utils';
+
+export interface FlowLockHolder {
+  hasFlowLock(): boolean;
+}
+
+export interface GuardedInvitationState {
+  mutex: Mutex;
+  current: Invitation;
+
+  complete(newState: Partial<Invitation>): void;
+  set(lockHolder: FlowLockHolder | null, newState: Invitation.State): boolean;
+  error(lockHolder: FlowLockHolder | null, error: any): boolean;
+}
+
+export const createGuardedInvitationState = (
+  ctx: Context,
+  invitation: Invitation,
+  stream: PushStream<Invitation>,
+): GuardedInvitationState => {
+  // the mutex guards invitation flow on host and guest side, making sure only one flow is currently active
+  // deadlocks seem very unlikely because hosts don't initiate multiple connections
+  // even if this somehow happens that there are 2 guests (A, B) and 2 hosts (1, 2) and:
+  //  A has lock for flow with 1, B has lock for flow with 2
+  //  1 has lock for flow with B, 2 has lock for flow with A
+  // there'll be a 10-second introduction timeout after which connection will be closed and deadlock broken
+  const mutex = new Mutex();
+  let lastActiveLockHolder: FlowLockHolder | null = null;
+  let currentInvitation = { ...invitation };
+  const isStateChangeAllowed = (lockHolder: FlowLockHolder | null) => {
+    if (ctx.disposed || (lockHolder !== null && mutex.isLocked() && !lockHolder.hasFlowLock())) {
+      return false;
+    }
+    // don't allow transitions from a terminal state unless a new extension acquired mutex
+    // handles a case when error occurs (e.g. connection is closed) after we completed the flow
+    // successfully or already reported another error
+    return lockHolder == null || lastActiveLockHolder !== lockHolder || isNonTerminalState(currentInvitation.state);
+  };
+  return {
+    mutex,
+    get current() {
+      return currentInvitation;
+    },
+    // disposing context prevents any further state updates
+    complete: (newState: Partial<Invitation>) => {
+      logStateUpdate(currentInvitation, undefined, invitation.state);
+      currentInvitation = { ...currentInvitation, ...newState };
+      stream.next(currentInvitation);
+      return ctx.dispose();
+    },
+    set: (lockHolder: FlowLockHolder | null, newState: Invitation.State): boolean => {
+      if (isStateChangeAllowed(lockHolder)) {
+        logStateUpdate(currentInvitation, lockHolder, newState);
+        currentInvitation = { ...currentInvitation, state: newState };
+        stream.next(currentInvitation);
+        lastActiveLockHolder = lockHolder;
+        return true;
+      }
+      return false;
+    },
+    error: (lockHolder: FlowLockHolder | null, error: any): boolean => {
+      if (isStateChangeAllowed(lockHolder)) {
+        logStateUpdate(currentInvitation, lockHolder, Invitation.State.ERROR, error);
+        currentInvitation = { ...currentInvitation, state: Invitation.State.ERROR };
+        stream.next(currentInvitation);
+        stream.error(error);
+        lastActiveLockHolder = lockHolder;
+        return true;
+      }
+      return false;
+    },
+  };
+};
+
+const logStateUpdate = (invitation: Invitation, actor: any, newState: Invitation.State, error?: Error) => {
+  const logContext = {
+    invitationId: invitation.invitationId,
+    actor: actor?.constructor.name,
+    newState: stateToString(newState),
+    oldState: stateToString(invitation.state),
+    error: error?.message,
+    errorStack: error?.stack,
+  };
+  if (isNonTerminalState(newState)) {
+    log.verbose('dxos.sdk.invitations-handler.state.update', logContext);
+  } else {
+    log.info('dxos.sdk.invitations-handler.state.update', logContext);
+  }
+};
+
+const isNonTerminalState = (currentState: Invitation.State): boolean => {
+  return ![
+    Invitation.State.SUCCESS,
+    Invitation.State.ERROR,
+    Invitation.State.CANCELLED,
+    Invitation.State.TIMEOUT,
+    Invitation.State.EXPIRED,
+  ].includes(currentState);
+};

package/src/packlets/invitations/invitations-handler.test.ts

@@ -2,13 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
+import { beforeEach, onTestFinished, describe, expect, test } from 'vitest';
 
 import { type PushStream, sleep, Trigger, waitForCondition } from '@dxos/async';
 import { Context } from '@dxos/context';
 import { PublicKey } from '@dxos/keys';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
-import { afterTest, describe, openAndClose, test } from '@dxos/test';
+import { openAndClose } from '@dxos/test-utils';
 import { range } from '@dxos/util';
 
 import { type InvitationProtocol } from './invitation-protocol';
@@ -34,6 +34,7 @@ type StateUpdateSink = PushStream<Invitation> & {
 
 describe('InvitationHandler', () => {
   let testBuilder: TestBuilder;
+
   beforeEach(() => {
     testBuilder = new TestBuilder();
   });
@@ -163,7 +164,7 @@ describe('InvitationHandler', () => {
       expect(guest.ctx.disposed).to.be.true;
     });
 
-    test('guest gives up after trying with three hosts', async () => {
+    test('guest gives up after trying with three hosts', { timeout: 20_000 }, async () => {
       const hosts: PeerSetup[] = [await createPeer()];
       const [host] = hosts;
       const invitation = await createInvitation(host, { multiUse: true });
@@ -181,7 +182,7 @@ describe('InvitationHandler', () => {
 
       await sleep(10);
       expect(guest.sink.lastState).to.eq(Invitation.State.ERROR);
-    }).timeout(20_000);
+    });
 
     test('single host - many guests', async () => {
       const hosts: PeerSetup[] = [await createPeer()];
@@ -256,12 +257,14 @@ describe('InvitationHandler', () => {
       const space = await peer.dataSpaceManager.createSpace();
       spaceKey = space.key;
     }
-    const invitationHandler = new InvitationsHandler(peer.networkManager, {
-      controlHeartbeatInterval: 250, // faster peer failure detection
+    const invitationHandler = new InvitationsHandler(peer.networkManager, undefined, {
+      teleport: { controlHeartbeatInterval: 250 }, // faster peer failure detection
     });
     const protocol = new SpaceInvitationProtocol(peer.dataSpaceManager, peer.identity, peer.keyring, spaceKey);
     const ctx = new Context();
-    afterTest(() => ctx.dispose());
+    onTestFinished(async () => {
+      await ctx.dispose();
+    });
     const sink = newStateUpdateSink();
     return { ctx, sink, peer, protocol, handler: invitationHandler, spaceKey };
   };
@@ -269,14 +272,18 @@ describe('InvitationHandler', () => {
   const hostInvitation = async (setup: PeerSetup, invitation: Invitation) => {
     await setup.ctx.dispose();
     setup.ctx = new Context();
-    afterTest(() => setup.ctx.dispose());
+    onTestFinished(async () => {
+      await setup.ctx.dispose();
+    });
     setup.handler.handleInvitationFlow(setup.ctx, setup.sink, setup.protocol, invitation);
   };
 
   const acceptInvitation = async (setup: PeerSetup, invitation: Invitation): Promise<Trigger<string>> => {
     await setup.ctx.dispose();
     setup.ctx = new Context();
-    afterTest(() => setup.ctx.dispose());
+    onTestFinished(async () => {
+      await setup.ctx.dispose();
+    });
     const authCodeInput = new Trigger<string>();
     setup.handler.acceptInvitation(setup.ctx, setup.sink, setup.protocol, invitation, authCodeInput);
     return authCodeInput;