spikard 0.3.6 → 0.5.0

data/vendor/crates/spikard-rb/src/lib.rs

@@ -1,4 +1,5 @@
 #![allow(deprecated)]
+#![deny(clippy::unwrap_used)]
 
 //! Spikard Ruby bindings using Magnus FFI.
 //!
@@ -7,7 +8,7 @@
 //!
 //! ## Modules
 //!
-//! - `test_client`: TestClient wrapper for integration testing
+//! - `testing`: Testing utilities (client, SSE, WebSocket)
 //! - `handler`: RubyHandler trait implementation
 //! - `di`: Dependency injection bridge for Ruby types
 //! - `config`: ServerConfig extraction from Ruby objects
@@ -16,26 +17,27 @@
 //! - `background`: Background task management
 //! - `lifecycle`: Lifecycle hook implementations
 //! - `sse`: Server-Sent Events support
-//! - `test_sse`: SSE testing utilities
 //! - `websocket`: WebSocket support
-//! - `test_websocket`: WebSocket testing utilities
 
 mod background;
 mod config;
 mod conversion;
 mod di;
+mod gvl;
 mod handler;
+mod integration;
 mod lifecycle;
+mod metadata;
+mod request;
+mod runtime;
 mod server;
 mod sse;
-mod test_client;
-mod test_sse;
-mod test_websocket;
+mod testing;
 mod websocket;
 
 use async_stream::stream;
 use axum::body::Body;
-use axum::http::{HeaderName, HeaderValue, Method, Request, Response, StatusCode};
+use axum::http::{HeaderName, HeaderValue, Method, StatusCode};
 use axum_test::{TestServer, TestServerConfig, Transport};
 use bytes::Bytes;
 use cookie::Cookie;
@@ -44,12 +46,11 @@ use magnus::value::{InnerValue, Opaque};
 use magnus::{
     Error, Module, RArray, RHash, RString, Ruby, TryConvert, Value, function, gc::Marker, method, r_hash::ForEach,
 };
-use once_cell::sync::Lazy;
-use serde_json::{Map as JsonMap, Value as JsonValue};
-use spikard_http::ParameterValidator;
-use spikard_http::problem::ProblemDetails;
+use serde_json::Value as JsonValue;
+use spikard_http::ProblemDetails;
 use spikard_http::testing::{
-    MultipartFilePart, SnapshotError, build_multipart_body, encode_urlencoded_body, snapshot_response,
+    MultipartFilePart, ResponseSnapshot, SnapshotError, build_multipart_body, encode_urlencoded_body,
+    snapshot_response,
 };
 use spikard_http::{Handler, HandlerResponse, HandlerResult, RequestData};
 use spikard_http::{Route, RouteMetadata, SchemaValidator};
@@ -59,14 +60,15 @@ use std::io;
 use std::mem;
 use std::pin::Pin;
 use std::sync::Arc;
-use tokio::runtime::{Builder, Runtime};
+use std::time::Duration;
+use url::Url;
 
-static GLOBAL_RUNTIME: Lazy<Runtime> = Lazy::new(|| {
-    Builder::new_current_thread()
-        .enable_all()
-        .build()
-        .expect("Failed to initialise global Tokio runtime")
-});
+use crate::config::extract_server_config;
+use crate::conversion::{extract_files, problem_to_json};
+use crate::integration::build_dependency_container;
+use crate::metadata::{build_route_metadata, ruby_value_to_json};
+use crate::request::NativeRequest;
+use crate::runtime::{normalize_route_metadata, run_server};
 
 #[derive(Default)]
 #[magnus::wrap(class = "Spikard::Native::TestClient", free_immediately, mark)]
