diff --git a/src/extractor.rs b/src/extractor.rs index e4781ab3..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) } } @@ -148,6 +135,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 +147,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), @@ -206,7 +200,7 @@ impl std::ops::Deref for SharedState { pub struct Message(T); impl Message { - /// Consume the extractor, returning the inner message. + /// Consumes the extractor and returns the inner deserialised message value. #[must_use] pub fn into_inner(self) -> T { self.0 } } @@ -214,6 +208,9 @@ impl Message { 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 } } @@ -223,6 +220,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<'_>, @@ -240,7 +245,7 @@ pub struct ConnectionInfo { } impl ConnectionInfo { - /// Returns the peer's socket address, if known. + /// Returns the peer's socket address for the current connection, if available. #[must_use] pub fn peer_addr(&self) -> Option { self.peer_addr } } @@ -248,6 +253,10 @@ impl ConnectionInfo { 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/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 c2994168..488f2a68 100644 --- a/tests/extractor.rs +++ b/tests/extractor.rs @@ -9,6 +9,11 @@ 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 +28,8 @@ 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 +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`. +/// +/// 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 +65,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();