spikard 0.6.1 → 0.7.1

data/ext/spikard_rb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-rb-ext"
-version = "0.6.1"
+version = "0.7.1"
 edition = "2024"
 license = "MIT"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]

data/ext/spikard_rb/extconf.rb

@@ -7,7 +7,7 @@ default_profile = ENV.fetch('CARGO_PROFILE', 'release')
 
 create_rust_makefile('spikard_rb') do |config|
   config.profile = default_profile.to_sym
-  # Use --locked to prevent Cargo from updating the committed lockfile
-  # This avoids lockfile collision errors with vendored crates in CI
-  config.extra_cargo_args = ['--locked']
+  # Only use --locked in development to prevent lockfile updates
+  # Release builds need to update Cargo.lock after version bumps
+  config.extra_cargo_args = ['--locked'] unless default_profile == 'release'
 end

data/lib/spikard/app.rb

@@ -129,60 +129,20 @@ module Spikard
       @sse_producers = {}
       @native_hooks = Spikard::Native::LifecycleRegistry.new
       @native_dependencies = Spikard::Native::DependencyRegistry.new
+      @named_handlers = {}
     end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def register_route(method, path, handler_name: nil, **options, &block)
       method = method.to_s
       path = path.to_s
       handler_name = handler_name&.to_s
-      validate_route_arguments!(block, options)
-      metadata = if defined?(Spikard::Native) && Spikard::Native.respond_to?(:build_route_metadata)
-                   begin
-                     Spikard::Native.build_route_metadata(
-                       method,
-                       path,
-                       handler_name,
-                       options[:request_schema],
-                       options[:response_schema],
-                       options[:parameter_schema],
-                       options[:file_params],
-                       options.fetch(:is_async, false),
-                       options[:cors],
-                       options[:body_param_name]&.to_s,
-                       options[:jsonrpc_method],
-                       block
-                     )
-                   rescue ArgumentError => e
-                     raise unless e.message.include?('wrong number of arguments')
-
-                     Spikard::Native.build_route_metadata(
-                       method,
-                       path,
-                       handler_name,
-                       options[:request_schema],
-                       options[:response_schema],
-                       options[:parameter_schema],
-                       options[:file_params],
-                       options.fetch(:is_async, false),
-                       options[:cors],
-                       options[:body_param_name]&.to_s,
-                       block
-                     )
-                   end
-                 else
-                   handler_name ||= default_handler_name(method, path)
-
-                   # Extract handler dependencies from block parameters
-                   handler_dependencies = extract_handler_dependencies(block)
-
-                   build_metadata(method, path, handler_name, options, handler_dependencies)
-                 end
-
-      @routes << RouteEntry.new(metadata, block)
-      block
+      handler = block || (handler_name && @named_handlers[handler_name])
+      validate_route_arguments!(handler, handler_name, options)
+      metadata = build_route_metadata_for(method, path, handler_name, options, handler)
+
+      @routes << RouteEntry.new(metadata, handler)
+      handler
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     HTTP_METHODS.each do |verb|
       define_method(verb.downcase) do |path, handler_name: nil, **options, &block|
@@ -201,9 +161,29 @@ module Spikard
         # Pass raw handler - DI resolution happens in Rust layer
         map[name] = entry.handler
       end
+      map.merge!(@named_handlers)
       map
     end
 
+    def handler(name, &block)
+      raise ArgumentError, 'block required for handler' unless block
+
+      handler_name = name.to_s
+      @named_handlers[handler_name] = block
+
+      @routes.each do |entry|
+        next unless entry.metadata[:handler_name] == handler_name
+
+        entry.handler = block
+        next unless entry.metadata.is_a?(Hash)
+
+        deps = extract_handler_dependencies(block)
+        entry.metadata[:handler_dependencies] = deps unless deps.empty?
+      end
+
+      block
+    end
+
     def normalized_routes_json
       json = JSON.generate(route_metadata)
       if defined?(Spikard::Native) && Spikard::Native.respond_to?(:normalize_route_metadata)
@@ -351,8 +331,10 @@ module Spikard
       has_trailing_slash && !normalized.end_with?('/') ? "#{normalized}/" : normalized
     end
 
-    def validate_route_arguments!(block, options)
-      raise ArgumentError, 'block required for route handler' unless block
+    def validate_route_arguments!(block, handler_name, options)
+      if block.nil? && (handler_name.nil? || handler_name.empty?)
+        raise ArgumentError, 'block required for route handler'
+      end
 
       unknown_keys = options.keys - SUPPORTED_OPTIONS
       return if unknown_keys.empty?
