RubyGems - spikard - Versions diffs - 0.3.6 → 0.6.1 - Mend

spikard 0.3.6 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

checksums.yaml +4 -4
data/LICENSE +1 -1
data/README.md +674 -659
data/ext/spikard_rb/Cargo.toml +17 -17
data/ext/spikard_rb/extconf.rb +13 -10
data/ext/spikard_rb/src/lib.rs +6 -6
data/lib/spikard/app.rb +405 -386
data/lib/spikard/background.rb +27 -27
data/lib/spikard/config.rb +396 -396
data/lib/spikard/converters.rb +13 -13
data/lib/spikard/handler_wrapper.rb +113 -113
data/lib/spikard/provide.rb +214 -214
data/lib/spikard/response.rb +173 -173
data/lib/spikard/schema.rb +243 -243
data/lib/spikard/sse.rb +111 -111
data/lib/spikard/streaming_response.rb +44 -44
data/lib/spikard/testing.rb +256 -221
data/lib/spikard/upload_file.rb +131 -131
data/lib/spikard/version.rb +5 -5
data/lib/spikard/websocket.rb +59 -59
data/lib/spikard.rb +43 -43
data/sig/spikard.rbs +366 -366
data/vendor/crates/spikard-bindings-shared/Cargo.toml +63 -0
data/vendor/crates/spikard-bindings-shared/examples/config_extraction.rs +132 -0
data/vendor/crates/spikard-bindings-shared/src/config_extractor.rs +752 -0
data/vendor/crates/spikard-bindings-shared/src/conversion_traits.rs +194 -0
data/vendor/crates/spikard-bindings-shared/src/di_traits.rs +246 -0
data/vendor/crates/spikard-bindings-shared/src/error_response.rs +401 -0
data/vendor/crates/spikard-bindings-shared/src/handler_base.rs +238 -0
data/vendor/crates/spikard-bindings-shared/src/lib.rs +24 -0
data/vendor/crates/spikard-bindings-shared/src/lifecycle_base.rs +292 -0
data/vendor/crates/spikard-bindings-shared/src/lifecycle_executor.rs +616 -0
data/vendor/crates/spikard-bindings-shared/src/response_builder.rs +305 -0
data/vendor/crates/spikard-bindings-shared/src/test_client_base.rs +248 -0
data/vendor/crates/spikard-bindings-shared/src/validation_helpers.rs +351 -0
data/vendor/crates/spikard-bindings-shared/tests/comprehensive_coverage.rs +454 -0
data/vendor/crates/spikard-bindings-shared/tests/error_response_edge_cases.rs +383 -0
data/vendor/crates/spikard-bindings-shared/tests/handler_base_integration.rs +280 -0
data/vendor/crates/spikard-core/Cargo.toml +40 -40
data/vendor/crates/spikard-core/src/bindings/mod.rs +3 -3
data/vendor/crates/spikard-core/src/bindings/response.rs +133 -133
data/vendor/crates/spikard-core/src/debug.rs +127 -63
data/vendor/crates/spikard-core/src/di/container.rs +702 -726
data/vendor/crates/spikard-core/src/di/dependency.rs +273 -273
data/vendor/crates/spikard-core/src/di/error.rs +118 -118
data/vendor/crates/spikard-core/src/di/factory.rs +534 -538
data/vendor/crates/spikard-core/src/di/graph.rs +506 -545
data/vendor/crates/spikard-core/src/di/mod.rs +192 -192
data/vendor/crates/spikard-core/src/di/resolved.rs +405 -411
data/vendor/crates/spikard-core/src/di/value.rs +281 -283
data/vendor/crates/spikard-core/src/errors.rs +69 -39
data/vendor/crates/spikard-core/src/http.rs +415 -153
data/vendor/crates/spikard-core/src/lib.rs +29 -29
data/vendor/crates/spikard-core/src/lifecycle.rs +1186 -422
data/vendor/crates/spikard-core/src/metadata.rs +389 -0
data/vendor/crates/spikard-core/src/parameters.rs +2525 -722
data/vendor/crates/spikard-core/src/problem.rs +344 -310
data/vendor/crates/spikard-core/src/request_data.rs +1154 -189
data/vendor/crates/spikard-core/src/router.rs +510 -249
data/vendor/crates/spikard-core/src/schema_registry.rs +183 -183
data/vendor/crates/spikard-core/src/type_hints.rs +304 -304
data/vendor/crates/spikard-core/src/validation/error_mapper.rs +696 -0
data/vendor/crates/spikard-core/src/{validation.rs → validation/mod.rs} +457 -699
data/vendor/crates/spikard-http/Cargo.toml +62 -68
data/vendor/crates/spikard-http/examples/sse-notifications.rs +148 -0
data/vendor/crates/spikard-http/examples/websocket-chat.rs +92 -0
data/vendor/crates/spikard-http/src/auth.rs +296 -247
data/vendor/crates/spikard-http/src/background.rs +1860 -249
data/vendor/crates/spikard-http/src/bindings/mod.rs +3 -3
data/vendor/crates/spikard-http/src/bindings/response.rs +1 -1
data/vendor/crates/spikard-http/src/body_metadata.rs +8 -8
data/vendor/crates/spikard-http/src/cors.rs +1005 -490
data/vendor/crates/spikard-http/src/debug.rs +128 -63
data/vendor/crates/spikard-http/src/di_handler.rs +1668 -423
data/vendor/crates/spikard-http/src/handler_response.rs +901 -190
data/vendor/crates/spikard-http/src/handler_trait.rs +838 -228
data/vendor/crates/spikard-http/src/handler_trait_tests.rs +290 -284
data/vendor/crates/spikard-http/src/lib.rs +534 -529
data/vendor/crates/spikard-http/src/lifecycle/adapter.rs +230 -149
data/vendor/crates/spikard-http/src/lifecycle.rs +1193 -428
data/vendor/crates/spikard-http/src/middleware/mod.rs +560 -285
data/vendor/crates/spikard-http/src/middleware/multipart.rs +912 -86
data/vendor/crates/spikard-http/src/middleware/urlencoded.rs +513 -147
data/vendor/crates/spikard-http/src/middleware/validation.rs +768 -287
data/vendor/crates/spikard-http/src/openapi/mod.rs +309 -309
data/vendor/crates/spikard-http/src/openapi/parameter_extraction.rs +535 -190
data/vendor/crates/spikard-http/src/openapi/schema_conversion.rs +1363 -308
data/vendor/crates/spikard-http/src/openapi/spec_generation.rs +665 -195
data/vendor/crates/spikard-http/src/query_parser.rs +793 -369
data/vendor/crates/spikard-http/src/response.rs +720 -399
data/vendor/crates/spikard-http/src/server/handler.rs +1650 -87
data/vendor/crates/spikard-http/src/server/lifecycle_execution.rs +234 -98
data/vendor/crates/spikard-http/src/server/mod.rs +1593 -805
data/vendor/crates/spikard-http/src/server/request_extraction.rs +789 -119
data/vendor/crates/spikard-http/src/server/routing_factory.rs +629 -0
data/vendor/crates/spikard-http/src/sse.rs +1409 -447
data/vendor/crates/spikard-http/src/testing/form.rs +52 -14
data/vendor/crates/spikard-http/src/testing/multipart.rs +64 -60
data/vendor/crates/spikard-http/src/testing/test_client.rs +311 -285
data/vendor/crates/spikard-http/src/testing.rs +406 -377
data/vendor/crates/spikard-http/src/websocket.rs +1404 -324
data/vendor/crates/spikard-http/tests/background_behavior.rs +832 -0
data/vendor/crates/spikard-http/tests/common/handlers.rs +309 -0
data/vendor/crates/spikard-http/tests/common/mod.rs +26 -0
data/vendor/crates/spikard-http/tests/di_integration.rs +192 -0
data/vendor/crates/spikard-http/tests/doc_snippets.rs +5 -0
data/vendor/crates/spikard-http/tests/lifecycle_execution.rs +1093 -0
data/vendor/crates/spikard-http/tests/multipart_behavior.rs +656 -0
data/vendor/crates/spikard-http/tests/server_config_builder.rs +314 -0
data/vendor/crates/spikard-http/tests/sse_behavior.rs +620 -0
data/vendor/crates/spikard-http/tests/websocket_behavior.rs +663 -0
data/vendor/crates/spikard-rb/Cargo.toml +48 -42
data/vendor/crates/spikard-rb/build.rs +199 -8
data/vendor/crates/spikard-rb/src/background.rs +63 -63
data/vendor/crates/spikard-rb/src/config/mod.rs +5 -0
data/vendor/crates/spikard-rb/src/{config.rs → config/server_config.rs} +285 -294
data/vendor/crates/spikard-rb/src/conversion.rs +554 -453
data/vendor/crates/spikard-rb/src/di/builder.rs +100 -0
data/vendor/crates/spikard-rb/src/{di.rs → di/mod.rs} +375 -409
data/vendor/crates/spikard-rb/src/handler.rs +618 -625
data/vendor/crates/spikard-rb/src/integration/mod.rs +3 -0
data/vendor/crates/spikard-rb/src/lib.rs +1806 -2771
data/vendor/crates/spikard-rb/src/lifecycle.rs +275 -274
data/vendor/crates/spikard-rb/src/metadata/mod.rs +5 -0
data/vendor/crates/spikard-rb/src/metadata/route_extraction.rs +442 -0
data/vendor/crates/spikard-rb/src/runtime/mod.rs +5 -0
data/vendor/crates/spikard-rb/src/runtime/server_runner.rs +324 -0
data/vendor/crates/spikard-rb/src/server.rs +305 -283
data/vendor/crates/spikard-rb/src/sse.rs +231 -231
data/vendor/crates/spikard-rb/src/{test_client.rs → testing/client.rs} +538 -404
data/vendor/crates/spikard-rb/src/testing/mod.rs +7 -0
data/vendor/crates/spikard-rb/src/{test_sse.rs → testing/sse.rs} +143 -143
data/vendor/crates/spikard-rb/src/testing/websocket.rs +608 -0
data/vendor/crates/spikard-rb/src/websocket.rs +377 -233
metadata +60 -13
data/vendor/crates/spikard-http/src/parameters.rs +0 -1
data/vendor/crates/spikard-http/src/problem.rs +0 -1
data/vendor/crates/spikard-http/src/router.rs +0 -1
data/vendor/crates/spikard-http/src/schema_registry.rs +0 -1
data/vendor/crates/spikard-http/src/type_hints.rs +0 -1
data/vendor/crates/spikard-http/src/validation.rs +0 -1
data/vendor/crates/spikard-rb/src/test_websocket.rs +0 -221

