@comapeo/core 2.3.1 → 3.0.0-0

package/src/invite/invite-api.js

@@ -0,0 +1,387 @@
+import { TypedEmitter } from 'tiny-typed-emitter'
+import { InviteResponse_Decision } from '../generated/rpc.js'
+import { assert, keyToId, noop } from '../utils.js'
+import HashMap from '../lib/hashmap.js'
+import timingSafeEqual from 'string-timing-safe-equal'
+import { Logger } from '../logger.js'
+import { createActor, fromPromise, toPromise } from 'xstate'
+import { inviteStateMachine } from './invite-state-machine.js'
+import {
+  NotFoundError,
+  AlreadyJoinedError,
+  InviteSendError,
+} from '../errors.js'
+
+/** @import { MapBuffers } from '../types.js' */
+/**
+ * @import {
+ *   Invite as InviteRpcMessage,
+ *   InviteCancel,
+ *   ProjectJoinDetails
+ * } from '../generated/rpc.js'
+ */
+
+// There are three slightly different invite types:
+//
+// - InviteRpcMessage comes from the protobuf.
+// - InviteInternal adds a locally-generated receive timestamp.
+// - Invite is the externally-facing type.
+
+/**
+ * @internal
+ * @typedef {InviteRpcMessage & { receivedAt: number }} InviteInternal
+ */
+/** @typedef {ExtractStateString<import('xstate').StateValueFrom<typeof inviteStateMachine>>} InviteState */
+/** @typedef {import('type-fest').Simplify<MapBuffers<InviteInternal> & { invitorDeviceId: string } & ({ state: Exclude<InviteState, 'error'> } | { state: 'error', error: Error })>} Invite */
+
+/**
+ * @typedef {import('xstate').ActorRefFrom<typeof inviteStateMachine>} invite.actor
+ */
+
+/**
+ * @typedef {Object} InviteApiEvents
+ * @property {(invite: Invite) => void} invite-received
+ * @property {(invite: Invite) => void} invite-updated
+ */
+
+/**
+ * @typedef {(projectDetails: Pick<ProjectJoinDetails, 'projectKey' | 'encryptionKeys'> & { projectName: string }) => Promise<string>} AddProjectQuery
+ */
+
+/**
+ * @extends {TypedEmitter<InviteApiEvents>}
+ */
+export class InviteApi extends TypedEmitter {
+  #getProjectByInviteId
+  #addProject
+  /** @type {HashMap<string | Buffer, { value: InviteInternal, actor: invite.actor, peerId: string }>} */
+  #invites = new HashMap(keyToId)
+  #l
+
+  /**
+   * @param {Object} options
+   * @param {import('../local-peers.js').LocalPeers} options.rpc
+   * @param {object} options.queries
+   * @param {(projectInviteId: Readonly<Buffer>) => undefined | { projectPublicId: string }} options.queries.getProjectByInviteId
+   * @param {AddProjectQuery} options.queries.addProject
+   * @param {Logger} [options.logger]
+   */
+  constructor({ rpc, queries, logger }) {
+    super()
+
+    this.#l = Logger.create('InviteApi', logger)
+
+    this.rpc = rpc
+    this.#getProjectByInviteId = queries.getProjectByInviteId
+    this.#addProject = queries.addProject
+
+    this.rpc.on('invite', (...args) => {
+      try {
+        this.#handleNewInvite(...args)
+      } catch (err) {
+        console.error('Error handling invite', err)
+      }
+    })
+
+    this.rpc.on('invite-cancel', (_peerId, inviteCancel) => {
+      try {
+        this.#handleInviteCancel(inviteCancel)
+      } catch (err) {
+        console.error('Error handling invite cancel', err)
+      }
+    })
+
+    this.rpc.on('got-project-details', (peerId, projectJoinDetails) => {
+      try {
+        this.#handleGotProjectDetails(peerId, projectJoinDetails)
+      } catch (err) {
+        console.error('Error handling got-project-details', err)
+      }
+    })
+  }
+
+  /** @param {Buffer} projectInviteId */
+  #isJoiningProject(projectInviteId) {
+    for (const { value, actor } of this.#invites.values()) {
+      const state = actor.getSnapshot()
+      if (
+        state.matches('joining') &&
+        value.projectInviteId.equals(projectInviteId)
+      ) {
+        return true
+      }
+    }
+    return false
+  }
+
+  /**
+   * @param {string} peerId
+   * @param {InviteRpcMessage} inviteRpcMessage
+   */
+  #handleNewInvite(peerId, inviteRpcMessage) {
+    const { inviteId, projectInviteId, projectName } = inviteRpcMessage
+    const invite = { ...inviteRpcMessage, receivedAt: Date.now() }
+
+    this.#l.log('Received invite %h from %S', inviteId, peerId)
+
+    const hasAlreadyReceivedThisInvite = this.#invites.has(inviteId)
+    if (hasAlreadyReceivedThisInvite) {
+      this.#l.log('Invite %h: already received this invite', inviteId)
+      return
+    }
+
+    const isAlreadyMember = Boolean(this.#getProjectByInviteId(projectInviteId))
+    if (isAlreadyMember) {
+      this.#l.log('Invite %h: already in project', inviteId)
+      this.rpc
+        .sendInviteResponse(peerId, {
+          decision: InviteResponse_Decision.ALREADY,
+          inviteId,
+        })
+        .catch(noop)
+      return
+    }
+
+    const actor = createActor(
+      inviteStateMachine.provide({
+        actors: {
+          sendInviteResponse: fromPromise(async ({ input: { decision } }) => {
+            return this.rpc.sendInviteResponse(peerId, { decision, inviteId })
+          }),
+          addProject: fromPromise(async ({ input: projectDetails }) => {
+            return this.#addProject({ ...projectDetails, projectName })
+          }),
+        },
+        guards: {
+          isNotAlreadyJoiningOrInProject: () => {
+            const isJoining = this.#isJoiningProject(projectInviteId)
+            const isAlreadyMember = Boolean(
+              this.#getProjectByInviteId(projectInviteId)
+            )
+            return !isJoining && !isAlreadyMember
+          },
+        },
+      })
+    )
+
+    this.#invites.set(inviteId, { value: invite, actor, peerId })
+
+    this.emit('invite-received', toInvite(invite, actor.getSnapshot(), peerId))
+    actor.start()
+    // Subscribe after start so that initial state (invite-received) is not emitted twice
+    actor.subscribe((snapshot) => {
+      this.emit('invite-updated', toInvite(invite, snapshot, peerId))
+    })
+  }
+
+  /**
+   * @param {InviteCancel} inviteCancel
+   */
+  #handleInviteCancel(inviteCancel) {
+    const { inviteId } = inviteCancel
+
+    this.#l.log('Received invite cancel for invite ID %h', inviteId)
+
+    const invite = this.#invites.get(inviteId)
+    assert(!!invite, `Cannot find invite ${inviteId.toString('hex')}`)
+
+    // TODO: Move this logging to the state machine
+    const state = invite.actor.getSnapshot()
+    if (!state.can({ type: 'CANCEL_INVITE' })) {
+      this.#l.log(
+        'Received invite cancel for %h but invite is already in state %o',
+        inviteId,
+        state.value
+      )
+      return
+    }
+
+    invite.actor.send({ type: 'CANCEL_INVITE' })
+  }
+
+  /**
+   * @param {string} peerId
+   * @param {ProjectJoinDetails} projectJoinDetails
+   */
+  #handleGotProjectDetails(peerId, projectJoinDetails) {
+    const invite = this.#invites.get(projectJoinDetails.inviteId)
+    if (!invite) {
+      this.#l.log(
+        'Received project details for %h but invite is not found',
+        projectJoinDetails.inviteId
+      )
+      return
+    }
+    if (!timingSafeEqual(peerId, invite.peerId)) {
+      this.#l.log(
+        'Received project details for %h but peer ID does not match',
+        projectJoinDetails.inviteId
+      )
+      return
+    }
+    invite.actor.send({
+      type: 'RECEIVE_PROJECT_DETAILS',
+      ...projectJoinDetails,
+    })
+  }
+
+  /**
+   * Get all invites (in all)
+   *
+   * @returns {Array<Invite>}
+   */
+  getMany() {
+    /** @type {Array<Invite>} */
+    const invites = []
+    for (const { value, actor, peerId } of this.#invites.values()) {
+      const snapshot = actor.getSnapshot()
+      invites.push(toInvite(value, snapshot, peerId))
+    }
+    return invites
+  }
+
+  /**
+   * Get an invite by inviteId
+   *
+   * @param {string} inviteIdString
+   * @returns {Invite}
+   */
+  getById(inviteIdString) {
+    const inviteId = Buffer.from(inviteIdString, 'hex')
+    const invite = this.#invites.get(inviteId)
+    if (!invite) {
+      throw new NotFoundError(`Cannot find invite ${inviteIdString}`)
+    }
+    return toInvite(invite.value, invite.actor.getSnapshot(), invite.peerId)
+  }
+
+  /**
+   * Attempt to accept the invite.
+   *
+   * This can fail if the invitor has canceled the invite or if you cannot
+   * connect to the invitor's device.
+   *
+   * If the invite is accepted and you had other invites to the same project,
+   * those invites are removed, and the invitors are told that you're already
+   * part of this project.
+   *
+   * @param {Pick<Invite, 'inviteId'>} invite
+   * @returns {Promise<string>}
+   */
+  async accept({ inviteId: inviteIdString }) {
+    const inviteId = Buffer.from(inviteIdString, 'hex')
+
+    const invite = this.#invites.get(inviteId)
+    assert(!!invite, new NotFoundError(`Cannot find invite ${inviteIdString}`))
+    assertCanSend(invite.actor, { type: 'ACCEPT_INVITE' })
+
+    this.#l.log('Accepting invite %h', inviteId)
+    invite.actor.send({ type: 'ACCEPT_INVITE' })
+
+    for (const { value, actor } of this.#invites.values()) {
+      if (value.inviteId.equals(inviteId)) continue
+      const inviteIsForSameProject = value.projectInviteId.equals(
+        invite.value.projectInviteId
+      )
+      if (inviteIsForSameProject) {
+        actor.send({ type: 'ALREADY_IN_PROJECT' })
+      }
+    }
+
+    const { projectPublicId } = await toPromise(invite.actor)
+
+    if (!projectPublicId) {
+      const { context, value } = invite.actor.getSnapshot()
+      throw value === 'respondedAlready'
+        ? new AlreadyJoinedError('Already joining or in project')
+        : context.error || new Error('Unknown error')
+    }
+
+    return projectPublicId
+  }
+
+  /**
+   * @param {Pick<Invite, 'inviteId'>} invite
+   * @returns {void}
+   */
+  reject({ inviteId: inviteIdString }) {
+    const inviteId = Buffer.from(inviteIdString, 'hex')
+
+    const invite = this.#invites.get(inviteId)
+    assert(!!invite, `Cannot find invite ${inviteIdString}`)
+    assertCanSend(invite.actor, { type: 'REJECT_INVITE' })
+
+    this.#l.log('Rejecting invite %h', inviteId)
+    invite.actor.send({ type: 'REJECT_INVITE' })
+  }
+}
+
+/**
+ * @param {InviteInternal} internal
+ * @param {import('xstate').SnapshotFrom<invite.actor>} snapshot
+ * @param {string} invitorDeviceId
+ * @returns {Invite}
+ */
+function toInvite(internal, snapshot, invitorDeviceId) {
+  const state = toStateString(snapshot.value)
+  if (state === 'error') {
+    return {
+      ...internal,
+      invitorDeviceId,
+      inviteId: internal.inviteId.toString('hex'),
+      projectInviteId: internal.projectInviteId.toString('hex'),
+      state,
+      error: snapshot.context.error || new Error('Unknown error'),
+    }
+  } else {
+    return {
+      ...internal,
+      invitorDeviceId,
+      inviteId: internal.inviteId.toString('hex'),
+      projectInviteId: internal.projectInviteId.toString('hex'),
+      state,
+    }
+  }
+}
+
+/**
+ * Assert that a given event type can be sent to the state machine (will throw
+ * if there is no transition defined for this event type for the current state
+ * of the machine)
+ *
+ * @param {invite.actor} actor
+ * @param {import('xstate').EventFrom<invite.actor>} eventType
+ */
+function assertCanSend(actor, eventType) {
+  const state = actor.getSnapshot()
+  assert(
+    state.can(eventType),
+    new InviteSendError(
+      `Cannot send ${JSON.stringify(eventType)} in state ${toStateString(
+        state.value
+      )}`
+    )
+  )
+}
+
+/**
+ * @template {import('xstate').StateValue} T
+ * @typedef {T extends string ? T : T extends import('xstate').StateValueMap ? keyof T : never} ExtractStateString
+ */
+
+/**
+ * "Flatten" nested states into a top-level string, e.g. in our case the state
+ * `{ joining: 'awaitingDetails' }` will be flattened to `'joining'`.
+ *
+ * @template {import('xstate').StateValue} T
+ * @param {T} stateValue
+ * @returns {ExtractStateString<T>}
+ */
+function toStateString(stateValue) {
+  if (typeof stateValue === 'string') {
+    // @ts-expect-error - typescript limitation
+    return stateValue
+  }
+  // @ts-expect-error - typescript limitation
+  return Object.keys(stateValue)[0]
+}