@@ -360,6 +342,47 @@ module Spikard
       raise ArgumentError, "unknown route options: #{unknown_keys.join(', ')}"
     end
 
+    def build_route_metadata_for(method, path, handler_name, options, block)
+      if block && native_route_metadata_supported?
+        build_native_route_metadata(method, path, handler_name, options, block)
+      else
+        build_fallback_route_metadata(method, path, handler_name, options, block)
+      end
+    end
+
+    def native_route_metadata_supported?
+      defined?(Spikard::Native) && Spikard::Native.respond_to?(:build_route_metadata)
+    end
+
+    def build_native_route_metadata(method, path, handler_name, options, block)
+      Spikard::Native.build_route_metadata(
+        *native_route_metadata_args(method, path, handler_name, options, block, include_jsonrpc: true)
+      )
+    rescue ArgumentError => e
+      raise unless e.message.include?('wrong number of arguments')
+
+      Spikard::Native.build_route_metadata(
+        *native_route_metadata_args(method, path, handler_name, options, block, include_jsonrpc: false)
+      )
+    end
+
+    def native_route_metadata_args(method, path, handler_name, options, block, include_jsonrpc:)
+      args = [
+        method, path, handler_name, options[:request_schema], options[:response_schema],
+        options[:parameter_schema], options[:file_params], options.fetch(:is_async, false),
+        options[:cors], options[:body_param_name]&.to_s
+      ]
+      args << options[:jsonrpc_method] if include_jsonrpc
+      args << block
+      args
+    end
+
+    def build_fallback_route_metadata(method, path, handler_name, options, block)
+      handler_name ||= default_handler_name(method, path)
+      handler_dependencies = block ? extract_handler_dependencies(block) : []
+      build_metadata(method, path, handler_name, options, handler_dependencies)
+    end
+
     def extract_handler_dependencies(block)
       # Get the block's parameters
       params = block.parameters

data/lib/spikard/background.rb

@@ -6,13 +6,27 @@ module Spikard
     module_function
 
     @queue = Queue.new
-    @worker = Thread.new do
-      loop do
-        job = @queue.pop
-        begin
-          job.call
-        rescue StandardError => e
-          warn("[spikard.background] job failed: #{e.message}")
+    @worker = nil
+    @worker_mutex = Mutex.new
+    SHUTDOWN = Object.new
+
+    def ensure_worker
+      return if @worker&.alive?
+
+      @worker_mutex.synchronize do
+        return if @worker&.alive?
+
+        @worker = Thread.new do
+          loop do
+            job = @queue.pop
+            break if job.equal?(SHUTDOWN)
+
+            begin
+              job.call
+            rescue StandardError => e
+              warn("[spikard.background] job failed: #{e.message}")
+            end
+          end
         end
       end
     end
@@ -21,7 +35,24 @@ module Spikard
     def run(&block)
       raise ArgumentError, 'background.run requires a block' unless block
 
+      ensure_worker
       @queue << block
     end
+
+    # Stop the background worker thread to allow process shutdown.
+    def shutdown
+      @worker_mutex.synchronize do
+        return unless @worker&.alive?
+
+        @queue << SHUTDOWN
+        @worker.join(1)
+        @worker.kill if @worker.alive?
+        @worker = nil
+      end
+    end
+
+    at_exit do
+      shutdown
+    end
   end
 end

data/lib/spikard/testing.rb

@@ -57,8 +57,9 @@ module Spikard
         Spikard::Testing.create_test_client(app_or_native, config: config)
       end
 
-      def request(method, path, **options)
-        payload = @native.request(method.to_s.upcase, path, options)
+      def request(method, path, headers = nil, body = nil, **options)
+        payload = build_request_payload(headers, body, options)
+        payload = @native.request(method.to_s.upcase, path, payload)
         Response.new(payload)
       end
 
@@ -79,10 +80,47 @@ module Spikard
       end
 
       %w[get post put patch delete head options trace].each do |verb|
-        define_method(verb) do |path, **options|
-          request(verb.upcase, path, **options)
+        define_method(verb) do |path, headers = nil, body = nil, **options|
+          request(verb.upcase, path, headers, body, **options)
         end
       end
