From a7b4fd11e958b968fb7c5e7ebcdacbe7bd5b48d6 Mon Sep 17 00:00:00 2001 From: Leynos Date: Thu, 5 Feb 2026 18:27:14 +0000 Subject: [PATCH 1/2] docs(protocol): add docs clarifying that ProtocolError must be () Added detailed comments to `WireframeApp::with_protocol` and the `WireframeProtocol` trait explaining that currently `ProtocolError` must be `()`. This ensures a uniform interface for dynamic dispatch and prevents leaking application-specific errors. Also added unit test module documentation for fragmentation and reassembly. Co-authored-by: devboxerhub[bot] --- src/app/builder_protocol.rs | 5 +++++ src/fragment/tests.rs | 6 ++++++ src/hooks.rs | 13 +++++++++++-- 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/src/app/builder_protocol.rs b/src/app/builder_protocol.rs index 3e3296a0..19132f20 100644 --- a/src/app/builder_protocol.rs +++ b/src/app/builder_protocol.rs @@ -22,6 +22,11 @@ where /// The protocol defines hooks for connection setup, frame modification, and /// command completion. It is wrapped in an [`Arc`] and stored for later use /// by the connection actor. + /// + /// At present, the protocol must use `ProtocolError = ()`. This keeps the + /// protocol object safe for dynamic dispatch, maintains a uniform + /// interface across connections, and avoids leaking application-specific + /// error types into the builder API. #[must_use] pub fn with_protocol

(self, protocol: P) -> Self where diff --git a/src/fragment/tests.rs b/src/fragment/tests.rs index c0283c47..1338aff1 100644 --- a/src/fragment/tests.rs +++ b/src/fragment/tests.rs @@ -1,3 +1,9 @@ +//! Unit tests for the fragmentation and reassembly subsystem. +//! +//! Covers `FragmentHeader` field access, `FragmentSeries` ordering and +//! validation, `Fragmenter` splitting and message ID management, and +//! `Reassembler` assembly with size limits and expiry handling. + use std::{ num::NonZeroUsize, time::{Duration, Instant}, diff --git a/src/hooks.rs b/src/hooks.rs index 86581544..4f26a750 100644 --- a/src/hooks.rs +++ b/src/hooks.rs @@ -19,10 +19,19 @@ use crate::{ pub struct ConnectionContext; /// Trait encapsulating protocol-specific logic and callbacks. +/// +/// `WireframeProtocol` allows a custom `ProtocolError` type, but +/// [`crate::app::WireframeApp::with_protocol`] currently requires +/// `ProtocolError = ()` so the protocol can be stored behind dynamic dispatch +/// with a uniform interface. This constraint may be relaxed in a future +/// release. pub trait WireframeProtocol: Send + Sync + 'static { /// Frame type written to the socket. type Frame: FrameLike; /// Custom error type for protocol operations. + /// + /// When installed via [`crate::app::WireframeApp::with_protocol`], this + /// must currently be `()`. type ProtocolError; /// Called once when a new connection is established. The provided @@ -45,7 +54,7 @@ pub trait WireframeProtocol: Send + Sync + 'static { /// /// impl WireframeProtocol for MyProtocol { /// type Frame = Vec; - /// type ProtocolError = String; + /// type ProtocolError = (); /// /// fn handle_error(&self, error: Self::ProtocolError, _ctx: &mut ConnectionContext) { /// tracing::error!(error = %error, "protocol error"); @@ -81,7 +90,7 @@ pub trait WireframeProtocol: Send + Sync + 'static { /// /// impl WireframeProtocol for MyProtocol { /// type Frame = Vec; - /// type ProtocolError = String; + /// type ProtocolError = (); /// /// fn on_eof(&self, error: &EofError, partial_data: &[u8], _ctx: &mut ConnectionContext) { /// match error { From bdb7990f6a2f3db653e76441979e96f77a9d087c Mon Sep 17 00:00:00 2001 From: Leynos Date: Sun, 8 Feb 2026 20:42:23 +0000 Subject: [PATCH 2/2] docs(hooks): simplify example by removing unused error variable In the WireframeProtocol trait example, changed the handle_error function to remove the unused `error` parameter and updated the logging statement accordingly to avoid unused variable warnings and improve clarity. Co-authored-by: devboxerhub[bot] --- src/hooks.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/hooks.rs b/src/hooks.rs index 4f26a750..4b7f1381 100644 --- a/src/hooks.rs +++ b/src/hooks.rs @@ -56,8 +56,8 @@ pub trait WireframeProtocol: Send + Sync + 'static { /// type Frame = Vec; /// type ProtocolError = (); /// - /// fn handle_error(&self, error: Self::ProtocolError, _ctx: &mut ConnectionContext) { - /// tracing::error!(error = %error, "protocol error"); + /// fn handle_error(&self, _error: Self::ProtocolError, _ctx: &mut ConnectionContext) { + /// tracing::error!("protocol error"); /// // Custom handling here /// } /// }