Rust docs for protocols::v2::codec-sv2

protocols/v2/codec-sv2/src/decoder.rs

@@ -1,3 +1,43 @@
+//! # Stratum V2 Codec Decoder
+//!
+//! This module provides functionality for decoding Stratum V2 messages, including support for
+//! the Noise protocol for secure communication.
+//!
+//! ## Features
+//!
+//! * **Standard Decoder**: Decodes Stratum V2 frames without encryption.
+//! * **Noise Decoder**: Decodes Stratum V2 frames with Noise protocol encryption.
+//!
+//! ## Types
+//!
+//! * `WithoutNoise`: Decoder for Sv2 frames without Noise protocol support.
+//! * `WithNoise`: Decoder for Sv2 frames with Noise protocol support (requires the `noise_sv2`
+//!   feature).
+//! * `StandardEitherFrame`: Represents an encoded or decoded frame that could be either a regular
+//!   or Noise-protected frame.
+//! * `StandardSv2Frame`: Represents an encoded or decoded Stratum V2 frame.
+//! * `StandardNoiseDecoder`: Decoder for Stratum V2 frames with Noise protocol support.
+//! * `StandardDecoder`: Decoder for Stratum V2 frames without Noise protocol support.
+//!
+//! ## Usage
+//!
+//! This module is designed to be used to decode incoming Sv2 messages, with optional Noise
+//! protocol encryption support for secure communication.
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use codec_sv2::decoder::{StandardDecoder, StandardNoiseDecoder};
+//!
+//! // Create a standard decoder
+//! let mut decoder: StandardDecoder<MyFrameType> = StandardDecoder::new();
+//!
+//! // Create a noise decoder (requires the `noise_sv2` feature)
+//! #[cfg(feature = "noise_sv2")]
+//! let mut noise_decoder: StandardNoiseDecoder<MyFrameType> = StandardNoiseDecoder::new();
+//! ```
+//!
+
 #[cfg(feature = "noise_sv2")]
 use binary_sv2::Deserialize;
 #[cfg(feature = "noise_sv2")]
@@ -34,22 +74,51 @@ use crate::Error::MissingBytes;
 #[cfg(feature = "noise_sv2")]
 use crate::State;
 
-#[cfg(feature = "noise_sv2")]
-pub type StandardNoiseDecoder<T> = WithNoise<Buffer, T>;
+/// An encoded or decoded frame that could either be a regular or Noise-protected frame.
 pub type StandardEitherFrame<T> = Frame<T, <Buffer as IsBuffer>::Slice>;
+
+/// An encoded or decoded Sv2 frame.
 pub type StandardSv2Frame<T> = Sv2Frame<T, <Buffer as IsBuffer>::Slice>;
+
+/// Standard decoder with Noise protocol support.
+#[cfg(feature = "noise_sv2")]
+pub type StandardNoiseDecoder<T> = WithNoise<Buffer, T>;
+
+/// Standard Sv2 decoder without Noise protocol support.
 pub type StandardDecoder<T> = WithoutNoise<Buffer, T>;
 
