Lightning.Collaboration.Session (Lightning v2.15.0-pre5)
View SourceManages individual user sessions for collaborative workflow editing.
A Session acts as a bridge between a parent process (typically a Phoenix channel) and a SharedDoc process that manages the Y.js CRDT document. Each user editing a workflow has their own Session process that handles:
- User presence tracking via
Lightning.Workflows.Presence - Bi-directional Y.js message routing between parent and SharedDoc
- Connection management to existing SharedDoc processes via Registry lookup
- Workflow document initialization with database data when needed
- Cleanup when the parent process disconnects
Sessions are temporary processes that monitor their parent and terminate when the parent disconnects, ensuring proper cleanup of presence tracking and SharedDoc observers.
Summary
Functions
Returns a specification to start this module under a supervisor.
Get the current document.
Resets the workflow document to the latest snapshot from the database.
Saves the current workflow state from the Y.Doc to the database.
Start a new session for a workflow.
Types
@type start_opts() :: [ workflow: Lightning.Workflows.Workflow.t(), user: Lightning.Accounts.User.t(), parent_pid: pid() ]
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
Get the current document.
@spec reset_workflow(pid(), Lightning.Accounts.User.t()) :: {:ok, Lightning.Workflows.Workflow.t()} | {:error, :workflow_deleted | :internal_error}
Resets the workflow document to the latest snapshot from the database.
This operation:
- Fetches the latest workflow from the database
- Clears all Y.Doc collections (jobs, edges, triggers arrays)
- Re-serializes the workflow to the Y.Doc
- Broadcasts updates to all connected clients via SharedDoc
All collaborative editing history in the Y.Doc is preserved (operation log), but the document content is replaced with the database state.
Parameters
session_pid: The Session process PIDuser: The user performing the reset (for authorization logging)
Returns
{:ok, workflow}- Successfully reset with updated workflow{:error, :workflow_deleted}- Workflow has been deleted from database{:error, :internal_error}- SharedDoc not available
Examples
iex> Session.reset_workflow(session_pid, user)
{:ok, %Workflow{lock_version: 5}}
iex> Session.reset_workflow(session_pid, user)
{:error, :workflow_deleted}@spec save_workflow(pid(), Lightning.Accounts.User.t()) :: {:ok, Lightning.Workflows.Workflow.t()} | {:error, :workflow_deleted | :deserialization_failed | :internal_error | Ecto.Changeset.t()}
Saves the current workflow state from the Y.Doc to the database.
This function:
- Extracts the current workflow data from the SharedDoc's Y.Doc
- Converts Y.js types to Elixir maps suitable for Ecto
- Calls Lightning.Workflows.save_workflow/3 for validation and persistence
- Returns the saved workflow
Note: This assumes all Y.js updates have been processed before this call, which is guaranteed by Phoenix Channel's synchronous message handling.
Parameters
session_pid: The Session process PIDuser: The user performing the save (for authorization and auditing)
Returns
{:ok, workflow}- Successfully saved{:error, :workflow_deleted}- Workflow has been deleted{:error, changeset}- Validation or persistence error
Examples
iex> Session.save_workflow(session_pid, user)
{:ok, %Workflow{}}
iex> Session.save_workflow(session_pid, user)
{:error, %Ecto.Changeset{}}Start a new session for a workflow.
The session will be started as a child of the Collaboration.Supervisor.
Options
workflow- The workflow struct to start the session for.user- The user to start the session for.parent_pid- The pid of the parent process. Defaults to the current process.