RubyGems - spikard - Versions diffs - 0.3.0 → 0.3.2 - Mend

spikard 0.3.0 → 0.3.2

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 (182) hide show

checksums.yaml +4 -4
data/LICENSE +1 -1
data/README.md +659 -659
data/ext/spikard_rb/Cargo.toml +17 -17
data/ext/spikard_rb/extconf.rb +10 -10
data/ext/spikard_rb/src/lib.rs +6 -6
data/lib/spikard/app.rb +386 -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 +221 -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 +360 -360
data/vendor/crates/spikard-core/Cargo.toml +40 -0
data/vendor/crates/spikard-core/src/bindings/mod.rs +3 -0
data/vendor/crates/spikard-core/src/bindings/response.rs +133 -0
data/vendor/crates/spikard-core/src/debug.rs +63 -0
data/vendor/crates/spikard-core/src/di/container.rs +726 -0
data/vendor/crates/spikard-core/src/di/dependency.rs +273 -0
data/vendor/crates/spikard-core/src/di/error.rs +118 -0
data/vendor/crates/spikard-core/src/di/factory.rs +538 -0
data/vendor/crates/spikard-core/src/di/graph.rs +545 -0
data/vendor/crates/spikard-core/src/di/mod.rs +192 -0
data/vendor/crates/spikard-core/src/di/resolved.rs +411 -0
data/vendor/crates/spikard-core/src/di/value.rs +283 -0
data/vendor/crates/spikard-core/src/errors.rs +39 -0
data/vendor/crates/spikard-core/src/http.rs +153 -0
data/vendor/crates/spikard-core/src/lib.rs +29 -0
data/vendor/crates/spikard-core/src/lifecycle.rs +422 -0
data/vendor/crates/spikard-core/src/parameters.rs +722 -0
data/vendor/crates/spikard-core/src/problem.rs +310 -0
data/vendor/crates/spikard-core/src/request_data.rs +189 -0
data/vendor/crates/spikard-core/src/router.rs +249 -0
data/vendor/crates/spikard-core/src/schema_registry.rs +183 -0
data/vendor/crates/spikard-core/src/type_hints.rs +304 -0
data/vendor/crates/spikard-core/src/validation.rs +699 -0
data/vendor/crates/spikard-http/Cargo.toml +58 -0
data/vendor/crates/spikard-http/src/auth.rs +247 -0
data/vendor/crates/spikard-http/src/background.rs +249 -0
data/vendor/crates/spikard-http/src/bindings/mod.rs +3 -0
data/vendor/crates/spikard-http/src/bindings/response.rs +1 -0
data/vendor/crates/spikard-http/src/body_metadata.rs +8 -0
data/vendor/crates/spikard-http/src/cors.rs +490 -0
data/vendor/crates/spikard-http/src/debug.rs +63 -0
data/vendor/crates/spikard-http/src/di_handler.rs +423 -0
data/vendor/crates/spikard-http/src/handler_response.rs +190 -0
data/vendor/crates/spikard-http/src/handler_trait.rs +228 -0
data/vendor/crates/spikard-http/src/handler_trait_tests.rs +284 -0
data/vendor/crates/spikard-http/src/lib.rs +529 -0
data/vendor/crates/spikard-http/src/lifecycle/adapter.rs +149 -0
data/vendor/crates/spikard-http/src/lifecycle.rs +428 -0
data/vendor/crates/spikard-http/src/middleware/mod.rs +285 -0
data/vendor/crates/spikard-http/src/middleware/multipart.rs +86 -0
data/vendor/crates/spikard-http/src/middleware/urlencoded.rs +147 -0
data/vendor/crates/spikard-http/src/middleware/validation.rs +287 -0
data/vendor/crates/spikard-http/src/openapi/mod.rs +309 -0
data/vendor/crates/spikard-http/src/openapi/parameter_extraction.rs +190 -0
data/vendor/crates/spikard-http/src/openapi/schema_conversion.rs +308 -0
data/vendor/crates/spikard-http/src/openapi/spec_generation.rs +195 -0
data/vendor/crates/spikard-http/src/parameters.rs +1 -0
data/vendor/crates/spikard-http/src/problem.rs +1 -0
data/vendor/crates/spikard-http/src/query_parser.rs +369 -0
data/vendor/crates/spikard-http/src/response.rs +399 -0
data/vendor/crates/spikard-http/src/router.rs +1 -0
data/vendor/crates/spikard-http/src/schema_registry.rs +1 -0
data/vendor/crates/spikard-http/src/server/handler.rs +87 -0
data/vendor/crates/spikard-http/src/server/lifecycle_execution.rs +98 -0
data/vendor/crates/spikard-http/src/server/mod.rs +805 -0
data/vendor/crates/spikard-http/src/server/request_extraction.rs +119 -0
data/vendor/crates/spikard-http/src/sse.rs +447 -0
data/vendor/crates/spikard-http/src/testing/form.rs +14 -0
data/vendor/crates/spikard-http/src/testing/multipart.rs +60 -0
data/vendor/crates/spikard-http/src/testing/test_client.rs +285 -0
data/vendor/crates/spikard-http/src/testing.rs +377 -0
data/vendor/crates/spikard-http/src/type_hints.rs +1 -0
data/vendor/crates/spikard-http/src/validation.rs +1 -0
data/vendor/crates/spikard-http/src/websocket.rs +324 -0
data/vendor/crates/spikard-rb/Cargo.toml +42 -0
data/vendor/crates/spikard-rb/build.rs +8 -0
data/vendor/crates/spikard-rb/src/background.rs +63 -0
data/vendor/crates/spikard-rb/src/config.rs +294 -0
data/vendor/crates/spikard-rb/src/conversion.rs +453 -0
data/vendor/crates/spikard-rb/src/di.rs +409 -0
data/vendor/crates/spikard-rb/src/handler.rs +625 -0
data/vendor/crates/spikard-rb/src/lib.rs +2771 -0
data/vendor/crates/spikard-rb/src/lifecycle.rs +274 -0
data/vendor/crates/spikard-rb/src/server.rs +283 -0
data/vendor/crates/spikard-rb/src/sse.rs +231 -0
data/vendor/crates/spikard-rb/src/test_client.rs +404 -0
data/vendor/crates/spikard-rb/src/test_sse.rs +143 -0
data/vendor/crates/spikard-rb/src/test_websocket.rs +221 -0
data/vendor/crates/spikard-rb/src/websocket.rs +233 -0
data/vendor/spikard-core/Cargo.toml +40 -0
data/vendor/spikard-core/src/bindings/mod.rs +3 -0
data/vendor/spikard-core/src/bindings/response.rs +133 -0
data/vendor/spikard-core/src/debug.rs +63 -0
data/vendor/spikard-core/src/di/container.rs +726 -0
data/vendor/spikard-core/src/di/dependency.rs +273 -0
data/vendor/spikard-core/src/di/error.rs +118 -0
data/vendor/spikard-core/src/di/factory.rs +538 -0
data/vendor/spikard-core/src/di/graph.rs +545 -0
data/vendor/spikard-core/src/di/mod.rs +192 -0
data/vendor/spikard-core/src/di/resolved.rs +411 -0
data/vendor/spikard-core/src/di/value.rs +283 -0
data/vendor/spikard-core/src/http.rs +153 -0
data/vendor/spikard-core/src/lib.rs +28 -0
data/vendor/spikard-core/src/lifecycle.rs +422 -0
data/vendor/spikard-core/src/parameters.rs +719 -0
data/vendor/spikard-core/src/problem.rs +310 -0
data/vendor/spikard-core/src/request_data.rs +189 -0
data/vendor/spikard-core/src/router.rs +249 -0
data/vendor/spikard-core/src/schema_registry.rs +183 -0
data/vendor/spikard-core/src/type_hints.rs +304 -0
data/vendor/spikard-core/src/validation.rs +699 -0
data/vendor/spikard-http/Cargo.toml +58 -0
data/vendor/spikard-http/src/auth.rs +247 -0
data/vendor/spikard-http/src/background.rs +249 -0
data/vendor/spikard-http/src/bindings/mod.rs +3 -0
data/vendor/spikard-http/src/bindings/response.rs +1 -0
data/vendor/spikard-http/src/body_metadata.rs +8 -0
data/vendor/spikard-http/src/cors.rs +490 -0
data/vendor/spikard-http/src/debug.rs +63 -0
data/vendor/spikard-http/src/di_handler.rs +423 -0
data/vendor/spikard-http/src/handler_response.rs +190 -0
data/vendor/spikard-http/src/handler_trait.rs +228 -0
data/vendor/spikard-http/src/handler_trait_tests.rs +284 -0
data/vendor/spikard-http/src/lib.rs +529 -0
data/vendor/spikard-http/src/lifecycle/adapter.rs +149 -0
data/vendor/spikard-http/src/lifecycle.rs +428 -0
data/vendor/spikard-http/src/middleware/mod.rs +285 -0
data/vendor/spikard-http/src/middleware/multipart.rs +86 -0
data/vendor/spikard-http/src/middleware/urlencoded.rs +147 -0
data/vendor/spikard-http/src/middleware/validation.rs +287 -0
data/vendor/spikard-http/src/openapi/mod.rs +309 -0
data/vendor/spikard-http/src/openapi/parameter_extraction.rs +190 -0
data/vendor/spikard-http/src/openapi/schema_conversion.rs +308 -0
data/vendor/spikard-http/src/openapi/spec_generation.rs +195 -0
data/vendor/spikard-http/src/parameters.rs +1 -0
data/vendor/spikard-http/src/problem.rs +1 -0
data/vendor/spikard-http/src/query_parser.rs +369 -0
data/vendor/spikard-http/src/response.rs +399 -0
data/vendor/spikard-http/src/router.rs +1 -0
data/vendor/spikard-http/src/schema_registry.rs +1 -0
data/vendor/spikard-http/src/server/handler.rs +80 -0
data/vendor/spikard-http/src/server/lifecycle_execution.rs +98 -0
data/vendor/spikard-http/src/server/mod.rs +805 -0
data/vendor/spikard-http/src/server/request_extraction.rs +119 -0
data/vendor/spikard-http/src/sse.rs +447 -0
data/vendor/spikard-http/src/testing/form.rs +14 -0
data/vendor/spikard-http/src/testing/multipart.rs +60 -0
data/vendor/spikard-http/src/testing/test_client.rs +285 -0
data/vendor/spikard-http/src/testing.rs +377 -0
data/vendor/spikard-http/src/type_hints.rs +1 -0
data/vendor/spikard-http/src/validation.rs +1 -0
data/vendor/spikard-http/src/websocket.rs +324 -0
data/vendor/spikard-rb/Cargo.toml +42 -0
data/vendor/spikard-rb/build.rs +8 -0
data/vendor/spikard-rb/src/background.rs +63 -0
data/vendor/spikard-rb/src/config.rs +294 -0
data/vendor/spikard-rb/src/conversion.rs +392 -0
data/vendor/spikard-rb/src/di.rs +409 -0
data/vendor/spikard-rb/src/handler.rs +534 -0
data/vendor/spikard-rb/src/lib.rs +2020 -0
data/vendor/spikard-rb/src/lifecycle.rs +267 -0
data/vendor/spikard-rb/src/server.rs +283 -0
data/vendor/spikard-rb/src/sse.rs +231 -0
data/vendor/spikard-rb/src/test_client.rs +404 -0
data/vendor/spikard-rb/src/test_sse.rs +143 -0
data/vendor/spikard-rb/src/test_websocket.rs +221 -0
data/vendor/spikard-rb/src/websocket.rs +233 -0
metadata +162 -8
/data/vendor/bundle/ruby/{3.3.0 → 3.4.0}/gems/diff-lcs-1.6.2/mise.toml +0 -0
/data/vendor/bundle/ruby/{3.3.0 → 3.4.0}/gems/rake-compiler-dock-1.10.0/build/buildkitd.toml +0 -0

