Refactor errors, buffer sizing, tests, and docs; add fixtures

docs/v0-1-0-to-v0-2-0-migration-guide.md

@@ -1,7 +1,7 @@
 # v0.1.0 to v0.2.0 migration guide
 
-This guide summarizes the breaking changes required when migrating from
-wireframe v0.1.0 to v0.2.0.
+This guide summarizes the breaking changes that must be addressed when
+migrating from wireframe v0.1.0 to v0.2.0.
 
 ## Configuration builder naming update
 

src/app/builder.rs

@@ -13,7 +13,12 @@ use std::{
 use tokio::sync::{OnceCell, mpsc};
 
 use super::{
-    builder_defaults::{MAX_READ_TIMEOUT_MS, MIN_READ_TIMEOUT_MS, default_fragmentation},
+    builder_defaults::{
+        DEFAULT_READ_TIMEOUT_MS,
+        MAX_READ_TIMEOUT_MS,
+        MIN_READ_TIMEOUT_MS,
+        default_fragmentation,
+    },
     envelope::{Envelope, Packet},
     error::{Result, WireframeError},
     lifecycle::{ConnectionSetup, ConnectionTeardown},
@@ -77,7 +82,7 @@ where
             protocol: None,
             push_dlq: None,
             codec,
-            read_timeout_ms: 100,
+            read_timeout_ms: DEFAULT_READ_TIMEOUT_MS,
             fragmentation: default_fragmentation(max_frame_length),
             message_assembler: None,
         }
@@ -164,6 +169,32 @@ where
         }
     }
 
+    /// Helper to rebuild the app when changing the connection state type.
+    pub(super) fn rebuild_with_connection_type<C2>(
+        self,
+        on_connect: Option<Arc<ConnectionSetup<C2>>>,
+        on_disconnect: Option<Arc<ConnectionTeardown<C2>>>,
+    ) -> WireframeApp<S, C2, E, F>
+    where
+        C2: Send + 'static,
+    {
+        WireframeApp {
+            handlers: self.handlers,
+            routes: OnceCell::new(),
+            middleware: self.middleware,
+            serializer: self.serializer,
+            app_data: self.app_data,
+            on_connect,
+            on_disconnect,
+            protocol: self.protocol,
+            push_dlq: self.push_dlq,
+            codec: self.codec,
+            read_timeout_ms: self.read_timeout_ms,
+            fragmentation: self.fragmentation,
+            message_assembler: self.message_assembler,
+        }
+    }
+
     /// Replace the frame codec used for framing I/O.
     ///
     /// This resets any installed protocol hooks because the frame type may
@@ -288,7 +319,7 @@ where
 
 impl<S, C, E> WireframeApp<S, C, E, LengthDelimitedFrameCodec>
 where
-    S: Serializer + Default + Send + Sync,
+    S: Serializer + Send + Sync,
     C: Send + 'static,
     E: Packet,
 {

src/app/builder_defaults.rs

@@ -6,6 +6,7 @@ use crate::{codec::clamp_frame_length, fragment::FragmentationConfig};
 
 pub(super) const MIN_READ_TIMEOUT_MS: u64 = 1;
 pub(super) const MAX_READ_TIMEOUT_MS: u64 = 86_400_000;
+pub(super) const DEFAULT_READ_TIMEOUT_MS: u64 = 100;
 const DEFAULT_FRAGMENT_TIMEOUT: Duration = Duration::from_secs(30);
 const DEFAULT_MESSAGE_SIZE_MULTIPLIER: usize = 16;
 

src/app/builder_lifecycle.rs

@@ -2,8 +2,6 @@
 
 use std::{future::Future, sync::Arc};
 
-use tokio::sync::OnceCell;
-
 use super::{builder::WireframeApp, envelope::Packet, error::Result};
 use crate::{codec::FrameCodec, serializer::Serializer};
 
@@ -39,21 +37,7 @@ where
         Fut: Future<Output = C2> + Send + 'static,
         C2: Send + 'static,
     {
-        Ok(WireframeApp {
-            handlers: self.handlers,
-            routes: OnceCell::new(),
-            middleware: self.middleware,
-            serializer: self.serializer,
-            app_data: self.app_data,
-            on_connect: Some(Arc::new(move || Box::pin(f()))),
-            on_disconnect: None,
-            protocol: self.protocol,
-            push_dlq: self.push_dlq,
-            codec: self.codec,
-            read_timeout_ms: self.read_timeout_ms,
-            fragmentation: self.fragmentation,
-            message_assembler: self.message_assembler,
-        })
+        Ok(self.rebuild_with_connection_type(Some(Arc::new(move || Box::pin(f()))), None))
     }
 
     /// Register a callback invoked when a connection is closed.

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<P>(self, protocol: P) -> Self
     where