zlayer-overlay 0.14.2

Encrypted overlay networking for containers using boringtun userspace WireGuard
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

//! Unprivileged userspace `WireGuard` edge client ("`ZLayer` Edge").
//!
//! Joins a process to an overlay without a TUN device and without
//! elevated privileges: boringtun's `Tunn` drives the `WireGuard` noise
//! pipeline over a plain UDP socket (see [`crate::tunn_loop`]), and a
//! smoltcp userspace netstack terminates TCP inside the tunnel so
//! forwarded connections never touch the host routing table.
//!
//! Not to be confused with [`crate::edge_cache`], the unrelated
//! CDN edge-cache module.

pub mod artifact;
pub mod client;
pub mod forward;
pub mod netstack;
pub mod probe;

use std::time::Duration;

/// Errors produced by the edge client.
#[derive(Debug, thiserror::Error)]
pub enum EdgeError {
    /// Fetching, staging, or validating an edge artifact failed.
    #[error("edge artifact error: {0}")]
    Artifact(String),

    /// The edge join token was malformed or unsupported.
    #[error("edge token error: {0}")]
    Token(#[from] zlayer_types::overlayd::EdgeTokenError),

    /// The smoltcp userspace netstack failed.
    #[error("edge netstack error: {0}")]
    Netstack(String),

    /// Establishing the `WireGuard` session with the overlay failed.
    #[error("edge connect error: {0}")]
    Connect(String),

    /// Forwarding a TCP connection across the tunnel failed.
    #[error("edge forward error: {0}")]
    Forward(String),

    /// A connectivity probe failed.
    #[error("edge probe error: {0}")]
    Probe(String),

    /// An underlying overlay-layer error.
    #[error(transparent)]
    Overlay(#[from] crate::OverlayError),

    /// An underlying I/O error.
    #[error(transparent)]
    Io(#[from] std::io::Error),
}

/// Per-direction (rx and tx) buffer size for each netstack TCP socket.
pub const EDGE_TCP_BUFFER_BYTES: usize = 256 * 1024;

/// Idle timeout applied to forwarded TCP connections.
pub const EDGE_TCP_TIMEOUT: Duration = Duration::from_secs(60);

/// Grace period after connect during which an absent `WireGuard`
/// handshake is tolerated before the session is declared failed.
pub const EDGE_HANDSHAKE_GRACE: Duration = Duration::from_secs(30);

/// Age after which the last completed handshake is considered stale and
/// the session must be re-established. Kept in parity with the overlay
/// health checker's [`crate::health::HANDSHAKE_TIMEOUT_SECS`].
pub const EDGE_HANDSHAKE_STALE: Duration = Duration::from_secs(180);

/// Upper bound for the exponential reconnect backoff.
pub const EDGE_BACKOFF_MAX: Duration = Duration::from_secs(60);

/// First port of the ephemeral source-port range used by the netstack
/// for outbound connections (start of the IANA dynamic range).
pub const EDGE_EPHEMERAL_PORT_START: u16 = 49152;

/// One forwarded TCP connection as a bidirectional byte pipe.
///
/// `tx` carries host→overlay bytes; dropping it closes the send half of
/// the tunneled connection. `rx` yields overlay→host bytes; a `None`
/// from `recv` means the remote peer closed.
pub struct TcpConn {
    /// Host→overlay bytes. Drop the sender to close the send half.
    pub tx: tokio::sync::mpsc::Sender<Vec<u8>>,
    /// Overlay→host bytes. Channel closure (`recv` → `None`) means the
    /// remote peer closed the connection.
    pub rx: tokio::sync::mpsc::Receiver<Vec<u8>>,
}