stratum_apps/network_helpers/
mod.rs

1//! High-level networking utilities for SV2 connections
2//!
3//! This module provides connection management, encrypted streams, and protocol handling
4//! for Stratum V2 applications. It includes support for:
5//!
6//! - Noise-encrypted connections ([`crate::network_helpers::noise_connection`],
7//!   [`crate::network_helpers::noise_stream`])
8//! - SV1 protocol connections (`sv1_connection`) - when `sv1` feature is enabled
9//! - Hostname resolution ([`crate::network_helpers::resolve_hostname`])
10//!
11//! Originally from the `network_helpers_sv2` crate.
12
13pub mod noise_connection;
14pub mod noise_stream;
15pub mod resolve_hostname;
16
17#[cfg(feature = "sv1")]
18pub mod sv1_connection;
19
20pub use resolve_hostname::{ResolveError, resolve_host, resolve_host_port};
21
22use async_channel::{RecvError, SendError};
23use std::{fmt, time::Duration};
24use stratum_core::{
25    codec_sv2::Error as CodecError,
26    noise_sv2::{Initiator, Responder},
27};
28use tokio::net::TcpStream;
29
30use crate::{
31    key_utils::{Secp256k1PublicKey, Secp256k1SecretKey},
32    network_helpers::noise_stream::NoiseTcpStream,
33};
34
35/// Networking errors that can occur in SV2 connections
36#[derive(Debug)]
37pub enum Error {
38    /// Invalid handshake message received from remote peer
39    HandshakeRemoteInvalidMessage,
40    /// Error from the codec layer
41    CodecError(CodecError),
42    /// Error receiving from async channel
43    RecvError,
44    /// Error sending to async channel
45    SendError,
46    /// Socket was closed, likely by the peer
47    SocketClosed,
48    /// Handshake timeout
49    HandshakeTimeout,
50    /// Invalid key provided to construct an Initiator or Responder
51    InvalidKey,
52    /// DNS resolution failed for a hostname
53    DnsResolutionFailed(String),
54}
55
56impl fmt::Display for Error {
57    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
58        match self {
59            Error::HandshakeRemoteInvalidMessage => {
60                write!(f, "Invalid handshake message received from remote peer")
61            }
62
63            Error::CodecError(e) => write!(f, "{e}"),
64
65            Error::RecvError => write!(f, "Error receiving from async channel"),
66
67            Error::SendError => write!(f, "Error sending to async channel"),
68
69            Error::SocketClosed => write!(f, "Socket was closed (likely by the peer)"),
70
71            Error::HandshakeTimeout => write!(f, "Handshake timeout"),
72
73            Error::InvalidKey => write!(f, "Invalid key provided for handshake"),
74
75            Error::DnsResolutionFailed(msg) => write!(f, "DNS resolution failed: {msg}"),
76        }
77    }
78}
79
80impl From<CodecError> for Error {
81    fn from(e: CodecError) -> Self {
82        Error::CodecError(e)
83    }
84}
85
86impl From<RecvError> for Error {
87    fn from(_: RecvError) -> Self {
88        Error::RecvError
89    }
90}
91
92impl<T> From<SendError<T>> for Error {
93    fn from(_: SendError<T>) -> Self {
94        Error::SendError
95    }
96}
97
98impl From<ResolveError> for Error {
99    fn from(e: ResolveError) -> Self {
100        Error::DnsResolutionFailed(e.to_string())
101    }
102}
103
104/// Default handshake timeout used by [`connect_with_noise`] and [`accept_noise_connection`].
105/// Use [`noise_stream::NoiseTcpStream::new`] directly to override.
106const NOISE_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
107
108/// Default timeout for establishing outbound TCP connections to SV2 peers.
109/// This keeps fallback attempts bounded when a remote endpoint is unreachable or filtered.
110pub const TCP_CONNECT_TIMEOUT: Duration = Duration::from_secs(5);
111
112/// Connects to an upstream server as a Noise initiator, returning the split read/write halves.
113///
114/// The handshake timeout is opinionated and fixed at `NOISE_HANDSHAKE_TIMEOUT`. If you need a
115/// custom timeout, use [`noise_stream::NoiseTcpStream::new`] directly.
116///
117/// Pass `Some(key)` to verify the server's authority public key, or `None` to skip
118/// verification (encrypted but unauthenticated — use only on trusted networks).
119pub async fn connect_with_noise(
120    stream: TcpStream,
121    authority_pub_key: Option<Secp256k1PublicKey>,
122) -> Result<NoiseTcpStream, Error> {
123    let initiator = match authority_pub_key {
124        Some(key) => Initiator::from_raw_k(key.into_bytes()).map_err(|_| Error::InvalidKey)?,
125        None => Initiator::without_pk().map_err(|_| Error::InvalidKey)?,
126    };
127    let stream =
128        noise_stream::NoiseTcpStream::connect(stream, initiator, NOISE_HANDSHAKE_TIMEOUT).await?;
129    Ok(stream)
130}
131
132/// Accepts a downstream connection as a Noise responder, returning the split read/write halves.
133///
134/// The handshake timeout is opinionated and fixed at `NOISE_HANDSHAKE_TIMEOUT`. If you need a
135/// custom timeout, use [`noise_stream::NoiseTcpStream::new`] directly.
136///
137/// `cert_validity` controls how long the generated Noise certificate is valid,
138/// which is independent of the handshake timeout.
139pub async fn accept_noise_connection(
140    stream: TcpStream,
141    pub_key: Secp256k1PublicKey,
142    prv_key: Secp256k1SecretKey,
143    cert_validity: u64,
144) -> Result<NoiseTcpStream, Error> {
145    let responder = Responder::from_authority_kp(
146        &pub_key.into_bytes(),
147        &prv_key.into_bytes(),
148        Duration::from_secs(cert_validity),
149    )
150    .map_err(|_| Error::InvalidKey)?;
151    let stream =
152        noise_stream::NoiseTcpStream::accept(stream, responder, NOISE_HANDSHAKE_TIMEOUT).await?;
153    Ok(stream)
154}
stratum_apps/network_helpers/mod.rs

stratum_apps/network_helpers/
mod.rs
