From cf4690066df1e5858b535664506c72f5f93aa3b2 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Thu, 19 Jun 2025 23:17:50 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`cod?= =?UTF-8?q?ex/define-extractors-and-implement-frommessagerequest`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @leynos. * https://github.com/leynos/wireframe/pull/79#issuecomment-2988066991 The following files were modified: * `src/extractor.rs` * `tests/extractor.rs` --- src/extractor.rs | 33 +++++++++++++++++++++++++++++---- tests/extractor.rs | 14 ++++++++++++++ 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/src/extractor.rs b/src/extractor.rs index e4781ab3..09237767 100644 --- a/src/extractor.rs +++ b/src/extractor.rs @@ -148,6 +148,9 @@ pub enum ExtractError { } impl std::fmt::Display for ExtractError { + /// Formats the `ExtractError` for display purposes. + /// + /// Displays a descriptive message for missing shared state or payload decoding errors. fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { Self::MissingState(ty) => write!(f, "no shared state registered for {ty}"), @@ -157,6 +160,10 @@ impl std::fmt::Display for ExtractError { } impl std::error::Error for ExtractError { + /// Returns the underlying error if this is an `InvalidPayload` variant. + /// + /// # Returns + /// An optional reference to the underlying decode error, or `None` if not applicable. fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { match self { Self::InvalidPayload(e) => Some(e), @@ -197,7 +204,9 @@ impl std::ops::Deref for SharedState { /// let state = Arc::new(42); /// let shared: SharedState = state.clone().into(); /// assert_eq!(*shared, 42); - /// ``` + /// Returns a reference to the inner value. +/// +/// This enables transparent access to the wrapped type via dereferencing. fn deref(&self) -> &Self::Target { &self.0 } } @@ -208,13 +217,17 @@ pub struct Message(T); impl Message { /// Consume the extractor, returning the inner message. #[must_use] - pub fn into_inner(self) -> T { self.0 } + /// Consumes the extractor and returns the inner deserialised message value. +pub fn into_inner(self) -> T { self.0 } } impl std::ops::Deref for Message { type Target = T; - fn deref(&self) -> &Self::Target { &self.0 } + /// Returns a reference to the inner value. +/// +/// This enables transparent access to the wrapped type via dereferencing. +fn deref(&self) -> &Self::Target { &self.0 } } impl FromMessageRequest for Message @@ -223,6 +236,14 @@ where { type Error = ExtractError; + /// Attempts to extract and deserialize a message of type `T` from the payload. + /// + /// Advances the payload by the number of bytes consumed during deserialization. + /// Returns an error if the payload cannot be decoded into the target type. + /// + /// # Returns + /// - `Ok(Self)`: The successfully extracted and deserialized message. + /// - `Err(ExtractError::InvalidPayload)`: If deserialization fails. fn from_message_request( _req: &MessageRequest, payload: &mut Payload<'_>, @@ -242,12 +263,16 @@ pub struct ConnectionInfo { impl ConnectionInfo { /// Returns the peer's socket address, if known. #[must_use] - pub fn peer_addr(&self) -> Option { self.peer_addr } + /// Returns the peer's socket address for the current connection, if available. +pub fn peer_addr(&self) -> Option { self.peer_addr } } impl FromMessageRequest for ConnectionInfo { type Error = std::convert::Infallible; + /// Extracts connection metadata from the message request. + /// + /// Returns a `ConnectionInfo` containing the peer's socket address, if available. This extraction is infallible. fn from_message_request( req: &MessageRequest, _payload: &mut Payload<'_>, diff --git a/tests/extractor.rs b/tests/extractor.rs index c2994168..7c69cd62 100644 --- a/tests/extractor.rs +++ b/tests/extractor.rs @@ -9,6 +9,10 @@ use wireframe::{ struct TestMsg(u8); #[test] +/// Tests that a message can be extracted from a payload and that the payload cursor advances fully. +/// +/// Verifies that a `TestMsg` instance serialised into bytes can be correctly extracted from a `Payload` +/// using `Message::::from_message_request`, and asserts that the payload has no remaining unread data after extraction. fn message_extractor_parses_and_advances() { let msg = TestMsg(42); let bytes = msg.to_bytes().unwrap(); @@ -23,6 +27,7 @@ fn message_extractor_parses_and_advances() { } #[test] +/// Tests that `ConnectionInfo` correctly reports the peer socket address extracted from a `MessageRequest`. fn connection_info_reports_peer() { let addr: SocketAddr = "127.0.0.1:12345".parse().unwrap(); let req = MessageRequest { @@ -35,6 +40,10 @@ fn connection_info_reports_peer() { } #[test] +/// Tests that shared state of type `u8` can be successfully extracted from a `MessageRequest`'s `app_data`. +/// +/// Inserts an `Arc` into the request's shared state, extracts it using the `SharedState` extractor, +/// and asserts that the extracted value matches the original. fn shared_state_extractor() { let mut data = HashMap::default(); data.insert( @@ -53,6 +62,11 @@ fn shared_state_extractor() { } #[test] +/// Tests that extracting a missing shared state from a `MessageRequest` +/// returns an `ExtractError::MissingState` containing the type name. +/// +/// Ensures that when no shared state of the requested type is present, +/// the correct error is produced and includes the expected type information. fn shared_state_missing_error() { let req = MessageRequest::default(); let mut payload = Payload::default(); From 01bbe1893aa75e68d8df7654bae76b88567123fa Mon Sep 17 00:00:00 2001 From: Leynos Date: Fri, 20 Jun 2025 01:05:55 +0100 Subject: [PATCH 2/2] Reorder attributes after doc comments (#84) --- src/extractor.rs | 40 ++++++++++++---------------------------- src/middleware.rs | 7 +++---- src/server.rs | 5 ++--- tests/extractor.rs | 15 +++++++++------ 4 files changed, 26 insertions(+), 41 deletions(-) diff --git a/src/extractor.rs b/src/extractor.rs index 09237767..f315c46c 100644 --- a/src/extractor.rs +++ b/src/extractor.rs @@ -95,7 +95,7 @@ pub trait FromMessageRequest: Sized { pub struct SharedState(Arc); impl SharedState { - /// Construct a new [`SharedState`]. + /// Creates a new [`SharedState`] instance wrapping the provided `Arc`. /// /// # Examples /// @@ -109,19 +109,6 @@ impl SharedState { /// assert_eq!(*state, 5); /// ``` #[must_use] - /// Creates a new `SharedState` instance wrapping the provided `Arc`. - /// - /// # Examples - /// - /// ```no_run - /// use std::sync::Arc; - /// - /// use wireframe::extractor::SharedState; - /// - /// let state = Arc::new(42); - /// let shared: SharedState = state.clone().into(); - /// assert_eq!(*shared, 42); - /// ``` #[deprecated(since = "0.2.0", note = "construct via `inner.into()` instead")] pub fn new(inner: Arc) -> Self { Self(inner) } } @@ -204,9 +191,7 @@ impl std::ops::Deref for SharedState { /// let state = Arc::new(42); /// let shared: SharedState = state.clone().into(); /// assert_eq!(*shared, 42); - /// Returns a reference to the inner value. -/// -/// This enables transparent access to the wrapped type via dereferencing. + /// ``` fn deref(&self) -> &Self::Target { &self.0 } } @@ -215,19 +200,18 @@ impl std::ops::Deref for SharedState { pub struct Message(T); impl Message { - /// Consume the extractor, returning the inner message. - #[must_use] /// Consumes the extractor and returns the inner deserialised message value. -pub fn into_inner(self) -> T { self.0 } + #[must_use] + pub fn into_inner(self) -> T { self.0 } } impl std::ops::Deref for Message { type Target = T; /// Returns a reference to the inner value. -/// -/// This enables transparent access to the wrapped type via dereferencing. -fn deref(&self) -> &Self::Target { &self.0 } + /// + /// This enables transparent access to the wrapped type via dereferencing. + fn deref(&self) -> &Self::Target { &self.0 } } impl FromMessageRequest for Message @@ -238,7 +222,7 @@ where /// Attempts to extract and deserialize a message of type `T` from the payload. /// - /// Advances the payload by the number of bytes consumed during deserialization. + /// Advances the payload by the number of bytes consumed during deserialization. /// Returns an error if the payload cannot be decoded into the target type. /// /// # Returns @@ -261,10 +245,9 @@ pub struct ConnectionInfo { } impl ConnectionInfo { - /// Returns the peer's socket address, if known. - #[must_use] /// Returns the peer's socket address for the current connection, if available. -pub fn peer_addr(&self) -> Option { self.peer_addr } + #[must_use] + pub fn peer_addr(&self) -> Option { self.peer_addr } } impl FromMessageRequest for ConnectionInfo { @@ -272,7 +255,8 @@ impl FromMessageRequest for ConnectionInfo { /// Extracts connection metadata from the message request. /// - /// Returns a `ConnectionInfo` containing the peer's socket address, if available. This extraction is infallible. + /// Returns a `ConnectionInfo` containing the peer's socket address, if available. This + /// extraction is infallible. fn from_message_request( req: &MessageRequest, _payload: &mut Payload<'_>, diff --git a/src/middleware.rs b/src/middleware.rs index 927648c0..10e10991 100644 --- a/src/middleware.rs +++ b/src/middleware.rs @@ -25,10 +25,7 @@ impl<'a, S> Next<'a, S> where S: Service + ?Sized, { - /// Create a new [`Next`] wrapping the given service. - #[inline] - #[must_use] - /// Creates a new `Next` instance wrapping a reference to the given service. + /// Creates a new [`Next`] instance wrapping a reference to the given service. /// /// # Examples /// @@ -46,6 +43,8 @@ where /// let service = MyService; /// let next = Next::new(&service); /// ``` + #[inline] + #[must_use] pub fn new(service: &'a S) -> Self { Self { service } } /// Call the next service with the provided request. diff --git a/src/server.rs b/src/server.rs index c0e0bb7b..cdf8e76c 100644 --- a/src/server.rs +++ b/src/server.rs @@ -183,9 +183,6 @@ where self } - /// Get the configured worker count. - #[inline] - #[must_use] /// Returns the configured number of worker tasks for the server. /// /// # Examples @@ -197,6 +194,8 @@ where /// let server = WireframeServer::new(factory); /// assert!(server.worker_count() >= 1); /// ``` + #[inline] + #[must_use] pub const fn worker_count(&self) -> usize { self.workers } /// Get the socket address the server is bound to, if available. diff --git a/tests/extractor.rs b/tests/extractor.rs index 7c69cd62..488f2a68 100644 --- a/tests/extractor.rs +++ b/tests/extractor.rs @@ -11,8 +11,9 @@ struct TestMsg(u8); #[test] /// Tests that a message can be extracted from a payload and that the payload cursor advances fully. /// -/// Verifies that a `TestMsg` instance serialised into bytes can be correctly extracted from a `Payload` -/// using `Message::::from_message_request`, and asserts that the payload has no remaining unread data after extraction. +/// Verifies that a `TestMsg` instance serialised into bytes can be correctly extracted from a +/// `Payload` using `Message::::from_message_request`, and asserts that the payload has no +/// remaining unread data after extraction. fn message_extractor_parses_and_advances() { let msg = TestMsg(42); let bytes = msg.to_bytes().unwrap(); @@ -27,7 +28,8 @@ fn message_extractor_parses_and_advances() { } #[test] -/// Tests that `ConnectionInfo` correctly reports the peer socket address extracted from a `MessageRequest`. +/// Tests that `ConnectionInfo` correctly reports the peer socket address extracted from a +/// `MessageRequest`. fn connection_info_reports_peer() { let addr: SocketAddr = "127.0.0.1:12345".parse().unwrap(); let req = MessageRequest { @@ -40,10 +42,11 @@ fn connection_info_reports_peer() { } #[test] -/// Tests that shared state of type `u8` can be successfully extracted from a `MessageRequest`'s `app_data`. +/// Tests that shared state of type `u8` can be successfully extracted from a `MessageRequest`'s +/// `app_data`. /// -/// Inserts an `Arc` into the request's shared state, extracts it using the `SharedState` extractor, -/// and asserts that the extracted value matches the original. +/// Inserts an `Arc` into the request's shared state, extracts it using the `SharedState` +/// extractor, and asserts that the extracted value matches the original. fn shared_state_extractor() { let mut data = HashMap::default(); data.insert(