---
title: Key Value Store
description: The per-connection metadata storage mechanism in Vane.
icon: Database
---
import { Steps, Step } from 'fumadocs-ui/components/steps';
The `KvStore` is a high-performance, per-connection storage space used to accumulate metadata as a connection traverses the different layers of the Vane engine. It serves as the primary source of truth for the [Template System](./templates) and plugin decision-making.
## Implementation
Technically, the `KvStore` is a type alias for `ahash::AHashMap<String, String>`.
- **AHashMap**: Vane uses `ahash` because it is significantly faster than the standard library's `HashMap` for small-to-medium string keys.
- **String Storage**: To maintain maximum compatibility, all values are stored as strings.
## Lifecycle
The `KvStore` follows the strict lifecycle of the network connection it is attached to.
<Steps>
<Step>
### Creation Phase
A new store is initialized in the `ingress` layer immediately after a TCP or UDP connection is accepted.
<Mermaid
chart="
graph LR
Socket[Accept Socket] --> Init[Init KvStore]
Init --> Fill[Populate conn.ip, uuid...]
Fill --> Flow[Pass to Flow Engine]
"
/>
</Step>
<Step>
### Mutation & Processing
The `KvStore` is owned by the connection task. As the connection traverses layers, metadata is added incrementally.
<Mermaid
chart="
graph LR
L4[L4 Layer] -->|conn.proto| KV[(KvStore)]
L4P[L4+ Layer] -->|tls.sni| KV
L7[L7 Middleware] -->|plugin.auth.user| KV
"
/>
</Step>
<Step>
### Destruction Phase
When the connection terminates, the task ends and the `KvStore` is automatically dropped.
<Mermaid
chart="
graph LR
Close[Connection Close] --> Drop[Drop KvStore]
Drop --> Free[Free Memory]
"
/>
</Step>
</Steps>
## Standard Connection Keys
Upon initialization, Vane pre-populates the store with essential metadata under the `conn` namespace:
| Key | Description | Example |
| :--------------- | :------------------------------------------------------- | :-------------- |
| `conn.uuid` | A unique UUIDv7 (ordered) identifier for the connection. | `018d1a...` |
| `conn.ip` | The source (client) IP address. | `192.168.1.100` |
| `conn.port` | The source (client) port number. | `54321` |
| `conn.proto` | The transport protocol (`tcp` or `udp`). | `tcp` |
| `conn.timestamp` | The Unix timestamp of when the connection was accepted. | `1736340000` |
## Key Scoping & Conventions
To prevent collisions, Vane follows a strict dot-notated naming convention:
- **`conn.*`**: Core transport-layer metadata.
- **`tls.*`**: Metadata from TLS inspection.
- **`http.*`**: Metadata from HTTP protocol handlers.
- **`plugin.<path>.<name>.*`**: Scoped keys added by specific plugins.
<Callout type="info" title="Performance Tip">
Avoid storing large blobs of data (like full request bodies) as keys. Use the store for metadata
and rely on the execution context for payload access.
</Callout>