spikard 0.8.2 → 0.10.1

data/ext/spikard_rb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-rb-ext"
-version = "0.8.2"
+version = "0.10.1"
 edition = "2024"
 license = "MIT"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
@@ -13,5 +13,5 @@ crate-type = ["cdylib"]
 
 [dependencies]
 magnus = { version = "0.8.2", features = ["rb-sys"] }
-# Use vendored crates for packaged gem distribution
-spikard_rb_core = { package = "spikard-rb", path = "../../vendor/crates/spikard-rb" }
+# Use crates from the workspace root
+spikard_rb_core = { package = "spikard-rb", path = "../../../../crates/spikard-rb" }

data/ext/spikard_rb/extconf.rb

@@ -7,7 +7,8 @@ default_profile = ENV.fetch('CARGO_PROFILE', 'release')
 
 create_rust_makefile('spikard_rb') do |config|
   config.profile = default_profile.to_sym
-  # 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'
+  # Always use --locked to maintain consistency with vendored crates.
+  # The vendor-crates.sh script patches Cargo.toml files and relies on a
+  # committed Cargo.lock to avoid workspace collision issues during builds.
+  config.extra_cargo_args = ['--locked']
 end

data/lib/spikard/config.rb

@@ -21,10 +21,34 @@ module Spikard
     # @param min_size [Integer] Minimum response size in bytes to compress (default: 1024)
     # @param quality [Integer] Compression quality level (0-11 for brotli, 0-9 for gzip, default: 6)
     def initialize(gzip: true, brotli: true, min_size: 1024, quality: 6)
-      @gzip = gzip
-      @brotli = brotli
-      @min_size = min_size
-      @quality = quality
+      @gzip = normalize_boolean('gzip', gzip)
+      @brotli = normalize_boolean('brotli', brotli)
+      @min_size = normalize_nonnegative_integer('min_size', min_size)
+      @quality = normalize_quality(quality)
+    end
+
+    private
+
+    def normalize_boolean(name, value)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} must be a boolean"
+    end
+
+    def normalize_nonnegative_integer(name, value)
+      raise ArgumentError, "#{name} must be an Integer" unless value.is_a?(Integer)
+      return value if value >= 0
+
+      raise ArgumentError, "#{name} must be >= 0"
+    end
+
+    def normalize_quality(value)
+      raise ArgumentError, 'quality must be a number' unless value.is_a?(Integer) || value.is_a?(Float)
+
+      normalized = value.to_i
+      return normalized if normalized.between?(0, 11)
+
+      raise ArgumentError, 'quality must be between 0 and 11'
     end
   end
 
@@ -378,19 +402,71 @@ module Spikard
       openapi: nil
     )
       @host = host
-      @port = port
-      @workers = workers
-      @enable_request_id = enable_request_id
-      @max_body_size = max_body_size
-      @request_timeout = request_timeout
+      @port = normalize_port(port)
+      @workers = normalize_workers(workers)
+      @enable_request_id = normalize_boolean('enable_request_id', enable_request_id)
+      @max_body_size = normalize_optional_nonnegative_integer('max_body_size', max_body_size)
+      @request_timeout = normalize_timeout('request_timeout', request_timeout)
       @compression = compression
       @rate_limit = rate_limit
       @jwt_auth = jwt_auth
       @api_key_auth = api_key_auth
-      @static_files = static_files
-      @graceful_shutdown = graceful_shutdown
-      @shutdown_timeout = shutdown_timeout
+      @static_files = normalize_static_files(static_files)
+      @graceful_shutdown = normalize_boolean('graceful_shutdown', graceful_shutdown)
+      @shutdown_timeout = normalize_timeout('shutdown_timeout', shutdown_timeout)
       @openapi = openapi
     end
