Add the SV2 TCP link and the V1 fallback policy
source-pr / source (pull_request) Successful in 12s

TcpLink turns a TCP stream into framed SV2 messages: it buffers partial reads
and returns one frame at a time, so a frame split across packets is not a
protocol error and two frames in one read are still delivered separately. A
closed stream is an error, never an empty frame.

The fallback policy permits Stratum V1 only when the operator allowed it and
the failure is not transport-level: a dead route or a dropped stream fails
identically on V1, so falling back there would only delay the real error. V1
failures never loop back to V2.
This commit is contained in:
2026-10-22 10:41:23 -06:00
parent 97ea7a4f65
commit e3e0dab0ec
2 changed files with 254 additions and 0 deletions
+1
View File
@@ -20,6 +20,7 @@ pub mod runtime;
pub mod scrypt_pow;
pub mod split;
pub mod stratum_client;
pub mod stratum_link;
pub mod stratum_session;
pub mod stratum_submit;
pub mod stratum_v1;
+253
View File
@@ -0,0 +1,253 @@
// SPDX-License-Identifier: MIT
//! Stratum V2 transport and version selection.
//!
//! `TcpLink` turns a TCP stream into the framed messages the session expects: it buffers partial
//! reads and hands out one frame at a time, so a frame split across packets is not a protocol
//! error. The selection policy decides when a miner may fall back to Stratum V1.
use crate::stratum_v2::{Frame, V2Error};
use crate::stratum_v2_session::V2Link;
use std::io::{self, Read, Write};
use std::net::{SocketAddr, TcpStream};
use std::time::Duration;
const READ_CHUNK: usize = 4096;
/// A framed connection over TCP.
pub struct TcpLink {
stream: TcpStream,
buffer: Vec<u8>,
}
impl TcpLink {
pub fn connect(address: SocketAddr, timeout: Duration) -> io::Result<Self> {
let stream = TcpStream::connect_timeout(&address, timeout)?;
stream.set_read_timeout(Some(timeout))?;
stream.set_write_timeout(Some(timeout))?;
stream.set_nodelay(true)?;
Ok(Self {
stream,
buffer: Vec::new(),
})
}
pub fn from_stream(stream: TcpStream) -> io::Result<Self> {
stream.set_nodelay(true)?;
Ok(Self {
stream,
buffer: Vec::new(),
})
}
/// Bytes received but not yet consumed, for diagnostics.
pub fn buffered(&self) -> usize {
self.buffer.len()
}
}
impl V2Link for TcpLink {
type Error = io::Error;
fn send(&mut self, frame: &Frame) -> io::Result<()> {
let mut wire = Vec::with_capacity(frame.payload.len() + 6);
frame.encode(&mut wire);
self.stream.write_all(&wire)?;
self.stream.flush()
}
fn recv(&mut self) -> io::Result<Frame> {
loop {
if !self.buffer.is_empty() {
match Frame::decode(&self.buffer) {
Ok((frame, consumed)) => {
self.buffer.drain(..consumed);
return Ok(frame);
}
Err(V2Error::Truncated) => {}
Err(error) => {
self.buffer.clear();
return Err(io::Error::new(io::ErrorKind::InvalidData, error));
}
}
}
let mut chunk = [0_u8; READ_CHUNK];
let count = self.stream.read(&mut chunk)?;
if count == 0 {
return Err(io::Error::new(
io::ErrorKind::UnexpectedEof,
"stratum v2 stream closed",
));
}
self.buffer.extend_from_slice(&chunk[..count]);
}
}
}
/// Which protocol the miner speaks.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum StratumVersion {
V1,
V2,
}
/// Why an attempt failed.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum FailureKind {
/// The server refused the connection or the setup message.
Refused,
/// No mutually supported version.
Unsupported,
/// The connection could not be established or dropped.
Transport,
/// The server did not answer in time.
Timeout,
}
/// Operator preference.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Preference {
pub primary: StratumVersion,
pub allow_v1_fallback: bool,
}
impl Default for Preference {
fn default() -> Self {
Self {
primary: StratumVersion::V2,
allow_v1_fallback: true,
}
}
}
/// The protocol to try next, or `None` when there is nothing left.
///
/// V1 is attempted only when the operator allowed it and the failure is not a transport-level
/// problem: a dead route or a dropped stream will fail identically on V1, so falling back would
/// only delay the operator-visible error.
pub fn fallback(
preference: Preference,
failed: StratumVersion,
kind: FailureKind,
) -> Option<StratumVersion> {
match (preference.primary, failed) {
(StratumVersion::V2, StratumVersion::V2)
if preference.allow_v1_fallback && kind != FailureKind::Transport =>
{
Some(StratumVersion::V1)
}
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::TcpListener;
#[test]
fn a_frame_arrives_intact_over_tcp() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x00, vec![1, 2, 3, 4]).encode(&mut wire);
stream.write_all(&wire).expect("write");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let frame = link.recv().expect("recv");
assert_eq!(frame.msg_type, 0x00);
assert_eq!(frame.payload, vec![1, 2, 3, 4]);
server.join().expect("join");
}
#[test]
fn a_frame_split_across_reads_is_reassembled() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x10, vec![9; 40]).encode(&mut wire);
stream.write_all(&wire[..5]).expect("first");
std::thread::sleep(Duration::from_millis(20));
stream.write_all(&wire[5..]).expect("rest");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let frame = link.recv().expect("recv");
assert_eq!(frame.msg_type, 0x10);
assert_eq!(frame.payload.len(), 40);
server.join().expect("join");
}
#[test]
fn two_frames_in_one_read_are_returned_one_at_a_time() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (mut stream, _) = listener.accept().expect("accept");
let mut wire = Vec::new();
Frame::new(0x01, vec![1]).encode(&mut wire);
Frame::new(0x02, vec![2]).encode(&mut wire);
stream.write_all(&wire).expect("write");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
assert_eq!(link.recv().expect("first").msg_type, 0x01);
assert_eq!(link.recv().expect("second").msg_type, 0x02);
server.join().expect("join");
}
#[test]
fn a_closed_stream_is_an_error_not_an_empty_frame() {
let listener = TcpListener::bind("127.0.0.1:0").expect("bind");
let address = listener.local_addr().expect("addr");
let server = std::thread::spawn(move || {
let (_stream, _) = listener.accept().expect("accept");
});
let mut link = TcpLink::connect(address, Duration::from_secs(2)).expect("connect");
let error = link.recv().expect_err("closed stream");
assert_eq!(error.kind(), io::ErrorKind::UnexpectedEof);
server.join().expect("join");
}
#[test]
fn v1_fallback_requires_permission_and_a_non_transport_failure() {
let allowed = Preference {
primary: StratumVersion::V2,
allow_v1_fallback: true,
};
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Refused),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Unsupported),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Timeout),
Some(StratumVersion::V1)
);
assert_eq!(
fallback(allowed, StratumVersion::V2, FailureKind::Transport),
None
);
}
#[test]
fn v1_fallback_can_be_disabled_and_v1_failures_do_not_loop() {
let denied = Preference {
primary: StratumVersion::V2,
allow_v1_fallback: false,
};
assert_eq!(
fallback(denied, StratumVersion::V2, FailureKind::Refused),
None
);
let allowed = Preference::default();
assert_eq!(
fallback(allowed, StratumVersion::V1, FailureKind::Refused),
None
);
}
}