GenServer managing a collaborative document session.

Sessions provide lifecycle management for collaborative documents:

• Dynamic start via Registry + DynamicSupervisor
• Subscriber tracking with automatic crash detection
• Grace period before shutdown when all subscribers leave
• Periodic persistence to storage
• Delta broadcasting via PubSub

Usage

# Start or get existing session
{:ok, pid} = Grove.Session.get_or_start("doc_123", pubsub: MyApp.PubSub)

# Join the session (returns current tree state)
{:ok, tree} = Grove.Session.join(pid)

# Mutate the tree and broadcast delta
:ok = Grove.Session.mutate(pid, fn tree ->
  updated = Grove.Tree.update_node(tree, "node_1", &update_fn/1)
  delta = {:update_attrs, "node_1", %{value: "new"}}
  {updated, delta}
end)

# Leave session when done
:ok = Grove.Session.leave(pid)

LiveView Integration

def mount(%{"id" => doc_id}, _session, socket) do
  {:ok, session_pid} = Grove.Session.get_or_start(doc_id, pubsub: MyApp.PubSub)
  {:ok, tree} = Grove.Session.join(session_pid)

  if connected?(socket) do
    Phoenix.PubSub.subscribe(MyApp.PubSub, Grove.Session.topic(doc_id))
  end

  socket = assign(socket, grove_session: session_pid, grove_tree: tree)
  {:ok, socket}
end

def terminate(_reason, socket) do
  if pid = socket.assigns[:grove_session] do
    Grove.Session.leave(pid)
  end
end

Options

• :pubsub - Required. Phoenix.PubSub module for broadcasting.
• :tree - Optional. Initial tree state. Defaults to empty tree.
• :grace_period - Optional. Ms before shutdown when empty. Default: 30_000.
• :snapshot_interval - Optional. Ms between persistence. Default: 60_000. Set to nil to disable.
• :storage - Optional. Storage module (e.g., Grove.Storage.ETS).
• :storage_ref - Optional. Storage reference for persistence.
• :use_document_storage - Optional. Use snapshot + event log persistence. Default: true. Set to false for legacy full-tree persistence.