Document unlimited builder and reuse test fixtures

Author: leynos

Cargo.lock

@@ -38,6 +38,7 @@ tracing-subscriber = "0.3"
 metrics = { version = "0.24.2", optional = true }
 metrics-exporter-prometheus = { version = "0.17.2", optional = true, features = ["http-listener"] }
 thiserror = "2.0.12"
+static_assertions = "1"
 
 [dev-dependencies]
 rstest = "0.26.1"

Cargo.toml

@@ -159,14 +159,26 @@ let (dlq_tx, _dlq_rx) = mpsc::channel(8);
 let (_queues, _handle) = PushQueues::<u8>::builder()
     .high_capacity(8)
     .low_capacity(8)
-    .rate(Some(100)) // pass None to disable rate limiting
+    .rate(Some(100))
     .dlq(Some(dlq_tx)) // frames drop if the DLQ is absent or full
     .build()
     .expect("failed to build PushQueues");
 # drop((_queues, _handle));
 # }
 ```
 
+Disable throttling with the `unlimited` convenience:
+
+```rust,no_run
+use wireframe::push::PushQueues;
+let (_queues, _handle) = PushQueues::<u8>::builder()
+    .high_capacity(8)
+    .low_capacity(8)
+    .unlimited()
+    .build()
+    .expect("failed to build PushQueues");
+```
+
 ## Connection Lifecycle
 
 Protocol callbacks are consolidated under the `WireframeProtocol` trait,

README.md

@@ -73,7 +73,7 @@ The public API is designed for clarity, performance, and ergonomic flexibility.
 The `Response` enum is the primary return type for all handlers. It is enhanced
 to provide optimized paths for common response patterns.
 
-```Rust
+```rust
 use futures_core::stream::Stream;
 use std::pin::Pin;
 
@@ -109,7 +109,7 @@ To enable more robust error handling, a generic error enum will be introduced.
 This allows the framework and protocol implementations to distinguish between
 unrecoverable transport failures and logical, protocol-level errors.
 
-```Rust
+```rust
 /// A generic error type for wireframe operations.
 #
 pub enum WireframeError<E> {
@@ -139,7 +139,7 @@ The following examples illustrate how developers will use the new API.
 
 Existing code continues to work without modification, fulfilling goal **G4**.
 
-```Rust
+```rust
 async fn handle_ping(_req: Request) -> Result<Response<MyFrame, MyError>, MyError> {
     // `MyFrame` implements `Into<Response<...>>`
     Ok(build_pong_frame().into())
@@ -151,7 +151,7 @@ async fn handle_ping(_req: Request) -> Result<Response<MyFrame, MyError>, MyErro
 For simple, fixed-size multi-part responses, like a MySQL result set header,
 `Response::Vec` is both ergonomic and performant.
 
-```Rust
+```rust
 async fn handle_select_headers(_req: Request) -> Result<Response<MySqlFrame, MyError>, MyError> {
     // Pre-build frames for: column-count, column-def, EOF
     let frames = vec!;
@@ -164,7 +164,7 @@ async fn handle_select_headers(_req: Request) -> Result<Response<MySqlFrame, MyE
 For large or dynamically generated result sets, like a PostgreSQL `COPY OUT`
 command, `async-stream` provides an intuitive way to generate the stream.
 
-```Rust
+```rust
 use async_stream::try_stream;
 
 async fn handle_copy_out(req: PgCopyRequest) -> Result<Response<PgFrame, PgError>, PgError> {

docs/multi-packet-and-streaming-responses-design.md

@@ -35,13 +35,24 @@ use super::{
 /// let (_queues, _handle) = PushQueues::<u8>::builder()
 ///     .high_capacity(8)
 ///     .low_capacity(8)
-///     .rate(Some(100)) // pass None to disable rate limiting
+///     .rate(Some(100))
 ///     .dlq(Some(dlq_tx)) // frames are dropped if no DLQ or DLQ is full
 ///     .build()
 ///     .expect("failed to build PushQueues");
 /// # }
 /// ```
 ///
