heldar-kernel 0.2.0

Heldar kernel — media/DVR control plane, perception ingest + sampler, zone engine, auth, and the worker SDK contract. The open, domain-agnostic platform that domain apps build on.
Documentation 
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

//! Remote-access overlay awareness (open kernel platform feature; see `docs/REMOTE-ACCESS.md`).
//!
//! A Heldar deployment is typically behind CGNAT (no inbound port-forward, DDNS useless). The
//! supported way to reach it remotely is a **WireGuard overlay** — Tailscale for personal/dev use,
//! NetBird self-hosted for shipped products — running as an EXTERNAL daemon on the host. The overlay
//! is deliberately *orthogonal* to the media stack: MediaMTX and this API keep serving on their
//! normal ports, now reachable over the overlay's interface by authorized peers. Connections are
//! P2P-first (direct hole-punched / IPv6 when possible) and end-to-end encrypted, so no relay can
//! ever read camera video.
//!
//! The kernel does **not** embed or manage WireGuard — that would duplicate mature daemons. It only
//! *observes* the configured overlay interface and reports whether remote access is currently
//! functional, so the dashboard/health surface can show it without log-diving. This keeps the
//! capability fully open (Apache-2.0) and transport-agnostic.

use serde::Serialize;

use crate::config::Config;

/// Health of the remote-access overlay, surfaced via `/api/v1/system`.
#[derive(Debug, Clone, Serialize)]
pub struct OverlayStatus {
    /// Whether remote access via an overlay is configured at all (else the deployment is LAN-only).
    pub enabled: bool,
    /// `tailscale` | `netbird` | `wireguard` | `none`.
    pub kind: String,
    /// The probed interface (e.g. `tailscale0`), if configured.
    pub iface: Option<String>,
    /// Whether that interface currently exists on the host (i.e. the overlay daemon created it).
    pub present: bool,
    /// Raw `operstate` of the interface, if readable.
    pub operstate: Option<String>,
    /// Whether remote access is considered functional right now.
    pub up: bool,
    /// Human-readable explanation for the dashboard.
    pub note: String,
}

/// A TUN/overlay interface is "up" when it exists and its operstate is `up` or `unknown`. WireGuard
/// and Tailscale TUN devices commonly report `unknown` even when fully functional (the kernel does
/// not track carrier on a point-to-point TUN), so `unknown` must NOT be treated as down.
fn is_up(present: bool, operstate: Option<&str>) -> bool {
    present && matches!(operstate, None | Some("up") | Some("unknown"))
}

/// Probe the configured overlay interface and report remote-access health. Dependency-free: reads
/// `/sys/class/net/<iface>` (Linux), so it is cheap enough to call per `/system` request.
pub fn status(cfg: &Config) -> OverlayStatus {
    if !cfg.overlay_enabled {
        return OverlayStatus {
            enabled: false,
            kind: cfg.overlay_kind.clone(),
            iface: cfg.overlay_iface.clone(),
            present: false,
            operstate: None,
            up: false,
            note: "Remote-access overlay disabled (HELDAR_OVERLAY_ENABLED=false); reachable on the LAN only."
                .into(),
        };
    }
    let Some(iface) = cfg.overlay_iface.clone() else {
        return OverlayStatus {
            enabled: true,
            kind: cfg.overlay_kind.clone(),
            iface: None,
            present: false,
            operstate: None,
            up: false,
            note: "Overlay enabled but HELDAR_OVERLAY_IFACE is unset; cannot determine status."
                .into(),
        };
    };

    let base = std::path::Path::new("/sys/class/net").join(&iface);
    let present = base.exists();
    let operstate = std::fs::read_to_string(base.join("operstate"))
        .ok()
        .map(|s| s.trim().to_string());
    let up = is_up(present, operstate.as_deref());

    let note = if !present {
        format!(
            "Overlay interface '{iface}' not found — is the {} daemon running and connected?",
            cfg.overlay_kind
        )
    } else if up {
        format!(
            "Overlay '{}' up on '{iface}'; deployment reachable to authorized peers (P2P-first, end-to-end encrypted).",
            cfg.overlay_kind
        )
    } else {
        format!(
            "Overlay interface '{iface}' present but not up (operstate={}).",
            operstate.as_deref().unwrap_or("?")
        )
    };

    OverlayStatus {
        enabled: true,
        kind: cfg.overlay_kind.clone(),
        iface: Some(iface),
        present,
        operstate,
        up,
        note,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn tun_unknown_counts_as_up() {
        // TUN devices report "unknown" when functional — must be treated as up.
        assert!(is_up(true, Some("unknown")));
        assert!(is_up(true, Some("up")));
        assert!(is_up(true, None));
    }

    #[test]
    fn down_or_absent_is_not_up() {
        assert!(!is_up(true, Some("down")));
        assert!(!is_up(false, Some("up")));
        assert!(!is_up(false, None));
    }
}