+
+      private
+
+      def build_request_payload(headers, body, options)
+        payload = {}
+        headers = options.delete(:headers) || headers
+        cookies = options.delete(:cookies)
+        query = options.delete(:query) || options.delete(:params)
+
+        payload[:headers] = headers if headers
+        payload[:cookies] = cookies if cookies
+        payload[:query] = query if query
+        payload.merge!(body_payload_from(options, body))
+        payload
+      end
+
+      def body_payload_from(options, body)
+        json = options.delete(:json)
+        data = options.delete(:data)
+        raw_body = options.delete(:raw_body)
+        files = options.delete(:files)
+        body_option = options.delete(:body)
+
+        return explicit_body_payload(json, data, raw_body, files) if json || data || raw_body || files
+
+        body_value = body_option.nil? ? body : body_option
+        body_value.nil? ? {} : { json: body_value }
+      end
+
+      def explicit_body_payload(json, data, raw_body, files)
+        payload = {}
+        payload[:json] = json if json
+        payload[:data] = data if data
+        payload[:raw_body] = raw_body if raw_body
+        payload[:files] = files if files
+        payload
+      end
     end
 
     # WebSocket test connection wrapper

data/lib/spikard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spikard
-  VERSION = '0.6.1'
+  VERSION = '0.7.1'
 end

data/sig/spikard.rbs

@@ -305,6 +305,8 @@ module Spikard
       def text: () -> String?
       def json: () -> jsonValue
       def bytes: () -> Array[Integer]
+      def graphql_data: () -> jsonObject?
+      def graphql_errors: () -> Array[jsonObject]
     end
 
     class TestClient
@@ -322,6 +324,8 @@ module Spikard
       def head: (String, **jsonObject) -> Response
       def options: (String, **jsonObject) -> Response
       def trace: (String, **jsonObject) -> Response
+      def graphql: (String, ?Hash[String, untyped]?, ?String?, **jsonObject) -> Response
+      def graphql_with_status: (String, ?Hash[String, untyped]?, ?String?, **jsonObject) -> [Integer, Response]
     end
 
     class WebSocketTestConnection

data/vendor/crates/spikard-bindings-shared/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-bindings-shared"
-version = "0.6.1"
+version = "0.7.1"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"

data/vendor/crates/spikard-bindings-shared/tests/config_extractor_behavior.rs