@@ -78,8 +80,7 @@ struct ClientInner {
     http_server: Arc<TestServer>,
     transport_server: Arc<TestServer>,
     /// Keep Ruby handler closures alive for GC; accessed via the `mark` hook.
-    #[allow(dead_code)]
-    handlers: Vec<RubyHandler>,
+    _handlers: Vec<RubyHandler>,
 }
 
 struct RequestConfig {
@@ -107,12 +108,8 @@ struct RubyHandler {
 struct RubyHandlerInner {
     handler_proc: Opaque<Value>,
     handler_name: String,
-    method: String,
-    path: String,
     json_module: Opaque<Value>,
-    request_validator: Option<Arc<SchemaValidator>>,
     response_validator: Option<Arc<SchemaValidator>>,
-    parameter_validator: Option<ParameterValidator>,
     #[cfg(feature = "di")]
     handler_dependencies: Vec<String>,
 }
@@ -146,6 +143,7 @@ struct NativeBuiltResponse {
     response: RefCell<Option<HandlerResponse>>,
     body_json: Option<JsonValue>,
     /// Ruby values that must be kept alive for GC (e.g., streaming enumerators)
+    #[allow(dead_code)]
     gc_handles: Vec<Opaque<Value>>,
 }
 
@@ -159,15 +157,17 @@ struct NativeLifecycleRegistry {
 #[magnus::wrap(class = "Spikard::Native::DependencyRegistry", free_immediately, mark)]
 struct NativeDependencyRegistry {
     container: RefCell<Option<spikard_core::di::DependencyContainer>>,
+    #[allow(dead_code)]
     gc_handles: RefCell<Vec<Opaque<Value>>>,
+    registered_keys: RefCell<Vec<String>>,
 }
 
 impl StreamingResponsePayload {
     fn into_response(self) -> Result<HandlerResponse, Error> {
         let ruby = Ruby::get().map_err(|_| {
             Error::new(
-                Ruby::get().unwrap().exception_runtime_error(),
-                "Ruby VM unavailable while building streaming response",
+                magnus::exception::runtime_error(),
+                "Ruby VM became unavailable during streaming response construction",
             )
         })?;
 
@@ -221,6 +221,7 @@ impl StreamingResponsePayload {
 }
 
 impl NativeBuiltResponse {
+    #[allow(dead_code)]
     fn new(response: HandlerResponse, body_json: Option<JsonValue>, gc_handles: Vec<Opaque<Value>>) -> Self {
         Self {
             response: RefCell::new(Some(response)),
@@ -229,7 +230,7 @@ impl NativeBuiltResponse {
         }
     }
 
-    fn into_parts(&self) -> Result<(HandlerResponse, Option<JsonValue>), Error> {
+    fn extract_parts(&self) -> Result<(HandlerResponse, Option<JsonValue>), Error> {
         let mut borrow = self.response.borrow_mut();
         let response = borrow
             .take()
@@ -274,11 +275,8 @@ impl NativeBuiltResponse {
         Ok(headers_hash.as_value())
     }
 
+    #[allow(dead_code)]
     fn mark(&self, marker: &Marker) {
-        if self.gc_handles.is_empty() {
-            return;
-        }
-
         if let Ok(ruby) = Ruby::get() {
             for handle in &self.gc_handles {
                 marker.mark(handle.get_inner_with(&ruby));
@@ -287,16 +285,6 @@ impl NativeBuiltResponse {
     }
 }
 
-impl Default for NativeBuiltResponse {
-    fn default() -> Self {
-        let response = axum::http::Response::builder()
-            .status(StatusCode::OK)
-            .body(Body::empty())
-            .unwrap();
-        Self::new(HandlerResponse::from(response), None, Vec::new())
-    }
-}
-
 impl NativeLifecycleRegistry {
     fn add_on_request(&self, hook_value: Value) -> Result<(), Error> {
         self.add_hook("on_request", hook_value, |hooks, hook| hooks.add_on_request(hook))
@@ -324,6 +312,13 @@ impl NativeLifecycleRegistry {
         mem::take(&mut *self.hooks.borrow_mut())
     }
 
+    #[allow(dead_code)]
+    fn mark(&self, marker: &Marker) {
+        for hook in self.ruby_hooks.borrow().iter() {
+            hook.mark(marker);
+        }
+    }
+
     fn add_hook<F>(&self, kind: &str, hook_value: Value, push: F) -> Result<(), Error>
     where
         F: Fn(&mut spikard_http::LifecycleHooks, Arc<crate::lifecycle::RubyLifecycleHook>),
@@ -338,12 +333,6 @@ impl NativeLifecycleRegistry {
         self.ruby_hooks.borrow_mut().push(hook);
         Ok(())
     }
-
-    fn mark(&self, marker: &Marker) {
-        for hook in self.ruby_hooks.borrow().iter() {
-            hook.mark(marker);
-        }
-    }
 }
 
 impl Default for NativeDependencyRegistry {
@@ -351,6 +340,7 @@ impl Default for NativeDependencyRegistry {
         Self {
             container: RefCell::new(Some(spikard_core::di::DependencyContainer::new())),
             gc_handles: RefCell::new(Vec::new()),
+            registered_keys: RefCell::new(Vec::new()),
         }
     }
 }
@@ -404,9 +394,20 @@ impl NativeDependencyRegistry {
             self.gc_handles.borrow_mut().push(Opaque::from(val));
         }
 
+        self.registered_keys.borrow_mut().push(key);
+
         Ok(())
     }
 
+    #[allow(dead_code)]
+    fn mark(&self, marker: &Marker) {
+        if let Ok(ruby) = Ruby::get() {
+            for handle in self.gc_handles.borrow().iter() {
+                marker.mark(handle.get_inner_with(&ruby));
+            }
+        }
+    }
+
     fn take_container(&self) -> Result<spikard_core::di::DependencyContainer, Error> {
         let mut borrow = self.container.borrow_mut();
         let container = borrow.take().ok_or_else(|| {
@@ -417,12 +418,9 @@ impl NativeDependencyRegistry {
         })?;
         Ok(container)
     }
-    fn mark(&self, marker: &Marker) {
-        if let Ok(ruby) = Ruby::get() {
-            for handle in self.gc_handles.borrow().iter() {
-                marker.mark(handle.get_inner_with(&ruby));
-            }
-        }
+
+    fn keys(&self) -> Vec<String> {
+        self.registered_keys.borrow().clone()
     }
 }
 
@@ -492,7 +490,6 @@ impl NativeTestClient {
 
         let mut server_config = extract_server_config(ruby, config_value)?;
 
-        // Extract and register dependencies
         #[cfg(feature = "di")]
         {
             if let Ok(registry) = <&NativeDependencyRegistry>::try_convert(dependencies) {
@@ -592,7 +589,8 @@ impl NativeTestClient {
             );
         }
 
-        let http_server = GLOBAL_RUNTIME
+        let runtime = crate::server::global_runtime(ruby)?;
+        let http_server = runtime
             .block_on(async { TestServer::new(router.clone()) })
             .map_err(|err| {
                 Error::new(
@@ -605,7 +603,7 @@ impl NativeTestClient {
             transport: Some(Transport::HttpRandomPort),
             ..Default::default()
         };
-        let transport_server = GLOBAL_RUNTIME
+        let transport_server = runtime
             .block_on(async { TestServer::new_with_config(router, ws_config) })
             .map_err(|err| {
                 Error::new(
@@ -617,7 +615,7 @@ impl NativeTestClient {
         *this.inner.borrow_mut() = Some(ClientInner {
             http_server: Arc::new(http_server),
             transport_server: Arc::new(transport_server),
-            handlers: handler_refs,
+            _handlers: handler_refs,
         });
 
         Ok(())
@@ -638,7 +636,8 @@ impl NativeTestClient {
 
         let request_config = parse_request_config(ruby, options)?;
 
-        let response = GLOBAL_RUNTIME
+        let runtime = crate::server::global_runtime(ruby)?;
+        let response = runtime
             .block_on(execute_request(
                 inner.http_server.clone(),
                 http_method,
@@ -670,16 +669,31 @@ impl NativeTestClient {
 
         drop(inner_borrow);
 
-        let handle =
-            GLOBAL_RUNTIME.spawn(async move { spikard_http::testing::connect_websocket(&server, &path).await });
-
-        let ws = GLOBAL_RUNTIME.block_on(async {
-            handle
-                .await
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("WebSocket task failed: {}", e)))
+        let timeout_duration = websocket_timeout();
+        let ws = crate::call_without_gvl!(
+            block_on_websocket_connect,
+            args: (
+                server, Arc<TestServer>,
+                path, String,
+                timeout_duration, Duration
+            ),
+            return_type: Result<crate::testing::websocket::WebSocketConnection, WebSocketConnectError>
+        )
+        .map_err(|err| match err {
+            WebSocketConnectError::Timeout => Error::new(
+                ruby.exception_runtime_error(),
+                format!(
+                    "WebSocket connect timed out after {}ms",
+                    timeout_duration.as_millis()
+                ),
+            ),
+            WebSocketConnectError::Other(message) => Error::new(
+                ruby.exception_runtime_error(),
+                format!("WebSocket connect failed: {}", message),
+            ),
         })?;
 
-        let ws_conn = test_websocket::WebSocketTestConnection::new(ws);
+        let ws_conn = testing::websocket::WebSocketTestConnection::new(ws);
         Ok(ruby.obj_wrap(ws_conn).as_value())
     }
 
@@ -689,18 +703,74 @@ impl NativeTestClient {
             .as_ref()
             .ok_or_else(|| Error::new(ruby.exception_runtime_error(), "TestClient not initialised"))?;
 
-        let response = GLOBAL_RUNTIME
-            .block_on(async {
-                let axum_response = inner.transport_server.get(&path).await;
-                snapshot_response(axum_response).await
-            })
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("SSE request failed: {}", e)))?;
+        let runtime = crate::server::global_runtime(ruby)?;
+        let request_config = RequestConfig {
+            query: None,
+            headers: HashMap::new(),
+            cookies: HashMap::new(),
+            body: None,
+        };
+        let response = runtime
+            .block_on(execute_request(
+                inner.http_server.clone(),
+                Method::GET,
+                path.clone(),
+                request_config,
+            ))
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), format!("SSE request failed: {}", err.0)))?;
+
+        let body = response.body_text.unwrap_or_default().into_bytes();
+        let snapshot = ResponseSnapshot {
+            status: response.status,
+            headers: response.headers,
+            body,
+        };
+
+        testing::sse::sse_stream_from_response(ruby, &snapshot)
+    }
+}
+
+fn websocket_timeout() -> Duration {
+    const DEFAULT_TIMEOUT_MS: u64 = 30_000;
+    let timeout_ms = std::env::var("SPIKARD_RB_WS_TIMEOUT_MS")
+        .ok()
+        .and_then(|value| value.parse::<u64>().ok())
+        .unwrap_or(DEFAULT_TIMEOUT_MS);
+    Duration::from_millis(timeout_ms)
+}
 
-        test_sse::sse_stream_from_response(ruby, &response)
+#[derive(Debug)]
+enum WebSocketConnectError {
+    Timeout,
+    Other(String),
+}
+
+fn block_on_websocket_connect(
+    server: Arc<TestServer>,
+    path: String,
+    timeout_duration: Duration,
+) -> Result<crate::testing::websocket::WebSocketConnection, WebSocketConnectError> {
+    let url = server
+        .server_url(&path)
+        .map_err(|err| WebSocketConnectError::Other(err.to_string()))?;
+    let ws_url = to_ws_url(url)?;
+
+    match crate::testing::websocket::WebSocketConnection::connect(ws_url, timeout_duration) {
+        Ok(ws) => Ok(ws),
+        Err(crate::testing::websocket::WebSocketIoError::Timeout) => Err(WebSocketConnectError::Timeout),
+        Err(err) => Err(WebSocketConnectError::Other(format!("{:?}", err))),
     }
 }
 
-impl ClientInner {}
+fn to_ws_url(mut url: Url) -> Result<Url, WebSocketConnectError> {
+    let scheme = match url.scheme() {
+        "https" => "wss",
+        _ => "ws",
+    };
+    url.set_scheme(scheme)
+        .map_err(|_| WebSocketConnectError::Other("Failed to set WebSocket scheme".to_string()))?;
+    Ok(url)
+}
 
 impl RubyHandler {
     fn new(route: &Route, handler_value: Value, json_module: Value) -> Result<Self, Error> {
@@ -708,12 +778,8 @@ impl RubyHandler {
             inner: Arc::new(RubyHandlerInner {
                 handler_proc: Opaque::from(handler_value),
                 handler_name: route.handler_name.clone(),
-                method: route.method.as_str().to_string(),
-                path: route.path.clone(),
                 json_module: Opaque::from(json_module),
-                request_validator: route.request_validator.clone(),
                 response_validator: route.response_validator.clone(),
-                parameter_validator: route.parameter_validator.clone(),
                 #[cfg(feature = "di")]
                 handler_dependencies: route.handler_dependencies.clone(),
             }),
@@ -727,8 +793,6 @@ impl RubyHandler {
         _ruby: &Ruby,
         handler_value: Value,
         handler_name: String,
-        method: String,
-        path: String,
         json_module: Value,
         route: &Route,
     ) -> Result<Self, Error> {
@@ -736,12 +800,8 @@ impl RubyHandler {
             inner: Arc::new(RubyHandlerInner {
                 handler_proc: Opaque::from(handler_value),
                 handler_name,
-                method,
-                path,
                 json_module: Opaque::from(json_module),
-                request_validator: route.request_validator.clone(),
                 response_validator: route.response_validator.clone(),
-                parameter_validator: route.parameter_validator.clone(),
                 #[cfg(feature = "di")]
                 handler_dependencies: route.handler_dependencies.clone(),
             }),
@@ -758,31 +818,7 @@ impl RubyHandler {
     }
 
     fn handle(&self, request_data: RequestData) -> HandlerResult {
-        if let Some(validator) = &self.inner.request_validator
-            && let Err(errors) = validator.validate(&request_data.body)
-        {
-            let problem = ProblemDetails::from_validation_error(&errors);
-            let error_json = problem_to_json(&problem);
-            return Err((problem.status_code(), error_json));
-        }
-
-        let validated_params = if let Some(validator) = &self.inner.parameter_validator {
-            match validator.validate_and_extract(
-                &request_data.query_params,
-                request_data.raw_query_params.as_ref(),
-                request_data.path_params.as_ref(),
-                request_data.headers.as_ref(),
-                request_data.cookies.as_ref(),
-            ) {
-                Ok(value) => Some(value),
-                Err(errors) => {
-                    let problem = ProblemDetails::from_validation_error(&errors);
-                    return Err((problem.status_code(), problem_to_json(&problem)));
-                }
-            }
-        } else {
-            None
-        };
+        let validated_params = request_data.validated_params.clone();
 
         let ruby = Ruby::get().map_err(|_| {
             (
@@ -791,25 +827,21 @@ impl RubyHandler {
             )
         })?;
 
-        let request_value = build_ruby_request(&ruby, &self.inner, &request_data, validated_params.as_ref())
+        #[cfg(feature = "di")]
+        let dependencies = request_data.dependencies.clone();
+
+        let request_value = build_ruby_request(&ruby, request_data, validated_params)
             .map_err(|err| (StatusCode::INTERNAL_SERVER_ERROR, err.to_string()))?;
 
         let handler_proc = self.inner.handler_proc.get_inner_with(&ruby);
 
-        // Extract resolved dependencies (if any) and convert to Ruby keyword arguments
         #[cfg(feature = "di")]
         let handler_result = {
-            if let Some(deps) = &request_data.dependencies {
-                // Build keyword arguments hash from dependencies
-                // ONLY include dependencies that the handler actually declared
+            if let Some(deps) = &dependencies {
                 let kwargs_hash = ruby.hash_new();
 
-                // Check if all required handler dependencies are present
-                // If any are missing, return error BEFORE calling handler
                 for key in &self.inner.handler_dependencies {
                     if !deps.contains(key) {
-                        // Handler requires a dependency that was not resolved
-                        // This should have been caught by DI system, but safety check here
                         return Err((
                             StatusCode::INTERNAL_SERVER_ERROR,
                             format!(
@@ -820,17 +852,11 @@ impl RubyHandler {
                     }
                 }
 
-                // Filter dependencies: only pass those declared by the handler
                 for key in &self.inner.handler_dependencies {
                     if let Some(value) = deps.get_arc(key) {
-                        // Check what type of dependency this is and extract Ruby value
                         let ruby_val = if let Some(wrapper) = value.downcast_ref::<crate::di::RubyValueWrapper>() {
-                            // It's a Ruby value wrapper (singleton with preserved mutations)
-                            // Get the raw Ruby value directly to preserve object identity
                             wrapper.get_value(&ruby)
                         } else if let Some(json) = value.downcast_ref::<serde_json::Value>() {
-                            // It's already JSON (non-singleton or value dependency)
-                            // Convert JSON to Ruby value
                             match crate::di::json_to_ruby(&ruby, json) {
                                 Ok(val) => val,
                                 Err(e) => {
@@ -850,7 +876,6 @@ impl RubyHandler {
                             ));
                         };
 
-                        // Add to kwargs hash
                         let key_sym = ruby.to_symbol(key);
                         if let Err(e) = kwargs_hash.aset(key_sym, ruby_val) {
                             return Err((
@@ -861,13 +886,6 @@ impl RubyHandler {
                     }
                 }
 
-                // Call handler with request and dependencies as keyword arguments
-                // Ruby 3.x requires keyword arguments to be passed differently than Ruby 2.x
-                // We'll create a Ruby lambda that calls the handler with ** splat operator
-                //
-                // Equivalent Ruby code:
-                //   lambda { |req, kwargs| handler_proc.call(req, **kwargs) }.call(request, kwargs_hash)
-
                 let wrapper_code = ruby
                     .eval::<Value>(
                         r#"
@@ -885,7 +903,6 @@ impl RubyHandler {
 
                 wrapper_code.funcall("call", (handler_proc, request_value, kwargs_hash))
             } else {
-                // No dependencies, call with just request
                 handler_proc.funcall("call", (request_value,))
             }
         };
@@ -1137,10 +1154,15 @@ fn parse_request_config(ruby: &Ruby, options: Value) -> Result<RequestConfig, Er
     };
 
     let files_opt = get_kw(ruby, hash, "files");
-    let has_files = files_opt.is_some() && !files_opt.unwrap().is_nil();
+    let has_files = files_opt.as_ref().is_some_and(|f| !f.is_nil());
 
     let body = if has_files {
-        let files_value = files_opt.unwrap();
+        let files_value = files_opt.ok_or_else(|| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                "Files option should be Some if has_files is true",
+            )
+        })?;
         let files = extract_files(ruby, files_value)?;
 
         let mut form_data = Vec::new();
@@ -1204,65 +1226,12 @@ fn parse_request_config(ruby: &Ruby, options: Value) -> Result<RequestConfig, Er
 
 fn build_ruby_request(
     ruby: &Ruby,
-    handler: &RubyHandlerInner,
-    request_data: &RequestData,
-    validated_params: Option<&JsonValue>,
+    request_data: RequestData,
+    validated_params: Option<JsonValue>,
 ) -> Result<Value, Error> {
-    let hash = ruby.hash_new();
-
-    hash.aset(ruby.intern("method"), ruby.str_new(&handler.method))?;
-    hash.aset(ruby.intern("path"), ruby.str_new(&handler.path))?;
-
-    let path_params = map_to_ruby_hash(ruby, request_data.path_params.as_ref())?;
-    hash.aset(ruby.intern("path_params"), path_params)?;
+    let native_request = NativeRequest::from_request_data(request_data, validated_params);
 
-    let query_value = json_to_ruby(ruby, &request_data.query_params)?;
-    hash.aset(ruby.intern("query"), query_value)?;
-
-    let raw_query = multimap_to_ruby_hash(ruby, request_data.raw_query_params.as_ref())?;
-    hash.aset(ruby.intern("raw_query"), raw_query)?;
-
-    let headers = map_to_ruby_hash(ruby, request_data.headers.as_ref())?;
-    hash.aset(ruby.intern("headers"), headers)?;
-
-    let cookies = map_to_ruby_hash(ruby, request_data.cookies.as_ref())?;
-    hash.aset(ruby.intern("cookies"), cookies)?;
-
-    let body_value = json_to_ruby(ruby, &request_data.body)?;
-    hash.aset(ruby.intern("body"), body_value)?;
-
-    let params_value = if let Some(validated) = validated_params {
-        json_to_ruby(ruby, validated)?
-    } else {
-        build_default_params(ruby, request_data)?
-    };
-    hash.aset(ruby.intern("params"), params_value)?;
-
-    Ok(hash.as_value())
-}
-
-fn build_default_params(ruby: &Ruby, request_data: &RequestData) -> Result<Value, Error> {
-    let mut map = JsonMap::new();
-
-    for (key, value) in request_data.path_params.as_ref() {
-        map.insert(key.clone(), JsonValue::String(value.clone()));
-    }
-
-    if let JsonValue::Object(obj) = &request_data.query_params {
-        for (key, value) in obj {
-            map.insert(key.clone(), value.clone());
-        }
-    }
-
-    for (key, value) in request_data.headers.as_ref() {
-        map.insert(key.clone(), JsonValue::String(value.clone()));
-    }
-
-    for (key, value) in request_data.cookies.as_ref() {
-        map.insert(key.clone(), JsonValue::String(value.clone()));
-    }
-
-    json_to_ruby(ruby, &JsonValue::Object(map))
+    Ok(ruby.obj_wrap(native_request).as_value())
 }
 
 fn interpret_handler_response(
@@ -1270,16 +1239,15 @@ fn interpret_handler_response(
     handler: &RubyHandlerInner,
     value: Value,
 ) -> Result<RubyHandlerResult, Error> {
-    // Prefer native-built responses to avoid Ruby-side normalization overhead
     let native_method = ruby.intern("to_native_response");
     if value.respond_to(native_method, false)? {
         let native_value: Value = value.funcall("to_native_response", ())?;
         if let Ok(native_resp) = <&NativeBuiltResponse>::try_convert(native_value) {
-            let (response, body_json) = native_resp.into_parts()?;
+            let (response, body_json) = native_resp.extract_parts()?;
             return Ok(RubyHandlerResult::Native(NativeResponseParts { response, body_json }));
         }
     } else if let Ok(native_resp) = <&NativeBuiltResponse>::try_convert(value) {
-        let (response, body_json) = native_resp.into_parts()?;
+        let (response, body_json) = native_resp.extract_parts()?;
         return Ok(RubyHandlerResult::Native(NativeResponseParts { response, body_json }));
     }
 
@@ -1384,6 +1352,7 @@ fn value_to_string_map(ruby: &Ruby, value: Value) -> Result<HashMap<String, Stri
     })
 }
 
+#[allow(dead_code)]
 fn header_pairs_from_map(headers: HashMap<String, String>) -> Result<Vec<(HeaderName, HeaderValue)>, Error> {
     let ruby = Ruby::get().map_err(|err| Error::new(magnus::exception::runtime_error(), err.to_string()))?;
     headers
@@ -1438,1334 +1407,404 @@ fn response_to_ruby(ruby: &Ruby, response: TestResponseData) -> Result<Value, Er
     Ok(hash.as_value())
 }
 
-fn ruby_value_to_json(ruby: &Ruby, json_module: Value, value: Value) -> Result<JsonValue, Error> {
-    if value.is_nil() {
-        return Ok(JsonValue::Null);
+fn get_kw(ruby: &Ruby, hash: RHash, name: &str) -> Option<Value> {
+    let sym = ruby.intern(name);
+    hash.get(sym).or_else(|| hash.get(name))
+}
+
+fn fetch_handler(ruby: &Ruby, handlers: &RHash, name: &str) -> Result<Value, Error> {
+    let symbol_key = ruby.intern(name);
+    if let Some(value) = handlers.get(symbol_key) {
+        return Ok(value);
     }
 
-    let json_string: String = json_module.funcall("generate", (value,))?;
-    serde_json::from_str(&json_string).map_err(|err| {
-        Error::new(
-            ruby.exception_runtime_error(),
-            format!("Failed to convert Ruby value to JSON: {err}"),
-        )
-    })
+    let string_key = ruby.str_new(name);
+    if let Some(value) = handlers.get(string_key) {
+        return Ok(value);
+    }
+
+    Err(Error::new(
+        ruby.exception_name_error(),
+        format!("Handler '{name}' not provided"),
+    ))
 }
 
-fn json_to_ruby(ruby: &Ruby, value: &JsonValue) -> Result<Value, Error> {
-    match value {
-        JsonValue::Null => Ok(ruby.qnil().as_value()),
-        JsonValue::Bool(b) => Ok(if *b {
-            ruby.qtrue().as_value()
-        } else {
-            ruby.qfalse().as_value()
-        }),
-        JsonValue::Number(num) => {
-            if let Some(i) = num.as_i64() {
-                Ok(ruby.integer_from_i64(i).as_value())
-            } else if let Some(f) = num.as_f64() {
-                Ok(ruby.float_from_f64(f).as_value())
-            } else {
-                Ok(ruby.qnil().as_value())
-            }
-        }
-        JsonValue::String(str_val) => Ok(ruby.str_new(str_val).as_value()),
-        JsonValue::Array(items) => {
-            let array = ruby.ary_new();
-            for item in items {
-                array.push(json_to_ruby(ruby, item)?)?;
-            }
-            Ok(array.as_value())
-        }
-        JsonValue::Object(map) => {
-            let hash = ruby.hash_new();
-            for (key, item) in map {
-                hash.aset(ruby.str_new(key), json_to_ruby(ruby, item)?)?;
-            }
-            Ok(hash.as_value())
+/// GC mark hook so Ruby keeps handler closures alive.
+#[allow(dead_code)]
+fn mark(client: &NativeTestClient, marker: &Marker) {
+    let inner_ref = client.inner.borrow();
+    if let Some(inner) = inner_ref.as_ref() {
+        for handler in &inner._handlers {
+            handler.mark(marker);
         }
     }
 }
 
-fn build_response(
-    ruby: &Ruby,
-    content: Value,
-    status_code: i64,
-    headers_value: Value,
-    content_type: Option<String>,
-) -> Result<NativeBuiltResponse, Error> {
+/// Return the Spikard version.
+fn version() -> String {
+    env!("CARGO_PKG_VERSION").to_string()
+}
+
+/// Build a native response from content, status code, and headers.
+///
+/// Called by `Spikard::Response` to construct native response objects.
+/// The content can be a String (raw body), Hash/Array (JSON), or nil.
+fn build_response(ruby: &Ruby, content: Value, status_code: i64, headers: Value) -> Result<Value, Error> {
     let status_u16 = u16::try_from(status_code)
         .map_err(|_| Error::new(ruby.exception_arg_error(), "status_code must be between 0 and 65535"))?;
 
-    let headers = value_to_string_map(ruby, headers_value)?;
-    let mut header_pairs = header_pairs_from_map(headers)?;
-
-    let has_content_type = header_pairs
-        .iter()
-        .any(|(name, _)| name == &HeaderName::from_static("content-type"));
-
-    let json_module = ruby
-        .class_object()
-        .const_get("JSON")
-        .map_err(|_| Error::new(ruby.exception_runtime_error(), "JSON module not available"))?;
+    let header_map = if headers.is_nil() {
+        HashMap::new()
+    } else {
+        let hash = RHash::try_convert(headers)?;
+        hash.to_hash_map::<String, String>()?
+    };
 
-    let mut body_json = None;
-    let body_bytes = if content.is_nil() {
-        Vec::new()
+    let (body_json, raw_body_opt) = if content.is_nil() {
+        (None, None)
     } else if let Ok(str_value) = RString::try_convert(content) {
         let slice = unsafe { str_value.as_slice() };
-        slice.to_vec()
+        (None, Some(slice.to_vec()))
     } else {
-        let json = ruby_value_to_json(ruby, json_module, content)?;
-        body_json = Some(json.clone());
-        serde_json::to_vec(&json).map_err(|err| {
-            Error::new(
-                ruby.exception_runtime_error(),
-                format!("Failed to serialise response body: {err}"),
-            )
-        })?
+        let json_module = ruby
+            .class_object()
+            .const_get("JSON")
+            .map_err(|_| Error::new(ruby.exception_runtime_error(), "JSON module not available"))?;
+        let json_value = ruby_value_to_json(ruby, json_module, content)?;
+        (Some(json_value), None)
     };
 
-    let mut response_builder = axum::http::Response::builder().status(status_u16);
+    let status = StatusCode::from_u16(status_u16).map_err(|err| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("Invalid status code {}: {}", status_u16, err),
+        )
+    })?;
 
-    for (name, value) in &header_pairs {
-        response_builder = response_builder.header(name, value);
-    }
+    let mut response_builder = axum::http::Response::builder().status(status);
 
-    if let Some(content_type) = content_type {
-        let header_value = HeaderValue::from_str(&content_type).map_err(|err| {
+    for (name, value) in &header_map {
+        let header_name = HeaderName::from_bytes(name.as_bytes()).map_err(|err| {
             Error::new(
                 ruby.exception_arg_error(),
-                format!("Invalid content type '{content_type}': {err}"),
+                format!("Invalid header name '{}': {}", name, err),
             )
         })?;
-        response_builder = response_builder.header(HeaderName::from_static("content-type"), header_value.clone());
-        header_pairs.push((HeaderName::from_static("content-type"), header_value));
-    } else if !has_content_type && body_json.is_some() {
-        response_builder = response_builder.header(
-            HeaderName::from_static("content-type"),
-            HeaderValue::from_static("application/json"),
-        );
+        let header_value = HeaderValue::from_str(value).map_err(|err| {
+            Error::new(
+                ruby.exception_arg_error(),
+                format!("Invalid header value for '{}': {}", name, err),
+            )
+        })?;
+        response_builder = response_builder.header(header_name, header_value);
     }
 
-    let response = response_builder.body(Body::from(body_bytes)).map_err(|err| {
+    let body_bytes = if let Some(raw) = raw_body_opt {
+        raw
+    } else if let Some(json_value) = body_json.as_ref() {
+        serde_json::to_vec(&json_value).map_err(|err| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("Failed to serialise response body: {}", err),
+            )
+        })?
+    } else {
+        Vec::new()
+    };
+
+    let axum_response = response_builder.body(Body::from(body_bytes)).map_err(|err| {
         Error::new(
             ruby.exception_runtime_error(),
-            format!("Failed to build response: {err}"),
+            format!("Failed to build response: {}", err),
         )
     })?;
 
-    Ok(NativeBuiltResponse::new(
-        HandlerResponse::from(response),
-        body_json,
-        Vec::new(),
-    ))
+    let handler_response = HandlerResponse::Response(axum_response);
+    let native_response = NativeBuiltResponse::new(handler_response, body_json.clone(), Vec::new());
+    Ok(ruby.obj_wrap(native_response).as_value())
 }
 
-fn build_streaming_response(
-    ruby: &Ruby,
-    stream_value: Value,
-    status_code: i64,
-    headers_value: Value,
-) -> Result<NativeBuiltResponse, Error> {
+/// Build a native streaming response from stream, status code, and headers.
+///
+/// Called by `Spikard::StreamingResponse` to construct native response objects.
+/// The stream must be an enumerator that responds to #next.
+fn build_streaming_response(ruby: &Ruby, stream: Value, status_code: i64, headers: Value) -> Result<Value, Error> {
     let status_u16 = u16::try_from(status_code)
         .map_err(|_| Error::new(ruby.exception_arg_error(), "status_code must be between 0 and 65535"))?;
 
-    if !stream_value.respond_to(ruby.intern("next"), false)? && !stream_value.respond_to(ruby.intern("each"), false)? {
-        return Err(Error::new(
-            ruby.exception_arg_error(),
-            "StreamingResponse requires an object responding to #next or #each",
-        ));
+    let header_map = if headers.is_nil() {
+        HashMap::new()
+    } else {
+        let hash = RHash::try_convert(headers)?;
+        hash.to_hash_map::<String, String>()?
+    };
+
+    let next_method = ruby.intern("next");
+    if !stream.respond_to(next_method, false)? {
+        return Err(Error::new(ruby.exception_arg_error(), "stream must respond to #next"));
     }
 
-    let headers = value_to_string_map(ruby, headers_value)?;
-    let enumerator = Arc::new(Opaque::from(stream_value));
-    let payload = StreamingResponsePayload {
-        enumerator: enumerator.clone(),
+    let streaming_payload = StreamingResponsePayload {
+        enumerator: Arc::new(Opaque::from(stream)),
         status: status_u16,
-        headers,
+        headers: header_map,
     };
 
-    let handler_response = payload.into_response()?;
-    Ok(NativeBuiltResponse::new(
-        handler_response,
-        None,
-        vec![(*enumerator).clone()],
-    ))
+    let response = streaming_payload.into_response()?;
+    let native_response = NativeBuiltResponse::new(response, None, vec![Opaque::from(stream)]);
+    Ok(ruby.obj_wrap(native_response).as_value())
 }
 
-fn map_to_ruby_hash(ruby: &Ruby, map: &HashMap<String, String>) -> Result<Value, Error> {
-    let hash = ruby.hash_new();
-    for (key, value) in map {
-        hash.aset(ruby.str_new(key), ruby.str_new(value))?;
-    }
-    Ok(hash.as_value())
-}
+#[magnus::init]
+pub fn init(ruby: &Ruby) -> Result<(), Error> {
+    let spikard = ruby.define_module("Spikard")?;
+    spikard.define_singleton_method("version", function!(version, 0))?;
+    let native = match spikard.const_get("Native") {
+        Ok(module) => module,
+        Err(_) => spikard.define_module("Native")?,
+    };
 
-fn multimap_to_ruby_hash(ruby: &Ruby, map: &HashMap<String, Vec<String>>) -> Result<Value, Error> {
-    let hash = ruby.hash_new();
-    for (key, values) in map {
-        let array = ruby.ary_new();
-        for value in values {
-            array.push(ruby.str_new(value))?;
-        }
-        hash.aset(ruby.str_new(key), array)?;
-    }
-    Ok(hash.as_value())
-}
+    native.define_singleton_method("run_server", function!(run_server, 7))?;
+    native.define_singleton_method("normalize_route_metadata", function!(normalize_route_metadata, 1))?;
+    native.define_singleton_method("background_run", function!(background::background_run, 1))?;
+    native.define_singleton_method("build_route_metadata", function!(build_route_metadata, 12))?;
+    native.define_singleton_method("build_response", function!(build_response, 3))?;
+    native.define_singleton_method("build_streaming_response", function!(build_streaming_response, 3))?;
 
-fn problem_to_json(problem: &ProblemDetails) -> String {
-    problem
-        .to_json_pretty()
-        .unwrap_or_else(|err| format!("Failed to serialise problem details: {err}"))
-}
+    let class = native.define_class("TestClient", ruby.class_object())?;
+    class.define_alloc_func::<NativeTestClient>();
+    class.define_method("initialize", method!(NativeTestClient::initialize, 6))?;
+    class.define_method("request", method!(NativeTestClient::request, 3))?;
+    class.define_method("websocket", method!(NativeTestClient::websocket, 1))?;
+    class.define_method("sse", method!(NativeTestClient::sse, 1))?;
+    class.define_method("close", method!(NativeTestClient::close, 0))?;
 
-fn normalize_path_for_route(path: &str) -> String {
-    let has_trailing_slash = path.ends_with('/');
-    let segments = path.split('/').map(|segment| {
-        if let Some(stripped) = segment.strip_prefix(':') {
-            format!("{{{}}}", stripped)
-        } else {
-            segment.to_string()
-        }
-    });
+    let built_response_class = native.define_class("BuiltResponse", ruby.class_object())?;
+    built_response_class.define_method("status_code", method!(NativeBuiltResponse::status_code, 0))?;
+    built_response_class.define_method("headers", method!(NativeBuiltResponse::headers, 0))?;
 
-    let normalized = segments.collect::<Vec<_>>().join("/");
-    if has_trailing_slash && !normalized.ends_with('/') {
-        format!("{normalized}/")
-    } else {
-        normalized
-    }
-}
+    let request_class = native.define_class("Request", ruby.class_object())?;
+    request_class.define_method("method", method!(NativeRequest::method, 0))?;
+    request_class.define_method("path", method!(NativeRequest::path, 0))?;
+    request_class.define_method("path_params", method!(NativeRequest::path_params, 0))?;
+    request_class.define_method("query", method!(NativeRequest::query, 0))?;
+    request_class.define_method("raw_query", method!(NativeRequest::raw_query, 0))?;
+    request_class.define_method("headers", method!(NativeRequest::headers, 0))?;
+    request_class.define_method("cookies", method!(NativeRequest::cookies, 0))?;
+    request_class.define_method("body", method!(NativeRequest::body, 0))?;
+    request_class.define_method("raw_body", method!(NativeRequest::raw_body, 0))?;
+    request_class.define_method("params", method!(NativeRequest::params, 0))?;
+    request_class.define_method("to_h", method!(NativeRequest::to_h, 0))?;
+    request_class.define_method("[]", method!(NativeRequest::index, 1))?;
 
-fn default_handler_name(method: &str, path: &str) -> String {
-    let normalized_path: String = path
-        .chars()
-        .map(|ch| if ch.is_ascii_alphanumeric() { ch } else { '_' })
-        .collect();
-    let trimmed = normalized_path.trim_matches('_');
-    let final_segment = if trimmed.is_empty() { "root" } else { trimmed };
-    format!("{}_{}", method.to_ascii_lowercase(), final_segment)
-}
+    let lifecycle_registry_class = native.define_class("LifecycleRegistry", ruby.class_object())?;
+    lifecycle_registry_class.define_alloc_func::<NativeLifecycleRegistry>();
+    lifecycle_registry_class.define_method("add_on_request", method!(NativeLifecycleRegistry::add_on_request, 1))?;
+    lifecycle_registry_class.define_method(
+        "pre_validation",
+        method!(NativeLifecycleRegistry::add_pre_validation, 1),
+    )?;
+    lifecycle_registry_class.define_method("pre_handler", method!(NativeLifecycleRegistry::add_pre_handler, 1))?;
+    lifecycle_registry_class.define_method("on_response", method!(NativeLifecycleRegistry::add_on_response, 1))?;
+    lifecycle_registry_class.define_method("on_error", method!(NativeLifecycleRegistry::add_on_error, 1))?;
 
-fn extract_handler_dependencies_from_ruby(_ruby: &Ruby, handler_value: Value) -> Result<Vec<String>, Error> {
-    if handler_value.is_nil() {
-        return Ok(Vec::new());
-    }
-
-    let params_value: Value = handler_value.funcall("parameters", ())?;
-    let params = RArray::try_convert(params_value)?;
-
-    let mut dependencies = Vec::new();
-    for i in 0..params.len() {
-        let entry: Value = params.entry(i as isize)?;
-        if let Some(pair) = RArray::from_value(entry) {
-            if pair.len() < 2 {
-                continue;
-            }
-
-            let kind_val: Value = pair.entry(0)?;
-            let name_val: Value = pair.entry(1)?;
-
-            let kind_symbol: magnus::Symbol = magnus::Symbol::try_convert(kind_val)?;
-            let kind_name = kind_symbol.name().unwrap_or_default();
+    let dependency_registry_class = native.define_class("DependencyRegistry", ruby.class_object())?;
+    dependency_registry_class.define_alloc_func::<NativeDependencyRegistry>();
+    dependency_registry_class.define_method("register_value", method!(NativeDependencyRegistry::register_value, 2))?;
+    dependency_registry_class.define_method(
+        "register_factory",
+        method!(NativeDependencyRegistry::register_factory, 5),
+    )?;
+    dependency_registry_class.define_method("keys", method!(NativeDependencyRegistry::keys, 0))?;
 
-            if kind_name == "key" || kind_name == "keyreq" {
-                dependencies.push(String::try_convert(name_val)?);
-            }
-        }
-    }
+    let spikard_module = ruby.define_module("Spikard")?;
+    testing::websocket::init(ruby, &spikard_module)?;
+    testing::sse::init(ruby, &spikard_module)?;
 
-    Ok(dependencies)
-}
+    let _ = NativeBuiltResponse::mark as fn(&NativeBuiltResponse, &Marker);
+    let _ = NativeLifecycleRegistry::mark as fn(&NativeLifecycleRegistry, &Marker);
+    let _ = NativeDependencyRegistry::mark as fn(&NativeDependencyRegistry, &Marker);
+    let _ = NativeRequest::mark as fn(&NativeRequest, &Marker);
+    let _ = RubyHandler::mark as fn(&RubyHandler, &Marker);
+    let _ = mark as fn(&NativeTestClient, &Marker);
 
-fn option_json_to_ruby(ruby: &Ruby, value: &Option<JsonValue>) -> Result<Value, Error> {
-    if let Some(json) = value {
-        json_to_ruby(ruby, json)
-    } else {
-        Ok(ruby.qnil().as_value())
-    }
+    Ok(())
 }
 
-fn cors_to_ruby(ruby: &Ruby, cors: &Option<spikard_http::CorsConfig>) -> Result<Value, Error> {
-    if let Some(cors_config) = cors {
-        let hash = ruby.hash_new();
-        let origins = cors_config
-            .allowed_origins
-            .iter()
-            .map(|s| JsonValue::String(s.clone()))
-            .collect();
-        hash.aset(
-            ruby.to_symbol("allowed_origins"),
-            json_to_ruby(ruby, &JsonValue::Array(origins))?,
-        )?;
-        let methods = cors_config
-            .allowed_methods
-            .iter()
-            .map(|s| JsonValue::String(s.clone()))
-            .collect();
-        hash.aset(
-            ruby.to_symbol("allowed_methods"),
-            json_to_ruby(ruby, &JsonValue::Array(methods))?,
-        )?;
-
-        if !cors_config.allowed_headers.is_empty() {
-            let headers = cors_config
-                .allowed_headers
-                .iter()
-                .map(|s| JsonValue::String(s.clone()))
-                .collect();
-            hash.aset(
-                ruby.to_symbol("allowed_headers"),
-                json_to_ruby(ruby, &JsonValue::Array(headers))?,
-            )?;
-        }
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
 
-        if let Some(expose_headers) = &cors_config.expose_headers {
-            let exposed = expose_headers.iter().map(|s| JsonValue::String(s.clone())).collect();
-            hash.aset(
-                ruby.to_symbol("expose_headers"),
-                json_to_ruby(ruby, &JsonValue::Array(exposed))?,
-            )?;
-        }
+    /// Test that NativeBuiltResponse can extract parts safely
+    #[test]
+    fn test_native_built_response_status_extraction() {
+        use axum::http::StatusCode;
 
-        if let Some(max_age) = cors_config.max_age {
-            hash.aset(ruby.to_symbol("max_age"), ruby.integer_from_i64(max_age as i64))?;
+        let valid_codes = vec![200u16, 201, 204, 301, 400, 404, 500, 503];
+        for code in valid_codes {
+            let status = StatusCode::from_u16(code);
+            assert!(status.is_ok(), "Status code {} should be valid", code);
         }
+    }
 
-        if let Some(allow_credentials) = cors_config.allow_credentials {
-            let bool_value: Value = if allow_credentials {
-                ruby.qtrue().as_value()
-            } else {
-                ruby.qfalse().as_value()
-            };
-            hash.aset(ruby.to_symbol("allow_credentials"), bool_value)?;
-        }
+    /// Test that invalid status codes are rejected
+    #[test]
+    fn test_native_built_response_invalid_status() {
+        use axum::http::StatusCode;
 
-        Ok(hash.as_value())
-    } else {
-        Ok(ruby.qnil().as_value())
+        assert!(StatusCode::from_u16(599).is_ok(), "599 should be valid");
     }
-}
 
-fn route_metadata_to_ruby(ruby: &Ruby, metadata: &RouteMetadata) -> Result<Value, Error> {
-    let hash = ruby.hash_new();
+    /// Test HeaderName/HeaderValue construction
+    #[test]
+    fn test_header_construction() {
+        use axum::http::{HeaderName, HeaderValue};
 
-    hash.aset(ruby.to_symbol("method"), ruby.str_new(&metadata.method))?;
-    hash.aset(ruby.to_symbol("path"), ruby.str_new(&metadata.path))?;
-    hash.aset(ruby.to_symbol("handler_name"), ruby.str_new(&metadata.handler_name))?;
-    let is_async_val: Value = if metadata.is_async {
-        ruby.qtrue().as_value()
-    } else {
-        ruby.qfalse().as_value()
-    };
-    hash.aset(ruby.to_symbol("is_async"), is_async_val)?;
+        let valid_headers = vec![
+            ("X-Custom-Header", "value"),
+            ("Content-Type", "application/json"),
+            ("Cache-Control", "no-cache"),
+            ("Accept", "*/*"),
+        ];
 
-    hash.aset(
-        ruby.to_symbol("request_schema"),
-        option_json_to_ruby(ruby, &metadata.request_schema)?,
-    )?;
-    hash.aset(
-        ruby.to_symbol("response_schema"),
-        option_json_to_ruby(ruby, &metadata.response_schema)?,
-    )?;
-    hash.aset(
-        ruby.to_symbol("parameter_schema"),
-        option_json_to_ruby(ruby, &metadata.parameter_schema)?,
-    )?;
-    hash.aset(
-        ruby.to_symbol("file_params"),
-        option_json_to_ruby(ruby, &metadata.file_params)?,
-    )?;
-    hash.aset(
-        ruby.to_symbol("body_param_name"),
-        metadata
-            .body_param_name
-            .as_ref()
-            .map(|s| ruby.str_new(s).as_value())
-            .unwrap_or_else(|| ruby.qnil().as_value()),
-    )?;
-
-    hash.aset(ruby.to_symbol("cors"), cors_to_ruby(ruby, &metadata.cors)?)?;
+        for (name, value) in valid_headers {
+            let header_name = HeaderName::from_bytes(name.as_bytes());
+            let header_value = HeaderValue::from_str(value);
 
-    #[cfg(feature = "di")]
-    {
-        if let Some(deps) = &metadata.handler_dependencies {
-            let array = ruby.ary_new();
-            for dep in deps {
-                array.push(ruby.str_new(dep))?;
-            }
-            hash.aset(ruby.to_symbol("handler_dependencies"), array)?;
-        } else {
-            hash.aset(ruby.to_symbol("handler_dependencies"), ruby.qnil())?;
+            assert!(header_name.is_ok(), "Header name '{}' should be valid", name);
+            assert!(header_value.is_ok(), "Header value '{}' should be valid", value);
         }
     }
 
-    Ok(hash.as_value())
-}
-
-fn parse_cors_config(ruby: &Ruby, value: Value) -> Result<Option<spikard_http::CorsConfig>, Error> {
-    if value.is_nil() {
-        return Ok(None);
-    }
-
-    let hash = RHash::try_convert(value)?;
+    /// Test invalid headers are rejected
+    #[test]
+    fn test_invalid_header_construction() {
+        use axum::http::{HeaderName, HeaderValue};
 
-    let allowed_origins = hash
-        .get(ruby.to_symbol("allowed_origins"))
-        .and_then(|v| Vec::<String>::try_convert(v).ok())
-        .unwrap_or_default();
-    let allowed_methods = hash
-        .get(ruby.to_symbol("allowed_methods"))
-        .and_then(|v| Vec::<String>::try_convert(v).ok())
-        .unwrap_or_default();
-    let allowed_headers = hash
-        .get(ruby.to_symbol("allowed_headers"))
-        .and_then(|v| Vec::<String>::try_convert(v).ok())
-        .unwrap_or_default();
-    let expose_headers = hash
-        .get(ruby.to_symbol("expose_headers"))
-        .and_then(|v| Vec::<String>::try_convert(v).ok());
-    let max_age = hash
-        .get(ruby.to_symbol("max_age"))
-        .and_then(|v| i64::try_convert(v).ok())
-        .map(|v| v as u32);
-    let allow_credentials = hash
-        .get(ruby.to_symbol("allow_credentials"))
-        .and_then(|v| bool::try_convert(v).ok());
-
-    Ok(Some(spikard_http::CorsConfig {
-        allowed_origins,
-        allowed_methods,
-        allowed_headers,
-        expose_headers,
-        max_age,
-        allow_credentials,
-    }))
-}
-
-#[allow(clippy::too_many_arguments)]
-fn build_route_metadata(
-    ruby: &Ruby,
-    method: String,
-    path: String,
-    handler_name: Option<String>,
-    request_schema_value: Value,
-    response_schema_value: Value,
-    parameter_schema_value: Value,
-    file_params_value: Value,
-    is_async: bool,
-    cors_value: Value,
-    body_param_name: Option<String>,
-    handler_value: Value,
-) -> Result<Value, Error> {
-    let normalized_path = normalize_path_for_route(&path);
-    let final_handler_name = handler_name.unwrap_or_else(|| default_handler_name(&method, &normalized_path));
-
-    let json_module = ruby
-        .class_object()
-        .const_get("JSON")
-        .map_err(|_| Error::new(ruby.exception_runtime_error(), "JSON module not available"))?;
-
-    let request_schema = if request_schema_value.is_nil() {
-        None
-    } else {
-        Some(ruby_value_to_json(ruby, json_module, request_schema_value)?)
-    };
-    let response_schema = if response_schema_value.is_nil() {
-        None
-    } else {
-        Some(ruby_value_to_json(ruby, json_module, response_schema_value)?)
-    };
-    let parameter_schema = if parameter_schema_value.is_nil() {
-        None
-    } else {
-        Some(ruby_value_to_json(ruby, json_module, parameter_schema_value)?)
-    };
-    let file_params = if file_params_value.is_nil() {
-        None
-    } else {
-        Some(ruby_value_to_json(ruby, json_module, file_params_value)?)
-    };
-
-    let cors = parse_cors_config(ruby, cors_value)?;
-    let handler_dependencies = extract_handler_dependencies_from_ruby(ruby, handler_value)?;
-
-    #[cfg(feature = "di")]
-    let handler_deps_option = if handler_dependencies.is_empty() {
-        None
-    } else {
-        Some(handler_dependencies.clone())
-    };
-
-    let mut metadata = RouteMetadata {
-        method,
-        path: normalized_path,
-        handler_name: final_handler_name,
-        request_schema,
-        response_schema,
-        parameter_schema,
-        file_params,
-        is_async,
-        cors,
-        body_param_name,
-        #[cfg(feature = "di")]
-        handler_dependencies: handler_deps_option,
-    };
-
-    // Validate schemas and parameter validator during build to fail fast
-    let registry = spikard_http::SchemaRegistry::new();
-    let route = Route::from_metadata(metadata.clone(), &registry).map_err(|err| {
-        Error::new(
-            ruby.exception_runtime_error(),
-            format!("Failed to build route metadata: {err}"),
-        )
-    })?;
+        let invalid_name = "X\nInvalid";
+        assert!(
+            HeaderName::from_bytes(invalid_name.as_bytes()).is_err(),
+            "Header with newline should be invalid"
+        );
 
-    if let Some(validator) = route.parameter_validator.as_ref() {
-        metadata.parameter_schema = Some(validator.schema().clone());
+        let invalid_value = "value\x00invalid";
+        assert!(
+            HeaderValue::from_str(invalid_value).is_err(),
+            "Header with null byte should be invalid"
+        );
     }
 
-    route_metadata_to_ruby(ruby, &metadata)
-}
+    /// Test JSON serialization for responses
+    #[test]
+    fn test_json_response_serialization() {
+        let json_obj = json!({
+            "status": "success",
+            "data": [1, 2, 3],
+            "nested": {
+                "key": "value"
+            }
+        });
 
-fn get_kw(ruby: &Ruby, hash: RHash, name: &str) -> Option<Value> {
-    let sym = ruby.intern(name);
-    hash.get(sym).or_else(|| hash.get(name))
-}
+        let serialized = serde_json::to_vec(&json_obj);
+        assert!(serialized.is_ok(), "JSON should serialize");
 
-fn fetch_handler(ruby: &Ruby, handlers: &RHash, name: &str) -> Result<Value, Error> {
-    let symbol_key = ruby.intern(name);
-    if let Some(value) = handlers.get(symbol_key) {
-        return Ok(value);
+        let bytes = serialized.expect("JSON should serialize");
+        assert!(!bytes.is_empty(), "Serialized JSON should not be empty");
     }
 
-    let string_key = ruby.str_new(name);
-    if let Some(value) = handlers.get(string_key) {
-        return Ok(value);
+    /// Test global runtime initialization
+    #[test]
+    fn test_global_runtime_initialization() {
+        assert!(crate::server::global_runtime_raw().is_ok());
     }
 
-    Err(Error::new(
-        ruby.exception_name_error(),
-        format!("Handler '{name}' not provided"),
-    ))
-}
+    /// Test path normalization logic for routes
+    #[test]
+    fn test_route_path_patterns() {
+        let paths = vec![
+            "/users",
+            "/users/:id",
+            "/users/:id/posts/:post_id",
+            "/api/v1/resource",
+            "/api-v2/users_list",
+            "/resource.json",
+        ];
 
-/// GC mark hook so Ruby keeps handler closures alive.
-#[allow(dead_code)]
-fn mark(client: &NativeTestClient, marker: &Marker) {
-    let inner_ref = client.inner.borrow();
-    if let Some(inner) = inner_ref.as_ref() {
-        for handler in &inner.handlers {
-            handler.mark(marker);
+        for path in paths {
+            assert!(!path.is_empty());
+            assert!(path.starts_with('/'));
         }
     }
-}
-
-/// Return the Spikard version.
-fn version() -> String {
-    env!("CARGO_PKG_VERSION").to_string()
-}
-
-/// Build dependency container from Ruby dependencies
-///
-/// Converts Ruby dependencies (values and factories) to Rust DependencyContainer
-#[cfg(feature = "di")]
-fn build_dependency_container(
-    ruby: &Ruby,
-    dependencies: Value,
-) -> Result<spikard_core::di::DependencyContainer, Error> {
-    use spikard_core::di::DependencyContainer;
-    use std::sync::Arc;
-
-    if dependencies.is_nil() {
-        return Ok(DependencyContainer::new());
-    }
-
-    let mut container = DependencyContainer::new();
-    let deps_hash = RHash::try_convert(dependencies)?;
-
-    deps_hash.foreach(|key: String, value: Value| -> Result<ForEach, Error> {
-        // Check if this is a factory (has a 'type' field set to :factory)
-        if let Ok(dep_hash) = RHash::try_convert(value) {
-            let dep_type: Option<String> = get_kw(ruby, dep_hash, "type").and_then(|v| {
-                // Handle both symbol and string types
-                if let Ok(sym) = magnus::Symbol::try_convert(v) {
-                    Some(sym.name().ok()?.to_string())
-                } else {
-                    String::try_convert(v).ok()
-                }
-            });
 
-            match dep_type.as_deref() {
-                Some("factory") => {
-                    // Factory dependency
-                    let factory = get_kw(ruby, dep_hash, "factory")
-                        .ok_or_else(|| Error::new(ruby.exception_runtime_error(), "Factory missing 'factory' key"))?;
+    /// Test HTTP method name validation
+    #[test]
+    fn test_http_method_names() {
+        let methods = vec!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 
-                    let depends_on: Vec<String> = get_kw(ruby, dep_hash, "depends_on")
-                        .and_then(|v| Vec::<String>::try_convert(v).ok())
-                        .unwrap_or_default();
-
-                    let singleton: bool = get_kw(ruby, dep_hash, "singleton")
-                        .and_then(|v| bool::try_convert(v).ok())
-                        .unwrap_or(false);
-
-                    let cacheable: bool = get_kw(ruby, dep_hash, "cacheable")
-                        .and_then(|v| bool::try_convert(v).ok())
-                        .unwrap_or(true);
-
-                    let factory_dep =
-                        crate::di::RubyFactoryDependency::new(key.clone(), factory, depends_on, singleton, cacheable);
-
-                    container.register(key.clone(), Arc::new(factory_dep)).map_err(|e| {
-                        Error::new(
-                            ruby.exception_runtime_error(),
-                            format!("Failed to register factory '{}': {}", key, e),
-                        )
-                    })?;
-                }
-                Some("value") => {
-                    // Value dependency
-                    let value_data = get_kw(ruby, dep_hash, "value").ok_or_else(|| {
-                        Error::new(ruby.exception_runtime_error(), "Value dependency missing 'value' key")
-                    })?;
-
-                    let value_dep = crate::di::RubyValueDependency::new(key.clone(), value_data);
-
-                    container.register(key.clone(), Arc::new(value_dep)).map_err(|e| {
-                        Error::new(
-                            ruby.exception_runtime_error(),
-                            format!("Failed to register value '{}': {}", key, e),
-                        )
-                    })?;
-                }
-                _ => {
-                    return Err(Error::new(
-                        ruby.exception_runtime_error(),
-                        format!("Invalid dependency type for '{}'", key),
-                    ));
-                }
-            }
-        } else {
-            // Treat as raw value
-            let value_dep = crate::di::RubyValueDependency::new(key.clone(), value);
-            container.register(key.clone(), Arc::new(value_dep)).map_err(|e| {
-                Error::new(
-                    ruby.exception_runtime_error(),
-                    format!("Failed to register value '{}': {}", key, e),
-                )
-            })?;
+        for method in methods {
+            assert!(!method.is_empty());
+            assert!(method.chars().all(|c| c.is_uppercase()));
         }
-
-        Ok(ForEach::Continue)
-    })?;
-
-    Ok(container)
-}
-
-/// Helper to extract an optional string from a Ruby Hash
-fn get_optional_string_from_hash(hash: RHash, key: &str) -> Result<Option<String>, Error> {
-    match hash.get(String::from(key)) {
-        Some(v) if !v.is_nil() => Ok(Some(String::try_convert(v)?)),
-        _ => Ok(None),
-    }
-}
-
-/// Helper to extract a required string from a Ruby Hash
-fn get_required_string_from_hash(hash: RHash, key: &str, ruby: &Ruby) -> Result<String, Error> {
-    let value = hash
-        .get(String::from(key))
-        .ok_or_else(|| Error::new(ruby.exception_arg_error(), format!("missing required key '{}'", key)))?;
-    if value.is_nil() {
-        return Err(Error::new(
-            ruby.exception_arg_error(),
-            format!("key '{}' cannot be nil", key),
-        ));
     }
-    String::try_convert(value)
-}
-
-fn extract_files(ruby: &Ruby, files_value: Value) -> Result<Vec<MultipartFilePart>, Error> {
-    let files_hash = RHash::try_convert(files_value)?;
-
-    let keys_array: RArray = files_hash.funcall("keys", ())?;
-    let mut result = Vec::new();
-
-    for i in 0..keys_array.len() {
-        let key_val = keys_array.entry::<Value>(i as isize)?;
-        let field_name = String::try_convert(key_val)?;
-        let value = files_hash
-            .get(key_val)
-            .ok_or_else(|| Error::new(ruby.exception_runtime_error(), "Failed to get hash value"))?;
-
-        if let Some(outer_array) = RArray::from_value(value) {
-            if outer_array.is_empty() {
-                continue;
-            }
 
-            let first_elem = outer_array.entry::<Value>(0)?;
-
-            if RArray::from_value(first_elem).is_some() {
-                for j in 0..outer_array.len() {
-                    let file_array = outer_array.entry::<Value>(j as isize)?;
-                    let file_data = extract_single_file(ruby, &field_name, file_array)?;
-                    result.push(file_data);
-                }
-            } else {
-                let file_data = extract_single_file(ruby, &field_name, value)?;
-                result.push(file_data);
-            }
+    /// Test handler name generation
+    #[test]
+    fn test_handler_name_patterns() {
+        let handler_names = vec![
+            "list_users",
+            "get_user",
+            "create_user",
+            "update_user",
+            "delete_user",
+            "get_user_posts",
+        ];
+
+        for name in handler_names {
+            assert!(!name.is_empty());
+            assert!(name.chars().all(|c| c.is_alphanumeric() || c == '_'));
         }
     }
 
-    Ok(result)
-}
-
-/// Extract a single file from Ruby array [filename, content, content_type (optional)]
-fn extract_single_file(ruby: &Ruby, field_name: &str, array_value: Value) -> Result<MultipartFilePart, Error> {
-    let array = RArray::from_value(array_value)
-        .ok_or_else(|| Error::new(ruby.exception_arg_error(), "file must be an Array [filename, content]"))?;
-
-    if array.len() < 2 {
-        return Err(Error::new(
-            ruby.exception_arg_error(),
-            "file Array must have at least 2 elements: [filename, content]",
-        ));
-    }
-
-    let filename: String = String::try_convert(array.shift()?)?;
-    let content_str: String = String::try_convert(array.shift()?)?;
-    let content = content_str.into_bytes();
-
-    let content_type: Option<String> = if !array.is_empty() {
-        String::try_convert(array.shift()?).ok()
-    } else {
-        None
-    };
-
-    Ok(MultipartFilePart {
-        field_name: field_name.to_string(),
-        filename,
-        content,
-        content_type,
-    })
-}
-
-/// Extract ServerConfig from Ruby ServerConfig object
-fn extract_server_config(ruby: &Ruby, config_value: Value) -> Result<spikard_http::ServerConfig, Error> {
-    use spikard_http::{
-        ApiKeyConfig, CompressionConfig, ContactInfo, JwtConfig, LicenseInfo, OpenApiConfig, RateLimitConfig,
-        ServerInfo, StaticFilesConfig,
-    };
-    use std::collections::HashMap;
-
-    let host: String = config_value.funcall("host", ())?;
-
-    let port: u32 = config_value.funcall("port", ())?;
-
-    let workers: usize = config_value.funcall("workers", ())?;
-
-    let enable_request_id: bool = config_value.funcall("enable_request_id", ())?;
-
-    let max_body_size_value: Value = config_value.funcall("max_body_size", ())?;
-    let max_body_size = if max_body_size_value.is_nil() {
-        None
-    } else {
-        Some(u64::try_convert(max_body_size_value)? as usize)
-    };
-
-    let request_timeout_value: Value = config_value.funcall("request_timeout", ())?;
-    let request_timeout = if request_timeout_value.is_nil() {
-        None
-    } else {
-        Some(u64::try_convert(request_timeout_value)?)
-    };
-
-    let graceful_shutdown: bool = config_value.funcall("graceful_shutdown", ())?;
-
-    let shutdown_timeout: u64 = config_value.funcall("shutdown_timeout", ())?;
-
-    let compression_value: Value = config_value.funcall("compression", ())?;
-    let compression = if compression_value.is_nil() {
-        None
-    } else {
-        let gzip: bool = compression_value.funcall("gzip", ())?;
-        let brotli: bool = compression_value.funcall("brotli", ())?;
-        let min_size: usize = compression_value.funcall("min_size", ())?;
-        let quality: u32 = compression_value.funcall("quality", ())?;
-        Some(CompressionConfig {
-            gzip,
-            brotli,
-            min_size,
-            quality,
-        })
-    };
-
-    let rate_limit_value: Value = config_value.funcall("rate_limit", ())?;
-    let rate_limit = if rate_limit_value.is_nil() {
-        None
-    } else {
-        let per_second: u64 = rate_limit_value.funcall("per_second", ())?;
-        let burst: u32 = rate_limit_value.funcall("burst", ())?;
-        let ip_based: bool = rate_limit_value.funcall("ip_based", ())?;
-        Some(RateLimitConfig {
-            per_second,
-            burst,
-            ip_based,
-        })
-    };
-
-    let jwt_auth_value: Value = config_value.funcall("jwt_auth", ())?;
-    let jwt_auth = if jwt_auth_value.is_nil() {
-        None
-    } else {
-        let secret: String = jwt_auth_value.funcall("secret", ())?;
-        let algorithm: String = jwt_auth_value.funcall("algorithm", ())?;
-        let audience_value: Value = jwt_auth_value.funcall("audience", ())?;
-        let audience = if audience_value.is_nil() {
-            None
-        } else {
-            Some(Vec::<String>::try_convert(audience_value)?)
+    /// Test multipart file handling structure
+    #[test]
+    fn test_multipart_file_part_structure() {
+        let file_data = spikard_http::testing::MultipartFilePart {
+            field_name: "file".to_string(),
+            filename: "test.txt".to_string(),
+            content: b"file content".to_vec(),
+            content_type: Some("text/plain".to_string()),
         };
-        let issuer_value: Value = jwt_auth_value.funcall("issuer", ())?;
-        let issuer = if issuer_value.is_nil() {
-            None
-        } else {
-            Some(String::try_convert(issuer_value)?)
-        };
-        let leeway: u64 = jwt_auth_value.funcall("leeway", ())?;
-        Some(JwtConfig {
-            secret,
-            algorithm,
-            audience,
-            issuer,
-            leeway,
-        })
-    };
 
-    let api_key_auth_value: Value = config_value.funcall("api_key_auth", ())?;
-    let api_key_auth = if api_key_auth_value.is_nil() {
-        None
-    } else {
-        let keys: Vec<String> = api_key_auth_value.funcall("keys", ())?;
-        let header_name: String = api_key_auth_value.funcall("header_name", ())?;
-        Some(ApiKeyConfig { keys, header_name })
-    };
-
-    let static_files_value: Value = config_value.funcall("static_files", ())?;
-    let static_files_array = RArray::from_value(static_files_value)
-        .ok_or_else(|| Error::new(ruby.exception_type_error(), "static_files must be an Array"))?;
-
-    let mut static_files = Vec::new();
-    for i in 0..static_files_array.len() {
-        let sf_value = static_files_array.entry::<Value>(i as isize)?;
-        let directory: String = sf_value.funcall("directory", ())?;
-        let route_prefix: String = sf_value.funcall("route_prefix", ())?;
-        let index_file: bool = sf_value.funcall("index_file", ())?;
-        let cache_control_value: Value = sf_value.funcall("cache_control", ())?;
-        let cache_control = if cache_control_value.is_nil() {
-            None
-        } else {
-            Some(String::try_convert(cache_control_value)?)
-        };
-        static_files.push(StaticFilesConfig {
-            directory,
-            route_prefix,
-            index_file,
-            cache_control,
-        });
+        assert_eq!(file_data.field_name, "file");
+        assert_eq!(file_data.filename, "test.txt");
+        assert!(!file_data.content.is_empty());
+        assert_eq!(file_data.content_type, Some("text/plain".to_string()));
     }
 
-    let openapi_value: Value = config_value.funcall("openapi", ())?;
-    let openapi = if openapi_value.is_nil() {
-        None
-    } else {
-        let enabled: bool = openapi_value.funcall("enabled", ())?;
-        let title: String = openapi_value.funcall("title", ())?;
-        let version: String = openapi_value.funcall("version", ())?;
-        let description_value: Value = openapi_value.funcall("description", ())?;
-        let description = if description_value.is_nil() {
-            None
-        } else {
-            Some(String::try_convert(description_value)?)
-        };
-        let swagger_ui_path: String = openapi_value.funcall("swagger_ui_path", ())?;
-        let redoc_path: String = openapi_value.funcall("redoc_path", ())?;
-        let openapi_json_path: String = openapi_value.funcall("openapi_json_path", ())?;
-
-        let contact_value: Value = openapi_value.funcall("contact", ())?;
-        let contact = if contact_value.is_nil() {
-            None
-        } else if let Some(contact_hash) = RHash::from_value(contact_value) {
-            let name = get_optional_string_from_hash(contact_hash, "name")?;
-            let email = get_optional_string_from_hash(contact_hash, "email")?;
-            let url = get_optional_string_from_hash(contact_hash, "url")?;
-            Some(ContactInfo { name, email, url })
-        } else {
-            let name_value: Value = contact_value.funcall("name", ())?;
-            let email_value: Value = contact_value.funcall("email", ())?;
-            let url_value: Value = contact_value.funcall("url", ())?;
-            Some(ContactInfo {
-                name: if name_value.is_nil() {
-                    None
-                } else {
-                    Some(String::try_convert(name_value)?)
-                },
-                email: if email_value.is_nil() {
-                    None
-                } else {
-                    Some(String::try_convert(email_value)?)
-                },
-                url: if url_value.is_nil() {
-                    None
-                } else {
-                    Some(String::try_convert(url_value)?)
-                },
-            })
-        };
-
-        let license_value: Value = openapi_value.funcall("license", ())?;
-        let license = if license_value.is_nil() {
-            None
-        } else if let Some(license_hash) = RHash::from_value(license_value) {
-            let name = get_required_string_from_hash(license_hash, "name", ruby)?;
-            let url = get_optional_string_from_hash(license_hash, "url")?;
-            Some(LicenseInfo { name, url })
-        } else {
-            let name: String = license_value.funcall("name", ())?;
-            let url_value: Value = license_value.funcall("url", ())?;
-            let url = if url_value.is_nil() {
-                None
-            } else {
-                Some(String::try_convert(url_value)?)
-            };
-            Some(LicenseInfo { name, url })
-        };
+    /// Test response header case sensitivity concepts
+    #[test]
+    fn test_response_header_concepts() {
+        use axum::http::HeaderName;
 
-        let servers_value: Value = openapi_value.funcall("servers", ())?;
-        let servers_array = RArray::from_value(servers_value)
-            .ok_or_else(|| Error::new(ruby.exception_type_error(), "servers must be an Array"))?;
+        let names = vec!["content-type", "Content-Type", "CONTENT-TYPE"];
 
-        let mut servers = Vec::new();
-        for i in 0..servers_array.len() {
-            let server_value = servers_array.entry::<Value>(i as isize)?;
-
-            let (url, description) = if let Some(server_hash) = RHash::from_value(server_value) {
-                let url = get_required_string_from_hash(server_hash, "url", ruby)?;
-                let description = get_optional_string_from_hash(server_hash, "description")?;
-                (url, description)
-            } else {
-                let url: String = server_value.funcall("url", ())?;
-                let description_value: Value = server_value.funcall("description", ())?;
-                let description = if description_value.is_nil() {
-                    None
-                } else {
-                    Some(String::try_convert(description_value)?)
-                };
-                (url, description)
-            };
-
-            servers.push(ServerInfo { url, description });
-        }
-
-        let security_schemes = HashMap::new();
-
-        Some(OpenApiConfig {
-            enabled,
-            title,
-            version,
-            description,
-            swagger_ui_path,
-            redoc_path,
-            openapi_json_path,
-            contact,
-            license,
-            servers,
-            security_schemes,
-        })
-    };
-
-    Ok(spikard_http::ServerConfig {
-        host,
-        port: port as u16,
-        workers,
-        enable_request_id,
-        max_body_size,
-        request_timeout,
-        compression,
-        rate_limit,
-        jwt_auth,
-        api_key_auth,
-        static_files,
-        graceful_shutdown,
-        shutdown_timeout,
-        background_tasks: spikard_http::BackgroundTaskConfig::default(),
-        openapi,
-        lifecycle_hooks: None,
-        di_container: None,
-    })
-}
-
-/// Start the Spikard HTTP server from Ruby
-///
-/// Creates an Axum HTTP server in a dedicated background thread with its own Tokio runtime.
-///
-/// # Arguments
-///
-/// * `routes_json` - JSON string containing route metadata
-/// * `handlers` - Ruby Hash mapping handler_name => Proc
-/// * `config` - Ruby ServerConfig object with all middleware settings
-/// * `hooks_value` - Lifecycle hooks
-/// * `ws_handlers` - WebSocket handlers
-/// * `sse_producers` - SSE producers
-/// * `dependencies` - Dependency injection container
-///
-/// # Example (Ruby)
-///
-/// ```ruby
-/// config = Spikard::ServerConfig.new(host: '0.0.0.0', port: 8000)
-/// Spikard::Native.run_server(routes_json, handlers, config, hooks, ws, sse, deps)
-/// ```
-#[allow(clippy::too_many_arguments)]
-fn run_server(
-    ruby: &Ruby,
-    routes_json: String,
-    handlers: Value,
-    config_value: Value,
-    hooks_value: Value,
-    ws_handlers: Value,
-    sse_producers: Value,
-    dependencies: Value,
-) -> Result<(), Error> {
-    use spikard_http::{SchemaRegistry, Server};
-    use tracing::{error, info, warn};
-
-    let mut config = extract_server_config(ruby, config_value)?;
-
-    let host = config.host.clone();
-    let port = config.port;
-
-    let metadata: Vec<RouteMetadata> = serde_json::from_str(&routes_json)
-        .map_err(|err| Error::new(ruby.exception_arg_error(), format!("Invalid routes JSON: {}", err)))?;
-
-    let handlers_hash = RHash::from_value(handlers).ok_or_else(|| {
-        Error::new(
-            ruby.exception_arg_error(),
-            "handlers parameter must be a Hash of handler_name => Proc",
-        )
-    })?;
-
-    let json_module = ruby
-        .class_object()
-        .funcall::<_, _, Value>("const_get", ("JSON",))
-        .map_err(|err| Error::new(ruby.exception_name_error(), format!("JSON module not found: {}", err)))?;
-
-    let schema_registry = SchemaRegistry::new();
-
-    let mut routes_with_handlers: Vec<(Route, Arc<dyn spikard_http::Handler>)> = Vec::new();
-
-    for route_meta in metadata {
-        let route = Route::from_metadata(route_meta.clone(), &schema_registry)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("Failed to create route: {}", e)))?;
-
-        let handler_key = ruby.str_new(&route_meta.handler_name);
-        let handler_value: Value = match handlers_hash.lookup(handler_key) {
-            Ok(val) => val,
-            Err(_) => {
-                return Err(Error::new(
-                    ruby.exception_arg_error(),
-                    format!("Handler '{}' not found in handlers hash", route_meta.handler_name),
-                ));
-            }
-        };
-
-        let ruby_handler = RubyHandler::new_for_server(
-            ruby,
-            handler_value,
-            route_meta.handler_name.clone(),
-            route_meta.method.clone(),
-            route_meta.path.clone(),
-            json_module,
-            &route,
-        )?;
-
-        routes_with_handlers.push((route, Arc::new(ruby_handler) as Arc<dyn spikard_http::Handler>));
-    }
-
-    let lifecycle_hooks = if let Ok(registry) = <&NativeLifecycleRegistry>::try_convert(hooks_value) {
-        Some(registry.take_hooks())
-    } else if !hooks_value.is_nil() {
-        let hooks_hash = RHash::from_value(hooks_value)
-            .ok_or_else(|| Error::new(ruby.exception_arg_error(), "lifecycle_hooks parameter must be a Hash"))?;
-
-        let mut hooks = spikard_http::LifecycleHooks::new();
-        type RubyHookVec = Vec<Arc<dyn spikard_http::lifecycle::LifecycleHook<Request<Body>, Response<Body>>>>;
-
-        let extract_hooks = |key: &str| -> Result<RubyHookVec, Error> {
-            let key_sym = ruby.to_symbol(key);
-            if let Some(hooks_array) = hooks_hash.get(key_sym)
-                && !hooks_array.is_nil()
-            {
-                let array = RArray::from_value(hooks_array)
-                    .ok_or_else(|| Error::new(ruby.exception_type_error(), format!("{} must be an Array", key)))?;
-
-                let mut result = Vec::new();
-                let len = array.len();
-                for i in 0..len {
-                    let hook_value: Value = array.entry(i as isize)?;
-                    let name = format!("{}_{}", key, i);
-                    let ruby_hook = lifecycle::RubyLifecycleHook::new(name, hook_value);
-                    result.push(Arc::new(ruby_hook)
-                        as Arc<
-                            dyn spikard_http::lifecycle::LifecycleHook<Request<Body>, Response<Body>>,
-                        >);
-                }
-                return Ok(result);
-            }
-            Ok(Vec::new())
-        };
-
-        for hook in extract_hooks("on_request")? {
-            hooks.add_on_request(hook);
-        }
-
-        for hook in extract_hooks("pre_validation")? {
-            hooks.add_pre_validation(hook);
-        }
-
-        for hook in extract_hooks("pre_handler")? {
-            hooks.add_pre_handler(hook);
-        }
-
-        for hook in extract_hooks("on_response")? {
-            hooks.add_on_response(hook);
-        }
-
-        for hook in extract_hooks("on_error")? {
-            hooks.add_on_error(hook);
-        }
-
-        Some(hooks)
-    } else {
-        None
-    };
-
-    config.lifecycle_hooks = lifecycle_hooks.map(Arc::new);
-
-    // Extract and register dependencies
-    #[cfg(feature = "di")]
-    {
-        if let Ok(registry) = <&NativeDependencyRegistry>::try_convert(dependencies) {
-            config.di_container = Some(Arc::new(registry.take_container()?));
-        } else if !dependencies.is_nil() {
-            match build_dependency_container(ruby, dependencies) {
-                Ok(container) => {
-                    config.di_container = Some(Arc::new(container));
-                }
-                Err(err) => {
-                    return Err(Error::new(
-                        ruby.exception_runtime_error(),
-                        format!("Failed to build DI container: {}", err),
-                    ));
-                }
-            }
+        for name in names {
+            let parsed = HeaderName::from_bytes(name.as_bytes());
+            assert!(parsed.is_ok(), "Header name should parse: {}", name);
         }
     }
 
-    Server::init_logging();
-
-    info!("Starting Spikard server on {}:{}", host, port);
-    info!("Registered {} routes", routes_with_handlers.len());
-
-    let mut app_router = Server::with_handlers(config.clone(), routes_with_handlers)
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("Failed to build router: {}", e)))?;
-
-    let mut ws_endpoints = Vec::new();
-    if !ws_handlers.is_nil() {
-        let ws_hash = RHash::from_value(ws_handlers)
-            .ok_or_else(|| Error::new(ruby.exception_arg_error(), "WebSocket handlers must be a Hash"))?;
-
-        ws_hash.foreach(|path: String, factory: Value| -> Result<ForEach, Error> {
-            let handler_instance = factory.funcall::<_, _, Value>("call", ()).map_err(|e| {
-                Error::new(
-                    ruby.exception_runtime_error(),
-                    format!("Failed to create WebSocket handler: {}", e),
-                )
-            })?;
-
-            let ws_state = crate::websocket::create_websocket_state(ruby, handler_instance)?;
-
-            ws_endpoints.push((path, ws_state));
-
-            Ok(ForEach::Continue)
-        })?;
-    }
-
-    let mut sse_endpoints = Vec::new();
-    if !sse_producers.is_nil() {
-        let sse_hash = RHash::from_value(sse_producers)
-            .ok_or_else(|| Error::new(ruby.exception_arg_error(), "SSE producers must be a Hash"))?;
-
-        sse_hash.foreach(|path: String, factory: Value| -> Result<ForEach, Error> {
-            let producer_instance = factory.funcall::<_, _, Value>("call", ()).map_err(|e| {
-                Error::new(
-                    ruby.exception_runtime_error(),
-                    format!("Failed to create SSE producer: {}", e),
-                )
-            })?;
-
-            let sse_state = crate::sse::create_sse_state(ruby, producer_instance)?;
-
-            sse_endpoints.push((path, sse_state));
-
-            Ok(ForEach::Continue)
-        })?;
-    }
-
-    use axum::routing::get;
-    for (path, ws_state) in ws_endpoints {
-        info!("Registered WebSocket endpoint: {}", path);
-        app_router = app_router.route(
-            &path,
-            get(spikard_http::websocket_handler::<crate::websocket::RubyWebSocketHandler>).with_state(ws_state),
-        );
-    }
-
-    for (path, sse_state) in sse_endpoints {
-        info!("Registered SSE endpoint: {}", path);
-        app_router = app_router.route(
-            &path,
-            get(spikard_http::sse_handler::<crate::sse::RubySseEventProducer>).with_state(sse_state),
-        );
-    }
-
-    let addr = format!("{}:{}", config.host, config.port);
-    let socket_addr: std::net::SocketAddr = addr.parse().map_err(|e| {
-        Error::new(
-            ruby.exception_arg_error(),
-            format!("Invalid socket address {}: {}", addr, e),
-        )
-    })?;
-
-    let runtime = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()
-        .map_err(|e| {
-            Error::new(
-                ruby.exception_runtime_error(),
-                format!("Failed to create Tokio runtime: {}", e),
-            )
-        })?;
-
-    let background_config = config.background_tasks.clone();
-
-    runtime.block_on(async move {
-        let listener = tokio::net::TcpListener::bind(socket_addr)
-            .await
-            .unwrap_or_else(|_| panic!("Failed to bind to {}", socket_addr));
-
-        info!("Server listening on {}", socket_addr);
-
-        let background_runtime = spikard_http::BackgroundRuntime::start(background_config.clone()).await;
-        crate::background::install_handle(background_runtime.handle());
-
-        let serve_result = axum::serve(listener, app_router).await;
-
-        crate::background::clear_handle();
-
-        if let Err(err) = background_runtime.shutdown().await {
-            warn!("Failed to drain background tasks during shutdown: {:?}", err);
-        }
-
-        if let Err(e) = serve_result {
-            error!("Server error: {}", e);
-        }
-    });
-
-    Ok(())
-}
+    /// Test error payload structure
+    #[test]
+    fn test_error_payload_structure() {
+        let error_json = json!({
+            "error": "Not Found",
+            "code": "404",
+            "details": {}
+        });
 
-/// Validate and normalize route metadata using the Rust RouteMetadata schema.
-///
-/// Parses the provided JSON, compiles schemas/parameter validators to ensure
-/// correctness, and returns a canonical JSON string. This keeps Ruby-sourced
-/// metadata aligned with the Rust core types.
-fn normalize_route_metadata(_ruby: &Ruby, routes_json: String) -> Result<String, Error> {
-    use spikard_http::SchemaRegistry;
-
-    let registry = SchemaRegistry::new();
-    let routes: Vec<RouteMetadata> = serde_json::from_str(&routes_json)
-        .map_err(|err| Error::new(magnus::exception::arg_error(), format!("Invalid routes JSON: {err}")))?;
-
-    for route in &routes {
-        Route::from_metadata(route.clone(), &registry).map_err(|err| {
-            Error::new(
-                magnus::exception::runtime_error(),
-                format!("Invalid route {} {}: {err}", route.method, route.path),
-            )
-        })?;
+        assert_eq!(error_json["error"], "Not Found");
+        assert_eq!(error_json["code"], "404");
+        assert!(error_json["details"].is_object());
     }
-
-    serde_json::to_string(&routes).map_err(|err| {
-        Error::new(
-            magnus::exception::runtime_error(),
-            format!("Failed to serialise routes: {err}"),
-        )
-    })
-}
-
-#[magnus::init]
-pub fn init(ruby: &Ruby) -> Result<(), Error> {
-    let spikard = ruby.define_module("Spikard")?;
-    spikard.define_singleton_method("version", function!(version, 0))?;
-    let native = match spikard.const_get("Native") {
-        Ok(module) => module,
-        Err(_) => spikard.define_module("Native")?,
-    };
-
-    native.define_singleton_method("run_server", function!(run_server, 7))?;
-    native.define_singleton_method("normalize_route_metadata", function!(normalize_route_metadata, 1))?;
-    native.define_singleton_method("background_run", function!(background::background_run, 1))?;
-    native.define_singleton_method("build_route_metadata", function!(build_route_metadata, 11))?;
-    native.define_singleton_method("build_response", function!(build_response, 4))?;
-    native.define_singleton_method("build_streaming_response", function!(build_streaming_response, 3))?;
-
-    let class = native.define_class("TestClient", ruby.class_object())?;
-    class.define_alloc_func::<NativeTestClient>();
-    class.define_method("initialize", method!(NativeTestClient::initialize, 6))?;
-    class.define_method("request", method!(NativeTestClient::request, 3))?;
-    class.define_method("websocket", method!(NativeTestClient::websocket, 1))?;
-    class.define_method("sse", method!(NativeTestClient::sse, 1))?;
-    class.define_method("close", method!(NativeTestClient::close, 0))?;
-
-    let built_response_class = native.define_class("BuiltResponse", ruby.class_object())?;
-    built_response_class.define_alloc_func::<NativeBuiltResponse>();
-    built_response_class.define_method("status_code", method!(NativeBuiltResponse::status_code, 0))?;
-    built_response_class.define_method("headers", method!(NativeBuiltResponse::headers, 0))?;
-
-    let lifecycle_registry_class = native.define_class("LifecycleRegistry", ruby.class_object())?;
-    lifecycle_registry_class.define_alloc_func::<NativeLifecycleRegistry>();
-    lifecycle_registry_class.define_method("add_on_request", method!(NativeLifecycleRegistry::add_on_request, 1))?;
-    lifecycle_registry_class.define_method(
-        "pre_validation",
-        method!(NativeLifecycleRegistry::add_pre_validation, 1),
-    )?;
-    lifecycle_registry_class.define_method("pre_handler", method!(NativeLifecycleRegistry::add_pre_handler, 1))?;
-    lifecycle_registry_class.define_method("on_response", method!(NativeLifecycleRegistry::add_on_response, 1))?;
-    lifecycle_registry_class.define_method("on_error", method!(NativeLifecycleRegistry::add_on_error, 1))?;
-
-    let dependency_registry_class = native.define_class("DependencyRegistry", ruby.class_object())?;
-    dependency_registry_class.define_alloc_func::<NativeDependencyRegistry>();
-    dependency_registry_class.define_method("register_value", method!(NativeDependencyRegistry::register_value, 2))?;
-    dependency_registry_class.define_method(
-        "register_factory",
-        method!(NativeDependencyRegistry::register_factory, 5),
-    )?;
-
-    let spikard_module = ruby.define_module("Spikard")?;
-    test_websocket::init(ruby, &spikard_module)?;
-    test_sse::init(ruby, &spikard_module)?;
-
-    Ok(())
 }