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

package/src/Presence.ts

@@ -1,722 +0,0 @@
-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)
-    })
-  }
-}