Trait NetworkProvider 

pub trait NetworkProvider: Send + Sync {
    // Required methods
    fn start(&mut self) -> impl Future<Output = Result<(), NetworkError>> + Send;
    fn stop(&mut self) -> impl Future<Output = Result<(), NetworkError>> + Send;
    fn local_identity(&self) -> NodeIdentity;
    fn local_addr(&self) -> PeerAddr;
    fn peer_events(&self) -> Receiver<NetworkPeerEvent>;
    fn peers(&self) -> impl Future<Output = Vec<NetworkPeer>> + Send;
    fn dial_tcp(
        &self,
        addr: &str,
        port: u16,
    ) -> impl Future<Output = Result<TcpStream, NetworkError>> + Send;
    fn listen_tcp(
        &self,
        port: u16,
    ) -> impl Future<Output = Result<NetworkTcpListener, NetworkError>> + Send;
    fn unlisten_tcp(
        &self,
        port: u16,
    ) -> impl Future<Output = Result<(), NetworkError>> + Send;
    fn bind_udp(
        &self,
        port: u16,
    ) -> impl Future<Output = Result<NetworkUdpSocket, NetworkError>> + Send;
    fn ping(
        &self,
        addr: &str,
    ) -> impl Future<Output = Result<PingResult, NetworkError>> + Send;
    fn health(&self) -> impl Future<Output = HealthInfo> + Send;

    // Provided methods
    fn proxy_add(
        &self,
        _config: ProxyAddParams,
    ) -> impl Future<Output = Result<ProxyAddResult, NetworkError>> + Send { ... }
    fn proxy_remove(
        &self,
        _id: &str,
    ) -> impl Future<Output = Result<(), NetworkError>> + Send { ... }
    fn proxy_list(
        &self,
    ) -> impl Future<Output = Result<Vec<ProxyListEntry>, NetworkError>> + Send { ... }
}

Provides network-level peer discovery and raw connectivity.

The primary implementation is TailscaleProvider which uses tsnet via a Go sidecar. The trait is designed to be swappable — future providers could use mDNS (LAN), STUN/TURN (internet), or Bluetooth.

Layer rules

• Layer 3 does NOT know about WebSocket, QUIC, or any Layer 4 protocol
• Layer 3 does NOT know about envelopes, namespaces, or messages
• Layer 3 provides raw TcpStream — not framed connections
• peer_events() is the ONLY source of peer events — no polling, no announce

All async methods return Send futures so that Node<N> can be used inside tokio::spawn tasks (required by the file transfer subsystem and any other code that needs to spawn tasks with node access).

Required Methods

fn start(&mut self) -> impl Future<Output = Result<(), NetworkError>> + Send

Start the network provider.

This spawns child processes, binds ports, and performs authentication. If authentication is required (e.g., Tailscale browser auth), the provider emits NetworkPeerEvent::AuthRequired { url } via peer_events() and keeps waiting until auth completes or the timeout is reached.

Callers should subscribe to peer_events() BEFORE calling start() to receive auth URLs and display them to the user.

Returns Ok(()) when the provider is fully online, or Err if auth times out or a fatal error occurs.

fn stop(&mut self) -> impl Future<Output = Result<(), NetworkError>> + Send

Stop the network provider and clean up all resources.

fn local_identity(&self) -> NodeIdentity

Local node’s identity (stable ID, hostname, display name).

Returns a clone of the current cached identity. The identity is populated after start() completes and may be updated when the sidecar reports tsnet:status.

fn local_addr(&self) -> PeerAddr

Local node’s network address.

Returns a clone of the current cached address. The address is populated after start() completes and may be updated when the sidecar reports tsnet:status.

fn peer_events(&self) -> Receiver<NetworkPeerEvent>

Subscribe to peer events. Fires immediately when peers join/leave/update.

Uses WatchIPNBus for real-time notifications instead of polling.

fn peers(&self) -> impl Future<Output = Vec<NetworkPeer>> + Send

Snapshot of all currently known peers.

fn dial_tcp( &self, addr: &str, port: u16, ) -> impl Future<Output = Result<TcpStream, NetworkError>> + Send

Dial a TCP connection to a peer via the encrypted Tailscale tunnel.

Returns a plain TcpStream — all bridge internals (pending_dials, session token, binary headers) are hidden inside the provider.

fn listen_tcp( &self, port: u16, ) -> impl Future<Output = Result<NetworkTcpListener, NetworkError>> + Send

Listen for incoming TCP connections on a port via the Tailscale tunnel.

The returned receiver yields TcpStreams for each accepted connection.

fn unlisten_tcp( &self, port: u16, ) -> impl Future<Output = Result<(), NetworkError>> + Send

Stop listening on a previously opened port.

fn bind_udp( &self, port: u16, ) -> impl Future<Output = Result<NetworkUdpSocket, NetworkError>> + Send

Bind a UDP socket on a port via the network tunnel.

Returns a NetworkUdpSocket that transparently relays datagrams through the network provider. The socket supports send_to / recv_from with full remote address information.

Not all providers support UDP. Returns NetworkError::Internal if the provider has not implemented UDP transport yet.

fn ping( &self, addr: &str, ) -> impl Future<Output = Result<PingResult, NetworkError>> + Send

Ping a peer via the network layer (Tailscale TSMP).

fn health(&self) -> impl Future<Output = HealthInfo> + Send

Node health info (key expiry, connection quality, warnings).

Provided Methods

fn proxy_add( &self, _config: ProxyAddParams, ) -> impl Future<Output = Result<ProxyAddResult, NetworkError>> + Send

Start a reverse proxy. Only supported by providers with sidecar integration.

fn proxy_remove( &self, _id: &str, ) -> impl Future<Output = Result<(), NetworkError>> + Send

Stop a reverse proxy.

fn proxy_list( &self, ) -> impl Future<Output = Result<Vec<ProxyListEntry>, NetworkError>> + Send

List active reverse proxies.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl NetworkProvider for TailscaleProvider