+/// Decoder for Sv2 frames with Noise protocol support.
 #[cfg(feature = "noise_sv2")]
 pub struct WithNoise<B: IsBuffer, T: Serialize + binary_sv2::GetSize> {
+    /// Used to maintain type information for the generic parameter `T`, which represents the type
+    /// of frames being decoded.
+    ///
+    /// `T` refers to a type that implements the necessary traits for serialization
+    /// (`binary_sv2::Serialize`), deserialization (`binary_sv2::Deserialize`), and size
+    /// calculation (`binary_sv2::GetSize`).
     frame: PhantomData<T>,
+
+    /// Number of missing bytes needed to complete the Noise header or payload.
+    ///
+    /// Keeps track of how many more bytes are required to fully decode the current Noise frame.
     missing_noise_b: usize,
+
+    /// Buffer for holding encrypted Noise data.
+    ///
+    /// Stores the incoming encrypted data until it is ready to be decrypted and processed.
     noise_buffer: B,
+
+    /// Buffer for holding decrypted Sv2 data.
+    ///
+    /// Stores the decrypted data from the Noise protocol until it is ready to be processed and
+    /// concerted into a Sv2 frame.
     sv2_buffer: B,
 }
 
 #[cfg(feature = "noise_sv2")]
 impl<'a, T: Serialize + GetSize + Deserialize<'a>, B: IsBuffer + AeadBuffer> WithNoise<B, T> {
+    /// Attempts to decode the next frame, returning either a frame or an error indicating how many
+    /// bytes are missing.
     #[inline]
     pub fn next_frame(&mut self, state: &mut State) -> Result<Frame<T, B::Slice>> {
         match state {
@@ -96,6 +165,11 @@ impl<'a, T: Serialize + GetSize + Deserialize<'a>, B: IsBuffer + AeadBuffer> Wit
         }
     }
 
+    /// Decodes a Noise-encrypted frame.
+    ///
+    /// Handles the decryption of Noise-encrypted frames, including both the header and the
+    /// payload. It processes the frame in chunks if necessary, ensuring that all encrypted data is
+    /// properly decrypted and converted into a usable frame.
     #[inline]
     fn decode_noise_frame(&mut self, noise_codec: &mut NoiseCodec) -> Result<Frame<T, B::Slice>> {
         match (
@@ -145,6 +219,11 @@ impl<'a, T: Serialize + GetSize + Deserialize<'a>, B: IsBuffer + AeadBuffer> Wit
         }
     }
 
+    /// Processes and decodes frames during the handshake phase of the Noise protocol.
+    ///
+    /// Used while the codec is in the handshake phase of the Noise protocol. It decodes a received
+    /// handshake frame from the `noise_buffer`, converting it into a `HandShakeFrame`, and then
+    /// encapsulates it a `Frame`, marking it as ready for further processing by the codec.
     fn while_handshaking(&mut self) -> Frame<T, B::Slice> {
         let src = self.noise_buffer.get_data_owned().as_mut().to_vec();
 
@@ -154,17 +233,24 @@ impl<'a, T: Serialize + GetSize + Deserialize<'a>, B: IsBuffer + AeadBuffer> Wit
         frame.into()
     }
 
+    /// Provides a writable buffer for incoming data.
     #[inline]
     pub fn writable(&mut self) -> &mut [u8] {
         self.noise_buffer.get_writable(self.missing_noise_b)
     }
+
+    /// Determines whether the decoder's internal buffers can be safely dropped.
     pub fn droppable(&self) -> bool {
         self.noise_buffer.is_droppable() && self.sv2_buffer.is_droppable()
     }
 }
 
 #[cfg(feature = "noise_sv2")]
 impl<T: Serialize + binary_sv2::GetSize> WithNoise<Buffer, T> {
+    /// Crates a new `WithNoise` decoder with default buffer sizes.
+    ///
+    /// Initializes the decoder with default buffer sizes and sets the number of missing bytes to
+    /// 0.
     pub fn new() -> Self {
         Self {
             frame: PhantomData,
@@ -182,14 +268,31 @@ impl<T: Serialize + binary_sv2::GetSize> Default for WithNoise<Buffer, T> {
     }
 }
 
+/// Decoder for Sv2 frames without Noise protocol support.
 #[derive(Debug)]
 pub struct WithoutNoise<B: IsBuffer, T: Serialize + binary_sv2::GetSize> {
+    /// Marker for the type of frame being decoded.
+    ///
+    /// Used to maintain type information for the generic parameter `T` which represents the type
+    /// of frames being decoded. `T` refers to a type that implements the necessary traits for
+    /// serialization (`binary_sv2::Serialize`), deserialization (`binary_sv2::Deserialize`), and
+    /// size calculation (`binary_sv2::GetSize`).
     frame: PhantomData<T>,
+
+    /// Number of missing bytes needed to complete the frame.
+    ///
+    /// Keeps track of how many more bytes are required to fully decode the current frame.
     missing_b: usize,
+
+    /// Buffer for holding data to be decoded.
+    ///
+    /// Stores incoming data until it is ready to be processed and converted into a Sv2 frame.
     buffer: B,
 }
 
 impl<T: Serialize + binary_sv2::GetSize, B: IsBuffer> WithoutNoise<B, T> {
+    /// Attempts to decode the next frame, returning either a frame or an error indicating how many
+    /// bytes are missing.
     #[inline]
     pub fn next_frame(&mut self) -> Result<Sv2Frame<T, B::Slice>> {
         let len = self.buffer.len();
@@ -210,12 +313,17 @@ impl<T: Serialize + binary_sv2::GetSize, B: IsBuffer> WithoutNoise<B, T> {
         }
     }
 
+    /// Provides a writable buffer for incoming data.
     pub fn writable(&mut self) -> &mut [u8] {
         self.buffer.get_writable(self.missing_b)
     }
 }
 
 impl<T: Serialize + binary_sv2::GetSize> WithoutNoise<Buffer, T> {
+    /// Creates a new `WithoutNoise` with a buffer of default size.
+    ///
+    /// Initializes the decoder with a default buffer size and sets the number of missing bytes to
+    /// the size of the header.
     pub fn new() -> Self {
         Self {
             frame: PhantomData,

protocols/v2/codec-sv2/src/encoder.rs

@@ -1,3 +1,47 @@
+//! # Stratum V2 Codec Encoder
+//!
+//! This module provides functionality for encoding Stratum V2 messages, including support for the
+//! Noise protocol for secure communication.
+//!
+//! ## Features
+//!
+//! Two primary encoders are defined:
+//! * **Standard Encoder**:
+//! * **Noise Encoder**:
+//!
+//! ## Types
+//!
+//! * `Encoder`: Encoder for Sv2 frames with Noise protocol support.
+//! * `NoiseEncoder`: Encoder for Sv2 frames without Noise protocol support (requires the
+//!   `noise_sv2` feature).
+//! * `Item<T>`: Represents an SV2 frame that is to be encoded and optionally encrypted using the
+//!   Noise protocol.
+//! * `Buffer`: Holds intermediate data during encoding, which can be either a pool-allocated
+//!   buffer or a system memory buffer depending on the feature flags.
+//! * `Slice`: Stores the serialized SV2 frame data before transmission.
+//!
+//! ## Usage
+//!
+//! This module is designed to be used to encode outgoing Sv2 messages, with optional Noise
+//! protocol encryption support for secure communication.
+//!
+//! ## Example
+//!
+//! ```ignore
+//! use codec_sv2::encoder::{Encoder, NoiseEncoder};
+//! use framing_sv2::framing::Sv2Frame;
+//!
+//! // Create a standard encoder for unencrypted SV2 frames
+//! let mut encoder: Encoder<MyFrameType> = Encoder::new();
+//!
+//! // Encode a frame into a byte slice
+//! let frame = Sv2Frame::new( /* frame details */ );
+//! let encoded_data = encoder.encode(frame).unwrap();
+//!
+//! // Create a Noise encoder for encrypted SV2 frames (requires the `noise_sv2` feature)
+//! #[cfg(feature = "noise_sv2")]
+//! let mut noise_encoder: NoiseEncoder<MyFrameType> = NoiseEncoder::new();
+//! ```
 use alloc::vec::Vec;
 use binary_sv2::{GetSize, Serialize};
 #[allow(unused_imports)]
@@ -25,28 +69,61 @@ use buffer_sv2::{Buffer as IsBuffer, BufferFromSystemMemory as Buffer};
 #[cfg(feature = "with_buffer_pool")]
 use buffer_sv2::{Buffer as IsBuffer, BufferFromSystemMemory, BufferPool};
 
+/// The buffer type for holding intermediate data during encoding.
+///
+/// When the `with_buffer_pool` feature is enabled, `Buffer` is a pool-allocated buffer type
+/// (`BufferPool`), which allows for more efficient memory management. Otherwise, it defaults to
+/// `BufferFromSystemMemory`.
+///
+/// `Buffer` is used for storing both serialized Sv2 frames and encrypted Noise data.
 #[cfg(feature = "noise_sv2")]
 #[cfg(feature = "with_buffer_pool")]
 type Buffer = BufferPool<BufferFromSystemMemory>;
 
 #[cfg(not(feature = "with_buffer_pool"))]
 type Slice = Vec<u8>;
 
+/// Holds the frame's serialized bytes before transmission.
 #[cfg(feature = "with_buffer_pool")]
 type Slice = buffer_sv2::Slice;
 
+/// Encoder for Sv2 frames with Noise protocol support.
 #[cfg(feature = "noise_sv2")]
 pub struct NoiseEncoder<T: Serialize + binary_sv2::GetSize> {
+    /// Buffer for holding encrypted Noise data.
+    ///
+    /// Stores the encrypted data from the Sv2 frame after it has been processed by the Noise
+    /// protocol and is ready to be transmitted.
     noise_buffer: Buffer,
+
+    /// Buffer for holding serialized Sv2 data.
+    ///
+    /// Stores the data to be encrypted by the Noise protocol after being encoded into a Sv2 frame.
     sv2_buffer: Buffer,
+
+    /// Used to maintain type information for the generic parameter `T`, which represents the type
+    /// of frames being encoded.
+    ///
+    /// `T` refers to a type that implements the necessary traits for serialization
+    /// (`binary_sv2::Serialize`) and size calculation (`binary_sv2::GetSize`).
     frame: PhantomData<T>,
 }
 
+/// A Sv2 frame to be encoded and optionally encrypted using the Noise protocol.
+///
+/// `Item` is primarily used in the context of encoding frames before transmission. It is an alias
+/// to a `Frame` that contains a payload of type `T` and uses a `Slice` as the underlying buffer.
+/// This type is used during the encoding process to encapsulate the data being processed.
 #[cfg(feature = "noise_sv2")]
 type Item<T> = Frame<T, Slice>;
 
 #[cfg(feature = "noise_sv2")]
 impl<T: Serialize + GetSize> NoiseEncoder<T> {
+    /// Encodes a Noise-encrypted frame.
+    ///
+    /// Encodes the given `item` into a Sv2 frame and then encrypts the frame using the Noise
+    /// protocol. The `state` of the Noise codec determines whether the encoder is in the handshake
+    /// or transport phase. On success, an encrypted frame as a `Slice` is returned.
     #[inline]
     pub fn encode(&mut self, item: Item<T>, state: &mut State) -> Result<Slice> {
         match state {
@@ -99,6 +176,12 @@ impl<T: Serialize + GetSize> NoiseEncoder<T> {
         Ok(self.noise_buffer.get_data_owned())
     }
 
+    /// Processes and encodes Sv2 frames during the handshake phase of the Noise protocol.
+    ///
+    /// Used when the codec is in the handshake phase. It encodes the provided `item` into a
+    /// handshake frame and stores the payload in the `noise_buffer`. This is necessary to
+    /// establish the initial secure communication channel before transitioning to the transport
+    /// phase of the Noise protocol.
     #[inline(never)]
     fn while_handshaking(&mut self, item: Item<T>) -> Result<()> {
         // ENCODE THE SV2 FRAME
@@ -114,13 +197,15 @@ impl<T: Serialize + GetSize> NoiseEncoder<T> {
         Ok(())
     }
 
+    /// Determines whether the encoder's internal buffers can be safely dropped.
     pub fn droppable(&self) -> bool {
         self.noise_buffer.is_droppable() && self.sv2_buffer.is_droppable()
     }
 }
 
 #[cfg(feature = "noise_sv2")]
 impl<T: Serialize + binary_sv2::GetSize> NoiseEncoder<T> {
+    /// Creates a new `NoiseEncoder` with default buffer sizes.
     pub fn new() -> Self {
         #[cfg(not(feature = "with_buffer_pool"))]
         let size = 512;
@@ -141,13 +226,27 @@ impl<T: Serialize + GetSize> Default for NoiseEncoder<T> {
     }
 }
 
+/// Encoder for Sv2 frames without Noise protocol support.
 #[derive(Debug)]
 pub struct Encoder<T> {
+    /// Buffer for holding data to be encoded.
+    ///
+    /// Stores data to be processed and converted into an Sv2 frame before it is transmitted.
     buffer: Vec<u8>,
+
+    /// Marker for the type of frame being encoded.
+    ///
+    /// Used to maintain type information for the generic parameter `T`, which represents the type
+    /// of frames being encoded. `T` refers to a type that implements the necessary traits for
+    /// serialization (`binary_sv2::Serialize`) and size calculation (`binary_sv2::GetSize`).
     frame: PhantomData<T>,
 }
 
 impl<T: Serialize + GetSize> Encoder<T> {
+    /// Encodes the provided `item` into a Sv2 frame, storing the result in the internal buffer.
+    ///
+    /// The frame of type `T` is serialized and placed in into the buffer, preparing it for
+    /// transmission.
     pub fn encode(
         &mut self,
         item: Sv2Frame<T, Slice>,
@@ -161,6 +260,7 @@ impl<T: Serialize + GetSize> Encoder<T> {
         Ok(&self.buffer[..])
     }
 
+    /// Creates a new `Encoder` with a buffer of default size.
     pub fn new() -> Self {
         Self {
             buffer: Vec::with_capacity(512),