package/src/invite/invite-state-machine.js

@@ -0,0 +1,208 @@
+import { setup, assign, fromPromise, assertEvent, raise } from 'xstate'
+import { omit } from '../lib/omit.js'
+import { InviteResponse_Decision } from '../generated/rpc.js'
+import ensureError from 'ensure-error'
+import { TimeoutError } from '../errors.js'
+
+const RECEIVE_PROJECT_DETAILS_TIMEOUT_MS = 10_000
+const ADD_PROJECT_TIMEOUT_MS = 10_000
+
+/** @import { StringToTaggedUnion } from '../types.js' */
+/** @import { ProjectJoinDetails } from '../generated/rpc.js' */
+/**
+ * @internal
+ * @typedef {object} Context
+ * @property {null | Error} error
+ * @property {null | string} projectPublicId
+ */
+/**
+ * @typedef {object} MachineSetupTypes
+ * @property {Context} context
+ * @property {{ projectPublicId: string | null }} output
+ * @property {StringToTaggedUnion<'ACCEPT_INVITE' | 'CANCEL_INVITE' | 'REJECT_INVITE' | 'ALREADY_IN_PROJECT' | 'ADDED_PROJECT' | 'PEER_DISCONNECTED'> | ({ type: 'RECEIVE_PROJECT_DETAILS' } & ProjectJoinDetails)} events
+ */
+
+export const inviteStateMachine = setup({
+  types: /** @type {MachineSetupTypes} */ ({}),
+  actors: {
+    sendInviteResponse: fromPromise(
+      /**
+       * @param {{ input: { decision: InviteResponse_Decision }}} _opts
+       */
+      async (_opts) => {}
+    ),
+    addProject: fromPromise(
+      /**
+       * @param {{ input: ProjectJoinDetails }} _opts
+       * @returns {Promise<string>} The project public ID
+       */
+      async (_opts) => ''
+    ),
+  },
+  guards: {
+    isNotAlreadyJoiningOrInProject: () => true,
+  },
+  delays: {
+    receiveTimeout: RECEIVE_PROJECT_DETAILS_TIMEOUT_MS,
+    addProjectTimeout: ADD_PROJECT_TIMEOUT_MS,
+  },
+}).createMachine({
+  id: 'invite',
+  context: {
+    error: null,
+    projectPublicId: null,
+  },
+  initial: 'pending',
+  states: {
+    pending: {
+      description: 'Pending invite awaiting response',
+      on: {
+        CANCEL_INVITE: { target: 'canceled' },
+        ACCEPT_INVITE: [
+          {
+            target: 'responding.accept',
+            guard: { type: 'isNotAlreadyJoiningOrInProject' },
+          },
+          {
+            actions: raise({ type: 'ALREADY_IN_PROJECT' }),
+          },
+        ],
+        ALREADY_IN_PROJECT: {
+          target: 'responding.already',
+        },
+        REJECT_INVITE: {
+          target: 'responding.reject',
+        },
+      },
+    },
+    responding: {
+      description: 'Responding to invite',
+      initial: 'default',
+      on: {
+        CANCEL_INVITE: { target: '#invite.canceled' },
+      },
+      states: {
+        default: {
+          always: {
+            target: '#invite.error',
+            actions: assign({ error: () => new TypeError('InvalidState') }),
+          },
+        },
+        accept: {
+          description: 'Sending accept response',
+          invoke: {
+            src: 'sendInviteResponse',
+            input: { decision: InviteResponse_Decision.ACCEPT },
+            onDone: '#invite.joining',
+            onError: '#invite.error',
+          },
+          on: {
+            // It's possible project details could be received before the send
+            // response promise resolves (e.g. somehow the peer receives the
+            // response and sends the project details before the response is
+            // confirmed as sent), so we accept project details at this point
+            RECEIVE_PROJECT_DETAILS: {
+              target: '#invite.joining.addingProject',
+            },
+          },
+        },
+        reject: {
+          description: 'Sending reject response',
+          invoke: {
+            src: 'sendInviteResponse',
+            input: { decision: InviteResponse_Decision.REJECT },
+            onDone: '#invite.rejected',
+            onError: '#invite.error',
+          },
+        },
+        already: {
+          description: 'Sending already response',
+          invoke: {
+            src: 'sendInviteResponse',
+            input: { decision: InviteResponse_Decision.ALREADY },
+            onDone: '#invite.respondedAlready',
+            onError: '#invite.error',
+          },
+        },
+      },
+    },
+    joining: {
+      initial: 'awaitingDetails',
+      description: 'Joining project from invite',
+      states: {
+        awaitingDetails: {
+          description: 'Waiting for project details',
+          on: {
+            RECEIVE_PROJECT_DETAILS: { target: 'addingProject' },
+            CANCEL_INVITE: { target: '#invite.canceled' },
+          },
+          after: {
+            receiveTimeout: {
+              target: '#invite.error',
+              actions: assign({
+                error: () =>
+                  new TimeoutError('Timed out waiting for project details'),
+              }),
+            },
+          },
+        },
+        addingProject: {
+          description: 'Adding project from invite',
+          invoke: {
+            src: 'addProject',
+            input: ({ event }) => {
+              assertEvent(event, 'RECEIVE_PROJECT_DETAILS')
+              return omit(event, ['type'])
+            },
+            onDone: {
+              target: '#invite.joined',
+              actions: assign({
+                projectPublicId: ({ event }) => event.output,
+              }),
+            },
+            onError: '#invite.error',
+          },
+          after: {
+            addProjectTimeout: {
+              target: '#invite.error',
+              actions: assign({
+                error: () => new TimeoutError('Timed out adding project'),
+              }),
+            },
+          },
+        },
+      },
+    },
+    canceled: {
+      description: 'The invite has been canceled',
+      type: 'final',
+    },
+    rejected: {
+      description: 'Rejected invite',
+      type: 'final',
+    },
+    respondedAlready: {
+      description: 'Responded that already in project',
+      type: 'final',
+    },
+    joined: {
+      description: 'Successfully joined project',
+      type: 'final',
+    },
+    error: {
+      entry: assign({
+        error: ({ event, context }) =>
+          context.error ||
+          ensureError(
+            // @ts-expect-error - xstate types are incorrect, for internal events
+            // the error property can exist, and ensureError handles event.error
+            // being undefined.
+            event.error
+          ),
+      }),
+      type: 'final',
+      description: 'Error joining project',
+    },
+  },
+  output: ({ context }) => ({ projectPublicId: context.projectPublicId }),
+})

