dig_nat/
config.rs

1//! Connection configuration — the enabled methods, per-method timeout, relay/STUN endpoints, and the
2//! cert-binding policy that shape a [`crate::connect`] call. Built with a fluent builder; the caller
3//! never selects the traversal method (only which ones are *enabled*).
4//!
5//! The local mTLS identity is NOT here: it is a [`dig_tls::NodeCert`] the caller passes to
6//! [`crate::connect`] directly (dig-tls owns the cert model — CA, leaf, peer_id, binding).
7
8use std::time::Duration;
9
10use crate::method::TraversalKind;
11use dig_tls::BindingPolicy;
12
13/// Which traversal methods are enabled + the per-method deadline, relay settings, and cert-binding
14/// policy for a connect.
15///
16/// The DEFAULT enables every method in the canonical order with sane timeouts and the canonical
17/// [`dig_constants::DIG_RELAY_URL`] relay. The caller tweaks via the builder but never picks *which*
18/// method wins — the strategy does, first-success-wins, relay-last.
19#[derive(Debug, Clone)]
20pub struct NatConfig {
21    /// The traversal techniques permitted, by kind. The strategy always tries them in
22    /// [`TraversalKind::rank`] order regardless of the order here.
23    pub enabled_methods: Vec<TraversalKind>,
24    /// Per-method hard timeout — a method that does not complete in this window is abandoned and the
25    /// strategy moves on (this is the guarantee that a hung method can never block `connect`).
26    pub per_method_timeout: Duration,
27    /// The relay WebSocket endpoint for the relay-coordinated + relayed methods. Defaults to the
28    /// canonical relay; honour the `DIG_RELAY_URL` env override / `=off` opt-out via
29    /// [`crate::relay::relay_url_from_env`] / [`crate::relay::relay_enabled`].
30    pub relay_endpoint: String,
31    /// A STUN server used to discover this node's reflexive address for candidate advertisement +
32    /// hole-punch. `None` = derive from the relay host on the standard STUN port
33    /// [`STUN_PORT`](crate::config::STUN_PORT) (the relay co-locates a STUN server, L7 spec §3):
34    /// point a node at a private relay and its STUN follows.
35    pub stun_server: Option<std::net::SocketAddr>,
36    /// The #1204 BLS cert-binding verification stance applied to the PEER's certificate during the
37    /// mTLS handshake. Defaults to [`BindingPolicy::Opportunistic`] (the rollout default: verify a
38    /// binding when present, reject a present-but-invalid one, tolerate a legacy peer that has none).
39    /// A node that requires payload sealing sets [`BindingPolicy::Required`] (fail-closed,
40    /// anti-downgrade). Verified via `dig-tls`; the verified peer BLS pubkey lands on
41    /// [`crate::PeerConnection::peer_bls_pub`].
42    pub binding_policy: BindingPolicy,
43    /// Fast-connect ([`crate::connect_fast`]) drain window: after a live relayed→direct promotion,
44    /// how long to keep the swapped-out relayed transport alive for in-flight streams to finish
45    /// before dropping it (releasing the per-peer relay tunnel). A short cap bounds the worst case
46    /// (a stuck stream can't pin the tunnel forever); request-scoped streams finish well within it.
47    pub fast_connect_grace: Duration,
48}
49
50/// The default [`NatConfig::fast_connect_grace`] post-promotion drain window.
51pub const DEFAULT_FAST_CONNECT_GRACE: Duration = Duration::from_secs(5);
52
53/// The standard STUN port (RFC 5389). The DIG relay serves STUN here, co-located with the relay host
54/// (`relay.dig.net:3478`); a node derives its STUN host from `DIG_RELAY_URL` (L7 spec §3).
55pub const STUN_PORT: u16 = 3478;
56
57impl Default for NatConfig {
58    fn default() -> Self {
59        NatConfig {
60            enabled_methods: vec![
61                TraversalKind::Direct,
62                TraversalKind::Upnp,
63                TraversalKind::NatPmp,
64                TraversalKind::Pcp,
65                TraversalKind::HolePunch,
66                TraversalKind::Relayed,
67            ],
68            per_method_timeout: Duration::from_secs(5),
69            relay_endpoint: dig_constants::DIG_RELAY_URL.to_string(),
70            stun_server: None,
71            binding_policy: BindingPolicy::Opportunistic,
72            fast_connect_grace: DEFAULT_FAST_CONNECT_GRACE,
73        }
74    }
75}
76
77impl NatConfig {
78    /// Start from the default config.
79    pub fn builder() -> NatConfigBuilder {
80        NatConfigBuilder {
81            cfg: NatConfig::default(),
82        }
83    }
84
85    /// Whether `kind` is enabled in this config.
86    pub fn is_enabled(&self, kind: TraversalKind) -> bool {
87        self.enabled_methods.contains(&kind)
88    }
89}
90
91/// Fluent builder for [`NatConfig`].
92#[derive(Debug, Clone)]
93pub struct NatConfigBuilder {
94    cfg: NatConfig,
95}
96
97impl NatConfigBuilder {
98    /// Restrict the enabled methods (they are still tried in canonical rank order).
99    pub fn enabled_methods(mut self, methods: Vec<TraversalKind>) -> Self {
100        self.cfg.enabled_methods = methods;
101        self
102    }
103
104    /// Disable a single method (e.g. turn off the relay fallback for an air-gapped node).
105    pub fn disable(mut self, kind: TraversalKind) -> Self {
106        self.cfg.enabled_methods.retain(|k| *k != kind);
107        self
108    }
109
110    /// Set the per-method timeout.
111    pub fn per_method_timeout(mut self, timeout: Duration) -> Self {
112        self.cfg.per_method_timeout = timeout;
113        self
114    }
115
116    /// Override the relay endpoint (defaults to the canonical relay).
117    pub fn relay_endpoint(mut self, endpoint: impl Into<String>) -> Self {
118        self.cfg.relay_endpoint = endpoint.into();
119        self
120    }
121
122    /// Set the STUN server used for reflexive-address discovery.
123    pub fn stun_server(mut self, addr: std::net::SocketAddr) -> Self {
124        self.cfg.stun_server = Some(addr);
125        self
126    }
127
128    /// Set the #1204 cert-binding verification stance for the peer's certificate (default
129    /// [`BindingPolicy::Opportunistic`]). Use [`BindingPolicy::Required`] on a node that seals
130    /// payloads to peers (fail-closed, anti-downgrade).
131    pub fn binding_policy(mut self, policy: BindingPolicy) -> Self {
132        self.cfg.binding_policy = policy;
133        self
134    }
135
136    /// Set the fast-connect ([`crate::connect_fast`]) post-promotion drain window (default
137    /// [`DEFAULT_FAST_CONNECT_GRACE`]). A test uses a tiny value for fast, deterministic teardown.
138    pub fn fast_connect_grace(mut self, grace: Duration) -> Self {
139        self.cfg.fast_connect_grace = grace;
140        self
141    }
142
143    /// Finalize the config.
144    pub fn build(self) -> NatConfig {
145        self.cfg
146    }
147}
dig_nat/config.rs

dig_nat/
config.rs
