@dxos/client-services 0.8.3 → 0.8.4-main.1c7ec43d41

package/src/packlets/identity/identity.ts

@@ -4,40 +4,38 @@
 
 import { Event } from '@dxos/async';
 import { AUTH_TIMEOUT, LOAD_CONTROL_FEEDS_TIMEOUT } from '@dxos/client-protocol';
-import { type Context } from '@dxos/context';
+import { type Context as DxosContext } from '@dxos/context';
 import {
-  DeviceStateMachine,
   type CredentialSigner,
-  createCredentialSignerWithKey,
-  createCredentialSignerWithChain,
+  DeviceStateMachine,
   ProfileStateMachine,
+  createCredentialSignerWithChain,
+  createCredentialSignerWithKey,
 } from '@dxos/credentials';
 import { type Signer } from '@dxos/crypto';
 import { type Space } from '@dxos/echo-pipeline';
 import { type EdgeConnection } from '@dxos/edge-client';
-import { writeMessages, type FeedWrapper } from '@dxos/feed-store';
+import { type FeedWrapper, writeMessages } from '@dxos/feed-store';
 import { invariant } from '@dxos/invariant';
-import { type IdentityDid, PublicKey, type SpaceId } from '@dxos/keys';
+import { type IdentityDid, PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { type Runtime } from '@dxos/protocols/proto/dxos/config';
 import { type FeedMessage } from '@dxos/protocols/proto/dxos/echo/feed';
 import {
   AdmittedFeed,
+  type Credential,
   type DeviceProfileDocument,
   type ProfileDocument,
-  type Credential,
 } from '@dxos/protocols/proto/dxos/halo/credentials';
 import { type DeviceAdmissionRequest } from '@dxos/protocols/proto/dxos/halo/invitations';
 import { type Presence } from '@dxos/teleport-extension-gossip';
-import { Timeframe } from '@dxos/timeframe';
 import { trace } from '@dxos/tracing';
 import { type ComplexMap, ComplexSet } from '@dxos/util';
 
-import { TrustedKeySetAuthVerifier } from './authenticator';
-import { DefaultSpaceStateMachine } from './default-space-state-machine';
 import { EdgeFeedReplicator } from '../spaces';
+import { TrustedKeySetAuthVerifier } from './authenticator';
 
-export type IdentityParams = {
+export type IdentityProps = {
   did: IdentityDid;
   identityKey: PublicKey;
   deviceKey: PublicKey;
@@ -59,7 +57,6 @@ export class Identity {
   private readonly _presence?: Presence;
   private readonly _deviceStateMachine: DeviceStateMachine;
   private readonly _profileStateMachine: ProfileStateMachine;
-  private readonly _defaultSpaceStateMachine: DefaultSpaceStateMachine;
   private readonly _edgeFeedReplicator?: EdgeFeedReplicator = undefined;
 
   public readonly authVerifier: TrustedKeySetAuthVerifier;
@@ -70,7 +67,7 @@ export class Identity {
 
   public readonly stateUpdate = new Event();
 
-  constructor(params: IdentityParams) {
+  constructor(params: IdentityProps) {
     this.space = params.space;
     this._signer = params.signer;
     this._presence = params.presence;
@@ -90,10 +87,6 @@ export class Identity {
       identityKey: this.identityKey,
       onUpdate: () => this.stateUpdate.emit(),
     });
-    this._defaultSpaceStateMachine = new DefaultSpaceStateMachine({
-      identityKey: this.identityKey,
-      onUpdate: () => this.stateUpdate.emit(),
-    });
 
     this.authVerifier = new TrustedKeySetAuthVerifier({
       trustedKeysProvider: () => new ComplexSet(PublicKey.hash, this.authorizedDeviceKeys.keys()),
@@ -111,32 +104,26 @@ export class Identity {
     return this._deviceStateMachine.authorizedDeviceKeys;
   }
 
-  get defaultSpaceId(): SpaceId | undefined {
-    return this._defaultSpaceStateMachine.spaceId;
-  }
-
-  @trace.span()
-  async open(ctx: Context): Promise<void> {
+  @trace.span({ op: 'lifecycle' })
+  async open(ctx: DxosContext): Promise<void> {
     await this._presence?.open();
     await this.space.spaceState.addCredentialProcessor(this._deviceStateMachine);
     await this.space.spaceState.addCredentialProcessor(this._profileStateMachine);
-    await this.space.spaceState.addCredentialProcessor(this._defaultSpaceStateMachine);
     if (this._edgeFeedReplicator) {
       this.space.protocol.feedAdded.append(this._onFeedAdded);
     }
     await this.space.open(ctx);
   }
 
-  public async joinNetwork(): Promise<void> {
-    await this.space.startProtocol();
+  public async joinNetwork(ctx: DxosContext): Promise<void> {
+    await this.space.startProtocol(ctx);
     await this._edgeFeedReplicator?.open();
   }
 
-  @trace.span()
-  async close(ctx: Context): Promise<void> {
+  @trace.span({ op: 'lifecycle' })
+  async close(ctx: DxosContext): Promise<void> {
     await this._presence?.close();
     await this.authVerifier.close();
-    await this.space.spaceState.removeCredentialProcessor(this._defaultSpaceStateMachine);
     await this.space.spaceState.removeCredentialProcessor(this._profileStateMachine);
     await this.space.spaceState.removeCredentialProcessor(this._deviceStateMachine);
 
@@ -146,7 +133,7 @@ export class Identity {
 
     await this._edgeFeedReplicator?.close();
 
-    await this.space.close();
+    await this.space.close(ctx);
   }
 
   async ready(): Promise<void> {
@@ -210,15 +197,6 @@ export class Identity {
     return createCredentialSignerWithKey(this._signer, this.deviceKey);
   }
 
-  async updateDefaultSpace(spaceId: SpaceId): Promise<void> {
-    const credential = await this.getDeviceCredentialSigner().createCredential({
-      subject: this.identityKey,
-      assertion: { '@type': 'dxos.halo.credentials.DefaultSpace', spaceId },
-    });
-    const receipt = await this.controlPipeline.writer.write({ credential: { credential } });
-    await this.controlPipeline.state.waitUntilTimeframe(new Timeframe([[receipt.feedKey, receipt.seq]]));
-  }
-
   async admitDevice({ deviceKey, controlFeedKey, dataFeedKey }: DeviceAdmissionRequest): Promise<Credential> {
     log('Admitting device:', {
       identityKey: this.identityKey,

package/src/packlets/invitations/device-invitation-protocol.test.ts

@@ -2,9 +2,9 @@
 // Copyright 2022 DXOS.org
 //
 
-import { describe, expect, test, onTestFinished } from 'vitest';
+import { describe, expect, onTestFinished, test } from 'vitest';
 
-import { asyncChain } from '@dxos/async';
+import { chain } from '@dxos/async';
 import { Context } from '@dxos/context';
 import { AlreadyJoinedError } from '@dxos/protocols';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
@@ -32,7 +32,7 @@ describe('services/device', () => {
   });
 
   test('creates and accepts invitation', async () => {
-    const [host, guest] = await asyncChain<ServiceContext>([closeAfterTest])(createPeers(2));
+    const [host, guest] = await chain<ServiceContext>([closeAfterTest])(createPeers(2));
 
     const identity1 = await host.createIdentity();
     expect(host.identityManager.identity).to.eq(identity1);
@@ -42,7 +42,7 @@ describe('services/device', () => {
   });
 
   test('invitation when already joined', async () => {
-    const [host, guest] = await asyncChain<ServiceContext>([closeAfterTest])(createPeers(2));
+    const [host, guest] = await chain<ServiceContext>([closeAfterTest])(createPeers(2));
 
     const identity1 = await host.createIdentity();
     expect(host.identityManager.identity).to.eq(identity1);

package/src/packlets/invitations/device-invitation-protocol.ts

@@ -2,11 +2,12 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type Context } from '@dxos/context';
 import { getCredentialAssertion } from '@dxos/credentials';
 import { invariant } from '@dxos/invariant';
 import { type Keyring } from '@dxos/keyring';
 import { type PublicKey } from '@dxos/keys';
-import { AlreadyJoinedError, type ApiError } from '@dxos/protocols';
+import { AlreadyJoinedError } from '@dxos/protocols';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import type { DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
 import {
@@ -15,14 +16,14 @@ import {
   type IntroductionRequest,
 } from '@dxos/protocols/proto/dxos/halo/invitations';
 
+import { type Identity, type JoinIdentityProps } from '../identity';
 import { type InvitationProtocol } from './invitation-protocol';
-import { type Identity, type JoinIdentityParams } from '../identity';
 
 export class DeviceInvitationProtocol implements InvitationProtocol {
   constructor(
     private readonly _keyring: Keyring,
     private readonly _getIdentity: () => Identity,
-    private readonly _acceptIdentity: (identity: JoinIdentityParams) => Promise<Identity>,
+    private readonly _acceptIdentity: (identity: JoinIdentityProps) => Promise<Identity>,
   ) {}
 
   toJSON(): object {
@@ -31,7 +32,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     };
   }
 
-  checkCanInviteNewMembers(): ApiError | undefined {
+  checkCanInviteNewMembers(): Error | undefined {
     return undefined;
   }
 
@@ -70,7 +71,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     try {
       const identity = this._getIdentity();
       if (identity) {
-        return new AlreadyJoinedError('Currently only one identity per client is supported.');
+        return new AlreadyJoinedError({ message: 'Currently only one identity per client is supported.' });
       }
     } catch {
       // No identity.
@@ -96,7 +97,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     };
   }
 
-  async accept(response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>> {
+  async accept(_ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>> {
     invariant(response.device);
     const { identityKey, haloSpaceKey, genesisFeedKey, controlTimeframe } = response.device;
 
@@ -104,6 +105,7 @@ export class DeviceInvitationProtocol implements InvitationProtocol {
     const { deviceKey, controlFeedKey, dataFeedKey, profile } = request.device;
 
     // TODO(wittjosiah): When multiple identities are supported, verify identity doesn't already exist before accepting.
+    // ctx is unused here because _acceptIdentity uses ServiceContext's lifecycle ctx internally.
 
     await this._acceptIdentity({
       identityKey,

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

@@ -19,17 +19,18 @@ 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 AdmissionResponse,
   type SpaceAdmissionRequest,
 } from '@dxos/protocols/proto/dxos/halo/invitations';
+import { trace } from '@dxos/tracing';
 
 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>;
+  onInvitationSuccess(ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<void>;
 }
 
 export const MAX_RETRIES_PER_INVITATION = 5;
@@ -41,6 +42,7 @@ export type EdgeInvitationConfig = {
   retryJitter?: number;
 };
 
+@trace.resource()
 export class EdgeInvitationHandler implements FlowLockHolder {
   private _flowLock: MutexGuard | undefined;
 
@@ -113,6 +115,7 @@ export class EdgeInvitationHandler implements FlowLockHolder {
     scheduleMicroTask(ctx, tryHandleInvitation);
   }
 
+  @trace.span({ op: 'invitation.edge' })
   private async _handleSpaceInvitationFlow(
     ctx: Context,
     guardedState: GuardedInvitationState,
@@ -126,13 +129,13 @@ export class EdgeInvitationHandler implements FlowLockHolder {
 
       guardedState.set(this, Invitation.State.CONNECTING);
 
-      const response = await this._joinSpaceByInvitation(guardedState, spaceId, {
+      const response = await this._joinSpaceByInvitation(ctx, guardedState, spaceId, {
         identityKey: admissionRequest.identityKey.toHex(),
         invitationId: guardedState.current.invitationId,
       });
 
       const admissionResponse = await this._mapToAdmissionResponse(response);
-      await this._callbacks.onInvitationSuccess(admissionResponse, { space: admissionRequest });
+      await this._callbacks.onInvitationSuccess(ctx, admissionResponse, { space: admissionRequest });
     } catch (error) {
       guardedState.set(this, Invitation.State.ERROR);
       throw error;
@@ -153,13 +156,14 @@ export class EdgeInvitationHandler implements FlowLockHolder {
   }
 
   private async _joinSpaceByInvitation(
+    ctx: Context,
     guardedState: GuardedInvitationState,
     spaceId: SpaceId,
     request: JoinSpaceRequest,
   ): Promise<JoinSpaceResponseBody> {
     invariant(this._client);
     try {
-      return await this._client.joinSpaceByInvitation(spaceId, request);
+      return await this._client.joinSpaceByInvitation(ctx, spaceId, request);
     } catch (error: any) {
       if (error instanceof EdgeAuthChallengeError) {
         const publicKey = guardedState.current.guestKeypair?.publicKey;
@@ -168,7 +172,7 @@ export class EdgeInvitationHandler implements FlowLockHolder {
           throw error;
         }
         const signature = sign(Buffer.from(error.challenge, 'base64'), privateKey);
-        return this._client.joinSpaceByInvitation(spaceId, {
+        return this._client.joinSpaceByInvitation(ctx, spaceId, {
           ...request,
           signature: Buffer.from(signature).toString('base64'),
         });

package/src/packlets/invitations/index.ts

@@ -3,7 +3,7 @@
 //
 
 export * from './device-invitation-protocol';
-export * from './invitation-protocol';
+export type * from './invitation-protocol';
 export * from './invitations-handler';
 export * from './invitations-service';
 export * from './space-invitation-protocol';

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

@@ -3,7 +3,7 @@
 //
 
 import { type Mutex, type MutexGuard, Trigger } from '@dxos/async';
-import { cancelWithContext, Context } from '@dxos/context';
+import { Context, cancelWithContext } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { InvalidInvitationExtensionRoleError } from '@dxos/protocols';
@@ -97,10 +97,12 @@ export class InvitationGuestExtension
       await cancelWithContext(this._ctx, this._remoteOptionsTrigger.wait({ timeout: OPTIONS_TIMEOUT }));
       log.verbose('options received');
       if (this._remoteOptions?.role !== InvitationOptions.Role.HOST) {
-        throw new InvalidInvitationExtensionRoleError(undefined, {
-          expected: InvitationOptions.Role.HOST,
-          remoteOptions: this._remoteOptions,
-          remotePeerId: context.remotePeerId,
+        throw new InvalidInvitationExtensionRoleError({
+          context: {
+            expected: InvitationOptions.Role.HOST,
+            remoteOptions: this._remoteOptions,
+            remotePeerId: context.remotePeerId,
+          },
         });
       }
 

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

@@ -3,12 +3,12 @@
 //
 
 import { type Mutex, type MutexGuard, Trigger, scheduleTask } from '@dxos/async';
-import { cancelWithContext, Context } from '@dxos/context';
+import { Context, cancelWithContext } from '@dxos/context';
 import { randomBytes, verify } from '@dxos/crypto';
-import { invariant, InvariantViolation } from '@dxos/invariant';
+import { InvariantViolation, invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { InvalidInvitationExtensionRoleError, trace } from '@dxos/protocols';
+import { InvalidInvitationExtensionRoleError } from '@dxos/protocols';
 import { schema } from '@dxos/protocols/proto';
 import { Invitation } from '@dxos/protocols/proto/dxos/client/services';
 import { type ProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
@@ -110,8 +110,7 @@ export class InvitationHostExtension
 
         introduce: async (request) => {
           const { profile, invitationId } = request;
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.introduce', trace.begin({ id: traceId }));
+          log('introducing host invitation');
 
           const invitation = this._requireActiveInvitation();
           this._assertInvitationState(Invitation.State.CONNECTED);
@@ -131,7 +130,7 @@ export class InvitationHostExtension
           this._challenge =
             invitation.authMethod === Invitation.AuthMethod.KNOWN_PUBLIC_KEY ? randomBytes(32) : undefined;
 
-          log.trace('dxos.sdk.invitation-handler.host.introduce', trace.end({ id: traceId }));
+          log('introduced host invitation');
           return {
             authMethod: invitation.authMethod,
             challenge: this._challenge,
@@ -139,8 +138,7 @@ export class InvitationHostExtension
         },
 
         authenticate: async ({ authCode: code, signedChallenge }) => {
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.begin({ id: traceId }));
+          log('authenticating host invitation');
 
           const invitation = this._requireActiveInvitation();
           log.verbose('received authentication request', { authCode: code });
@@ -201,13 +199,12 @@ export class InvitationHostExtension
             return { status };
           }
 
-          log.trace('dxos.sdk.invitation-handler.host.authenticate', trace.end({ id: traceId, data: { status } }));
+          log('authenticated host invitation', { status });
           return { status };
         },
 
         admit: async (request) => {
-          const traceId = PublicKey.random().toHex();
-          log.trace('dxos.sdk.invitation-handler.host.admit', trace.begin({ id: traceId }));
+          log('admitting guest');
           const invitation = this._requireActiveInvitation();
 
           try {
@@ -221,7 +218,7 @@ export class InvitationHostExtension
 
             const response = await this._callbacks.admit(request);
 
-            log.trace('dxos.sdk.invitation-handler.host.admit', trace.end({ id: traceId }));
+            log('admitted guest');
             return response;
           } catch (err: any) {
             this._callbacks.onError(err);
@@ -245,10 +242,12 @@ export class InvitationHostExtension
       await cancelWithContext(this._ctx, this._remoteOptionsTrigger.wait({ timeout: OPTIONS_TIMEOUT }));
       log.verbose('options received');
       if (this._remoteOptions?.role !== InvitationOptions.Role.GUEST) {
-        throw new InvalidInvitationExtensionRoleError(undefined, {
-          expected: InvitationOptions.Role.GUEST,
-          remoteOptions: this._remoteOptions,
-          remotePeerId: context.remotePeerId,
+        throw new InvalidInvitationExtensionRoleError({
+          context: {
+            expected: InvitationOptions.Role.GUEST,
+            remoteOptions: this._remoteOptions,
+            remotePeerId: context.remotePeerId,
+          },
         });
       }
       this._callbacks.onStateUpdate(Invitation.State.CONNECTED);

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

@@ -2,10 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
+import { type Context } from '@dxos/context';
 import { type PublicKey } from '@dxos/keys';
-import type { ApiError } from '@dxos/protocols';
 import type { Invitation } from '@dxos/protocols/proto/dxos/client/services';
-import type { ProfileDocument, DeviceProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
+import type { DeviceProfileDocument, ProfileDocument } from '@dxos/protocols/proto/dxos/halo/credentials';
 import type {
   AdmissionRequest,
   AdmissionResponse,
@@ -26,7 +26,7 @@ export interface InvitationProtocol {
   // Host
   //
 
-  checkCanInviteNewMembers(): ApiError | undefined;
+  checkCanInviteNewMembers(): Error | undefined;
 
   /**
    * Protocol-specific information to include in the invitation.
@@ -58,7 +58,7 @@ export interface InvitationProtocol {
    *
    * For example, the guest may already be a member of the space.
    */
-  checkInvitation(invitation: Partial<Invitation>): ApiError | undefined;
+  checkInvitation(invitation: Partial<Invitation>): Error | undefined;
 
   /**
    * Get profile information to send to the host to identify the guest.
@@ -72,6 +72,9 @@ export interface InvitationProtocol {
 
   /**
    * Redeem the admission credential.
+   * @param ctx - Caller context used for tracing and cancellation. Forwarded to downstream
+   *   internal methods (e.g. `DataSpaceManager.acceptSpace`) so their spans become children of
+   *   the invitation flow span.
    */
-  accept(response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>>;
+  accept(ctx: Context, response: AdmissionResponse, request: AdmissionRequest): Promise<Partial<Invitation>>;
 }

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

@@ -31,12 +31,6 @@ export const createGuardedInvitationState = (
   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 };
@@ -44,9 +38,6 @@ export const createGuardedInvitationState = (
     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 {
@@ -54,7 +45,6 @@ export const createGuardedInvitationState = (
     get current() {
       return currentInvitation;
     },
-    // disposing context prevents any further state updates
     complete: (newState: Partial<Invitation>) => {
       logStateUpdate(currentInvitation, undefined, invitation.state);
       currentInvitation = { ...currentInvitation, ...newState };
@@ -94,11 +84,7 @@ const logStateUpdate = (invitation: Invitation, actor: any, newState: Invitation
     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);
-  }
+  log.verbose('dxos.sdk.invitations-handler.state.update', logContext);
 };
 
 const isNonTerminalState = (currentState: Invitation.State): boolean => {