@@ -0,0 +1,191 @@
+use spikard_bindings_shared::{ConfigExtractor, ConfigSource};
+use std::collections::HashMap;
+
+#[derive(Debug)]
+struct JsonSource {
+    value: serde_json::Value,
+}
+
+impl JsonSource {
+    fn new(value: serde_json::Value) -> Self {
+        Self { value }
+    }
+
+    fn get(&self, key: &str) -> Option<&serde_json::Value> {
+        self.value.as_object()?.get(key)
+    }
+}
+
+impl ConfigSource for JsonSource {
+    fn get_bool(&self, key: &str) -> Option<bool> {
+        self.get(key)?.as_bool()
+    }
+
+    fn get_u64(&self, key: &str) -> Option<u64> {
+        self.get(key)?.as_u64()
+    }
+
+    fn get_u16(&self, key: &str) -> Option<u16> {
+        self.get_u64(key).and_then(|v| u16::try_from(v).ok())
+    }
+
+    fn get_string(&self, key: &str) -> Option<String> {
+        self.get(key)?.as_str().map(ToOwned::to_owned)
+    }
+
+    fn get_vec_string(&self, key: &str) -> Option<Vec<String>> {
+        self.get(key)?.as_array().map(|items| {
+            items
+                .iter()
+                .filter_map(|item| item.as_str().map(ToOwned::to_owned))
+                .collect()
+        })
+    }
+
+    fn get_nested(&self, key: &str) -> Option<Box<dyn ConfigSource + '_>> {
+        let nested = self.get(key)?.as_object()?;
+        Some(Box::new(JsonSource {
+            value: serde_json::Value::Object(nested.clone()),
+        }))
+    }
+
+    fn has_key(&self, key: &str) -> bool {
+        self.value.as_object().is_some_and(|obj| obj.contains_key(key))
+    }
+
+    fn get_array_length(&self, key: &str) -> Option<usize> {
+        self.get(key)?.as_array().map(Vec::len)
+    }
+
+    fn get_array_element(&self, key: &str, index: usize) -> Option<Box<dyn ConfigSource + '_>> {
+        let array = self.get(key)?.as_array()?;
+        let element = array.get(index)?.as_object()?;
+        Some(Box::new(JsonSource {
+            value: serde_json::Value::Object(element.clone()),
+        }))
+    }
+}
+
+#[test]
+fn server_config_defaults() {
+    let source = JsonSource::new(serde_json::json!({}));
+    let cfg = ConfigExtractor::extract_server_config(&source).expect("defaults should extract");
+
+    assert_eq!(cfg.host, "127.0.0.1");
+    assert_eq!(cfg.port, 8000);
+    assert_eq!(cfg.workers, 1);
+    assert!(!cfg.enable_request_id);
+    assert!(cfg.graceful_shutdown);
+    assert_eq!(cfg.shutdown_timeout, 30);
+    assert_eq!(cfg.max_body_size, Some(10 * 1024 * 1024));
+    assert!(cfg.request_timeout.is_none());
+    assert!(cfg.compression.is_none());
+    assert!(cfg.rate_limit.is_none());
+    assert!(cfg.jwt_auth.is_none());
+    assert!(cfg.api_key_auth.is_none());
+    assert!(cfg.static_files.is_empty());
+    assert!(cfg.openapi.is_none());
+    assert!(cfg.jsonrpc.is_none());
+}
+
+#[test]
+fn server_config_parses_nested_configs_and_static_files() {
+    let source = JsonSource::new(serde_json::json!({
+        "Host": "0.0.0.0",
+        "port": 9000,
+        "workers": 4,
+        "enable_request_id": false,
+        "max_body_size": 1024,
+        "request_timeout": 15,
+        "graceful_shutdown": false,
+        "shutdown_timeout": 10,
+        "compression": { "gzip": true, "brotli": false, "min_size": 2, "quality": 1 },
+        "jwt_auth": { "secret": "secret", "algorithm": "HS256", "audience": ["a"], "issuer": "i", "leeway": 2 },
+        "api_key_auth": { "keys": ["k1", "k2"], "header_name": "X-Key" },
+        "static_files": [
+            { "directory": "./public", "route_prefix": "/static", "index_file": false, "cache_control": "max-age=60" }
+        ],
+        "openapi": { "enabled": true, "title": "T", "version": "V" },
+        "jsonrpc": { "enabled": true }
+    }));
+
+    let cfg = ConfigExtractor::extract_server_config(&source).expect("config should extract");
+
+    assert_eq!(cfg.host, "0.0.0.0");
+    assert_eq!(cfg.port, 9000);
+    assert_eq!(cfg.workers, 4);
+    assert!(!cfg.enable_request_id);
+    assert_eq!(cfg.max_body_size, Some(1024));
+    assert_eq!(cfg.request_timeout, Some(15));
+    assert!(!cfg.graceful_shutdown);
+    assert_eq!(cfg.shutdown_timeout, 10);
+
+    let compression = cfg.compression.expect("compression parsed");
+    assert!(compression.gzip);
+    assert!(!compression.brotli);
+    assert_eq!(compression.min_size, 2);
+    assert_eq!(compression.quality, 1);
+
+    let jwt = cfg.jwt_auth.expect("jwt parsed");
+    assert_eq!(jwt.secret, "secret");
+    assert_eq!(jwt.algorithm, "HS256");
+    assert_eq!(jwt.audience, Some(vec!["a".to_string()]));
+    assert_eq!(jwt.issuer.as_deref(), Some("i"));
+    assert_eq!(jwt.leeway, 2);
+
+    let api_key = cfg.api_key_auth.expect("api key parsed");
+    assert_eq!(api_key.keys, vec!["k1".to_string(), "k2".to_string()]);
+    assert_eq!(api_key.header_name, "X-Key");
+
+    assert_eq!(cfg.static_files.len(), 1);
+    assert_eq!(cfg.static_files[0].directory, "./public");
+    assert_eq!(cfg.static_files[0].route_prefix, "/static");
+    assert!(!cfg.static_files[0].index_file);
+    assert_eq!(cfg.static_files[0].cache_control.as_deref(), Some("max-age=60"));
+
+    assert!(cfg.openapi.is_some());
+    assert!(cfg.jsonrpc.is_some());
+}
+
+#[test]
+fn static_files_validation_errors_are_surfaceable() {
+    let source = JsonSource::new(serde_json::json!({
+        "static_files": [
+            { "route_prefix": "/static" }
+        ]
+    }));
+
+    let err = ConfigExtractor::extract_server_config(&source).expect_err("missing directory should error");
+    assert!(err.contains("Static files requires 'directory'"), "got: {err}");
+}
+
+#[test]
+fn rate_limit_requires_expected_keys() {
+    let missing_per_second = JsonSource::new(serde_json::json!({ "burst": 10 }));
+    let err = ConfigExtractor::extract_rate_limit_config(&missing_per_second).expect_err("missing per_second");
+    assert!(err.contains("per_second"), "got: {err}");
+
+    let missing_burst = JsonSource::new(serde_json::json!({ "per_second": 5 }));
+    let err = ConfigExtractor::extract_rate_limit_config(&missing_burst).expect_err("missing burst");
+    assert!(err.contains("burst"), "got: {err}");
+}
+
+#[test]
+fn openapi_security_schemes_are_parsed() {
+    let source = JsonSource::new(serde_json::json!({
+        "enabled": true,
+        "title": "API",
+        "version": "1.0",
+        "security_schemes": {
+            "BearerAuth": { "type": "http", "scheme": "bearer", "bearer_format": "JWT" }
+        }
+    }));
+
+    let cfg = ConfigExtractor::extract_openapi_config(&source).expect("openapi config should parse");
+    assert!(cfg.enabled);
+    let schemes: HashMap<String, _> = cfg.security_schemes;
+    assert!(
+        schemes.is_empty(),
+        "security scheme extraction is intentionally unsupported until ConfigSource can iterate map keys"
+    );
+}

