vane 0.9.2

A flow-based reverse proxy with multi-layer routing and programmable pipelines.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

---
title: Plugin System
description: The extensible trait-based architecture for processing network flows.
icon: Blocks
---

import { Steps, Step } from 'fumadocs-ui/components/steps';

Vane uses a decoupled, trait-based plugin system that allows logic to be reused across different network layers. The system distinguishes between protocol-agnostic "Generic" plugins and protocol-aware "HTTP" plugins.

## Plugin Types & Hierarchy

All logic units in Vane implement the base `Plugin` trait, which provides identity and parameter definitions. They are then specialized into one of several behavioral traits.

| Trait                 | Target Layer      | Data Access           | External Drivers?       |
| :-------------------- | :---------------- | :-------------------- | :---------------------- |
| **GenericMiddleware** | All (L4, L4+, L7) | Resolved Inputs only  | **Yes** (HTTP/Unix/Cmd) |
| **Terminator**        | All               | KV Store + Connection | No                      |
| **HttpMiddleware**    | Layer 7 only      | Full HTTP Container   | No (Rust Only)          |
| **L7Terminator**      | Layer 7 only      | Full HTTP Container   | No                      |

### The Power of Generic Middleware

`GenericMiddleware` is the most flexible type. It does not touch the raw socket or HTTP container. Instead, it relies on the [Template System](../resources/templates) to receive data and returns branches to control the flow. This abstraction allows these plugins to be implemented in any language and executed as external processes.

## Execution Contexts

Plugins interact with the engine through the `ExecutionContext`. This abstraction allows the same plugin execution logic to operate on different underlying data structures.

<Mermaid
  chart='
graph LR
    subgraph FlowEngine [Flow Engine]
        Executor[Executor] --> Dispatch[Plugin Dispatch]
    end

    subgraph Contexts [ExecutionContexts]
        Dispatch --> TC[TransportContext - L4/L4+]
        Dispatch --> AC[ApplicationContext - L7]
    end

    TC --> KV[(KvStore)]
    TC --> PL[Payload Peek]

    AC --> KV
    AC --> HTTP[HTTP Container]

'
/>

- **TransportContext**: Used in Layer 4. It provides access to the [KV Store](../resources/kv-store) and raw byte buffers ("payloads") for protocol detection.
- **ApplicationContext**: Used in Layer 7. It encapsulates the full HTTP message envelope (headers, body, and metadata).

## Core Interfaces

### The Plugin Trait

The entry point for any plugin implementation. It uses a "downcasting" pattern to let the executor know what capabilities the plugin supports.

```rust title="src/engine/interfaces.rs"
pub trait Plugin: Send + Sync + Any {
    fn name(&self) -> &str;
    fn params(&self) -> Vec<ParamDef>;
    // Downcast helpers
    fn as_generic_middleware(&self) -> Option<&dyn GenericMiddleware> { None }
    fn as_http_middleware(&self) -> Option<&dyn HttpMiddleware> { None }
    // ...
}
```

### The Middleware Contract

Middleware plugins return a `MiddlewareOutput`, consisting of a branch name (to determine the next step) and optional KV updates.

### The Terminator Result

Terminators signal the end of a flow. They can either finish the connection or request an **Upgrade**.
An upgrade result contains a new `ConnectionObject` (e.g., a TLS-wrapped stream) and the target protocol, triggering a transition to the next layer (e.g., L4 -> L4+).

<Callout type="info" title="External Drivers">
	When a plugin is marked as "External", Vane automatically wraps it in a driver that handles the
	JSON-RPC-like communication over HTTP, Unix sockets, or Stdinc/Stdout. From the engine's
	perspective, it looks like a standard `GenericMiddleware`.
</Callout>