data/vendor/crates/spikard-rb/src/lifecycle.rs ADDED Viewed

@@ -0,0 +1,274 @@
+//! Ruby lifecycle hooks implementation
+//!
+//! This module provides the bridge between Ruby blocks/procs and Rust's lifecycle hook system.
+//! Uses magnus to safely call Ruby code from Rust async tasks.
+use axum::{
+    body::Body,
+    http::{Request, Response, StatusCode},
+};
+use magnus::{RHash, Value, gc::Marker, prelude::*, value::InnerValue, value::Opaque};
+use serde_json::Value as JsonValue;
+use spikard_http::lifecycle::{HookResult, LifecycleHook};
+use std::future::Future;
+use std::pin::Pin;
+/// Ruby lifecycle hook wrapper
+///
+/// Wraps a Ruby proc/block and makes it callable from Rust's lifecycle system.
+/// Handles conversion between Rust HTTP types and Ruby request/response objects.
+pub struct RubyLifecycleHook {
+    name: String,
+    /// Ruby proc/callable object (Opaque for Send safety)
+    func: Opaque<Value>,
+}
+impl RubyLifecycleHook {
+    /// Create a new Ruby lifecycle hook
+    pub fn new(name: String, func: Value) -> Self {
+        Self {
+            name,
+            func: func.into(),
+        }
+    }
+    /// Mark Ruby values for GC
+    pub fn mark(&self, marker: &Marker) {
+        if let Ok(ruby) = magnus::Ruby::get() {
+            marker.mark(self.func.get_inner_with(&ruby));
+        }
+    }
+}
+impl LifecycleHook<Request<Body>, Response<Body>> for RubyLifecycleHook {
+    fn name(&self) -> &str {
+        &self.name
+    }
+    fn execute_request<'a>(
+        &'a self,
+        req: Request<Body>,
+    ) -> Pin<Box<dyn Future<Output = Result<HookResult<Request<Body>, Response<Body>>, String>> + Send + 'a>> {
+        let func = self.func;
+        let name = self.name.clone();
+        let name_for_error = name.clone();
+        Box::pin(async move {
+            let (parts, body) = req.into_parts();
+            let body_bytes = axum::body::to_bytes(body, usize::MAX)
+                .await
+                .map_err(|e| format!("Failed to read request body: {}", e))?;
+            let body_value: JsonValue = if body_bytes.is_empty() {
+                JsonValue::Null
+            } else {
+                serde_json::from_slice(&body_bytes)
+                    .unwrap_or_else(|_| JsonValue::String(String::from_utf8_lossy(&body_bytes).to_string()))
+            };
+            let result = magnus::Ruby::get()
+                .map_err(|e| format!("Failed to get Ruby: {}", e))
+                .and_then(|ruby| {
+                    let request_hash = RHash::new();
+                    request_hash
+                        .aset(ruby.to_symbol("method"), ruby.str_new(parts.method.as_str()))
+                        .map_err(|e| format!("Failed to set method: {}", e))?;
+                    request_hash
+                        .aset(ruby.to_symbol("path"), ruby.str_new(parts.uri.path()))
+                        .map_err(|e| format!("Failed to set path: {}", e))?;
+                    let headers_hash = RHash::new();
+                    for (key, value) in parts.headers.iter() {
+                        headers_hash
+                            .aset(ruby.str_new(key.as_str()), ruby.str_new(value.to_str().unwrap_or("")))
+                            .map_err(|e| format!("Failed to set header: {}", e))?;
+                    }
+                    request_hash
+                        .aset(ruby.to_symbol("headers"), headers_hash)
+                        .map_err(|e| format!("Failed to set headers: {}", e))?;
+                    let body_str =
+                        serde_json::to_string(&body_value).map_err(|e| format!("Failed to serialize body: {}", e))?;
+                    request_hash
+                        .aset(ruby.to_symbol("body"), ruby.str_new(&body_str))
+                        .map_err(|e| format!("Failed to set body: {}", e))?;
+                    let func_value = ruby.get_inner(func);
+                    let result: Value = func_value
+                        .funcall("call", (request_hash,))
+                        .map_err(|e| format!("Hook '{}' call failed: {}", name, e))?;
+                    if let Some(result_hash) = RHash::from_value(result) {
+                        if let Some(status_value) = result_hash.get(ruby.to_symbol("status_code")) {
+                            let status = i64::try_convert(status_value)
+                                .map_err(|e| format!("Failed to convert status code: {}", e))?;
+                            let content = result_hash
+                                .get(ruby.to_symbol("content"))
+                                .or_else(|| result_hash.get(ruby.to_symbol("body")))
+                                .unwrap_or_else(|| ruby.qnil().as_value());
+                            let body_str = if content.is_nil() {
+                                "{}".to_string()
+                            } else {
+                                String::try_convert(content).unwrap_or_else(|_| {
+                                    content
+                                        .to_r_string()
+                                        .map(|s| s.to_string().unwrap_or_else(|_| "{}".to_string()))
+                                        .unwrap_or_else(|_| "{}".to_string())
+                                })
+                            };
+                            let response = Response::builder()
+                                .status(StatusCode::from_u16(status as u16).unwrap_or(StatusCode::OK))
+                                .header("content-type", "application/json")
+                                .body(Body::from(body_str))
+                                .map_err(|e| format!("Failed to build response: {}", e))?;
+                            return Ok(HookResult::ShortCircuit(response));
+                        }
+                        let method = result_hash
+                            .get(ruby.to_symbol("method"))
+                            .and_then(|v| String::try_convert(v).ok())
+                            .unwrap_or_else(|| "GET".to_string());
+                        let path = result_hash
+                            .get(ruby.to_symbol("path"))
+                            .and_then(|v| String::try_convert(v).ok())
+                            .unwrap_or_else(|| "/".to_string());
+                        let req_builder = Request::builder().method(method.as_str()).uri(path);
+                        let body = if let Some(body_val) = result_hash.get(ruby.to_symbol("body")) {
+                            if body_val.is_nil() {
+                                Body::empty()
+                            } else {
+                                let body_str = String::try_convert(body_val).unwrap_or_else(|_| {
+                                    body_val
+                                        .to_r_string()
+                                        .map(|s| s.to_string().unwrap_or_default())
+                                        .unwrap_or_default()
+                                });
+                                Body::from(body_str)
+                            }
+                        } else {
+                            Body::empty()
+                        };
+                        let request = req_builder
+                            .body(body)
+                            .map_err(|e| format!("Failed to build request: {}", e))?;
+                        Ok(HookResult::Continue(request))
+                    } else {
+                        Err(format!("Hook must return a Hash, got {}", unsafe {
+                            result.classname()
+                        }))
+                    }
+                });
+            result.map_err(|e| format!("Hook '{}' task error: {}", name_for_error, e))
+        })
+    }
+    fn execute_response<'a>(
+        &'a self,
+        resp: Response<Body>,
+    ) -> Pin<Box<dyn Future<Output = Result<HookResult<Response<Body>, Response<Body>>, String>> + Send + 'a>> {
+        let func = self.func;
+        let name = self.name.clone();
+        let name_for_error = name.clone();
+        Box::pin(async move {
+            let (parts, body) = resp.into_parts();
+            let body_bytes = axum::body::to_bytes(body, usize::MAX)
+                .await
+                .map_err(|e| format!("Failed to read response body: {}", e))?;
+            let body_value: JsonValue = if body_bytes.is_empty() {
+                JsonValue::Null
+            } else {
+                serde_json::from_slice(&body_bytes)
+                    .unwrap_or_else(|_| JsonValue::String(String::from_utf8_lossy(&body_bytes).to_string()))
+            };
+            let result = magnus::Ruby::get()
+                .map_err(|e| format!("Failed to get Ruby: {}", e))
+                .and_then(|ruby| {
+                    let response_hash = RHash::new();
+                    response_hash
+                        .aset(
+                            ruby.to_symbol("status_code"),
+                            ruby.integer_from_i64(parts.status.as_u16() as i64),
+                        )
+                        .map_err(|e| format!("Failed to set status_code: {}", e))?;
+                    let headers_hash = RHash::new();
+                    for (key, value) in parts.headers.iter() {
+                        headers_hash
+                            .aset(ruby.str_new(key.as_str()), ruby.str_new(value.to_str().unwrap_or("")))
+                            .map_err(|e| format!("Failed to set header: {}", e))?;
+                    }
+                    response_hash
+                        .aset(ruby.to_symbol("headers"), headers_hash)
+                        .map_err(|e| format!("Failed to set headers: {}", e))?;
+                    let body_str =
+                        serde_json::to_string(&body_value).map_err(|e| format!("Failed to serialize body: {}", e))?;
+                    response_hash
+                        .aset(ruby.to_symbol("content"), ruby.str_new(&body_str))
+                        .map_err(|e| format!("Failed to set content: {}", e))?;
+                    let func_value = ruby.get_inner(func);
+                    let result: Value = func_value
+                        .funcall("call", (response_hash,))
+                        .map_err(|e| format!("Hook '{}' call failed: {}", name, e))?;
+                    if let Some(result_hash) = RHash::from_value(result) {
+                        let status = result_hash
+                            .get(ruby.to_symbol("status_code"))
+                            .and_then(|v| i64::try_convert(v).ok())
+                            .unwrap_or(200);
+                        let content = result_hash
+                            .get(ruby.to_symbol("content"))
+                            .or_else(|| result_hash.get(ruby.to_symbol("body")))
+                            .unwrap_or_else(|| ruby.qnil().as_value());
+                        let body_str = if content.is_nil() {
+                            "{}".to_string()
+                        } else {
+                            String::try_convert(content).unwrap_or_else(|_| {
+                                content
+                                    .to_r_string()
+                                    .map(|s| s.to_string().unwrap_or_else(|_| "{}".to_string()))
+                                    .unwrap_or_else(|_| "{}".to_string())
+                            })
+                        };
+                        let mut response_builder =
+                            Response::builder().status(StatusCode::from_u16(status as u16).unwrap_or(StatusCode::OK));
+                        response_builder = response_builder.header("content-type", "application/json");
+                        let response = response_builder
+                            .body(Body::from(body_str))
+                            .map_err(|e| format!("Failed to build response: {}", e))?;
+                        Ok(HookResult::Continue(response))
+                    } else {
+                        Err(format!("Hook must return a Hash, got {}", unsafe {
+                            result.classname()
+                        }))
+                    }
+                });
+            result.map_err(|e| format!("Hook '{}' task error: {}", name_for_error, e))
+        })
+    }
+}
+unsafe impl Send for RubyLifecycleHook {}
+unsafe impl Sync for RubyLifecycleHook {}