+
+    private
+
+    def normalize_port(port)
+      raise ArgumentError, 'port must be an Integer' unless port.is_a?(Integer)
+      return port if port.between?(1, 65_535)
+
+      raise ArgumentError, 'port must be between 1 and 65535'
+    end
+
+    def normalize_workers(workers)
+      raise ArgumentError, 'workers must be an Integer' unless workers.is_a?(Integer)
+      return workers if workers >= 1
+
+      raise ArgumentError, 'workers must be >= 1'
+    end
+
+    def normalize_boolean(name, value)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} must be a boolean"
+    end
+
+    def normalize_optional_nonnegative_integer(name, value)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be an Integer" unless value.is_a?(Integer)
+      return value if value >= 0
+
+      raise ArgumentError, "#{name} must be >= 0"
+    end
+
+    def normalize_timeout(name, value)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be a number" unless value.is_a?(Integer) || value.is_a?(Float)
+
+      normalized = value.to_i
+      return normalized if normalized >= 0
+
+      raise ArgumentError, "#{name} must be >= 0"
+    end
+
+    def normalize_static_files(static_files)
+      return [] if static_files.nil?
+      raise ArgumentError, 'static_files must be an Array' unless static_files.is_a?(Array)
+
+      static_files.each do |entry|
+        next if entry.is_a?(StaticFilesConfig)
+
+        raise ArgumentError, 'static_files entries must be StaticFilesConfig'
+      end
+      static_files
+    end
   end
 end

data/lib/spikard/testing.rb

@@ -38,8 +38,10 @@ module Spikard
       handlers = app.handler_map.transform_keys(&:to_sym)
       ws_handlers = app.websocket_handlers || {}
       sse_producers = app.sse_producers || {}
+      hooks = app.instance_variable_get(:@native_hooks)
       dependencies = app.dependencies || {}
-      Spikard::Native::TestClient.new(routes_json, handlers, config, ws_handlers, sse_producers, dependencies)
+      payload = { hooks: hooks, dependencies: dependencies }
+      Spikard::Native::TestClient.new(routes_json, handlers, config, ws_handlers, sse_producers, payload)
     end
 
     # High level wrapper around the native test client.

data/lib/spikard/version.rb

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

data/lib/spikard.rb

@@ -34,6 +34,17 @@ rescue LoadError => e
   MSG
 end
 
+if defined?(Spikard::Native::TestClient) && !Spikard::Native::TestClient.method_defined?(:__spikard_native_request,
+                                                                                         false)
+  Spikard::Native::TestClient.class_eval do
+    alias_method :__spikard_native_request, :request
+
+    def request(method, path, options = nil)
+      __spikard_native_request(method, path, options)
+    end
+  end
+end
+
 # Convenience aliases and methods at top level
 module Spikard
   TestClient = Testing::TestClient

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

@@ -1,15 +1,24 @@
 [package]
 name = "spikard-bindings-shared"
-version = "0.8.2"
+version = "0.10.1"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
 repository = "https://github.com/Goldziher/spikard"
 homepage = "https://github.com/Goldziher/spikard"
 
+[lints.rust]
+unexpected_cfgs = { level = "allow", check-cfg = ['cfg(tarpaulin_include)'] }
+
+[lints.clippy]
+all = { level = "deny", priority = 0 }
+pedantic = { level = "deny", priority = 0 }
+nursery = { level = "deny", priority = 0 }
+
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
+simd-json = "0.17"
 axum = { version = "0.8", features = ["multipart", "ws"] }
 tokio = { version = "1", features = ["full"] }
 thiserror = "2.0"
@@ -19,6 +28,7 @@ tracing = "0.1"
 http = "1.4"
 http-body-util = "0.1"
 tonic = "0.14"
+bytes = "1.11"
 
 [features]
 default = []
@@ -26,7 +36,6 @@ python-support = ["pyo3", "pyo3-async-runtimes"]
 node-support = ["napi", "napi-derive"]
 ruby-support = ["magnus"]
 php-support = ["ext-php-rs"]
-wasm-support = ["wasm-bindgen"]
 
 [dependencies.pyo3]
 version = "0.27"
@@ -56,9 +65,5 @@ optional = true
 version = "0.15"
 optional = true
 
