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 ([`noise_connection`], [`noise_stream`])
7//! - SV1 protocol connections ([`sv1_connection`]) - when `sv1` feature is enabled
8//! - Hostname resolution ([`resolve_hostname`])
9//!
10//! Originally from the `network_helpers_sv2` crate.
11
12pub mod noise_connection;
13pub mod noise_stream;
14pub mod resolve_hostname;
15
16#[cfg(feature = "sv1")]
17pub mod sv1_connection;
18
19pub use resolve_hostname::{resolve_host, resolve_host_port, ResolveError};
20
21use async_channel::{RecvError, SendError};
22use std::{fmt, time::Duration};
23use stratum_core::{
24    binary_sv2::{Deserialize, GetSize, Serialize},
25    codec_sv2::{Error as CodecError, HandshakeRole},
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/// Connects to an upstream server as a Noise initiator, returning the split read/write halves.
109///
110/// The handshake timeout is opinionated and fixed at [`NOISE_HANDSHAKE_TIMEOUT`]. If you need a
111/// custom timeout, use [`noise_stream::NoiseTcpStream::new`] directly.
112///
113/// Pass `Some(key)` to verify the server's authority public key, or `None` to skip
114/// verification (encrypted but unauthenticated — use only on trusted networks).
115pub async fn connect_with_noise<Message>(
116    stream: TcpStream,
117    authority_pub_key: Option<Secp256k1PublicKey>,
118) -> Result<NoiseTcpStream<Message>, Error>
119where
120    Message: Serialize + Deserialize<'static> + GetSize + Send + 'static,
121{
122    let initiator = match authority_pub_key {
123        Some(key) => Initiator::from_raw_k(key.into_bytes()).map_err(|_| Error::InvalidKey)?,
124        None => Initiator::without_pk().map_err(|_| Error::InvalidKey)?,
125    };
126    let stream = noise_stream::NoiseTcpStream::new(
127        stream,
128        HandshakeRole::Initiator(initiator),
129        NOISE_HANDSHAKE_TIMEOUT,
130    )
131    .await?;
132    Ok(stream)
133}
134
135/// Accepts a downstream connection as a Noise responder, returning the split read/write halves.
136///
137/// The handshake timeout is opinionated and fixed at [`NOISE_HANDSHAKE_TIMEOUT`]. If you need a
138/// custom timeout, use [`noise_stream::NoiseTcpStream::new`] directly.
139///
140/// `cert_validity` controls how long the generated Noise certificate is valid,
141/// which is independent of the handshake timeout.
142pub async fn accept_noise_connection<Message>(
143    stream: TcpStream,
144    pub_key: Secp256k1PublicKey,
145    prv_key: Secp256k1SecretKey,
146    cert_validity: u64,
147) -> Result<NoiseTcpStream<Message>, Error>
148where
149    Message: Serialize + Deserialize<'static> + GetSize + Send + 'static,
150{
151    let responder = Responder::from_authority_kp(
152        &pub_key.into_bytes(),
153        &prv_key.into_bytes(),
154        Duration::from_secs(cert_validity),
155    )
156    .map_err(|_| Error::InvalidKey)?;
157    let stream = noise_stream::NoiseTcpStream::new(
158        stream,
159        HandshakeRole::Responder(responder),
160        NOISE_HANDSHAKE_TIMEOUT,
161    )
162    .await?;
163    Ok(stream)
164}
stratum_apps/network_helpers/mod.rs

stratum_apps/network_helpers/
mod.rs