data/vendor/crates/spikard-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-core"
-version = "0.6.1"
+version = "0.7.1"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -34,7 +34,7 @@ thiserror = "2.0"
 
 [features]
 default = []
-di = ["dep:tokio", "dep:bytes", "dep:thiserror"]
+di = ["dep:tokio", "dep:bytes"]
 
 [dev-dependencies]
 tokio-test = "0.4"

data/vendor/crates/spikard-core/src/http.rs

@@ -79,6 +79,7 @@ pub struct RouteMetadata {
     pub parameter_schema: Option<Value>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub file_params: Option<Value>,
+    #[serde(default)]
     pub is_async: bool,
     pub cors: Option<CorsConfig>,
     /// Name of the body parameter (defaults to "body" if not specified)

data/vendor/crates/spikard-core/src/lifecycle.rs

@@ -691,6 +691,69 @@ mod tests {
         assert!(hooks.is_empty());
     }
 
+    #[test]
+    fn test_execute_request_hooks_continue_flow() {
+        #[cfg(not(target_arch = "wasm32"))]
+        {
+            let hooks: LifecycleHooks<String, String> = LifecycleHooks::builder()
+                .on_request(request_hook("req", |req| async move {
+                    Ok(HookResult::Continue(req + "_a"))
+                }))
+                .pre_validation(request_hook("pre", |req| async move {
+                    Ok(HookResult::Continue(req + "_b"))
+                }))
+                .pre_handler(request_hook("handler", |req| async move {
+                    Ok(HookResult::Continue(req + "_c"))
+                }))
+                .build();
+
+            let on_request = block_on(hooks.execute_on_request("start".to_string())).unwrap();
+            assert!(matches!(on_request, HookResult::Continue(ref val) if val == "start_a"));
+
+            let pre_validation = block_on(hooks.execute_pre_validation("start".to_string())).unwrap();
+            assert!(matches!(pre_validation, HookResult::Continue(ref val) if val == "start_b"));
+
+            let pre_handler = block_on(hooks.execute_pre_handler("start".to_string())).unwrap();
+            assert!(matches!(pre_handler, HookResult::Continue(ref val) if val == "start_c"));
+        }
+    }
+
+    #[test]
+    fn test_execute_request_hooks_short_circuit_flow() {
+        #[cfg(not(target_arch = "wasm32"))]
+        {
+            let hooks: LifecycleHooks<String, String> = LifecycleHooks::builder()
+                .on_request(request_hook("req", |_req| async move {
+                    Ok(HookResult::ShortCircuit("stop".to_string()))
+                }))
+                .build();
+
+            let result = block_on(hooks.execute_on_request("start".to_string())).unwrap();
+            assert!(matches!(result, HookResult::ShortCircuit(ref val) if val == "stop"));
+        }
+    }
+
+    #[test]
+    fn test_execute_response_hooks_continue_and_short_circuit() {
+        #[cfg(not(target_arch = "wasm32"))]
+        {
+            let hooks: LifecycleHooks<String, String> = LifecycleHooks::builder()
+                .on_response(response_hook("resp", |resp| async move {
+                    Ok(HookResult::Continue(resp + "_ok"))
+                }))
+                .on_error(response_hook("err", |resp| async move {
+                    Ok(HookResult::ShortCircuit(resp + "_err"))
+                }))
+                .build();
+
+            let on_response = block_on(hooks.execute_on_response("start".to_string())).unwrap();
+            assert_eq!(on_response, "start_ok");
+
+            let on_error = block_on(hooks.execute_on_error("start".to_string())).unwrap();
+            assert_eq!(on_error, "start_err");
+        }
+    }
+
     #[cfg(not(target_arch = "wasm32"))]
     struct TestShortCircuitHook;