+/// Disable rate limiting with the `unlimited` convenience:
+///
+/// ```rust,no_run
+/// use wireframe::push::PushQueues;
+/// let (_queues, _handle) = PushQueues::<u8>::builder()
+///     .unlimited()
+///     .build()
+///     .expect("failed to build PushQueues");
+/// # drop((_queues, _handle));
+/// ```
+///
 /// Builders can also be constructed directly:
 ///
 /// ```

src/push/queues/builder.rs

@@ -12,6 +12,7 @@ use std::{
 };
 
 use leaky_bucket::RateLimiter;
+use static_assertions::const_assert;
 use tokio::sync::mpsc;
 
 mod builder;
@@ -38,7 +39,7 @@ const DEFAULT_PUSH_RATE: usize = 100;
 pub const MAX_PUSH_RATE: usize = 10_000;
 
 // Compile-time guard: DEFAULT_PUSH_RATE must not exceed MAX_PUSH_RATE.
-const _: () = assert!(DEFAULT_PUSH_RATE <= MAX_PUSH_RATE);
+const_assert!(DEFAULT_PUSH_RATE <= MAX_PUSH_RATE);
 
 /// Priority level for outbound messages.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]

src/push/queues/mod.rs

@@ -20,7 +20,7 @@ use wireframe_testing::{push_expect, recv_expect};
 
 #[fixture]
 fn queues() -> (PushQueues<u8>, PushHandle<u8>) {
-    support::builder()
+    support::builder::<u8>()
         .high_capacity(2)
         .low_capacity(2)
         .rate(Some(1))
@@ -30,7 +30,7 @@ fn queues() -> (PushQueues<u8>, PushHandle<u8>) {
 
 #[fixture]
 fn small_queues() -> (PushQueues<u8>, PushHandle<u8>) {
-    support::builder()
+    support::builder::<u8>()
         .build()
         .expect("failed to build PushQueues")
 }
@@ -40,29 +40,29 @@ fn small_queues() -> (PushQueues<u8>, PushHandle<u8>) {
 #[case::zero(0)]
 #[case::too_high(MAX_PUSH_RATE + 1)]
 fn builder_rejects_invalid_rate(#[case] rate: usize) {
-    let result = support::builder().rate(Some(rate)).build();
+    let result = support::builder::<u8>().rate(Some(rate)).build();
     assert!(matches!(result, Err(PushConfigError::InvalidRate(r)) if r == rate));
 }
 
 /// Setting the rate to `None` disables throttling without error.
 #[test]
 fn builder_accepts_none_rate() {
-    let result = support::builder().rate(None).build();
+    let result = support::builder::<u8>().rate(None).build();
     assert!(result.is_ok(), "builder should accept None rate");
 }
 
 /// Builder accepts the maximum supported rate.
 #[test]
 fn builder_accepts_max_rate() {
-    let result = support::builder().rate(Some(MAX_PUSH_RATE)).build();
+    let result = support::builder::<u8>().rate(Some(MAX_PUSH_RATE)).build();
     assert!(result.is_ok(), "builder should accept MAX_PUSH_RATE");
 }
 
 /// Disabling throttling allows rapid bursts to succeed.
 #[tokio::test]
 async fn disables_throttling_allows_burst_pushes() {
     time::pause();
-    let (_queues, handle) = support::builder()
+    let (_queues, handle) = support::builder::<u8>()
         .high_capacity(20)
         .low_capacity(20)
         .unlimited()
@@ -81,19 +81,19 @@ async fn disables_throttling_allows_burst_pushes() {
 
 #[test]
 fn builder_rejects_zero_capacity() {
-    let hi = support::builder().high_capacity(0).build();
+    let hi = support::builder::<u8>().high_capacity(0).build();
     assert!(matches!(
         hi,
         Err(PushConfigError::InvalidCapacity { high: 0, low: 1 })
     ));
 
-    let lo = support::builder().low_capacity(0).build();
+    let lo = support::builder::<u8>().low_capacity(0).build();
     assert!(matches!(
         lo,
         Err(PushConfigError::InvalidCapacity { high: 1, low: 0 })
     ));
 
-    let both = support::builder().high_capacity(0).low_capacity(0).build();
+    let both = support::builder::<u8>().high_capacity(0).low_capacity(0).build();
     assert!(matches!(
         both,
         Err(PushConfigError::InvalidCapacity { high: 0, low: 0 })
@@ -230,7 +230,7 @@ async fn rate_limiter_shared_across_priorities() {
 #[tokio::test]
 async fn unlimited_queues_do_not_block() {
     time::pause();
-    let (mut queues, handle) = support::builder()
+    let (mut queues, handle) = support::builder::<u8>()
         .unlimited()
         .build()
         .expect("failed to build PushQueues");
@@ -248,7 +248,7 @@ async fn unlimited_queues_do_not_block() {
 #[tokio::test]
 async fn rate_limiter_allows_burst_within_capacity_and_blocks_excess() {
     time::pause();
-    let (mut queues, handle) = support::builder()
+    let (mut queues, handle) = support::builder::<u8>()
         .high_capacity(4)
         .low_capacity(4)
         .rate(Some(3))

tests/push.rs

@@ -2,21 +2,14 @@
 
 mod support;
 
-use futures::future::BoxFuture;
+use futures::{FutureExt, future::BoxFuture};
 use rstest::{fixture, rstest};
 use serial_test::serial;
 use tokio::{runtime::Runtime, sync::mpsc};
-use futures::FutureExt;
 use wireframe::push::{PushPolicy, PushPriority, PushQueuesBuilder};
 use wireframe_testing::{LoggerHandle, logger};
 
 /// Builds a single-thread [`Runtime`] for async tests.
-#[expect(
-    unused_braces,
-    reason = "rustc false positive for single line rstest fixtures"
-)]
-// allow(unfulfilled_lint_expectations): rustc may miss lint for single-line rstest fixtures.
-#[allow(unfulfilled_lint_expectations)]
 #[fixture]
 fn rt() -> Runtime {
     tokio::runtime::Builder::new_current_thread()
@@ -25,14 +18,10 @@ fn rt() -> Runtime {
         .expect("failed to build test runtime")
 }
 
-#[expect(
-    unused_braces,
-    reason = "rustc false positive for single line rstest fixtures"
-)]
-// allow(unfulfilled_lint_expectations): rustc may miss lint for single-line rstest fixtures.
-#[allow(unfulfilled_lint_expectations)]
 #[fixture]
-fn builder() -> PushQueuesBuilder<u8> { support::builder() }
+fn builder() -> PushQueuesBuilder<u8> {
+    support::builder::<u8>()
+}
 
 /// Verifies how queue policies log and drop when the queue is full.
 #[rstest]

tests/push_policies.rs

@@ -6,19 +6,11 @@ use wireframe::{
 };
 
 #[fixture]
-#[expect(
-    unused_braces,
-    reason = "rustc false positive for single-line rstest fixtures"
-)]
-#[allow(unfulfilled_lint_expectations)]
-fn registry() -> SessionRegistry<u8> { SessionRegistry::default() }
+fn registry() -> SessionRegistry<u8> {
+    SessionRegistry::default()
+}
 
 #[fixture]
-#[expect(
-    unused_braces,
-    reason = "rustc false positive for single-line rstest fixtures"
-)]
-#[allow(unfulfilled_lint_expectations)]
 fn push_setup() -> (PushQueues<u8>, PushHandle<u8>) {
     PushQueues::<u8>::builder()
         .high_capacity(1)

tests/session_registry.rs

@@ -4,6 +4,6 @@ use wireframe::push::{PushQueues, PushQueuesBuilder};
 
 /// Returns a builder with unit capacities for reuse across tests.
 #[must_use]
-pub fn builder() -> PushQueuesBuilder<u8> {
-    PushQueues::<u8>::builder().high_capacity(1).low_capacity(1)
+pub fn builder<F: Send + 'static>() -> PushQueuesBuilder<F> {
+    PushQueues::<F>::builder().high_capacity(1).low_capacity(1)
 }