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

---
title: System
description: OS abstractions, lifecycle management, and file system watchers.
icon: Cpu
---

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

The `src/common/sys` module acts as the interface between the Vane engine and the underlying operating system. It handles process lifecycle, resource introspection, and file system monitoring.

## Lifecycle Management

The `lifecycle.rs` module ensures the system environment is correct before the engine starts and manages background maintenance tasks.

### Initialization

Before any listener binds to a port, `ensure_config_files_exist()` is called. This function performs a "dry run" of the filesystem, creating any missing configuration directories (`listener/`, `certs/`, etc.) to ensure a smooth first-run experience.

### Background Tasks

It is also responsible for spawning the "heartbeat" of the system:

- Upstream health checkers.
- UDP/QUIC session cleanup tasks.
- Periodical maintenance routines.

## Hotswap Watcher

The `watcher.rs` module implements the file system monitoring logic that powers Vane's zero-downtime reconfiguration.

### Event Processing Pipeline

The watcher system is designed to be robust against "noisy" file system events (like those generated by text editors). It employs a sophisticated **Routing** and **Debouncing** pipeline:

<Mermaid
	chart='
graph TD;
    Event[FS Event] --> Watcher[Notify Watcher];
    Watcher --> Filter{Path Filter};
    
    Filter -- "listener/*" --> ChP[Ports Channel];
    Filter -- "nodes.json" --> ChN[Nodes Channel];
    Filter -- "resolvers/*" --> ChR[Resolvers Channel];
    Filter -- "certs/*" --> ChC[Certs Channel];
    Filter -- "applications/*" --> ChA[Apps Channel];
    
    subgraph Debouncer [Debouncing Logic]
        ChP --> TimerP{Reset Timer?};
        ChN --> TimerN{Reset Timer?};
        ChR --> TimerR{Reset Timer?};
        ChC --> TimerC{Reset Timer?};
        ChA --> TimerA{Reset Timer?};
    end
    
    TimerP -- "Silence > 2s" --> SigP([Reload Ports]);
    TimerN -- "Silence > 2s" --> SigN([Reload Nodes]);
    TimerR -- "Silence > 2s" --> SigR([Reload Resolvers]);
    TimerC -- "Silence > 2s" --> SigC([Reload Certs]);
    TimerA -- "Silence > 2s" --> SigA([Reload Apps]);
'
/>

### The Debouncing Strategy

To prevent rapid-fire reloads (e.g., when an editor writes a temporary swap file before the actual file), Vane implements a **2-second debounce window**.

The logic works by constantly resetting a timer whenever a new event arrives. Only when the channel remains silent for the full duration is the signal propagated to the reload handlers.

```rust
// Simplified logic
loop {
    tokio::select! {
        Some(_) = rx.recv() => continue, // Reset timer on new event
        _ = sleep(Duration::from_secs(2)) => {
            // Fire event only after 2 seconds of silence
            tx.send(()).await;
        }
    }
}
```

## Resource Introspection

The `system.rs` module provides cross-platform utilities to query the host's hardware resources, primarily used by the [Adaptive Memory Monitor](../bootstrap/monitoring).

- **Linux**: Parses `/proc/meminfo`.
- **macOS / FreeBSD**: Uses `sysctl` commands (`vm.page_free_count`).

<Callout type="warn" title="Platform Support">
	If the operating system is not one of the supported targets (Linux, macOS, FreeBSD),
	`get_free_memory()` returns `None`, causing Vane to fall back to safe, static memory limits.
</Callout>