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

---
title: Network Layers
description: Understanding Vane's multi-tier packet processing architecture.
icon: Layers
---

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

Vane operates on a strictly tiered architecture, processing connections at different levels of the OSI model depending on the required depth of inspection.

<Mermaid
	chart="
graph LR
    In[Ingress] --> L4{Layer 4: Transport}
    L4 -- TCP/UDP --> L4P{Layer 4+: Carrier}
    L4P -- TLS/QUIC --> L7{Layer 7: Application}
    L7 -- HTTP --> Out[Response]

    L4 -- Proxy --> Upstream[Upstream]
    L4P -- Proxy --> Upstream
    L7 -- Fetch --> Upstream

"
/>

## The Three Layers

### 1. Layer 4 (Transport)

**Source**: `src/layers/l4/`

The entry point for all connections. It operates on raw **TCP Streams** and **UDP Datagrams**.

- **Focus**: Routing based on IP, Port, and initial packet sniffing.
- **Context**: `TransportContext` (Connection metadata, peek buffer).
- **Actions**: Proxy (TCP/UDP), Deny, or **Upgrade** to a higher layer.

### 2. Layer 4+ (Carrier)

**Source**: `src/layers/l4p/`

The "Carrier" layer handles protocol inspection **without full termination**. It parses handshake headers (ClientHello) to make intelligent routing decisions for encrypted protocols.

- **Focus**: TLS SNI, ALPN, QUIC Connection IDs.
- **Context**: `TransportContext` (Same as L4, but with protocol-specific metadata).
- **Actions**: Route based on SNI/Host, Proxy, or **Upgrade** to L7.

### 3. Layer 7 (Application)

**Source**: `src/layers/l7/`

The Application layer provides full **HTTP Termination**. It parses the entire request, allowing for deep inspection and modification.

- **Focus**: HTTP Headers, Body, Path, Query, Methods.
- **Context**: `Container` (Full Request/Response envelope).
- **Actions**: Middleware transformation, Synthetic Responses, Upstream Fetching.

## Layer Transitions (Upgrading)

Connections move up the stack via an **Upgrade** mechanism. This is triggered by a `Terminator` plugin returning an upgrade signal.

<Steps>
<Step>

### L4 Ingress

A TCP connection arrives. The **L4 Flow** peeks at the first few bytes. The `detect.tls` plugin identifies a TLS ClientHello.

<Mermaid
	chart="
graph LR
    Socket[New Socket] --> Peek{Peek Bytes}
    Peek -- 0x16 --> Detect[Detect TLS]
    Detect --> Term[Upgrade Terminator]
"
/>

</Step>
<Step>

### Upgrade Signal

The L4 flow executes an **Upgrade Terminator** (e.g., `upgrade "tls"`). The engine suspends L4 processing and wraps the stream in a TLS parser.

<Mermaid
	chart="
graph LR
    Term --> Signal[Signal: Upgrade TLS]
    Signal --> Engine[Engine Switch]
    Engine --> Wrap[Wrap Stream]
    Wrap --> L4P[L4+ Dispatcher]
"
/>

</Step>
<Step>

### L4+ Routing

The **L4+ Flow** (`tls.json`) parses the SNI (e.g., `example.com`). It decides this domain requires WAF processing.

<Mermaid
	chart="
graph LR
    L4P --> Parse[Parse ClientHello]
    Parse --> SNI[Extract SNI]
    SNI --> Route{Check Rules}
    Route -- Match --> Next[Upgrade HTTTPX]
"
/>

</Step>
<Step>

### Final Upgrade

The L4+ flow executes `upgrade "httpx"`. The engine performs the TLS handshake (using the cert for `example.com`), decrypts the traffic, and hands the plaintext stream to the **L7 Engine**.

<Mermaid
	chart="
graph LR
    Next --> Handshake[TLS Handshake]
    Handshake --> Decrypt[Decrypt Stream]
    Decrypt --> L7[L7 Adapter]
"
/>

</Step>
</Steps>