From f2bd22e72c2faa792bca930c68be01f6e078eaeb Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 16 Jun 2025 17:43:33 +0100 Subject: [PATCH 1/2] Add module-level comments --- src/app.rs | 6 ++++++ src/extractor.rs | 6 ++++++ src/frame.rs | 6 ++++++ src/lib.rs | 5 +++++ src/main.rs | 4 ++++ src/message.rs | 5 +++++ src/middleware.rs | 5 +++++ src/preamble.rs | 5 +++++ src/rewind_stream.rs | 5 +++++ src/server.rs | 6 ++++++ tests/preamble.rs | 2 ++ tests/server.rs | 2 ++ 12 files changed, 57 insertions(+) diff --git a/src/app.rs b/src/app.rs index 3776271b..90041e77 100644 --- a/src/app.rs +++ b/src/app.rs @@ -1,3 +1,9 @@ +//! Application builder configuring routes and middleware. +//! +//! `WireframeApp` stores registered routes, services, and middleware +//! for a [`WireframeServer`]. Methods return [`Result`] so callers +//! can chain registrations ergonomically. + use std::{boxed::Box, collections::HashMap, future::Future, pin::Pin}; /// Configures routing and middleware for a `WireframeServer`. diff --git a/src/extractor.rs b/src/extractor.rs index f3b0af39..d5e2ae9f 100644 --- a/src/extractor.rs +++ b/src/extractor.rs @@ -1,3 +1,9 @@ +//! Request context types and extractor traits. +//! +//! The `MessageRequest` struct carries connection metadata and shared +//! application state. Implement [`FromMessageRequest`] to extract data +//! for handlers. + use std::{net::SocketAddr, sync::Arc}; /// Request context passed to extractors. diff --git a/src/frame.rs b/src/frame.rs index c15c3a66..c2ca7492 100644 --- a/src/frame.rs +++ b/src/frame.rs @@ -1,3 +1,9 @@ +//! Frame encoding and decoding traits. +//! +//! A `FrameProcessor` converts raw bytes into logical frames and back. +//! Implementations may use any framing strategy suitable for the +//! underlying transport. + use async_trait::async_trait; use bytes::BytesMut; diff --git a/src/lib.rs b/src/lib.rs index d9acc4e3..12962837 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,8 @@ +//! Public API for the `wireframe` library. +//! +//! This crate provides building blocks for asynchronous binary protocol +//! servers, including routing, middleware, and connection utilities. + pub mod app; pub mod extractor; pub mod frame; diff --git a/src/main.rs b/src/main.rs index de72fc02..c21b86c0 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,3 +1,7 @@ +//! Minimal binary demonstrating `wireframe` usage. +//! +//! Currently prints a greeting and exits. + fn main() { println!("Hello from Wireframe!"); } diff --git a/src/message.rs b/src/message.rs index 6d44e918..d2acc1dc 100644 --- a/src/message.rs +++ b/src/message.rs @@ -1,3 +1,8 @@ +//! Message trait and serialization helpers. +//! +//! Types implementing [`Message`] can be encoded and decoded using +//! `bincode` with standard configuration. + use bincode::{ BorrowDecode, Encode, diff --git a/src/middleware.rs b/src/middleware.rs index d857e3c6..5abce8b7 100644 --- a/src/middleware.rs +++ b/src/middleware.rs @@ -1,3 +1,8 @@ +//! Traits and helpers for request middleware. +//! +//! Middleware components implement [`Transform`] to wrap services and +//! process [`ServiceRequest`]s before passing them along the chain. + use async_trait::async_trait; /// Incoming request wrapper passed through middleware. diff --git a/src/preamble.rs b/src/preamble.rs index bc71aa52..62642f3e 100644 --- a/src/preamble.rs +++ b/src/preamble.rs @@ -1,3 +1,8 @@ +//! Connection preamble decoding utilities. +//! +//! The optional preamble is read before processing a connection. This +//! module provides helpers to decode it using `bincode`. + use bincode::{BorrowDecode, borrow_decode_from_slice, config, error::DecodeError}; use tokio::io::{self, AsyncRead, AsyncReadExt}; diff --git a/src/rewind_stream.rs b/src/rewind_stream.rs index 88ac90e9..d40f4791 100644 --- a/src/rewind_stream.rs +++ b/src/rewind_stream.rs @@ -1,3 +1,8 @@ +//! Async stream adapter that replays leftover bytes. +//! +//! `RewindStream` emits any bytes buffered from a preamble read before +//! delegating reads and writes to the underlying stream. + use std::{ io, pin::Pin, diff --git a/src/server.rs b/src/server.rs index d294b27e..c5b5bc00 100644 --- a/src/server.rs +++ b/src/server.rs @@ -1,3 +1,9 @@ +//! Tokio-based server for `WireframeApp` instances. +//! +//! `WireframeServer` spawns worker tasks to accept TCP connections, +//! optionally decoding a connection preamble before handing the +//! stream to the application. + use std::io; #[cfg(not(debug_assertions))] diff --git a/tests/preamble.rs b/tests/preamble.rs index ecb1fd4d..0b090e09 100644 --- a/tests/preamble.rs +++ b/tests/preamble.rs @@ -1,3 +1,5 @@ +//! Tests for connection preamble reading. + use bincode::error::DecodeError; use tokio::{ io::{AsyncWriteExt, duplex}, diff --git a/tests/server.rs b/tests/server.rs index 3c619683..031ec01d 100644 --- a/tests/server.rs +++ b/tests/server.rs @@ -1,3 +1,5 @@ +//! Tests for [`WireframeServer`] configuration. + use wireframe::{app::WireframeApp, server::WireframeServer}; #[test] From a0946af4482cab4fc51474a1efded0b0f6c6d3b5 Mon Sep 17 00:00:00 2001 From: Leynos Date: Mon, 16 Jun 2025 18:00:16 +0100 Subject: [PATCH 2/2] Refine documentation --- src/lib.rs | 1 + src/middleware.rs | 2 +- src/preamble.rs | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 12962837..e763b16b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,4 @@ +#![doc(html_root_url = "https://docs.rs/wireframe/latest")] //! Public API for the `wireframe` library. //! //! This crate provides building blocks for asynchronous binary protocol diff --git a/src/middleware.rs b/src/middleware.rs index 5abce8b7..927648c0 100644 --- a/src/middleware.rs +++ b/src/middleware.rs @@ -1,7 +1,7 @@ //! Traits and helpers for request middleware. //! //! Middleware components implement [`Transform`] to wrap services and -//! process [`ServiceRequest`]s before passing them along the chain. +//! process `ServiceRequest` instances before passing them along the chain. use async_trait::async_trait; diff --git a/src/preamble.rs b/src/preamble.rs index 62642f3e..4f2bda14 100644 --- a/src/preamble.rs +++ b/src/preamble.rs @@ -1,6 +1,6 @@ //! Connection preamble decoding utilities. //! -//! The optional preamble is read before processing a connection. This +//! The optional preamble is read before processing a connection, and this //! module provides helpers to decode it using `bincode`. use bincode::{BorrowDecode, borrow_decode_from_slice, config, error::DecodeError};