Lightning.Collaborate (Lightning v2.18.0)

View Source

Public API for starting collaborative workflow editing sessions.

This module serves as the main entry point for collaborative editing, coordinating the creation and management of document and session processes for workflow collaboration.

All collaborative sessions require a workflow struct.

Example

# Existing workflow
workflow = Lightning.Workflows.get_workflow(workflow_id)

Collaborate.start(user: user, workflow: workflow)

# New workflow
workflow = %Lightning.Workflows.Workflow{
  id: workflow_id,
  project_id: project_id,
  name: "",
  positions: %{}
}

Collaborate.start(user: user, workflow: workflow)

Summary

Functions

lookup(key)

See Lightning.Collaboration.Registry.lookup/1.

start(instance \\ Instance.default(), opts)
start_document(workflow, document_name)

Starts the collaborative document tree for document_name.

start_document(instance, workflow, document_name)
start_document(instance, workflow, document_name, opts)
stop_document(instance \\ Instance.default(), document_name)

Deterministically stops the collaborative document for document_name.

whereis(key)

See Lightning.Collaboration.Registry.whereis/1.

Functions

lookup(key)

See Lightning.Collaboration.Registry.lookup/1.

start(instance \\ Instance.default(), opts)

@spec start(instance :: Lightning.Collaboration.Instance.t(), opts :: Keyword.t()) ::
  GenServer.on_start()

start_document(workflow, document_name)

@spec start_document(
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t()
) :: {:ok, pid()} | {:error, term()}

Starts the collaborative document tree for document_name.

document_name is a positional payload (domain identity); the registered name and the optional owner are process configuration and live in trailing opts, per .claude/guidelines/testable-supervision-trees.md §1.

Options

  • :owner — a pid the document tree monitors. When that pid goes :DOWN, the tree stops :normal (running its flush via terminate/2; :transient means no restart). Lets any caller — a test, a request — get deterministic cleanup by passing owner: self(), with no wrapper. Defaults to nil (no monitor), so production documents outlive the LiveView that starts them.

start_document(instance, workflow, document_name)

@spec start_document(
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t(),
  opts :: Keyword.t()
) :: {:ok, pid()} | {:error, term()}
@spec start_document(
  instance :: Lightning.Collaboration.Instance.t(),
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t()
) :: {:ok, pid()} | {:error, term()}

start_document(instance, workflow, document_name, opts)

@spec start_document(
  instance :: Lightning.Collaboration.Instance.t(),
  workflow :: Lightning.Workflows.Workflow.t(),
  document_name :: String.t(),
  opts :: Keyword.t()
) :: {:ok, pid()} | {:error, term()}

stop_document(instance \\ Instance.default(), document_name)

@spec stop_document(
  instance :: Lightning.Collaboration.Instance.t(),
  document_name :: String.t()
) ::
  :ok

Deterministically stops the collaborative document for document_name.

Tears down its DocumentSupervisor, SharedDoc and PersistenceWriter (with a final flush). Synchronous and idempotent: returns :ok whether or not a document is running. The symmetric partner to start_document/2.

whereis(key)

See Lightning.Collaboration.Registry.whereis/1.