data/vendor/crates/spikard-http/src/testing.rs CHANGED Viewed

@@ -1,377 +1,406 @@
-use axum::body::Body;
-use axum::http::Request as AxumRequest;
-use axum_test::{TestResponse as AxumTestResponse, TestServer, TestWebSocket, WsMessage};
-pub mod multipart;
-pub use multipart::{MultipartFilePart, build_multipart_body};
-pub mod form;
-pub mod test_client;
-pub use test_client::TestClient;
-use brotli::Decompressor;
-use flate2::read::GzDecoder;
-pub use form::encode_urlencoded_body;
-use http_body_util::BodyExt;
-use serde_json::Value;
-use std::collections::HashMap;
-use std::io::{Cursor, Read};
-/// Snapshot of an Axum response used by higher-level language bindings.
-#[derive(Debug, Clone)]
-pub struct ResponseSnapshot {
-    /// HTTP status code.
-    pub status: u16,
-    /// Response headers (lowercase keys for predictable lookups).
-    pub headers: HashMap<String, String>,
-    /// Response body bytes (decoded for supported encodings).
-    pub body: Vec<u8>,
-}
-impl ResponseSnapshot {
-    /// Return response body as UTF-8 string.
-    pub fn text(&self) -> Result<String, std::string::FromUtf8Error> {
-        String::from_utf8(self.body.clone())
-    }
-    /// Parse response body as JSON.
-    pub fn json(&self) -> Result<Value, serde_json::Error> {
-        serde_json::from_slice(&self.body)
-    }
-    /// Lookup header by case-insensitive name.
-    pub fn header(&self, name: &str) -> Option<&str> {
-        self.headers.get(&name.to_ascii_lowercase()).map(|s| s.as_str())
-    }
-}
-/// Possible errors while converting an Axum response into a snapshot.
-#[derive(Debug)]
-pub enum SnapshotError {
-    /// Response header could not be decoded to UTF-8.
-    InvalidHeader(String),
-    /// Body decompression failed.
-    Decompression(String),
-}
-impl std::fmt::Display for SnapshotError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            SnapshotError::InvalidHeader(msg) => write!(f, "Invalid header: {}", msg),
-            SnapshotError::Decompression(msg) => write!(f, "Failed to decode body: {}", msg),
-        }
-    }
-}
-impl std::error::Error for SnapshotError {}
-/// Execute an HTTP request against an Axum [`TestServer`] by rehydrating it
-/// into the server's own [`axum_test::TestRequest`] builder.
-pub async fn call_test_server(server: &TestServer, request: AxumRequest<Body>) -> AxumTestResponse {
-    let (parts, body) = request.into_parts();
-    let mut path = parts.uri.path().to_string();
-    if let Some(query) = parts.uri.query()
-        && !query.is_empty()
-    {
-        path.push('?');
-        path.push_str(query);
-    }
-    let mut test_request = server.method(parts.method.clone(), &path);
-    for (name, value) in parts.headers.iter() {
-        test_request = test_request.add_header(name.clone(), value.clone());
-    }
-    let collected = body
-        .collect()
-        .await
-        .expect("failed to read request body for test dispatch");
-    let bytes = collected.to_bytes();
-    if !bytes.is_empty() {
-        test_request = test_request.bytes(bytes);
-    }
-    test_request.await
-}
-/// Convert an `AxumTestResponse` into a reusable [`ResponseSnapshot`].
-pub async fn snapshot_response(response: AxumTestResponse) -> Result<ResponseSnapshot, SnapshotError> {
-    let status = response.status_code().as_u16();
-    let mut headers = HashMap::new();
-    for (name, value) in response.headers() {
-        let header_value = value
-            .to_str()
-            .map_err(|e| SnapshotError::InvalidHeader(e.to_string()))?;
-        headers.insert(name.to_string().to_ascii_lowercase(), header_value.to_string());
-    }
-    let body = response.into_bytes();
-    let decoded_body = decode_body(&headers, body.to_vec())?;
-    Ok(ResponseSnapshot {
-        status,
-        headers,
-        body: decoded_body,
-    })
-}
-fn decode_body(headers: &HashMap<String, String>, body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
-    let encoding = headers
-        .get("content-encoding")
-        .map(|value| value.trim().to_ascii_lowercase());
-    match encoding.as_deref() {
-        Some("gzip") | Some("x-gzip") => decode_gzip(body),
-        Some("br") => decode_brotli(body),
-        _ => Ok(body),
-    }
-}
-fn decode_gzip(body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
-    let mut decoder = GzDecoder::new(Cursor::new(body));
-    let mut decoded = Vec::new();
-    decoder
-        .read_to_end(&mut decoded)
-        .map_err(|e| SnapshotError::Decompression(e.to_string()))?;
-    Ok(decoded)
-}
-fn decode_brotli(body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
-    let mut decoder = Decompressor::new(Cursor::new(body), 4096);
-    let mut decoded = Vec::new();
-    decoder
-        .read_to_end(&mut decoded)
-        .map_err(|e| SnapshotError::Decompression(e.to_string()))?;
-    Ok(decoded)
-}
-/// WebSocket connection wrapper for testing.
-///
-/// Provides a simple interface for sending and receiving WebSocket messages
-/// during tests without needing a real network connection.
-pub struct WebSocketConnection {
-    inner: TestWebSocket,
-}
-impl WebSocketConnection {
-    /// Create a new WebSocket connection from an axum-test TestWebSocket.
-    pub fn new(inner: TestWebSocket) -> Self {
-        Self { inner }
-    }
-    /// Send a text message over the WebSocket.
-    pub async fn send_text(&mut self, text: impl std::fmt::Display) {
-        self.inner.send_text(text).await;
-    }
-    /// Send a JSON message over the WebSocket.
-    pub async fn send_json<T: serde::Serialize>(&mut self, value: &T) {
-        self.inner.send_json(value).await;
-    }
-    /// Send a raw WebSocket message.
-    pub async fn send_message(&mut self, msg: WsMessage) {
-        self.inner.send_message(msg).await;
-    }
-    /// Receive the next text message from the WebSocket.
-    pub async fn receive_text(&mut self) -> String {
-        self.inner.receive_text().await
-    }
-    /// Receive and parse a JSON message from the WebSocket.
-    pub async fn receive_json<T: serde::de::DeserializeOwned>(&mut self) -> T {
-        self.inner.receive_json().await
-    }
-    /// Receive raw bytes from the WebSocket.
-    pub async fn receive_bytes(&mut self) -> bytes::Bytes {
-        self.inner.receive_bytes().await
-    }
-    /// Receive the next raw message from the WebSocket.
-    pub async fn receive_message(&mut self) -> WebSocketMessage {
-        let msg = self.inner.receive_message().await;
-        WebSocketMessage::from_ws_message(msg)
-    }
-    /// Close the WebSocket connection.
-    pub async fn close(self) {
-        self.inner.close().await;
-    }
-}
-/// A WebSocket message that can be text or binary.
-#[derive(Debug, Clone)]
-pub enum WebSocketMessage {
-    /// A text message.
-    Text(String),
-    /// A binary message.
-    Binary(Vec<u8>),
-    /// A close message.
-    Close(Option<String>),
-    /// A ping message.
-    Ping(Vec<u8>),
-    /// A pong message.
-    Pong(Vec<u8>),
-}
-impl WebSocketMessage {
-    fn from_ws_message(msg: WsMessage) -> Self {
-        match msg {
-            WsMessage::Text(text) => WebSocketMessage::Text(text.to_string()),
-            WsMessage::Binary(data) => WebSocketMessage::Binary(data.to_vec()),
-            WsMessage::Close(frame) => WebSocketMessage::Close(frame.map(|f| f.reason.to_string())),
-            WsMessage::Ping(data) => WebSocketMessage::Ping(data.to_vec()),
-            WsMessage::Pong(data) => WebSocketMessage::Pong(data.to_vec()),
-            WsMessage::Frame(_) => WebSocketMessage::Close(None),
-        }
-    }
-    /// Get the message as text, if it's a text message.
-    pub fn as_text(&self) -> Option<&str> {
-        match self {
-            WebSocketMessage::Text(text) => Some(text),
-            _ => None,
-        }
-    }
-    /// Get the message as JSON, if it's a text message containing JSON.
-    pub fn as_json(&self) -> Result<Value, String> {
-        match self {
-            WebSocketMessage::Text(text) => {
-                serde_json::from_str(text).map_err(|e| format!("Failed to parse JSON: {}", e))
-            }
-            _ => Err("Message is not text".to_string()),
-        }
-    }
-    /// Get the message as binary, if it's a binary message.
-    pub fn as_binary(&self) -> Option<&[u8]> {
-        match self {
-            WebSocketMessage::Binary(data) => Some(data),
-            _ => None,
-        }
-    }
-    /// Check if this is a close message.
-    pub fn is_close(&self) -> bool {
-        matches!(self, WebSocketMessage::Close(_))
-    }
-}
-/// Connect to a WebSocket endpoint on the test server.
-pub async fn connect_websocket(server: &TestServer, path: &str) -> WebSocketConnection {
-    let ws = server.get_websocket(path).await.into_websocket().await;
-    WebSocketConnection::new(ws)
-}
-/// Server-Sent Events (SSE) stream for testing.
-///
-/// Wraps a response body and provides methods to parse SSE events.
-#[derive(Debug)]
-pub struct SseStream {
-    body: String,
-    events: Vec<SseEvent>,
-}
-impl SseStream {
-    /// Create a new SSE stream from a response.
-    pub fn from_response(response: &ResponseSnapshot) -> Result<Self, String> {
-        let body = response
-            .text()
-            .map_err(|e| format!("Failed to read response body: {}", e))?;
-        let events = Self::parse_events(&body);
-        Ok(Self { body, events })
-    }
-    fn parse_events(body: &str) -> Vec<SseEvent> {
-        let mut events = Vec::new();
-        let lines: Vec<&str> = body.lines().collect();
-        let mut i = 0;
-        while i < lines.len() {
-            if lines[i].starts_with("data:") {
-                let data = lines[i].trim_start_matches("data:").trim().to_string();
-                events.push(SseEvent { data });
-            } else if lines[i].starts_with("data") {
-                let data = lines[i].trim_start_matches("data").trim().to_string();
-                if !data.is_empty() || lines[i].len() == 4 {
-                    events.push(SseEvent { data });
-                }
-            }
-            i += 1;
-        }
-        events
-    }
-    /// Get all events from the stream.
-    pub fn events(&self) -> &[SseEvent] {
-        &self.events
-    }
-    /// Get the raw body of the SSE response.
-    pub fn body(&self) -> &str {
-        &self.body
-    }
-    /// Get events as JSON values.
-    pub fn events_as_json(&self) -> Result<Vec<Value>, String> {
-        self.events
-            .iter()
-            .map(|event| event.as_json())
-            .collect::<Result<Vec<_>, _>>()
-    }
-}
-/// A single Server-Sent Event.
-#[derive(Debug, Clone)]
-pub struct SseEvent {
-    /// The data field of the event.
-    pub data: String,
-}
-impl SseEvent {
-    /// Parse the event data as JSON.
-    pub fn as_json(&self) -> Result<Value, String> {
-        serde_json::from_str(&self.data).map_err(|e| format!("Failed to parse JSON: {}", e))
-    }
-}
-#[cfg(test)]
-mod tests {
-    use super::*;
-    #[test]
-    fn sse_stream_parses_multiple_events() {
-        let mut headers = HashMap::new();
-        headers.insert("content-type".to_string(), "text/event-stream".to_string());
-        let snapshot = ResponseSnapshot {
-            status: 200,
-            headers,
-            body: b"data: {\"id\": 1}\n\ndata: \"hello\"\n\n".to_vec(),
-        };
-        let stream = SseStream::from_response(&snapshot).expect("stream");
-        assert_eq!(stream.events().len(), 2);
-        assert_eq!(stream.events()[0].as_json().unwrap()["id"], serde_json::json!(1));
-        assert_eq!(stream.events()[1].data, "\"hello\"");
-        assert_eq!(stream.events_as_json().unwrap().len(), 2);
-    }
-    #[test]
-    fn sse_event_reports_invalid_json() {
-        let event = SseEvent {
-            data: "not-json".to_string(),
-        };
-        assert!(event.as_json().is_err());
-    }
-}
+use axum::body::Body;
+use axum::http::Request as AxumRequest;
+use axum_test::{TestResponse as AxumTestResponse, TestServer, TestWebSocket, WsMessage};
+pub mod multipart;
+pub use multipart::{MultipartFilePart, build_multipart_body};
+pub mod form;
+pub mod test_client;
+pub use test_client::TestClient;
+use brotli::Decompressor;
+use flate2::read::GzDecoder;
+pub use form::encode_urlencoded_body;
+use http_body_util::BodyExt;
+use serde_json::Value;
+use std::collections::HashMap;
+use std::io::{Cursor, Read};
+/// Snapshot of an Axum response used by higher-level language bindings.
+#[derive(Debug, Clone)]
+pub struct ResponseSnapshot {
+    /// HTTP status code.
+    pub status: u16,
+    /// Response headers (lowercase keys for predictable lookups).
+    pub headers: HashMap<String, String>,
+    /// Response body bytes (decoded for supported encodings).
+    pub body: Vec<u8>,
+}
+impl ResponseSnapshot {
+    /// Return response body as UTF-8 string.
+    pub fn text(&self) -> Result<String, std::string::FromUtf8Error> {
+        String::from_utf8(self.body.clone())
+    }
+    /// Parse response body as JSON.
+    pub fn json(&self) -> Result<Value, serde_json::Error> {
+        serde_json::from_slice(&self.body)
+    }
+    /// Lookup header by case-insensitive name.
+    pub fn header(&self, name: &str) -> Option<&str> {
+        self.headers.get(&name.to_ascii_lowercase()).map(|s| s.as_str())
+    }
+}
+/// Possible errors while converting an Axum response into a snapshot.
+#[derive(Debug)]
+pub enum SnapshotError {
+    /// Response header could not be decoded to UTF-8.
+    InvalidHeader(String),
+    /// Body decompression failed.
+    Decompression(String),
+}
+impl std::fmt::Display for SnapshotError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            SnapshotError::InvalidHeader(msg) => write!(f, "Invalid header: {}", msg),
+            SnapshotError::Decompression(msg) => write!(f, "Failed to decode body: {}", msg),
+        }
+    }
+}
+impl std::error::Error for SnapshotError {}
+/// Execute an HTTP request against an Axum [`TestServer`] by rehydrating it
+/// into the server's own [`axum_test::TestRequest`] builder.
+pub async fn call_test_server(server: &TestServer, request: AxumRequest<Body>) -> AxumTestResponse {
+    let (parts, body) = request.into_parts();
+    let mut path = parts.uri.path().to_string();
+    if let Some(query) = parts.uri.query()
+        && !query.is_empty()
+    {
+        path.push('?');
+        path.push_str(query);
+    }
+    let mut test_request = server.method(parts.method.clone(), &path);
+    for (name, value) in parts.headers.iter() {
+        test_request = test_request.add_header(name.clone(), value.clone());
+    }
+    let collected = body
+        .collect()
+        .await
+        .expect("failed to read request body for test dispatch");
+    let bytes = collected.to_bytes();
+    if !bytes.is_empty() {
+        test_request = test_request.bytes(bytes);
+    }
+    test_request.await
+}
+/// Convert an `AxumTestResponse` into a reusable [`ResponseSnapshot`].
+pub async fn snapshot_response(response: AxumTestResponse) -> Result<ResponseSnapshot, SnapshotError> {
+    let status = response.status_code().as_u16();
+    let mut headers = HashMap::new();
+    for (name, value) in response.headers() {
+        let header_value = value
+            .to_str()
+            .map_err(|e| SnapshotError::InvalidHeader(e.to_string()))?;
+        headers.insert(name.to_string().to_ascii_lowercase(), header_value.to_string());
+    }
+    let body = response.into_bytes();
+    let decoded_body = decode_body(&headers, body.to_vec())?;
+    Ok(ResponseSnapshot {
+        status,
+        headers,
+        body: decoded_body,
+    })
+}
+/// Convert an Axum response into a reusable [`ResponseSnapshot`].
+pub async fn snapshot_http_response(
+    response: axum::response::Response<Body>,
+) -> Result<ResponseSnapshot, SnapshotError> {
+    let (parts, body) = response.into_parts();
+    let status = parts.status.as_u16();
+    let mut headers = HashMap::new();
+    for (name, value) in parts.headers.iter() {
+        let header_value = value
+            .to_str()
+            .map_err(|e| SnapshotError::InvalidHeader(e.to_string()))?;
+        headers.insert(name.to_string().to_ascii_lowercase(), header_value.to_string());
+    }
+    let collected = body
+        .collect()
+        .await
+        .map_err(|e| SnapshotError::Decompression(e.to_string()))?;
+    let bytes = collected.to_bytes();
+    let decoded_body = decode_body(&headers, bytes.to_vec())?;
+    Ok(ResponseSnapshot {
+        status,
+        headers,
+        body: decoded_body,
+    })
+}
+fn decode_body(headers: &HashMap<String, String>, body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
+    let encoding = headers
+        .get("content-encoding")
+        .map(|value| value.trim().to_ascii_lowercase());
+    match encoding.as_deref() {
+        Some("gzip" | "x-gzip") => decode_gzip(body),
+        Some("br") => decode_brotli(body),
+        _ => Ok(body),
+    }
+}
+fn decode_gzip(body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
+    let mut decoder = GzDecoder::new(Cursor::new(body));
+    let mut decoded_bytes = Vec::new();
+    decoder
+        .read_to_end(&mut decoded_bytes)
+        .map_err(|e| SnapshotError::Decompression(e.to_string()))?;
+    Ok(decoded_bytes)
+}
+fn decode_brotli(body: Vec<u8>) -> Result<Vec<u8>, SnapshotError> {
+    let mut decoder = Decompressor::new(Cursor::new(body), 4096);
+    let mut decoded_bytes = Vec::new();
+    decoder
+        .read_to_end(&mut decoded_bytes)
+        .map_err(|e| SnapshotError::Decompression(e.to_string()))?;
+    Ok(decoded_bytes)
+}
+/// WebSocket connection wrapper for testing.
+///
+/// Provides a simple interface for sending and receiving WebSocket messages
+/// during tests without needing a real network connection.
+pub struct WebSocketConnection {
+    inner: TestWebSocket,
+}
+impl WebSocketConnection {
+    /// Create a new WebSocket connection from an axum-test TestWebSocket.
+    pub fn new(inner: TestWebSocket) -> Self {
+        Self { inner }
+    }
+    /// Send a text message over the WebSocket.
+    pub async fn send_text(&mut self, text: impl std::fmt::Display) {
+        self.inner.send_text(text).await;
+    }
+    /// Send a JSON message over the WebSocket.
+    pub async fn send_json<T: serde::Serialize>(&mut self, value: &T) {
+        self.inner.send_json(value).await;
+    }
+    /// Send a raw WebSocket message.
+    pub async fn send_message(&mut self, msg: WsMessage) {
+        self.inner.send_message(msg).await;
+    }
+    /// Receive the next text message from the WebSocket.
+    pub async fn receive_text(&mut self) -> String {
+        self.inner.receive_text().await
+    }
+    /// Receive and parse a JSON message from the WebSocket.
+    pub async fn receive_json<T: serde::de::DeserializeOwned>(&mut self) -> T {
+        self.inner.receive_json().await
+    }
+    /// Receive raw bytes from the WebSocket.
+    pub async fn receive_bytes(&mut self) -> bytes::Bytes {
+        self.inner.receive_bytes().await
+    }
+    /// Receive the next raw message from the WebSocket.
+    pub async fn receive_message(&mut self) -> WebSocketMessage {
+        let msg = self.inner.receive_message().await;
+        WebSocketMessage::from_ws_message(msg)
+    }
+    /// Close the WebSocket connection.
+    pub async fn close(self) {
+        self.inner.close().await;
+    }
+}
+/// A WebSocket message that can be text or binary.
+#[derive(Debug, Clone)]
+pub enum WebSocketMessage {
+    /// A text message.
+    Text(String),
+    /// A binary message.
+    Binary(Vec<u8>),
+    /// A close message.
+    Close(Option<String>),
+    /// A ping message.
+    Ping(Vec<u8>),
+    /// A pong message.
+    Pong(Vec<u8>),
+}
+impl WebSocketMessage {
+    fn from_ws_message(msg: WsMessage) -> Self {
+        match msg {
+            WsMessage::Text(text) => WebSocketMessage::Text(text.to_string()),
+            WsMessage::Binary(data) => WebSocketMessage::Binary(data.to_vec()),
+            WsMessage::Close(frame) => WebSocketMessage::Close(frame.map(|f| f.reason.to_string())),
+            WsMessage::Ping(data) => WebSocketMessage::Ping(data.to_vec()),
+            WsMessage::Pong(data) => WebSocketMessage::Pong(data.to_vec()),
+            WsMessage::Frame(_) => WebSocketMessage::Close(None),
+        }
+    }
+    /// Get the message as text, if it's a text message.
+    pub fn as_text(&self) -> Option<&str> {
+        match self {
+            WebSocketMessage::Text(text) => Some(text),
+            _ => None,
+        }
+    }
+    /// Get the message as JSON, if it's a text message containing JSON.
+    pub fn as_json(&self) -> Result<Value, String> {
+        match self {
+            WebSocketMessage::Text(text) => {
+                serde_json::from_str(text).map_err(|e| format!("Failed to parse JSON: {}", e))
+            }
+            _ => Err("Message is not text".to_string()),
+        }
+    }
+    /// Get the message as binary, if it's a binary message.
+    pub fn as_binary(&self) -> Option<&[u8]> {
+        match self {
+            WebSocketMessage::Binary(data) => Some(data),
+            _ => None,
+        }
+    }
+    /// Check if this is a close message.
+    pub fn is_close(&self) -> bool {
+        matches!(self, WebSocketMessage::Close(_))
+    }
+}
+/// Connect to a WebSocket endpoint on the test server.
+pub async fn connect_websocket(server: &TestServer, path: &str) -> WebSocketConnection {
+    let ws = server.get_websocket(path).await.into_websocket().await;
+    WebSocketConnection::new(ws)
+}
+/// Server-Sent Events (SSE) stream for testing.
+///
+/// Wraps a response body and provides methods to parse SSE events.
+#[derive(Debug)]
+pub struct SseStream {
+    body: String,
+    events: Vec<SseEvent>,
+}
+impl SseStream {
+    /// Create a new SSE stream from a response.
+    pub fn from_response(response: &ResponseSnapshot) -> Result<Self, String> {
+        let body = response
+            .text()
+            .map_err(|e| format!("Failed to read response body: {}", e))?;
+        let events = Self::parse_events(&body);
+        Ok(Self { body, events })
+    }
+    fn parse_events(body: &str) -> Vec<SseEvent> {
+        let mut events = Vec::new();
+        let lines: Vec<&str> = body.lines().collect();
+        let mut i = 0;
+        while i < lines.len() {
+            if lines[i].starts_with("data:") {
+                let data = lines[i].trim_start_matches("data:").trim().to_string();
+                events.push(SseEvent { data });
+            } else if lines[i].starts_with("data") {
+                let data = lines[i].trim_start_matches("data").trim().to_string();
+                if !data.is_empty() || lines[i].len() == 4 {
+                    events.push(SseEvent { data });
+                }
+            }
+            i += 1;
+        }
+        events
+    }
+    /// Get all events from the stream.
+    pub fn events(&self) -> &[SseEvent] {
+        &self.events
+    }
+    /// Get the raw body of the SSE response.
+    pub fn body(&self) -> &str {
+        &self.body
+    }
+    /// Get events as JSON values.
+    pub fn events_as_json(&self) -> Result<Vec<Value>, String> {
+        self.events
+            .iter()
+            .map(|event| event.as_json())
+            .collect::<Result<Vec<_>, _>>()
+    }
+}
+/// A single Server-Sent Event.
+#[derive(Debug, Clone)]
+pub struct SseEvent {
+    /// The data field of the event.
+    pub data: String,
+}
+impl SseEvent {
+    /// Parse the event data as JSON.
+    pub fn as_json(&self) -> Result<Value, String> {
+        serde_json::from_str(&self.data).map_err(|e| format!("Failed to parse JSON: {}", e))
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn sse_stream_parses_multiple_events() {
+        let mut headers = HashMap::new();
+        headers.insert("content-type".to_string(), "text/event-stream".to_string());
+        let snapshot = ResponseSnapshot {
+            status: 200,
+            headers,
+            body: b"data: {\"id\": 1}\n\ndata: \"hello\"\n\n".to_vec(),
+        };
+        let stream = SseStream::from_response(&snapshot).expect("stream");
+        assert_eq!(stream.events().len(), 2);
+        assert_eq!(stream.events()[0].as_json().unwrap()["id"], serde_json::json!(1));
+        assert_eq!(stream.events()[1].data, "\"hello\"");
+        assert_eq!(stream.events_as_json().unwrap().len(), 2);
+    }
+    #[test]
+    fn sse_event_reports_invalid_json() {
+        let event = SseEvent {
+            data: "not-json".to_string(),
+        };
+        assert!(event.as_json().is_err());
+    }
+}