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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

---
title: Plugin Types
description: Detailed implementation of internal plugins and external system drivers.
icon: Component
---

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

Vane categorizes plugins based on their implementation source and operational logic. This guide covers the high-performance internal components and the drivers that power external extensions.

## Internal Plugins (Rust)

Built-in plugins are compiled directly into the Vane binary for maximum performance.

<Mermaid
	chart="
graph LR
    Engine[Flow Engine] --> Internal{Type?}
    Internal -- Middleware --> Matcher[Matcher/RateLimit]
    Internal -- Terminator --> Proxy[Proxy/Response]
"
/>

### Middleware

Used for cross-layer logic like:

- **`matcher`**: Evaluates conditions against the [KV Store](../resources/kv-store).
- **`ratelimit`**: Token-bucket based limiting.

### Terminators

Responsible for the final action of a flow:

- **L4 Proxy**: TCP/UDP forwarding.
- **L7 Upstream**: Full HTTP reverse proxying.

---

## External Drivers

External plugins are executed by Vane via specialized drivers.

<Mermaid
	chart="
graph LR
    Engine --> Driver{Driver Type}
    Driver -- HTTP --> Remote[Remote Service]
    Driver -- Unix --> Sidecar[Local Sidecar]
    Driver -- Command --> Child[Subprocess]
"
/>

### 1. HTTPX & Unix Drivers

Both drivers encapsulate the plugin's `inputs` into a POST request.

- **HTTPX**: Supports custom timeouts and TLS.
- **Unix**: Communicates over a local socket file.

### 2. Command Driver (Subprocess)

The `command` driver executes a binary or script.

<Steps>
<Step>

### Path Validation

The program must exist within the **Trusted Bin Root** to prevent unauthorized execution.

<Mermaid
	chart="
graph LR
    Input[Program Path] --> Check{In Trusted Root?}
    Check -- Yes --> Safe[Proceed]
    Check -- No --> Block[Log Error]
"
/>

</Step>
<Step>

### Environment Sanitization

To prevent privilege escalation, Vane filters dangerous environment variables.

<Mermaid
	chart="
graph LR
    Env[Input Env] --> Filter{Filter}
    Filter -- Drop --> Unsafe[LD_PRELOAD / PYTHONPATH]
    Filter -- Keep --> Safe[APP_KEY / DEBUG]
    Safe --> Child[Child Process]
"
/>

</Step>
<Step>

### Communication & Logging

Vane pipes inputs to `stdin` and captures `stdout` for results. `stderr` is redirected to Vane's debug logs.

<Mermaid
	chart="
graph LR
    Vane -->|JSON| Stdin[Subprocess STDIN]
    Stdout[Subprocess STDOUT] -->|JSON| Vane
    Stderr[Subprocess STDERR] -->|Text| Log[Vane Logger]
"
/>

</Step>
</Steps>

## External API Contract

All external drivers expect the following JSON response structure:

```json
{
	"status": "success",
	"data": {
		"branch": "success",
		"store": { "user_id": "12345" }
	},
	"message": "Optional error or info message"
}
```

<Callout type="warn" title="Driver Failures">
	If an external driver encounters an I/O error (e.g., connection refused or process crash), it
	automatically triggers the [Passive Circuit
	Breaker](../engine/flow-executor#passive-circuit-breaker) to prevent performance degradation.
</Callout>