-[dependencies.wasm-bindgen]
-version = "0.2"
-optional = true
-
 [dev-dependencies]
 pretty_assertions = "1.4"

data/vendor/crates/spikard-bindings-shared/examples/config_extraction.rs

@@ -1,12 +1,12 @@
-//! Example of implementing ConfigSource for a language binding
+//! Example of implementing `ConfigSource` for a language binding
 //!
 //! This example demonstrates how a language binding (e.g., Python, Node.js, Ruby, PHP)
-//! would implement the `ConfigSource` trait to extract ServerConfig from language-specific objects.
+//! would implement the `ConfigSource` trait to extract `ServerConfig` from language-specific objects.
 
 use spikard_bindings_shared::{ConfigExtractor, ConfigSource};
 use std::collections::HashMap;
 
-/// Example: PyO3 Python dict wrapper
+/// Example: `PyO3` Python dict wrapper
 struct PyDictWrapper {
     data: HashMap<String, String>,
 }
@@ -74,7 +74,7 @@ fn main() {
             println!("   min_size: {}", config.min_size);
             println!("   quality: {}\n", config.quality);
         }
-        Err(e) => println!("   Error: {}\n", e),
+        Err(e) => println!("   Error: {e}\n"),
     }
 
     println!("2. Extracting JWT authentication configuration:");
@@ -89,7 +89,7 @@ fn main() {
             println!("   algorithm: {}", config.algorithm);
             println!("   leeway: {}\n", config.leeway);
         }
-        Err(e) => println!("   Error: {}\n", e),
+        Err(e) => println!("   Error: {e}\n"),
     }
 
     println!("3. Extracting API Key authentication configuration:");
@@ -102,7 +102,7 @@ fn main() {
             println!("   keys: {:?}", config.keys);
             println!("   header_name: {}\n", config.header_name);
         }
-        Err(e) => println!("   Error: {}\n", e),
+        Err(e) => println!("   Error: {e}\n"),
     }
 
     println!("4. Extracting rate limit configuration:");
@@ -117,7 +117,7 @@ fn main() {
             println!("   burst: {}", config.burst);
             println!("   ip_based: {}\n", config.ip_based);
         }
-        Err(e) => println!("   Error: {}\n", e),
+        Err(e) => println!("   Error: {e}\n"),
     }
 
     println!("5. Testing error handling (missing 'burst' field):");