data/vendor/crates/spikard-rb/src/server.rs ADDED Viewed

@@ -0,0 +1,283 @@
+//! HTTP server setup and lifecycle management.
+//!
+//! This module handles the creation and startup of the Spikard HTTP server
+//! including route registration, middleware configuration, and lifecycle hooks.
+#![allow(dead_code)]
+use axum::body::Body;
+use axum::http::Request;
+use axum::http::Response;
+use magnus::prelude::*;
+use magnus::{Error, RArray, RHash, Ruby, Value, r_hash::ForEach};
+use once_cell::sync::Lazy;
+use spikard_http::{Handler, Route, RouteMetadata, SchemaRegistry, Server};
+use std::sync::Arc;
+use tokio::runtime::{Builder, Runtime};
+use tracing::{error, info, warn};
+use crate::config::extract_server_config;
+use crate::handler::RubyHandler;
+/// Global Tokio runtime for async operations.
+///
+/// Initialized once and reused for all async operations throughout the lifetime
+/// of the Ruby process.
+pub static GLOBAL_RUNTIME: Lazy<Runtime> = Lazy::new(|| {
+    Builder::new_current_thread().enable_all().build().unwrap_or_else(|e| {
+        eprintln!("Failed to initialise global Tokio runtime: {}", e);
+        panic!("Cannot continue without Tokio runtime");
+    })
+});
+/// Start the Spikard HTTP server from Ruby
+///
+/// Creates an Axum HTTP server in a dedicated background thread with its own Tokio runtime.
+///
+/// # Arguments
+///
+/// * `ruby` - Ruby VM reference
+/// * `routes_json` - JSON string containing route metadata
+/// * `handlers` - Ruby Hash mapping handler_name => Proc
+/// * `config_value` - Ruby ServerConfig object with all middleware settings
+/// * `hooks_value` - Ruby Hash of lifecycle hooks (optional)
+/// * `ws_handlers` - Ruby Hash of WebSocket handlers (optional)
+/// * `sse_producers` - Ruby Hash of SSE producers (optional)
+///
+/// # Example (Ruby)
+///
+/// ```ruby
+/// config = Spikard::ServerConfig.new(host: '0.0.0.0', port: 8000)
+/// Spikard::Native.run_server(routes_json, handlers, config, hooks, ws_handlers, sse_producers)
+/// ```
+pub fn run_server(
+    ruby: &Ruby,
+    routes_json: String,
+    handlers: Value,
+    config_value: Value,
+    hooks_value: Value,
+    ws_handlers: Value,
+    sse_producers: Value,
+) -> Result<(), Error> {
+    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 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 Handler>));
+    }
+    let lifecycle_hooks = 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 = crate::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);
+    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(())
+}