@dxos/client-services 0.6.13-main.ed424a1 → 0.6.13

package/src/packlets/agents/edge-agent-manager.ts

@@ -1,163 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { DeferredTask, Event, scheduleTask, synchronized } from '@dxos/async';
-import { Resource } from '@dxos/context';
-import { type EdgeHttpClient } from '@dxos/edge-client';
-import { invariant } from '@dxos/invariant';
-import { PublicKey } from '@dxos/keys';
-import { log } from '@dxos/log';
-import { EdgeAgentStatus, EdgeCallFailedError } from '@dxos/protocols';
-import { SpaceState } from '@dxos/protocols/proto/dxos/client/services';
-import { type Runtime } from '@dxos/protocols/proto/dxos/config';
-
-import { type Identity } from '../identity';
-import { type DataSpaceManager } from '../spaces';
-
-const AGENT_STATUS_QUERY_RETRY_INTERVAL = 5000;
-const AGENT_STATUS_QUERY_RETRY_JITTER = 1000;
-
-export type EdgeAgentManagerConfig = {};
-
-export class EdgeAgentManager extends Resource {
-  public agentStatusChanged = new Event<EdgeAgentStatus>();
-
-  private _agentDeviceKey: PublicKey | undefined;
-  private _agentStatus: EdgeAgentStatus | undefined;
-
-  private _lastKnownDeviceCount = 0;
-
-  private _fetchAgentStatusTask: DeferredTask | undefined;
-
-  constructor(
-    private readonly _edgeFeatures: Runtime.Client.EdgeFeatures | undefined,
-    private readonly _edgeHttpClient: EdgeHttpClient | undefined,
-    private readonly _dataSpaceManager: DataSpaceManager,
-    private readonly _identity: Identity,
-  ) {
-    super();
-  }
-
-  public get agentStatus(): EdgeAgentStatus | undefined {
-    return this._agentStatus;
-  }
-
-  public get agentExists() {
-    return this._agentStatus && this._agentStatus !== EdgeAgentStatus.NOT_FOUND;
-  }
-
-  @synchronized
-  public async createAgent() {
-    invariant(this.isOpen);
-    invariant(this._edgeHttpClient);
-    invariant(this._edgeFeatures?.agents);
-
-    const response = await this._edgeHttpClient.createAgent({
-      identityKey: this._identity.identityKey.toHex(),
-      haloSpaceId: this._identity.haloSpaceId,
-      haloSpaceKey: this._identity.haloSpaceKey.toHex(),
-    });
-
-    const deviceKey = PublicKey.fromHex(response.deviceKey);
-
-    await this._identity.admitDevice({
-      deviceKey,
-      controlFeedKey: PublicKey.fromHex(response.feedKey),
-      // TODO: agents don't have data feed, should be removed
-      dataFeedKey: PublicKey.random(),
-    });
-
-    log('agent created', response);
-
-    this._updateStatus(EdgeAgentStatus.ACTIVE, deviceKey);
-  }
-
-  protected override async _open() {
-    const isEnabled = this._edgeHttpClient && this._edgeFeatures?.agents;
-
-    log('edge agent manager open', { isEnabled });
-
-    if (!isEnabled) {
-      return;
-    }
-
-    this._lastKnownDeviceCount = this._identity.authorizedDeviceKeys.size;
-    this._fetchAgentStatusTask = new DeferredTask(this._ctx, async () => {
-      await this._fetchAgentStatus();
-    });
-    this._fetchAgentStatusTask.schedule();
-
-    this._dataSpaceManager.updated.on(this._ctx, () => {
-      if (this._agentDeviceKey) {
-        this._ensureAgentIsInSpaces(this._agentDeviceKey);
-      }
-    });
-
-    this._identity.stateUpdate.on(this._ctx, () => {
-      const maybeAgentWasCreated = this._identity.authorizedDeviceKeys.size > this._lastKnownDeviceCount;
-      if (this.agentExists || !maybeAgentWasCreated) {
-        return;
-      }
-      this._lastKnownDeviceCount = this._identity.authorizedDeviceKeys.size;
-      this._fetchAgentStatusTask?.schedule();
-    });
-  }
-
-  protected override async _close() {
-    this._fetchAgentStatusTask = undefined;
-    this._lastKnownDeviceCount = 0;
-  }
-
-  protected async _fetchAgentStatus() {
-    invariant(this._edgeHttpClient);
-    try {
-      log('fetching agent status');
-      const { agent } = await this._edgeHttpClient.getAgentStatus({ ownerIdentityKey: this._identity.identityKey });
-      const wasAgentCreatedDuringQuery = this._agentStatus === EdgeAgentStatus.ACTIVE;
-      if (!wasAgentCreatedDuringQuery) {
-        const deviceKey = agent.deviceKey ? PublicKey.fromHex(agent.deviceKey) : undefined;
-        this._updateStatus(agent.status, deviceKey);
-      }
-    } catch (err) {
-      if (err instanceof EdgeCallFailedError) {
-        if (!err.isRetryable) {
-          log.warn('non retryable error on agent status fetch attempt', { err });
-          return;
-        }
-      }
-      const retryAfterMs = AGENT_STATUS_QUERY_RETRY_INTERVAL + Math.random() * AGENT_STATUS_QUERY_RETRY_JITTER;
-      log.info('agent status fetching failed', { err, retryAfterMs });
-      scheduleTask(this._ctx, () => this._fetchAgentStatusTask?.schedule(), retryAfterMs);
-    }
-  }
-
-  /**
-   * We don't want notarization plugin to always actively poll edge looking for credentials to notarize,
-   * because most of the time we'll be getting an empty response.
-   * Instead, we stay in active polling mode while there are spaces where we don't see our agent's feed.
-   */
-  protected _ensureAgentIsInSpaces(agentDeviceKey: PublicKey) {
-    for (const space of this._dataSpaceManager.spaces.values()) {
-      if ([SpaceState.SPACE_INACTIVE, SpaceState.SPACE_CLOSED].includes(space.state)) {
-        continue;
-      }
-      const agentFeedNeedsNotarization = !space.inner.spaceState.feeds
-        .values()
-        .some((feed) => feed.assertion.deviceKey.equals(agentDeviceKey));
-      space.notarizationPlugin.setActiveEdgePollingEnabled(agentFeedNeedsNotarization);
-
-      log.info('set active edge polling', { enabled: agentFeedNeedsNotarization, spaceId: space.id });
-    }
-  }
-
-  private _updateStatus(status: EdgeAgentStatus, deviceKey: PublicKey | undefined) {
-    this._agentStatus = status;
-    this._agentDeviceKey = deviceKey;
-    this.agentStatusChanged.emit(status);
-    if (deviceKey) {
-      this._ensureAgentIsInSpaces(deviceKey);
-    }
-    log.info('agent status update', { status });
-  }
-}