@@ -125,7 +125,7 @@ fn main() {
 
     match ConfigExtractor::extract_rate_limit_config(&rate_limit_config) {
         Ok(_config) => println!("   Success (unexpected!)"),
-        Err(e) => println!("   Expected error: {}\n", e),
+        Err(e) => println!("   Expected error: {e}\n"),
     }
 
     println!("=== Example Complete ===");

data/vendor/crates/spikard-bindings-shared/src/config_extractor.rs

@@ -1,6 +1,6 @@
 //! Configuration extraction trait and implementation for language bindings
 //!
-//! This module provides a trait-based abstraction for extracting ServerConfig and related
+//! This module provides a trait-based abstraction for extracting `ServerConfig` and related
 //! configuration structs from language-specific objects (Python dicts, JavaScript objects, etc.)
 //! without duplicating extraction logic across bindings.
 //!
@@ -17,7 +17,7 @@ use std::collections::HashMap;
 /// Trait for reading configuration from language-specific objects
 ///
 /// Bindings implement this trait to provide unified access to configuration values
-/// regardless of the language-specific representation (PyDict, JavaScript Object, etc.).
+/// regardless of the language-specific representation (`PyDict`, JavaScript Object, etc.).
 pub trait ConfigSource {
     /// Get a boolean value from the source
     fn get_bool(&self, key: &str) -> Option<bool>;
@@ -34,7 +34,7 @@ pub trait ConfigSource {
     /// Get a vector of strings from the source
     fn get_vec_string(&self, key: &str) -> Option<Vec<String>>;
 
-    /// Get a nested ConfigSource for nested objects
+    /// Get a nested `ConfigSource` for nested objects
     fn get_nested(&self, key: &str) -> Option<Box<dyn ConfigSource + '_>>;
 
     /// Check if a key exists in the source
@@ -61,11 +61,15 @@ pub trait ConfigSource {
     }
 }
 
-/// Configuration extractor that works with any ConfigSource
+/// Configuration extractor that works with any `ConfigSource`
 pub struct ConfigExtractor;
 
 impl ConfigExtractor {
-    /// Extract a complete ServerConfig from a ConfigSource
+    /// Extract a complete `ServerConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if required configuration fields are invalid or missing.
     pub fn extract_server_config(source: &dyn ConfigSource) -> Result<ServerConfig, String> {
         let mut config = ServerConfig::default();
 
@@ -73,10 +77,14 @@ impl ConfigExtractor {
             config.host = host;
         }
 
-        if let Some(port) = source
-            .get_u16("port")
-            .or_else(|| source.get_u32("port").map(|p| p as u16))
-        {
+        if let Some(port) = source.get_u16("port").or_else(|| {
+            source.get_u32("port").map(|p| {
+                #[allow(clippy::cast_possible_truncation)]
+                {
+                    p as u16
+                }
+            })
+        }) {
             config.port = port;
         }
 
@@ -144,7 +152,11 @@ impl ConfigExtractor {
         Ok(config)
     }
 
-    /// Extract CompressionConfig from a ConfigSource
+    /// Extract `CompressionConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if required configuration fields are invalid.
     pub fn extract_compression_config(source: &dyn ConfigSource) -> Result<CompressionConfig, String> {
         let gzip = source.get_bool("gzip").unwrap_or(true);
         let brotli = source.get_bool("brotli").unwrap_or(true);
@@ -162,7 +174,11 @@ impl ConfigExtractor {
         })
     }
 
-    /// Extract RateLimitConfig from a ConfigSource
+    /// Extract `RateLimitConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if required fields `per_second` or `burst` are missing.
     pub fn extract_rate_limit_config(source: &dyn ConfigSource) -> Result<RateLimitConfig, String> {
         let per_second = source.get_u64("per_second").ok_or("Rate limit requires 'per_second'")?;
 
@@ -177,7 +193,11 @@ impl ConfigExtractor {
         })
     }
 
-    /// Extract JwtConfig from a ConfigSource
+    /// Extract `JwtConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the required `secret` field is missing.
     pub fn extract_jwt_config(source: &dyn ConfigSource) -> Result<JwtConfig, String> {
         let secret = source.get_string("secret").ok_or("JWT auth requires 'secret'")?;
 
@@ -198,7 +218,11 @@ impl ConfigExtractor {
         })
     }
 
-    /// Extract ApiKeyConfig from a ConfigSource
+    /// Extract `ApiKeyConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the required `keys` field is missing.
     pub fn extract_api_key_config(source: &dyn ConfigSource) -> Result<ApiKeyConfig, String> {
         let keys = source
             .get_vec_string("keys")
@@ -211,7 +235,11 @@ impl ConfigExtractor {
         Ok(ApiKeyConfig { keys, header_name })
     }
 
-    /// Extract static files configuration list from a ConfigSource
+    /// Extract static files configuration list from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if array elements are invalid or missing required fields.
     pub fn extract_static_files_config(source: &dyn ConfigSource) -> Result<Vec<StaticFilesConfig>, String> {
         let length = source.get_array_length("static_files").unwrap_or(0);
         if length == 0 {
@@ -247,7 +275,11 @@ impl ConfigExtractor {
         Ok(configs)
     }
 
-    /// Extract OpenApiConfig from a ConfigSource
+    /// Extract `OpenApiConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if required configuration fields are invalid.
     pub fn extract_openapi_config(source: &dyn ConfigSource) -> Result<OpenApiConfig, String> {
         let enabled = source.get_bool("enabled").unwrap_or(false);
         let title = source.get_string("title").unwrap_or_else(|| "API".to_string());
@@ -279,7 +311,7 @@ impl ConfigExtractor {
 
         let servers = Self::extract_servers_config(source)?;
 
-        let security_schemes = Self::extract_security_schemes_config(source)?;
+        let security_schemes = Self::extract_security_schemes_config(source);
 
         Ok(OpenApiConfig {
             enabled,
@@ -296,7 +328,11 @@ impl ConfigExtractor {
         })
     }
 
-    /// Extract servers list from OpenAPI config
+    /// Extract servers list from `OpenAPI` config
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if array elements are invalid or missing.
     fn extract_servers_config(source: &dyn ConfigSource) -> Result<Vec<ServerInfo>, String> {
         let length = source.get_array_length("servers").unwrap_or(0);
         if length == 0 {
@@ -319,15 +355,17 @@ impl ConfigExtractor {
         Ok(servers)
     }
 
-    /// Extract security schemes from OpenAPI config
-    fn extract_security_schemes_config(
-        _source: &dyn ConfigSource,
-    ) -> Result<HashMap<String, SecuritySchemeInfo>, String> {
+    /// Extract security schemes from `OpenAPI` config
+    fn extract_security_schemes_config(_source: &dyn ConfigSource) -> HashMap<String, SecuritySchemeInfo> {
         // TODO: Implement when bindings support iterating HashMap-like structures
-        Ok(HashMap::new())
+        HashMap::new()
     }
 
-    /// Extract JsonRpcConfig from a ConfigSource
+    /// Extract `JsonRpcConfig` from a `ConfigSource`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if required configuration fields are invalid.
     pub fn extract_jsonrpc_config(source: &dyn ConfigSource) -> Result<JsonRpcConfig, String> {
         let enabled = source.get_bool("enabled").unwrap_or(true);
         let endpoint_path = source.get_string("endpoint_path").unwrap_or_else(|| "/rpc".to_string());
@@ -549,7 +587,7 @@ mod tests {
         assert_eq!(config.port, 3000);
         assert_eq!(config.workers, 4);
         assert!(!config.enable_request_id);
-        assert_eq!(config.max_body_size, Some(5242880));
+        assert_eq!(config.max_body_size, Some(5_242_880));
         assert_eq!(config.request_timeout, Some(60));
         assert!(!config.graceful_shutdown);
         assert_eq!(config.shutdown_timeout, 10);
@@ -582,7 +620,7 @@ mod tests {
     fn test_security_schemes_config_empty() {
         let source = MockConfigSource::new();
 
-        let schemes = ConfigExtractor::extract_security_schemes_config(&source).unwrap();
+        let schemes = ConfigExtractor::extract_security_schemes_config(&source);
         assert_eq!(schemes.len(), 0);
     }
 

data/vendor/crates/spikard-bindings-shared/src/conversion_traits.rs

@@ -8,6 +8,10 @@ pub trait FromLanguage: Sized {
     type Error: std::fmt::Display;
 
     /// Convert from a language-specific value
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the value cannot be converted to the expected type.
     fn from_any(value: &(dyn Any + Send + Sync)) -> Result<Self, Self::Error>;
 }
 
@@ -17,6 +21,10 @@ pub trait ToLanguage {
     type Error: std::fmt::Display;
 
     /// Convert to a language-specific value
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the conversion fails.
     fn to_any(&self) -> Result<Box<dyn Any + Send + Sync>, Self::Error>;
 }
 
@@ -26,9 +34,17 @@ pub trait JsonConvertible: Sized {
     type Error: std::fmt::Display;
 
     /// Convert from a JSON value
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the JSON value is not valid for the target type.
     fn from_json(value: serde_json::Value) -> Result<Self, Self::Error>;
 
     /// Convert to a JSON value
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the conversion fails.
     fn to_json(&self) -> Result<serde_json::Value, Self::Error>;
 }
 
@@ -71,7 +87,7 @@ mod tests {
         fn from_any(value: &(dyn Any + Send + Sync)) -> Result<Self, Self::Error> {
             value
                 .downcast_ref::<i32>()
-                .map(|&v| TestType { value: v })
+                .map(|&v| Self { value: v })
                 .ok_or_else(|| "Invalid type".to_string())
         }
     }
@@ -153,7 +169,7 @@ mod tests {
     #[test]
     fn test_json_null_conversion() {
         let null_value = serde_json::Value::Null;
-        let result = serde_json::Value::from_json(null_value.clone());
+        let result = serde_json::Value::from_json(null_value);
         assert!(result.is_ok());
         assert!(result.unwrap().is_null());
     }
@@ -161,7 +177,7 @@ mod tests {
     #[test]
     fn test_json_array_conversion() {
         let array = json!([1, 2, 3, 4, 5]);
-        let result = serde_json::Value::from_json(array.clone());
+        let result = serde_json::Value::from_json(array);
         assert!(result.is_ok());
         let converted = result.unwrap();
         assert!(converted.is_array());
@@ -180,7 +196,7 @@ mod tests {
             }
         });
 
-        let result = serde_json::Value::from_json(nested.clone());
+        let result = serde_json::Value::from_json(nested);
         assert!(result.is_ok());
         let converted = result.unwrap();
         assert_eq!(converted["level1"]["level2"]["level3"]["value"], "deep");

data/vendor/crates/spikard-bindings-shared/src/di_traits.rs

@@ -19,21 +19,21 @@ type DependencyFuture<'a> =
 /// Adapter trait for value dependencies across language bindings
 ///
 /// Language bindings should implement this trait to wrap their
-/// language-specific value storage (e.g., Py<PyAny>, Opaque<Value>, etc.)
+/// language-specific value storage (e.g., `Py<PyAny>`, `Opaque<Value>`, etc.)
 pub trait ValueDependencyAdapter: Send + Sync {
     /// Get the dependency key
     fn key(&self) -> &str;
 
     /// Resolve the stored value
     ///
-    /// Returns an Arc<dyn Any> that can be downcast to the concrete type
+    /// Returns an `Arc<dyn Any>` that can be downcast to the concrete type
     fn resolve_value(&self) -> DependencyFuture<'_>;
 }
 
 /// Adapter trait for factory dependencies across language bindings
 ///
 /// Language bindings should implement this trait to wrap their
-/// language-specific callable storage (e.g., Py<PyAny>, ThreadsafeFunction, etc.)
+/// language-specific callable storage (e.g., `Py<PyAny>`, `ThreadsafeFunction`, etc.)
 pub trait FactoryDependencyAdapter: Send + Sync {
     /// Get the dependency key
     fn key(&self) -> &str;
@@ -41,7 +41,7 @@ pub trait FactoryDependencyAdapter: Send + Sync {
     /// Invoke the factory with resolved dependencies
     ///
     /// The factory receives already-resolved dependencies and returns
-    /// a new instance wrapped in Arc<dyn Any>
+    /// a new instance wrapped in `Arc<dyn Any>`
     fn invoke_factory(
         &self,
         request: &Request<()>,
@@ -81,6 +81,9 @@ impl<T: ValueDependencyAdapter + 'static> Dependency for ValueDependencyBridge<T
         self.adapter.key()
     }
 
+    // PERFORMANCE: Value dependencies have no sub-dependencies.
+    // Returning an empty Vec is unavoidable if the trait requires it, but
+    // consider optimizing the DI system to use Option<&[String]> or a default method.
     fn depends_on(&self) -> Vec<String> {
         vec![]
     }
@@ -114,6 +117,9 @@ impl<T: FactoryDependencyAdapter + 'static> Dependency for FactoryDependencyBrid
         self.adapter.key()
     }
 
+    // PERFORMANCE: Factory dependencies may or may not have sub-dependencies.
+    // Language bindings should override this if they track dependencies.
+    // The default empty Vec is acceptable for language bindings that don't track explicit dependency graphs.
     fn depends_on(&self) -> Vec<String> {
         vec![]
     }