---
title: Flow Executor
description: The high-performance recursive runtime for plugin execution.
icon: GitBranch
---
import { Steps, Step } from 'fumadocs-ui/components/steps';
The Flow Executor is the heart of Vane's runtime. It is responsible for orchestrating the transition between plugins, managing the connections metadata, and ensuring system stability through timeouts and circuit breakers.
## Execution Algorithm
The executor operates recursively through the flow tree. At each step, it performs a series of validations and dispatches before moving to the next branch.
<Steps>
<Step>
### Input Resolution
Before a plugin is executed, its `input` parameters are passed through the Template System. This replaces double-brace variables with real-time metadata.
<Mermaid
chart="
graph LR
Input[JSON Input] --> Tpl[Template Engine]
KV[(KV Store)] --> Tpl
Tpl --> Resolved[Resolved Parameters]
"
/>
</Step>
<Step>
### Plugin Dispatch
The engine looks up the plugin in the registry and invokes it. Vane follows a strict priority order based on the implemented Traits.
<Mermaid
chart="
graph LR
Params[Resolved Params] --> Registry{Lookup Plugin}
Registry --> Http[HttpMiddleware]
Registry --> Generic[GenericMiddleware]
Registry --> Term[Terminator]
"
/>
</Step>
<Step>
### Result Processing
The outcome of the plugin determines whether the engine recurses into a deeper branch or finishes the current flow.
<Mermaid
chart="
graph LR
Result{Plugin Result}
Result -- Branch Name --> Next[Recurse: Next Step]
Result -- Finished --> Done([End Flow])
Result -- Upgrade --> Layer([Layer Transition])
"
/>
</Step>
</Steps>
## Passive Circuit Breaker
To protect the engine from slow or failing external plugins (HTTP/Unix/Command), the executor implements a passive circuit breaker.
<Mermaid
chart="
graph LR
Exec[Execute Plugin] --> Check{In Quiet Period?}
Check -- Yes --> Skip[Skip IO / Return failure]
Check -- No --> RealExec[Invoke External Plugin]
RealExec -- Error/Failure --> Mark[Mark Fail / Start Timer]
RealExec -- Success --> Reset[Reset Failure State]
"
/>
- **Trigger**: A circuit breaker activates if an external plugin returns a runtime error or a designated `failure` branch.
- **Quiet Period**: Controlled by `EXTERNAL_PLUGIN_QUIET_PERIOD_SECS` (default 3s).
## Key Scoping
To ensure that plugins remain modular and don't overwrite each other's data, Vane automatically namespaces every value stored in the [KV Store](../resources/kv-store).
### Scoping Format
`plugin.{flow_path}.{sanitized_plugin_name}.{key}`
- **`flow_path`**: The exact branch path taken to reach this plugin (e.g., `detect.tls.route.match`).
- **`plugin_name`**: The name of the plugin (dots replaced by underscores).
**Example:**
If a plugin named `auth` is executed after a `detect` branch, its output `user` will be stored as:
`plugin.detect.success.auth.user`
## Safety & Limits
| Parameter | Default | Description |
| :---------------------------------- | :------ | :---------------------------------------------------------- |
| `FLOW_EXECUTION_TIMEOUT_SECS` | `10s` | Maximum time allowed for a full flow to complete. |
| `EXTERNAL_PLUGIN_QUIET_PERIOD_SECS` | `3s` | Duration to wait before retrying a failing external plugin. |
<Callout type="warn" title="Key Name Validation">
The executor strictly validates all key names added by plugins. Any attempt to store a key
containing `{` or `}` is rejected to prevent template injection vulnerabilities.
</Callout>