# FlowDrop Session

> Session and message entities for managing interactive, multi-turn workflow execution.

## Overview

The `flowdrop_session` module provides the entity layer for interactive workflow sessions. A session represents an isolated execution environment for a workflow, and session messages track the conversation-like exchange between the user and the workflow.

This module is the foundation for interactive features like the [playground](flowdrop_playground.md) and supports multi-turn workflows where the user sends input and the workflow responds over multiple exchanges. It includes a deferred message processor that handles workflow execution after the HTTP response is sent, keeping the UI responsive.

## Dependencies

- [flowdrop_workflow](flowdrop_workflow.md) (workflow definitions)
- [flowdrop_pipeline](flowdrop_pipeline.md) (execution pipelines)
- [flowdrop_orchestration](flowdrop_orchestration.md) (orchestrator resolution)
- `drupal:user` (session ownership)

## Configuration

### Permissions

| Permission | Description |
|------------|-------------|
| `administer flowdrop_session` | Full administrative access to sessions. Restricted. |
| `create flowdrop_session` | Create new sessions |
| `view own flowdrop_session` | View own sessions |
| `view any flowdrop_session` | View any session |
| `edit own flowdrop_session` | Edit own sessions |
| `edit any flowdrop_session` | Edit any session |
| `delete own flowdrop_session` | Delete own sessions |
| `delete any flowdrop_session` | Delete any session |
| `view own flowdrop_session_message` | View own session messages |
| `view any flowdrop_session_message` | View any session message |
| `execute session workflow` | Execute workflows within a session context |

## Tips and Tricks

### Session Lifecycle

1. **Created** — A new session is created for a specific workflow
2. **Idle** — Session is waiting for user input
3. **Processing** — A message has been sent and the workflow is executing
4. **Completed** — The session has finished (workflow reached a terminal state)

### Deferred Message Processing

The `DeferredMessageProcessor` service handles workflow execution after the HTTP response is sent. This means the user sees an immediate response while the workflow runs in the background. Message status can be polled via the API.

### Queue-Based Processing

For heavier workloads, the module includes a `SessionMessageWorker` queue worker that processes session messages from a Drupal queue, enabling reliable background processing.

## Developer API

> All PHP classes in this module are `@internal` and not part of the stable public API. They may change without notice in any release. See the [BC Policy](../reference/api/bc-policy.md) for details.

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_session.service` | `SessionService` | Main service for session CRUD, message management, and event dispatching |
| `flowdrop_session.deferred_message_processor` | `DeferredMessageProcessor` | Processes workflow execution after HTTP response |

### Entities

#### FlowDropSession (Content Entity)

Represents an isolated execution environment for a workflow. Tracks the session state, associated workflow, and ownership.

#### FlowDropSessionMessage (Content Entity)

Messages within a session — both user inputs and workflow responses.

## References

- [flowdrop_playground](flowdrop_playground.md) — interactive testing UI built on sessions
- [flowdrop_interrupt](flowdrop_interrupt.md) — handles pauses within sessions
- [flowdrop_workflow_executor](flowdrop_workflow_executor.md) — nested workflow execution uses sessions
