@automerge/automerge-repo 2.5.0 → 2.5.2-alpha.0

package/src/Presence.ts

@@ -0,0 +1,722 @@
+import { DocHandle, DocHandleEphemeralMessagePayload } from "./DocHandle.js"
+import { PeerId } from "./types.js"
+import { EventEmitter } from "eventemitter3"
+
+export type UserId = unknown
+export type DeviceId = unknown
+
+export const PRESENCE_MESSAGE_MARKER = "__presence"
+
+export type PeerState<State> = {
+  peerId: PeerId
+  deviceId?: DeviceId
+  userId?: UserId
+  value: State
+}
+
+type PresenceMessageBase = {
+  deviceId?: DeviceId
+  userId?: UserId
+}
+
+type PresenceMessageUpdate = PresenceMessageBase & {
+  type: "update"
+  channel: string
+  value: any
+}
+
+type PresenceMessageSnapshot = PresenceMessageBase & {
+  type: "snapshot"
+  state: any
+}
+
+type PresenceMessageHeartbeat = PresenceMessageBase & {
+  type: "heartbeat"
+}
+
+type PresenceMessageGoodbye = PresenceMessageBase & {
+  type: "goodbye"
+}
+
+type PresenceMessage = {
+  [PRESENCE_MESSAGE_MARKER]:
+    | PresenceMessageUpdate
+    | PresenceMessageSnapshot
+    | PresenceMessageHeartbeat
+    | PresenceMessageGoodbye
+}
+
+type PresenceMessageType =
+  PresenceMessage[typeof PRESENCE_MESSAGE_MARKER]["type"]
+
+type WithPeerId = { peerId: PeerId }
+
+export type PresenceEventUpdate = PresenceMessageUpdate & WithPeerId
+export type PresenceEventSnapshot = PresenceMessageSnapshot & WithPeerId
+export type PresenceEventHeartbeat = PresenceMessageHeartbeat & WithPeerId
+export type PresenceEventGoodbye = PresenceMessageGoodbye & WithPeerId
+
+/**
+ * Events emitted by Presence when ephemeral messages are received from peers.
+ */
+export type PresenceEvents = {
+  /**
+   * Handle a state update broadcast by a peer.
+   */
+  update: (msg: PresenceEventUpdate) => void
+  /**
+   * Handle a full state snapshot broadcast by a peer.
+   */
+  snapshot: (msg: PresenceEventSnapshot) => void
+  /**
+   * Handle a heartbeat broadcast by a peer.
+   */
+  heartbeat: (msg: PresenceEventHeartbeat) => void
+  /**
+   * Handle a disconnection broadcast by a peer.
+   */
+  goodbye: (msg: PresenceEventGoodbye) => void
+}
+
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000
+export const DEFAULT_PEER_TTL_MS = 3 * DEFAULT_HEARTBEAT_INTERVAL_MS
+
+export type PresenceConfig<State> = {
+  /** The full initial state to broadcast to peers */
+  initialState: State
+  /** How frequently to send heartbeats (default {@link DEFAULT_HEARTBEAT_INTERVAL_MS}) */
+  heartbeatMs?: number
+  /** How long to wait until forgetting peers with no activity  (default {@link DEFAULT_PEER_TTL_MS}) */
+  peerTtlMs?: number
+}
+
+/**
+ * Presence encapsulates ephemeral state communication for a specific doc
+ * handle. It tracks caller-provided local state and broadcasts that state to
+ * all peers. It sends periodic heartbeats when there are no state updates.
+ *
+ * It also tracks ephemeral state broadcast by peers and emits events when peers
+ * send ephemeral state updates (see {@link PresenceEvents}).
+ *
+ * Presence starts out in an inactive state. Call {@link start} and {@link stop}
+ * to activate and deactivate it.
+ */
+export class Presence<
+  State extends Record<string, any>,
+  DocType = any
+> extends EventEmitter<PresenceEvents> {
+  #handle: DocHandle<DocType>
+  readonly deviceId?: DeviceId
+  readonly userId?: UserId
+  #peers: PeerPresenceInfo<State>
+  #localState?: State
+  #heartbeatMs?: number
+
+  #handleEphemeralMessage:
+    | ((e: DocHandleEphemeralMessagePayload<DocType>) => void)
+    | undefined
+
+  #heartbeatInterval: ReturnType<typeof setInterval> | undefined
+  #pruningInterval: ReturnType<typeof setInterval> | undefined
+  #hellos: ReturnType<typeof setTimeout>[] = []
+
+  #running = false
+
+  /**
+   * Create a new Presence to share ephemeral state with peers.
+   *
+   * @param config see {@link PresenceConfig}
+   * @returns
+   */
+  constructor({
+    handle,
+    deviceId,
+    userId,
+  }: {
+    handle: DocHandle<DocType>
+    /** Our device id (like userId, this is unverified; peers can send anything) */
+    deviceId?: DeviceId
+    /** Our user id (this is unverified; peers can send anything) */
+    userId?: UserId
+  }) {
+    super()
+    this.#handle = handle
+    this.#peers = new PeerPresenceInfo(DEFAULT_PEER_TTL_MS)
+    this.userId = userId
+    this.deviceId = deviceId
+  }
+
+  /**
+   * Start listening to ephemeral messages on the handle, broadcast initial
+   * state to peers, and start sending heartbeats.
+   */
+  start({ initialState, heartbeatMs, peerTtlMs }: PresenceConfig<State>) {
+    if (this.#running) {
+      return
+    }
+    this.#running = true
+
+    this.#heartbeatMs = heartbeatMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS
+    this.#peers = new PeerPresenceInfo(peerTtlMs ?? DEFAULT_PEER_TTL_MS)
+    this.#localState = initialState
+
+    // N.B.: We can't use a regular member function here since member functions
+    // of two distinct objects are identical, and we need to be able to stop
+    // listening to the handle for just this Presence instance in stop()
+    this.#handleEphemeralMessage = (
+      e: DocHandleEphemeralMessagePayload<DocType>
+    ) => {
+      const peerId = e.senderId
+      const envelope = e.message as PresenceMessage
+
+      if (!(PRESENCE_MESSAGE_MARKER in envelope)) {
+        return
+      }
+
+      const message = envelope[PRESENCE_MESSAGE_MARKER]
+      const { deviceId, userId } = message
+
+      if (!this.#peers.view.has(peerId)) {
+        this.announce()
+      }
+
+      switch (message.type) {
+        case "heartbeat":
+          this.#peers.markSeen(peerId, deviceId, userId)
+          this.emit("heartbeat", {
+            type: "heartbeat",
+            peerId,
+            deviceId,
+            userId,
+          })
+          break
+        case "goodbye":
+          this.#peers.delete(peerId)
+          this.emit("goodbye", {
+            type: "goodbye",
+            peerId,
+            deviceId,
+            userId,
+          })
+          break
+        case "update":
+          this.#peers.update({
+            peerId,
+            deviceId,
+            userId,
+            channel: message.channel as keyof State,
+            value: message.value,
+          })
+          this.emit("update", {
+            type: "update",
+            peerId,
+            deviceId,
+            userId,
+            channel: message.channel,
+            value: message.value,
+          })
+          break
+        case "snapshot":
+          Object.entries(message.state as State).forEach(([channel, value]) => {
+            this.#peers.update({
+              peerId,
+              deviceId,
+              userId,
+              channel: channel as keyof State,
+              value,
+            })
+          })
+          this.emit("snapshot", {
+            type: "snapshot",
+            peerId,
+            deviceId,
+            userId,
+            state: message.state,
+          })
+          break
+      }
+    }
+    this.#handle.on("ephemeral-message", this.#handleEphemeralMessage)
+
+    this.broadcastLocalState() // also starts heartbeats
+    this.startPruningPeers()
+  }
+
+  /**
+   * Return a view of current peer states.
+   */
+  getPeerStates() {
+    return this.#peers.view
+  }
+
+  /**
+   * Return a view of current local state.
+   */
+  getLocalState() {
+    return this.#localState
+  }
+
+  /**
+   * Update state for the specific channel, and broadcast new state to all
+   * peers.
+   *
+   * @param channel
+   * @param value
+   */
+  broadcast<Channel extends keyof State>(
+    channel: Channel,
+    value: State[Channel]
+  ) {
+    this.#localState = Object.assign({}, this.#localState, {
+      [channel]: value,
+    })
+    this.broadcastChannelState(channel, value)
+  }
+
+  /**
+   * Whether this Presence is currently active. See
+   * {@link start} and {@link stop}.
+   */
+  get running() {
+    return this.#running
+  }
+
+  /**
+   * Stop this Presence: broadcast a "goodbye" message (when received, other
+   * peers will immediately forget the sender), stop sending heartbeats, and
+   * stop listening to ephemeral-messages broadcast from peers.
+   *
+   * This can be used with browser events like
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/pagehide_event | "pagehide"}
+   * or
+   * {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event | "visibilitychange"}
+   * to stop sending and receiving updates when not active.
+   */
+  stop() {
+    if (!this.#running) {
+      return
+    }
+    this.#hellos.forEach(timeoutId => {
+      clearTimeout(timeoutId)
+    })
+    this.#hellos = []
+    this.#handle.off("ephemeral-message", this.#handleEphemeralMessage)
+    this.stopHeartbeats()
+    this.stopPruningPeers()
+    this.doBroadcast("goodbye")
+    this.#running = false
+  }
+
+  private announce() {
+    // Broadcast our current state whenever we see new peers
+    // TODO: We currently need to wait for the peer to be ready, but waiting
+    // some arbitrary amount of time is brittle
+    const helloId = setTimeout(() => {
+      this.broadcastLocalState()
+      this.#hellos = this.#hellos.filter(id => id !== helloId)
+    }, 500)
+    this.#hellos.push(helloId)
+  }
+
+  private broadcastLocalState() {
+    this.doBroadcast("snapshot", { state: this.#localState })
+    this.resetHeartbeats()
+  }
+
+  private broadcastChannelState<Channel extends keyof State>(
+    channel: Channel,
+    value: State[Channel]
+  ) {
+    this.doBroadcast("update", { channel, value })
+    this.resetHeartbeats()
+  }
+
+  private resetHeartbeats() {
+    // Reset heartbeats every time we broadcast a message to avoid sending
+    // unnecessary heartbeats when there is plenty of actual update activity
+    // happening.
+    this.stopHeartbeats()
+    this.startHeartbeats()
+  }
+
+  private sendHeartbeat() {
+    this.doBroadcast("heartbeat")
+  }
+
+  private doBroadcast(
+    type: PresenceMessageType,
+    extra?: Record<string, unknown>
+  ) {
+    if (!this.#running) {
+      return
+    }
+    this.#handle.broadcast({
+      [PRESENCE_MESSAGE_MARKER]: {
+        userId: this.userId,
+        deviceId: this.deviceId,
+        type,
+        ...extra,
+      },
+    })
+  }
+
+  private startHeartbeats() {
+    if (this.#heartbeatInterval !== undefined) {
+      return
+    }
+    this.#heartbeatInterval = setInterval(() => {
+      this.sendHeartbeat()
+    }, this.#heartbeatMs)
+  }
+
+  private stopHeartbeats() {
+    if (this.#heartbeatInterval === undefined) {
+      return
+    }
+    clearInterval(this.#heartbeatInterval)
+    this.#heartbeatInterval = undefined
+  }
+
+  private startPruningPeers() {
+    if (this.#pruningInterval !== undefined) {
+      return
+    }
+    // Pruning happens at the heartbeat frequency, not on a peer ttl frequency,
+    // to minimize variance between peer expiration, since the heartbeat frequency
+    // is expected to be several times higher.
+    this.#pruningInterval = setInterval(() => {
+      this.#peers.prune()
+    }, this.#heartbeatMs)
+  }
+
+  private stopPruningPeers() {
+    if (this.#pruningInterval === undefined) {
+      return
+    }
+    clearInterval(this.#pruningInterval)
+    this.#pruningInterval = undefined
+  }
+}
+
+/**
+ * A summary of the latest Presence information for the set of peers who have
+ * reported a Presence status to us.
+ */
+export class PeerPresenceView<State> {
+  #peersLastSeen = new Map<PeerId, number>()
+  #peerStates = new Map<PeerId, PeerState<State>>()
+  #userPeers = new Map<UserId, Set<PeerId>>()
+  #devicePeers = new Map<DeviceId, Set<PeerId>>()
+
+  /** @hidden */
+  constructor(
+    peersLastSeen: Map<PeerId, number>,
+    peerStates: Map<PeerId, PeerState<State>>,
+    userPeers: Map<UserId, Set<PeerId>>,
+    devicePeers: Map<DeviceId, Set<PeerId>>
+  ) {
+    this.#peersLastSeen = peersLastSeen
+    this.#peerStates = peerStates
+    this.#userPeers = userPeers
+    this.#devicePeers = devicePeers
+  }
+
+  /**
+   * Check if peer is currently present.
+   *
+   * @param peerId
+   * @returns true if the peer has been seen recently
+   */
+  has(peerId: PeerId) {
+    return this.#peerStates.has(peerId)
+  }
+
+  /**
+   * Check when the peer was last seen.
+   *
+   * @param peerId
+   * @returns last seen UNIX timestamp, or undefined for unknown peers
+   */
+  getLastSeen(peerId: PeerId) {
+    return this.#peersLastSeen.get(peerId)
+  }
+
+  /**
+   * Get all recently-seen peers.
+   *
+   * @returns Array of peer ids
+   */
+  getPeers() {
+    return Array.from(this.#peerStates.keys())
+  }
+
+  /**
+   * Get all recently-seen users.
+   *
+   * @returns Array of user ids
+   */
+  getUsers() {
+    return Array.from(this.#userPeers.keys())
+  }
+
+  /**
+   * Get all recently-seen devices.
+   *
+   * @returns Array of device ids
+   */
+  getDevices() {
+    return Array.from(this.#devicePeers.keys())
+  }
+
+  /**
+   * Get all recently-seen peers for this user.
+   *
+   * @param userId
+   * @returns Array of peer ids for this user
+   */
+  getUserPeers(userId: UserId) {
+    const peers = this.#userPeers.get(userId)
+    if (!peers) {
+      return
+    }
+    return Array.from(peers)
+  }
+
+  /**
+   * Get all recently-seen peers for this device.
+   *
+   * @param deviceId
+   * @returns Array of peer ids for this device
+   */
+  getDevicePeers(deviceId: DeviceId) {
+    const peers = this.#devicePeers.get(deviceId)
+    if (!peers) {
+      return
+    }
+    return Array.from(peers)
+  }
+
+  /**
+   * Get most-recently-seen peer from this group.
+   *
+   * @param peers
+   * @returns id of most recently seen peer
+   */
+  getFreshestPeer(peers: Set<PeerId>) {
+    let freshestLastSeen: number
+    return Array.from(peers).reduce((freshest: PeerId | undefined, curr) => {
+      const lastSeen = this.#peersLastSeen.get(curr)
+      if (!lastSeen) {
+        return freshest
+      }
+
+      if (!freshest || lastSeen > freshestLastSeen) {
+        freshestLastSeen = lastSeen
+        return curr
+      }
+
+      return freshest
+    }, undefined)
+  }
+
+  /**
+   * Get current @type PeerState for given peer.
+   *
+   * @param peerId
+   * @returns details for the peer
+   */
+  getPeerInfo(peerId: PeerId) {
+    return this.#peerStates.get(peerId)
+  }
+
+  /**
+   * Get current ephemeral state value for this peer. If a channel is specified,
+   * only returns the ephemeral state for that specific channel. Otherwise,
+   * returns the full ephemeral state.
+   *
+   * @param peerId
+   * @param channel
+   * @returns latest ephemeral state received
+   */
+  getPeerState<Channel extends keyof State>(peerId: PeerId, channel?: Channel) {
+    const fullState = this.#peerStates.get(peerId)?.value
+    if (!channel) {
+      return fullState
+    }
+
+    return fullState?.[channel]
+  }
+
+  /**
+   * Get current ephemeral state value for this user's most-recently-active
+   * peer. See {@link getPeerState}.
+   *
+   * @param userId
+   * @param channel
+   * @returns
+   */
+  getUserState<Channel extends keyof State>(userId: UserId, channel?: Channel) {
+    const peers = this.#userPeers.get(userId)
+    if (!peers) {
+      return undefined
+    }
+    const peer = this.getFreshestPeer(peers)
+    if (!peer) {
+      return undefined
+    }
+
+    return this.getPeerState(peer, channel)
+  }
+
+  /**
+   * Get current ephemeral state value for this device's most-recently-active
+   * peer. See {@link getPeerState}.
+   *
+   * @param userId
+   * @param channel
+   * @returns
+   */
+  getDeviceState<Channel extends keyof State>(
+    deviceId: UserId,
+    channel?: Channel
+  ) {
+    const peers = this.#devicePeers.get(deviceId)
+    if (!peers) {
+      return undefined
+    }
+    const peer = this.getFreshestPeer(peers)
+    if (!peer) {
+      return undefined
+    }
+
+    return this.getPeerState(peer, channel)
+  }
+}
+
+class PeerPresenceInfo<State> extends EventEmitter<PresenceEvents> {
+  #peersLastSeen = new Map<PeerId, number>()
+  #peerStates = new Map<PeerId, PeerState<State>>()
+  #userPeers = new Map<UserId, Set<PeerId>>()
+  #devicePeers = new Map<DeviceId, Set<PeerId>>()
+
+  readonly view: PeerPresenceView<State>
+
+  /**
+   * Build a new peer presence state.
+   *
+   * @param ttl in milliseconds - peers with no activity within this timeframe
+   * are forgotten when {@link prune} is called.
+   */
+  constructor(readonly ttl: number) {
+    super()
+    this.view = new PeerPresenceView(
+      this.#peersLastSeen,
+      this.#peerStates,
+      this.#userPeers,
+      this.#devicePeers
+    )
+  }
+
+  /**
+   * Record that we've seen the given peer recently.
+   *
+   * @param peerId
+   * @param deviceId
+   * @param userId
+   */
+  markSeen(peerId: PeerId, deviceId?: DeviceId, userId?: UserId) {
+    const devicePeers = this.#devicePeers.get(deviceId) ?? new Set<PeerId>()
+    devicePeers.add(peerId)
+    this.#devicePeers.set(deviceId, devicePeers)
+
+    const userPeers = this.#userPeers.get(userId) ?? new Set<PeerId>()
+    userPeers.add(peerId)
+    this.#userPeers.set(userId, userPeers)
+
+    this.#peersLastSeen.set(peerId, Date.now())
+  }
+
+  /**
+   * Record a state update for the given peer. It is also automatically updated with {@link markSeen}.
+   *
+   * @param peerId
+   * @param deviceId
+   * @param userId
+   * @param value
+   */
+  update<Channel extends keyof State>({
+    peerId,
+    deviceId,
+    userId,
+    channel,
+    value,
+  }: {
+    peerId: PeerId
+    deviceId?: DeviceId
+    userId?: UserId
+    channel: Channel
+    value: State[Channel]
+  }) {
+    this.markSeen(peerId, deviceId, userId)
+
+    const peerState = this.#peerStates.get(peerId)
+    const existingState = peerState?.value ?? ({} as State)
+    this.#peerStates.set(peerId, {
+      peerId,
+      deviceId,
+      userId,
+      value: {
+        ...existingState,
+        [channel]: value,
+      },
+    })
+  }
+
+  /**
+   * Forget the given peer.
+   *
+   * @param peerId
+   */
+  delete(peerId: PeerId) {
+    this.#peersLastSeen.delete(peerId)
+    this.#peerStates.delete(peerId)
+
+    Array.from(this.#devicePeers.entries()).forEach(([deviceId, peerIds]) => {
+      if (peerIds.has(peerId)) {
+        peerIds.delete(peerId)
+      }
+      if (peerIds.size === 0) {
+        this.#devicePeers.delete(deviceId)
+      }
+    })
+    Array.from(this.#userPeers.entries()).forEach(([userId, peerIds]) => {
+      if (peerIds.has(peerId)) {
+        peerIds.delete(peerId)
+      }
+      if (peerIds.size === 0) {
+        this.#userPeers.delete(userId)
+      }
+    })
+  }
+
+  /**
+   * Prune all peers that have not been seen since the configured ttl has
+   * elapsed.
+   */
+  prune() {
+    const threshold = Date.now() - this.ttl
+    const stalePeers = new Set(
+      Array.from(this.#peersLastSeen.entries())
+        .filter(([, lastSeen]) => {
+          return lastSeen < threshold
+        })
+        .map(([peerId]) => peerId)
+    )
+    if (stalePeers.size === 0) {
+      return
+    }
+    stalePeers.forEach(stalePeer => {
+      this.delete(stalePeer)
+    })
+  }
+}

package/src/Repo.ts

@@ -977,6 +977,10 @@ export class Repo extends EventEmitter<RepoEvents> {
   metrics(): { documents: { [key: string]: any } } {
     return { documents: this.synchronizer.metrics() }
   }
+
+  shareConfigChanged() {
+    void this.synchronizer.reevaluateDocumentShare()
+  }
 }
 
 export interface RepoConfig {