package/src/local-peers.js

@@ -169,7 +169,7 @@ class Peer {
   }
   /** @param {Invite} invite */
   sendInvite(invite) {
-    this.#assertConnected()
+    this.#assertConnected('Peer disconnected before sending invite')
     const buf = Buffer.from(Invite.encode(invite).finish())
     const messageType = MESSAGE_TYPES.Invite
     this.#channel.messages[messageType].send(buf)
@@ -177,7 +177,7 @@ class Peer {
   }
   /** @param {InviteCancel} inviteCancel */
   sendInviteCancel(inviteCancel) {
-    this.#assertConnected()
+    this.#assertConnected('Peer disconnected before sending invite cancel')
     const buf = Buffer.from(InviteCancel.encode(inviteCancel).finish())
     const messageType = MESSAGE_TYPES.InviteCancel
     this.#channel.messages[messageType].send(buf)
@@ -185,7 +185,7 @@ class Peer {
   }
   /** @param {InviteResponse} response */
   sendInviteResponse(response) {
-    this.#assertConnected()
+    this.#assertConnected('Peer disconnected before sending invite response')
     const buf = Buffer.from(InviteResponse.encode(response).finish())
     const messageType = MESSAGE_TYPES.InviteResponse
     this.#channel.messages[messageType].send(buf)
@@ -193,7 +193,9 @@ class Peer {
   }
   /** @param {ProjectJoinDetails} details */
   sendProjectJoinDetails(details) {
-    this.#assertConnected()
+    this.#assertConnected(
+      'Peer disconnected before sending project join details'
+    )
     const buf = Buffer.from(ProjectJoinDetails.encode(details).finish())
     const messageType = MESSAGE_TYPES.ProjectJoinDetails
     this.#channel.messages[messageType].send(buf)
@@ -212,10 +214,11 @@ class Peer {
     this.#deviceType = deviceInfo.deviceType
     this.#log('received deviceInfo %o', deviceInfo)
   }
-  #assertConnected() {
+  /** @param {string} [message] */
+  #assertConnected(message) {
     if (this.#state === 'connected' && !this.#channel.closed) return
     /* c8 ignore next */
-    throw new PeerDisconnectedError() // TODO: report error - this should not happen
+    throw new PeerDisconnectedError(message) // TODO: report error - this should not happen
   }
 }
 
@@ -614,7 +617,7 @@ export { TimeoutError }
 
 export class UnknownPeerError extends Error {
   /** @param {string} [message] */
-  constructor(message) {
+  constructor(message = 'UnknownPeerError') {
     super(message)
     this.name = 'UnknownPeerError'
   }
@@ -622,7 +625,7 @@ export class UnknownPeerError extends Error {
 
 export class PeerDisconnectedError extends Error {
   /** @param {string} [message] */
-  constructor(message) {
+  constructor(message = 'Peer disconnected') {
     super(message)
     this.name = 'PeerDisconnectedError'
   }
@@ -630,7 +633,7 @@ export class PeerDisconnectedError extends Error {
 
 export class PeerFailedConnectionError extends Error {
   /** @param {string} [message] */
-  constructor(message) {
+  constructor(message = 'PeerFailedConnectionError') {
     super(message)
     this.name = 'PeerFailedConnectionError'
   }

package/src/mapeo-manager.js

@@ -42,7 +42,7 @@ import IconServerPlugin from './fastify-plugins/icons.js'
 import { plugin as MapServerPlugin } from './fastify-plugins/maps.js'
 import { getFastifyServerAddress } from './fastify-plugins/utils.js'
 import { LocalPeers } from './local-peers.js'
-import { InviteApi } from './invite-api.js'
+import { InviteApi } from './invite/invite-api.js'
 import { LocalDiscovery } from './discovery/local-discovery.js'
 import { Roles } from './roles.js'
 import { Logger } from './logger.js'