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

package/src/presence/Presence.ts

@@ -0,0 +1,311 @@
+import { EventEmitter } from "eventemitter3"
+
+import { DocHandle, DocHandleEphemeralMessagePayload } from "../DocHandle.js"
+import {
+  DeviceId,
+  PresenceConfig,
+  PresenceEvents,
+  PresenceMessage,
+  PresenceMessageType,
+  PresenceState,
+  UserId,
+} from "./types.js"
+import {
+  DEFAULT_HEARTBEAT_INTERVAL_MS,
+  DEFAULT_PEER_TTL_MS,
+  PRESENCE_MESSAGE_MARKER,
+} from "./constants.js"
+import { PeerPresenceInfo } from "./PeerPresenceInfo.js"
+
+/**
+ * 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 PresenceState,
+  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<State>(DEFAULT_PEER_TTL_MS)
+    this.#localState = {} as State
+    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<State>(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.has(peerId)) {
+        this.announce()
+      }
+
+      switch (message.type) {
+        case "heartbeat":
+          this.#peers.markSeen(peerId)
+          this.emit("heartbeat", { type: "heartbeat", peerId })
+          break
+        case "goodbye":
+          this.#peers.delete(peerId)
+          this.emit("goodbye", { type: "goodbye", peerId })
+          break
+        case "update":
+          this.#peers.update({
+            peerId,
+            deviceId,
+            userId,
+            value: { [message.channel]: message.value } as Partial<State>,
+          })
+          this.emit("update", {
+            type: "update",
+            peerId,
+            deviceId,
+            userId,
+            channel: message.channel,
+            value: message.value,
+          })
+          break
+        case "snapshot":
+          this.#peers.update({
+            peerId,
+            deviceId,
+            userId,
+            value: message.state as State,
+          })
+          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.states
+  }
+
+  /**
+   * 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)
+  }
+
+  /**
+   * 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.send({ type: "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) {
+    const value = this.#localState[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 doBroadcast(
+    type: PresenceMessageType,
+    extra?: Record<string, unknown>
+  ) {
+    this.send({
+      userId: this.userId,
+      deviceId: this.deviceId,
+      type,
+      ...extra,
+    })
+  }
+
+  private send(message: Record<string, unknown>) {
+    if (!this.#running) {
+      return
+    }
+    this.#handle.broadcast({
+      [PRESENCE_MESSAGE_MARKER]: message,
+    })
+  }
+
+  private startHeartbeats() {
+    if (this.#heartbeatInterval !== undefined) {
+      return
+    }
+    this.#heartbeatInterval = setInterval(() => {
+      this.send({ type: "heartbeat" })
+    }, 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
+  }
+}

package/src/presence/constants.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000
+export const DEFAULT_PEER_TTL_MS = 3 * DEFAULT_HEARTBEAT_INTERVAL_MS
+export const PRESENCE_MESSAGE_MARKER = "__presence"

package/src/presence/types.ts

@@ -0,0 +1,94 @@
+import { PeerId } from "../types.js"
+import { PRESENCE_MESSAGE_MARKER } from "./constants.js"
+
+export type UserId = unknown
+export type DeviceId = unknown
+
+export type PresenceState = Record<string, any>
+
+export type PeerStatesValue<State extends PresenceState> = Record<
+  PeerId,
+  PeerState<State>
+>
+
+export type PeerState<State extends PresenceState> = {
+  peerId: PeerId
+  lastActiveAt: number
+  lastUpdateAt: number
+  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"
+}
+
+export type PresenceMessage = {
+  [PRESENCE_MESSAGE_MARKER]:
+    | PresenceMessageUpdate
+    | PresenceMessageSnapshot
+    | PresenceMessageHeartbeat
+    | PresenceMessageGoodbye
+}
+
+export 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 type PresenceConfig<State extends PresenceState> = {
+  /** 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
+}

package/test/Presence.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it } from "vitest"
+
+import { Presence } from "../src/presence/Presence.js"
+import { PresenceEventHeartbeat } from "../src/presence/types.js"
+import { Repo } from "../src/Repo.js"
+import { PeerId } from "../src/types.js"
+import { DummyNetworkAdapter } from "../src/helpers/DummyNetworkAdapter.js"
+import { waitFor } from "./helpers/waitFor.js"
+import { wait } from "./helpers/wait.js"
+
+type PresenceState = { position: number }
+
+describe("Presence", () => {
+  async function setup(opts?: { skipAnnounce?: boolean }) {
+    const alice = new Repo({ peerId: "alice" as PeerId })
+    const bob = new Repo({ peerId: "bob" as PeerId })
+    const [aliceToBob, bobToAlice] = DummyNetworkAdapter.createConnectedPair()
+    alice.networkSubsystem.addNetworkAdapter(aliceToBob)
+    bob.networkSubsystem.addNetworkAdapter(bobToAlice)
+    if (!opts?.skipAnnounce) {
+      aliceToBob.peerCandidate("bob" as PeerId)
+      bobToAlice.peerCandidate("alice" as PeerId)
+    }
+    await Promise.all([
+      alice.networkSubsystem.whenReady(),
+      bob.networkSubsystem.whenReady(),
+    ])
+
+    const aliceHandle = alice.create({
+      test: "doc",
+    })
+    const alicePresence = new Presence<PresenceState>({
+      handle: aliceHandle,
+      userId: "alice",
+      deviceId: "phone",
+    })
+
+    const bobHandle = await bob.find(aliceHandle.url)
+    const bobPresence = new Presence<PresenceState>({
+      handle: bobHandle,
+      userId: "bob",
+      deviceId: "phone",
+    })
+
+    return {
+      alice: {
+        repo: alice,
+        handle: aliceHandle,
+        presence: alicePresence,
+        network: aliceToBob,
+      },
+      bob: {
+        repo: bob,
+        handle: bobHandle,
+        presence: bobPresence,
+        network: bobToAlice,
+      },
+    }
+  }
+
+  describe("start", () => {
+    it("activates presence and shares initial state", async () => {
+      const { alice, bob } = await setup()
+
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+      })
+      expect(alice.presence.running).toBe(true)
+
+      bob.presence.start({
+        initialState: {
+          position: 456,
+        },
+      })
+      expect(bob.presence.running).toBe(true)
+
+      await waitFor(() => {
+        const bobPeerStates = bob.presence.getPeerStates().value
+        const bobPeers = Object.keys(bobPeerStates)
+
+        expect(bobPeers.length).toBe(1)
+        expect(bobPeers[0]).toBe(alice.repo.peerId)
+        expect(bobPeerStates[alice.repo.peerId].value.position).toBe(123)
+
+        const alicePeerStates = alice.presence.getPeerStates().value
+        const alicePeers = Object.keys(alicePeerStates)
+
+        expect(alicePeers.length).toBe(1)
+        expect(alicePeers[0]).toBe(bob.repo.peerId)
+        expect(alicePeerStates[bob.repo.peerId].value.position).toBe(456)
+      })
+    })
+
+    it("does nothing if invoked on an already-running Presence", async () => {
+      const { alice } = await setup()
+
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+      })
+      expect(alice.presence.running).toBe(true)
+
+      alice.presence.start({
+        initialState: {
+          position: 789,
+        },
+      })
+      expect(alice.presence.running).toBe(true)
+      expect(alice.presence.getLocalState().position).toBe(123)
+    })
+  })
+
+  describe("stop", () => {
+    it("stops running presence and ignores further broadcasts", async () => {
+      const { alice, bob } = await setup()
+
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+      })
+      expect(alice.presence.running).toBe(true)
+
+      bob.presence.start({
+        initialState: {
+          position: 456,
+        },
+      })
+
+      await waitFor(() => {
+        const bobPeerStates = bob.presence.getPeerStates().value
+        const bobPeers = Object.keys(bobPeerStates)
+
+        expect(bobPeers.length).toBe(1)
+        expect(bobPeers[0]).toBe(alice.repo.peerId)
+        expect(bobPeerStates[alice.repo.peerId].value.position).toBe(123)
+      })
+
+      alice.presence.stop()
+      expect(alice.presence.running).toBe(false)
+
+      console.log("waiting for peers to leave")
+      await waitFor(() => {
+        const bobPeerStates = bob.presence.getPeerStates().value
+        const bobPeers = Object.keys(bobPeerStates)
+
+        expect(bobPeers.length).toBe(0)
+      })
+    })
+
+    it("does nothing if invoked on a non-running Presence", async () => {
+      const { alice } = await setup()
+
+      expect(alice.presence.running).toBe(false)
+
+      alice.presence.stop()
+
+      expect(alice.presence.running).toBe(false)
+    })
+  })
+
+  describe("heartbeats", () => {
+    it("sends heartbeats on the configured interval", async () => {
+      const { alice, bob } = await setup()
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+        heartbeatMs: 10,
+      })
+
+      bob.presence.start({
+        initialState: {
+          position: 456,
+        },
+      })
+
+      let hbPeerMsg: PresenceEventHeartbeat
+      bob.presence.on("heartbeat", msg => {
+        hbPeerMsg = msg
+      })
+
+      await waitFor(() => {
+        expect(hbPeerMsg.peerId).toEqual(alice.repo.peerId)
+        expect(hbPeerMsg.type).toEqual("heartbeat")
+      })
+    })
+
+    it("delays heartbeats when there is a state update", async () => {
+      const { alice, bob } = await setup()
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+        heartbeatMs: 10,
+      })
+
+      bob.presence.start({
+        initialState: {
+          position: 456,
+        },
+      })
+
+      let hbPeerMsg: PresenceEventHeartbeat
+      bob.presence.on("heartbeat", msg => {
+        hbPeerMsg = msg
+      })
+
+      await wait(7)
+      alice.presence.broadcast("position", 789)
+      await wait(7)
+
+      expect(hbPeerMsg).toBeUndefined()
+
+      await wait(20)
+      expect(hbPeerMsg.peerId).toEqual(alice.repo.peerId)
+      expect(hbPeerMsg.type).toEqual("heartbeat")
+    })
+  })
+
+  describe("broadcast", () => {
+    it("sends updates to peers", async () => {
+      const { alice, bob } = await setup()
+      alice.presence.start({
+        initialState: {
+          position: 123,
+        },
+      })
+
+      bob.presence.start({
+        initialState: {
+          position: 456,
+        },
+      })
+
+      await waitFor(() => {
+        const bobPeerStates = bob.presence.getPeerStates().value
+        const bobPeers = Object.keys(bobPeerStates)
+
+        expect(bobPeers.length).toBe(1)
+        expect(bobPeerStates[alice.repo.peerId].value.position).toBe(123)
+      })
+
+      alice.presence.broadcast("position", 213)
+
+      await waitFor(() => {
+        const bobPeerStates = bob.presence.getPeerStates().value
+        const bobPeers = Object.keys(bobPeerStates)
+
+        expect(bobPeers.length).toBe(1)
+        expect(bobPeerStates[alice.repo.peerId].value.position).toBe(213)
+      })
+    })
+  })
+})

package/test/helpers/wait.ts

@@ -0,0 +1,5 @@
+export async function wait(ms: number) {
+  return new Promise(resolve => {
+    setTimeout(resolve, ms)
+  })
+}

package/test/helpers/waitFor.ts

@@ -0,0 +1,14 @@
+export async function waitFor(callback: () => void) {
+  let sleepMs = 10
+  while (true) {
+    try {
+      callback()
+      break
+    } catch (e) {
+      sleepMs *= 2
+      await new Promise(resolve => {
+        setTimeout(resolve, sleepMs)
+      })
+    }
+  }
+}