Trait NetworkProvider 

pub trait NetworkProvider: Send + Sync {
    // Required methods
    fn start(&mut self) -> impl Future<Output = Result<(), NetworkError>> + Send;
    fn stop(&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 dial_tcp_opts(
        &self,
        addr: &str,
        port: u16,
        opts: DialOpts,
    ) -> impl Future<Output = Result<TcpStream, NetworkError>> + Send { ... }
    fn listen_tcp_opts(
        &self,
        port: u16,
        opts: ListenOpts,
    ) -> impl Future<Output = Result<NetworkTcpListener, NetworkError>> + Send { ... }
    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 { ... }
    fn proxy_runtime_errors(&self) -> Option<Receiver<ProxyRuntimeError>> { ... }
}

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(&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 dial_tcp_opts( &self, addr: &str, port: u16, opts: DialOpts, ) -> impl Future<Output = Result<TcpStream, NetworkError>> + Send

Dial a TCP connection with explicit options (e.g. a TLS override).

The default implementation ignores the options and delegates to dial_tcp, so providers that don’t support the options keep working unchanged.

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

As listen_tcp, with options (RFC 023 §7.1).

Providers without TLS listener support reject tls: true rather than silently serving plaintext.

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.

fn proxy_runtime_errors(&self) -> Option<Receiver<ProxyRuntimeError>>

Subscribe to runtime proxy-engine errors (RFC 023 G5). None for providers without a proxy engine — the caller then skips spawning a forwarding task.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl NetworkProvider for TailscaleProvider