package/src/packlets/agents/edge-agent-service.ts

@@ -1,42 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { Stream } from '@dxos/codec-protobuf';
-import { EdgeAgentStatus } from '@dxos/protocols';
-import { QueryAgentStatusResponse, type EdgeAgentService } from '@dxos/protocols/proto/dxos/client/services';
-
-import { type EdgeAgentManager } from './edge-agent-manager';
-
-export class EdgeAgentServiceImpl implements EdgeAgentService {
-  constructor(private readonly _agentManagerProvider: () => Promise<EdgeAgentManager>) {}
-
-  public async createAgent(): Promise<void> {
-    return (await this._agentManagerProvider()).createAgent();
-  }
-
-  queryAgentStatus(): Stream<QueryAgentStatusResponse> {
-    return new Stream(({ ctx, next }) => {
-      next({ status: QueryAgentStatusResponse.AgentStatus.UNKNOWN });
-      void this._agentManagerProvider().then((agentManager) => {
-        next({ status: mapStatus(agentManager.agentStatus) });
-        agentManager.agentStatusChanged.on(ctx, (newStatus) => {
-          next({ status: mapStatus(newStatus) });
-        });
-      });
-    });
-  }
-}
-
-const mapStatus = (agentStatus: EdgeAgentStatus | undefined): QueryAgentStatusResponse.AgentStatus => {
-  switch (agentStatus) {
-    case EdgeAgentStatus.ACTIVE:
-      return QueryAgentStatusResponse.AgentStatus.ACTIVE;
-    case EdgeAgentStatus.INACTIVE:
-      return QueryAgentStatusResponse.AgentStatus.INACTIVE;
-    case EdgeAgentStatus.NOT_FOUND:
-      return QueryAgentStatusResponse.AgentStatus.NOT_FOUND;
-    case undefined:
-      return QueryAgentStatusResponse.AgentStatus.UNKNOWN;
-  }
-};

package/src/packlets/agents/index.ts

@@ -1,6 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './edge-agent-manager';
-export * from './edge-agent-service';

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

@@ -1,185 +0,0 @@
-//
-// 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-state.ts

@@ -1,111 +0,0 @@
-/**
- * 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>) => {
-      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);
-        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) => {
-  if (isNonTerminalState(newState)) {
-    log('invitation state update', {
-      actor: actor?.constructor.name,
-      newState: stateToString(newState),
-      oldState: stateToString(invitation.state),
-    });
-  } else {
-    log.info('invitation state update', {
-      actor: actor?.constructor.name,
-      newState: stateToString(newState),
-      oldState: stateToString(invitation.state),
-    });
-  }
-};
-
-const isNonTerminalState = (currentState: Invitation.State): boolean => {
-  return ![
-    Invitation.State.SUCCESS,
-    Invitation.State.ERROR,
-    Invitation.State.CANCELLED,
-    Invitation.State.TIMEOUT,
-    Invitation.State.EXPIRED,
-  ].includes(currentState);
-};