kirei 0.8.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4947e7d5e49692f86c0c631f9f4110eb05f12c5dabaf0eaec50290187aa3200d
-  data.tar.gz: 77babab3bd17e5646a2cdf0171a132267e324e73f1ffe28340e077e187ef2b92
+  metadata.gz: e175975ffe2d5eef5e50f3125cdf29f3c56005458362c1c45080c2cc54642e36
+  data.tar.gz: e9b84d4fb46d281d2f601515c96d186daf64a89e95661b48cf288c088255f420
 SHA512:
-  metadata.gz: c3bb40d4a5101c510594910f88bcfb68522f12735c7970dcd071cb6ac9b0728545bbca8bf5e3f3b94bc680b9f3050bb55aa78589e7198049051b840bff9318c4
-  data.tar.gz: dd36b2aa00e79c5c33946e54fc18739bcf29e0e0b9410201eac9404bc0d605e8d00df78d07e81cd326a2971f3f2ef4fdda159d5cc66aa243b669cb758003b52c
+  metadata.gz: 7fc9d9756a1f4a7b2e030063f1aad7378dd054e7312ea0d04222fa5537278fae1a29a77e760be80d22507c5c2a054e8bc63743471f9991c60c505f09919b3979
+  data.tar.gz: 68a0e0a944c7596f682e48beae0eaade2ee046b1110de7c1f50ea034b035bb0d386347a82117207624d90ee03b267796102a24fb10ece7e2458d2784b95d1629

data/README.md

@@ -2,7 +2,7 @@
 
 Kirei is a strictly typed Ruby micro/REST-framework for building scalable and performant APIs. It is built from the ground up to be clean and easy to use. Kirei is based on [Sequel](https://github.com/jeremyevans/sequel) as an ORM, [Sorbet](https://github.com/sorbet/sorbet) for typing, and [Rack](https://github.com/rack/rack) as web server interface. It strives to have zero magic and to be as explicit as possible.
 
-Kirei's main advantages over other frameworks are its strict typing, low memory footprint, and build-in high-performance logging and metric-tracking toolkits. It is opiniated in terms of tooling, allowing you to focus on your core-business. It is a great choice for building APIs that need to scale.
+Kirei's main advantages over other frameworks are its strict typing, low memory footprint, and built-in high-performance logging and pluggable metric-tracking toolkit. It is opinionated in terms of tooling, allowing you to focus on your core-business. It is a great choice for building APIs that need to scale.
 
 > Kirei (きれい) is a Japanese adjective that primarily means "beautiful" or "pretty." It can also be used to describe something that is "clean" or "neat."
 
@@ -227,6 +227,12 @@ module Kirei::Routing
         controller: Controllers::Airports,
         action: "index",
       ),
+      Route.new(
+        verb: Verb::GET,
+        path: "/airports/:iata",
+        controller: Controllers::Airports,
+        action: "show",
+      ),
     ],
   )
 end
@@ -234,7 +240,24 @@ end
 
 #### Controllers
 
-Controllers can be defined anywhere; by convention, they are defined in the `app/controllers` directory:
+Controllers can be defined anywhere; by convention, they are defined in the `app/controllers` directory.
+
+Three render helpers are available:
+
+| Method | Use case |
+|---|---|
+| `render(body, status:, headers:)` | Raw string responses (plain text, pre-serialized data) |
+| `render_json(data, status:, headers:)` | JSON responses with automatic serialization |
+| `render_error(errors, status:, headers:)` | JSON:API-compliant error responses |
+
+`render_json` accepts multiple data types:
+
+| `data` type | Behavior |
+|---|---|
+| `String` | Pass-through (assumed to be pre-serialized JSON) |
+| `Hash` / `Array` | Serialized via `Oj.dump` |
+| Object responding to `#serialize` (e.g. `T::Struct`) | Calls `.serialize`, then `Oj.dump` if the result is not a String |
+| Anything else | Raises `ArgumentError` |
 
 ```ruby
 module Controllers
@@ -245,14 +268,24 @@ module Controllers
     def index
       search = T.let(params.fetch("q", nil), T.nilable(String))
 
-      airports = Kirei::Services::Runner.call("Airports::Filter") do
-        Airports::Filter.call(search) # T::Array[Airport]
+      service = Kirei::Services::Runner.call("Airports::Filter") do
+        Airports::Filter.call(search)
       end
+      return render_error(service.errors, status: 400) if service.failed?
 
-      # or use a serializer
-      data = Oj.dump(airports.map(&:serialize))
+      render_json(service.result.map(&:serialize))
+    end
+
+    sig { returns(T.anything) }
+    def show
+      iata = T.must(params.fetch("iata", nil)) # named param from dynamic route
 
-      render(status: 200, body: data)
+      airport = Kirei::Services::Runner.call("Airports::Find") do
+        Airports::Find.call(iata) # T.nilable(Airport)
+      end
+      return render(status: 204) if airport.nil?
+
+      render_json(airport) # T::Struct — calls .serialize automatically
     end
   end
 end
@@ -287,11 +320,46 @@ module Airports
 end
 ```
 
+#### Metrics
+
+Kirei ships with a pluggable metrics interface via `Kirei::Metrics::Backend`. Three backends are included:
+
+| Backend | Description |
+|---|---|
+| `LoggingBackend` | **Default.** Prints metrics to stdout via `puts` — great for local development and small MVPs. |
+| `StatsdBackend` | Wraps [`statsd-instrument`](https://github.com/Shopify/statsd-instrument). Add `gem 'statsd-instrument'` to your Gemfile. |
+| `NullBackend` | No-op — silently discards all metrics. |
+
+The backend exposes three methods: `increment`, `measure`, and `gauge`.
+
+Configure the backend in your app:
+
+```ruby
+class MyApp < Kirei::App
+  # Use StatsD (requires `gem 'statsd-instrument'` in Gemfile)
+  config.metrics_backend = Kirei::Metrics::StatsdBackend.new
+
+  # Or disable metrics entirely
+  config.metrics_backend = Kirei::Metrics::NullBackend.new
+end
+```
+
+Emit custom metrics anywhere via `Kirei::Logging::Metric`:
+
+```ruby
+Kirei::Logging::Metric.call("airports_search_term", 1, tags: { "query" => search })
+```
+
+Request timing and service execution timing are tracked automatically.
+
+To build a custom backend (e.g. Prometheus, OpenTelemetry), subclass `Kirei::Metrics::Backend` and implement `increment`, `measure`, and `gauge`.
+
 ### Goes well with these gems
 
 * [pagy](https://github.com/ddnexus/pagy) for pagination
 * [argon2](https://github.com/technion/ruby-argon2) for password hashing
 * [rack-session](https://github.com/rack/rack-session) for session management
+* [pgvector](https://github.com/pgvector/pgvector-ruby) for vector columns — add `:pgvector` to `App.config.db_extensions`
 
 ### Middlewares
 

data/cops/layout.yml

@@ -0,0 +1,17 @@
+Layout/EndAlignment:
+  Enabled: true
+  EnforcedStyleAlignWith: variable
+  AutoCorrect: true
+
+Layout/ParameterAlignment:
+  EnforcedStyle: with_fixed_indentation
+  SupportedStyles:
+    - with_first_parameter
+    - with_fixed_indentation
+
+Layout/LineLength:
+  Max: 120
+  AllowCopDirectives: false
+  AllowedPatterns: ['\s#\s|^#\s'] # allows comments to overflow the line length. E.g. for URLs
+  Exclude:
+    - "spec/**/*"

data/cops/lint.yml

@@ -0,0 +1,23 @@
+Lint/DuplicateBranch:
+  Enabled: true
+
+Lint/DuplicateRegexpCharacterClassElement:
+  Enabled: true
+
+Lint/EmptyBlock:
+  Enabled: true
+
+Lint/EmptyClass:
+  Enabled: true
+
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: true
+
+Lint/ToEnumArguments:
+  Enabled: true
+
+Lint/UnexpectedBlockArity:
+  Enabled: true
+
+Lint/UnmodifiedReduceAccumulator:
+  Enabled: true

data/cops/metrics.yml

@@ -0,0 +1,20 @@
+Metrics/BlockLength:
+  Exclude:
+    - describe
+    - context
+    - feature
+    - scenario
+
+Metrics/MethodLength:
+  Max: 30
+  CountAsOne:
+    - "array"
+    - "heredoc"
+    - "method_call"
+
+Metrics/ModuleLength:
+  Max: 150
+  CountAsOne:
+    - "array"
+    - "heredoc"
+    - "method_call"

data/cops/naming.yml

@@ -0,0 +1,2 @@
+Naming/VariableNumber:
+  EnforcedStyle: snake_case

data/cops/rspec.yml

@@ -0,0 +1,13 @@
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - if
+    - and
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 20

data/cops/style.yml

@@ -0,0 +1,77 @@
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# enforces to use 'name'.to_sym over 'name'.intern and so on
+Style/StringMethods:
+  Enabled: true
+
+# @NOTE: changed from "compact" to "expanded"
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+  SupportedStyles:
+    - compact
+    - expanded
+
+# @NOTE: allowed AllowMultipleReturnValues
+Style/RedundantReturn:
+  Enabled: true
+  AllowMultipleReturnValues: true
+
+# @NOTE: allowed AllowAsExpressionSeparator
+Style/Semicolon:
+  Enabled: true
+  AllowAsExpressionSeparator: true
+
+Style/CollectionMethods:
+  Enabled: true
+
+Style/Documentation:
+  Enabled: false
+
+# @NOTE: changed EnforcedStyleForMultiline from "no_comma" to "comma"
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+# @NOTE: changed EnforcedStyleForMultiline from "no_comma" to "comma"
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+# @NOTE: changed EnforcedStyleForMultiline from "no_comma" to "comma"
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+#
+# @NOTE: the following cops are "pending" by default
+#
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/CollectionCompact:
+  Enabled: true
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: true
+
+Style/NegatedIfElseCondition:
+  Enabled: true
+
+Style/NilLambda:
+  Enabled: true
+
+Style/RedundantArgument:
+  Enabled: true
+
+Style/SwapValues:
+  Enabled: true
+
+# "private_class_method" must always be inlined, no need for a cop
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes

data/cops/types.yml

@@ -0,0 +1,12 @@
+Sorbet/HasSigil:
+  MinimumStrictness: strict
+  SuggestedStrictness: strict
+  Exclude:
+    - "spec/**/*"
+    - "test/**/*"
+
+Sorbet/StrictSigil:
+  Enabled: true
+  Exclude:
+    - "spec/**/*"
+    - "lib/tasks/**/*"

data/kirei.gemspec

@@ -34,6 +34,7 @@ Gem::Specification.new do |spec|
     # do not include RBIs for gems, because users might use different versions
     "sorbet/rbi/dsl/**/*.rbi",
     "sorbet/rbi/shims/**/*.rbi",
+    "cops/**/*",
     "LICENSE",
     "README.md",
   ]
@@ -46,7 +47,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "logger", "~> 1.5" # for Ruby 3.5+
   spec.add_dependency "oj", "~> 3.0"
   spec.add_dependency "sorbet-runtime", "~> 0.5"
-  spec.add_dependency "statsd-instrument", "~> 3.0"
   spec.add_dependency "tzinfo-data", "~> 1.0" # for containerized environments, e.g. on AWS ECS
   spec.add_dependency "zeitwerk", "~> 2.5"
 

data/lib/kirei/config.rb

@@ -21,6 +21,7 @@ module Kirei
     prop :log_level, Kirei::Logging::Level, default: Kirei::Logging::Level::INFO
 
     prop :metric_default_tags, T::Hash[String, T.untyped], default: {}
+    prop :metrics_backend, Kirei::Metrics::Backend, factory: -> { Kirei::Metrics::LoggingBackend.new }
 
     # dup to allow the user to extend the existing list of sensitive keys
     prop :sensitive_keys, T::Array[Regexp], factory: -> { SENSITIVE_KEYS.dup }

data/lib/kirei/domain/value_object.rb

@@ -18,24 +18,6 @@ module Kirei
           instance_variable_get(var) == other.instance_variable_get(var)
         end
       end
-
-      sig do
-        params(
-          other: T.untyped,
-          array_mode: Kirei::Services::ArrayComparison::Mode,
-        ).returns(T::Boolean)
-      end
-      def equal_with_array_mode?(other, array_mode: Kirei::Services::ArrayComparison::Mode::STRICT)
-        return false unless instance_of?(other.class)
-
-        instance_variables.all? do |var|
-          one = instance_variable_get(var)
-          two = other.instance_variable_get(var)
-          next one == two unless one.is_a?(Array)
-
-          Kirei::Services::ArrayComparison.call(one, two, mode: array_mode)
-        end
-      end
     end
   end
 end

data/lib/kirei/helpers.rb

@@ -10,19 +10,13 @@ module Kirei
       sig { params(string: String).returns(String) }
       def underscore(string)
         string.gsub!(/([A-Z])(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) do
-          T.must((::Regexp.last_match(1) || ::Regexp.last_match(2))) << "_"
+          T.must(::Regexp.last_match(1) || ::Regexp.last_match(2)) << "_"
         end
         string.tr!("-", "_")
         string.downcase!
         string
       end
 
-      # Simplified version from Rails' ActiveSupport
-      sig { params(string: T.any(String, Symbol)).returns(T::Boolean) }
-      def blank?(string)
-        string.nil? || string.to_s.empty?
-      end
-
       sig { params(object: T.untyped).returns(T.untyped) }
       def deep_stringify_keys(object)
         deep_transform_keys(object) { _1.to_s rescue _1 } # rubocop:disable Style/RescueModifier
@@ -74,7 +68,7 @@ module Kirei
         when Hash
           # using `each_key` results in a `RuntimeError: can't add a new key into hash during iteration`
           # which is, because the receiver here does not necessarily have a `Hash` type
-          object.keys.each do |key| # rubocop:disable Style/HashEachMethods
+          object.keys.each do |key|
             value = object.delete(key)
             object[yield(key)] = deep_transform_keys!(value, &block)
           end

data/lib/kirei/logging/logger.rb

@@ -156,7 +156,7 @@ module Kirei
         hash = T.cast(hash, T::Hash[String, T.untyped])
 
         hash.each do |key, value|
-          new_prefix = Kirei::Helpers.blank?(prefix) ? key : "#{prefix}.#{key}"
+          new_prefix = prefix.empty? ? key : "#{prefix}.#{key}"
 
           case value
           when Hash

data/lib/kirei/logging/metric.rb

@@ -14,13 +14,11 @@ module Kirei
         ).void
       end
       def self.call(metric_name, value = 1, tags: {})
-        return if ENV["NO_METRICS"] == "true"
-
         inject_defaults(tags)
 
         # Do not `compact_blank` tags, since one might want to track empty strings/"false"/NULLs.
         # NOT having any tag doesn't tell the user if the tag was empty or not set at all.
-        StatsD.increment(metric_name, value, tags: tags)
+        App.config.metrics_backend.increment(metric_name, value, tags: tags)
       end
 
       sig { params(tags: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped]) }

data/lib/kirei/metrics/backend.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Metrics
+    class Backend
+      extend T::Sig
+      extend T::Helpers
+
+      abstract!
+
+      sig do
+        abstract.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def increment(name, value = 1, tags: {})
+      end
+
+      sig do
+        abstract.params(
+          name: String,
+          duration_ms: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def measure(name, duration_ms, tags: {})
+      end
+
+      sig do
+        abstract.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def gauge(name, value, tags: {})
+      end
+    end
+  end
+end

data/lib/kirei/metrics/logging_backend.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Metrics
+    class LoggingBackend < Backend
+      extend T::Sig
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def increment(name, value = 1, tags: {})
+        puts("[Metric] increment #{name} #{value} #{tags}")
+      end
+
+      sig do
+        override.params(
+          name: String,
+          duration_ms: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def measure(name, duration_ms, tags: {})
+        puts("[Metric] measure #{name} #{duration_ms}ms #{tags}")
+      end
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def gauge(name, value, tags: {})
+        puts("[Metric] gauge #{name} #{value} #{tags}")
+      end
+    end
+  end
+end

data/lib/kirei/metrics/null_backend.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Metrics
+    class NullBackend < Backend
+      extend T::Sig
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def increment(name, value = 1, tags: {})
+      end
+
+      sig do
+        override.params(
+          name: String,
+          duration_ms: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def measure(name, duration_ms, tags: {})
+      end
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def gauge(name, value, tags: {})
+      end
+    end
+  end
+end

data/lib/kirei/metrics/statsd_backend.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Metrics
+    class StatsdBackend < Backend
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        super
+        return if defined?(::StatsD)
+
+        raise "statsd-instrument is not loaded. Add `gem 'statsd-instrument'` to your Gemfile to use StatsdBackend."
+      end
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def increment(name, value = 1, tags: {})
+        ::StatsD.increment(name, value, tags: tags)
+      end
+
+      sig do
+        override.params(
+          name: String,
+          duration_ms: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def measure(name, duration_ms, tags: {})
+        ::StatsD.measure(name, duration_ms, tags: tags)
+      end
+
+      sig do
+        override.params(
+          name: String,
+          value: T.any(Integer, Float),
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def gauge(name, value, tags: {})
+        ::StatsD.gauge(name, value, tags: tags)
+      end
+    end
+  end
+end

data/lib/kirei/model/base_class_interface.rb

@@ -8,6 +8,7 @@ module Kirei
     module BaseClassInterface
       extend T::Sig
       extend T::Helpers
+
       interface!
 
       sig { abstract.params(hash: T.untyped).returns(T.untyped) }

data/lib/kirei/model/class_methods.rb

@@ -9,7 +9,7 @@ module Kirei
 
       # the attached class is the class that extends this module
       # e.g. "User", "Airport", ..
-      has_attached_class!
+      has_attached_class!(:out)
 
       include Kirei::Model::BaseClassInterface
 
@@ -85,13 +85,15 @@ module Kirei
       # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
       sig { override.params(attributes: T::Hash[T.any(Symbol, String), T.untyped]).void }
-      def wrap_jsonb_non_primivitives!(attributes)
+      def wrap_jsonb_non_primivitives!(attributes) # rubocop:disable Metrics/AbcSize
         # setting `@raw_db_connection.wrap_json_primitives = true`
         # only works on JSON primitives, but not on blank hashes/arrays
         return unless App.config.db_extensions.include?(:pg_json)
 
+        pgvector_enabled = App.config.db_extensions.include?(:pgvector)
+
         attributes.each_pair do |key, value|
-          if vector_column?(key.to_s)
+          if pgvector_enabled && vector_column?(key.to_s)
             attributes[key] = cast_to_vector(value)
           elsif value.is_a?(Hash) || value.is_a?(Array)
             attributes[key] = T.unsafe(Sequel).pg_jsonb_wrap(value)
@@ -104,6 +106,10 @@ module Kirei
       # also add `:pgvector` to the `App.config.db_extensions` array
       # and enable the vector extension on the database.
       #
+      # Note: Sequel caches `db.schema` results internally (Database#cache_schema is true by default),
+      # so this only hits the database once per table per app lifecycle.
+      # @see https://github.com/jeremyevans/sequel/blob/master/lib/sequel/extensions/schema_caching.rb
+      #
       sig { params(column_name: String).returns(T::Boolean) }
       def vector_column?(column_name)
         _col_name, col_info = T.let(

data/lib/kirei/model.rb

@@ -25,7 +25,7 @@ module Kirei
     # Delete keeps the original object intact. Returns true if the record was deleted.
     # Calling delete multiple times will return false after the first (successful) call.
     sig { returns(T::Boolean) }
-    def delete
+    def delete # rubocop:disable Naming/PredicateMethod
       count = self.class.query.where({ id: id }).delete
       count == 1
     end

data/lib/kirei/routing/base.rb

@@ -1,8 +1,7 @@
 # typed: strict
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/all
-
+# rubocop:disable Metrics
 module Kirei
   module Routing
     class Base
@@ -36,8 +35,10 @@ module Kirei
         #
 
         lookup_verb = http_verb == Verb::HEAD ? Verb::GET : http_verb
-        route = router.get(lookup_verb, req_path)
-        return NOT_FOUND if route.nil?
+        result = router.resolve(lookup_verb, req_path)
+        return NOT_FOUND if result.nil?
+
+        route, path_params = result
 
         router.current_env = env # expose the env to the controller
 
@@ -52,16 +53,23 @@ module Kirei
                  when Verb::POST, Verb::PUT, Verb::PATCH
                    # TODO: based on content-type, parse the body differently
                    #       built-in support for JSON & XML
-                   body = T.cast(env.fetch("rack.input"), T.any(IO, StringIO))
-                   res = Oj.load(body.read, Kirei::OJ_OPTIONS)
-                   body.rewind # TODO: maybe don't rewind if we don't need to?
-                   T.cast(res, T::Hash[String, T.untyped])
+                   body = env.fetch("rack.input")
+                   if body.nil? || !body.respond_to?(:read) || (body.respond_to?(:empty?) && body.empty?)
+                     {}
+                   else
+                     body = T.cast(body, T.any(IO, StringIO))
+                     res = Oj.load(body.read, Kirei::OJ_OPTIONS)
+                     body.rewind # TODO: maybe don't rewind if we don't need to?
+                     T.cast(res, T::Hash[String, T.untyped])
+                   end
                  when Verb::HEAD, Verb::DELETE, Verb::OPTIONS, Verb::TRACE, Verb::CONNECT
                    {}
                  else
                    T.absurd(http_verb)
         end
 
+        params.merge!(path_params)
+
         req_id = T.cast(env["HTTP_X_REQUEST_ID"], T.nilable(String))
         req_id ||= "req_#{App.environment}_#{SecureRandom.uuid}"
         Thread.current[:request_id] = req_id
@@ -120,7 +128,7 @@ module Kirei
         stop = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
         if start # early return for 404
           latency_in_ms = stop - start
-          ::StatsD.measure("request", latency_in_ms, tags: statsd_timing_tags)
+          App.config.metrics_backend.measure("request", latency_in_ms, tags: statsd_timing_tags)
 
           Kirei::Logging::Logger.call(
             level: status >= 500 ? Kirei::Logging::Level::ERROR : Kirei::Logging::Level::INFO,
@@ -154,6 +162,56 @@ module Kirei
         ]
       end
 
+      #
+      # Renders a JSON response. Accepts:
+      #   - String: treated as pre-serialized JSON (pass-through)
+      #   - Hash / Array: serialized via Oj.dump
+      #   - Object responding to #serialize (e.g. T::Struct): calls #serialize,
+      #     then Oj.dump if the result is not already a String
+      #   - Anything else: raises ArgumentError
+      #
+      sig do
+        params(
+          data: T.untyped,
+          status: Integer,
+          headers: T::Hash[String, String],
+        ).returns(RackResponseType)
+      end
+      def render_json(data, status: 200, headers: {})
+        body = case data
+               when String
+                 data
+               when Hash, Array
+                 Oj.dump(data, Kirei::OJ_OPTIONS)
+               else
+                 unless data.respond_to?(:serialize)
+                   raise ArgumentError,
+                         "render_json expects a String, Hash, Array, or an object responding to #serialize, " \
+                         "got #{data.class}"
+                 end
+
+                 result = data.serialize
+                 result.is_a?(String) ? result : Oj.dump(result, Kirei::OJ_OPTIONS)
+        end
+
+        render(body, status: status, headers: headers)
+      end
+
+      #
+      # Renders a JSON:API-compliant error response.
+      # Wraps an array of JsonApiError structs into { "errors": [...] }.
+      #
+      sig do
+        params(
+          errors: T::Array[Errors::JsonApiError],
+          status: Integer,
+          headers: T::Hash[String, String],
+        ).returns(RackResponseType)
+      end
+      def render_error(errors, status: 422, headers: {})
+        render_json({ "errors" => errors.map(&:serialize) }, status: status, headers: headers)
+      end
+
       sig { returns(T::Hash[String, String]) }
       def default_headers
         {
@@ -218,5 +276,4 @@ module Kirei
     end
   end
 end
-
-# rubocop:enable Metrics/all
+# rubocop:enable Metrics

data/lib/kirei/routing/route.rb

@@ -4,10 +4,22 @@
 module Kirei
   module Routing
     class Route < T::Struct
+      extend T::Sig
+
       const :verb, Verb
       const :path, String
       const :controller, T.class_of(Controller)
       const :action, String
+
+      sig { returns(T::Array[String]) }
+      def segments
+        @segments ||= T.let(path.split("/"), T.nilable(T::Array[String]))
+      end
+
+      sig { returns(T::Boolean) }
+      def dynamic?
+        segments.any? { |s| s.start_with?(":") }
+      end
     end
   end
 end

data/lib/kirei/routing/router.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+# rubocop:disable Metrics
+
 require("singleton")
 
 module Kirei
@@ -25,17 +27,26 @@ module Kirei
         T::Hash[String, Route]
       end
 
+      ResolveResult = T.type_alias do
+        T.nilable([Route, T::Hash[String, String]])
+      end
+
       sig { returns(T.nilable(T::Hash[String, T.untyped])) }
       attr_accessor :current_env
 
       sig { void }
       def initialize
         @routes = T.let({}, RoutesHash)
+        @dynamic_routes = T.let([], T::Array[Route])
       end
 
       sig { returns(RoutesHash) }
       attr_reader :routes
 
+      sig { returns(T::Array[Route]) }
+      attr_reader :dynamic_routes
+
+      # Looks up a static route by exact verb + path match. O(1).
       sig do
         params(
           verb: Verb,
@@ -47,13 +58,72 @@ module Kirei
         routes[key]
       end
 
+      # Resolves a request to a route and extracted path parameters.
+      # Tries static O(1) lookup first, then falls back to dynamic segment matching.
+      sig do
+        params(
+          verb: Verb,
+          path: String,
+        ).returns(ResolveResult)
+      end
+      def resolve(verb, path)
+        static_route = get(verb, path)
+        return [static_route, {}] unless static_route.nil?
+
+        match_dynamic(verb, path)
+      end
+
       sig { params(routes: T::Array[Route]).void }
       def self.add_routes(routes)
         routes.each do |route|
-          key = "#{route.verb.serialize} #{route.path}"
-          instance.routes[key] = route
+          if route.dynamic?
+            instance.dynamic_routes << route
+          else
+            key = "#{route.verb.serialize} #{route.path}"
+            instance.routes[key] = route
+          end
+        end
+      end
+
+      # Matches a request path against registered dynamic routes.
+      # Returns [Route, extracted_params] or nil.
+      sig do
+        params(
+          verb: Verb,
+          path: String,
+        ).returns(ResolveResult)
+      end
+      private def match_dynamic(verb, path)
+        request_segments = path.split("/")
+
+        dynamic_routes.each do |route|
+          next unless route.verb == verb
+
+          route_segments = route.segments
+          next unless route_segments.length == request_segments.length
+
+          path_params = T.let({}, T::Hash[String, String])
+          matched = T.let(true, T::Boolean)
+
+          route_segments.each_with_index do |route_seg, idx|
+            req_seg = T.must(request_segments[idx])
+
+            if route_seg.start_with?(":")
+              param_name = T.must(route_seg[1..])
+              path_params[param_name] = req_seg
+            elsif route_seg != req_seg
+              matched = false
+              break
+            end
+          end
+
+          return [route, path_params] if matched
         end
+
+        nil
       end
     end
   end
 end
+
+# rubocop:enable Metrics

data/lib/kirei/services/runner.rb

@@ -27,7 +27,7 @@ module Kirei
         result = service_result(service)
 
         metric_tags = Logging::Metric.inject_defaults({ "service.result" => result })
-        ::StatsD.measure(class_name, latency_in_ms, tags: metric_tags)
+        App.config.metrics_backend.measure(class_name, latency_in_ms, tags: metric_tags)
 
         logtags = {
           "service.name" => class_name.to_s,

data/lib/kirei/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Kirei
-  VERSION = "0.8.3"
+  VERSION = "0.9.0"
 end

data/lib/kirei.rb

@@ -13,7 +13,6 @@ require "bundler/setup"
 
 # Second: load all gems (runtime dependencies only)
 require "logger"
-require "statsd-instrument"
 require "sorbet-runtime"
 require "oj"
 require "rack"

data/sorbet/rbi/shims/statsd.rbi

@@ -0,0 +1,17 @@
+# typed: true
+
+# Minimal shim for `statsd-instrument`.
+# The gem is an optional dependency — this shim lets Sorbet
+# type-check `StatsdBackend` without requiring the gem at analysis time.
+module StatsD
+  extend T::Sig
+
+  sig { params(name: String, value: T.any(Integer, Float), tags: T.untyped).void }
+  def self.increment(name, value = 1, tags: {}); end
+
+  sig { params(name: String, value: T.any(Integer, Float), tags: T.untyped).void }
+  def self.measure(name, value, tags: {}); end
+
+  sig { params(name: String, value: T.any(Integer, Float), tags: T.untyped).void }
+  def self.gauge(name, value, tags: {}); end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kirei
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.9.0
 platform: ruby
 authors:
 - Ludwig Reinmiedl
@@ -51,20 +51,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
-- !ruby/object:Gem::Dependency
-  name: statsd-instrument
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: tzinfo-data
   requirement: !ruby/object:Gem::Requirement
@@ -165,6 +151,13 @@ files:
 - ".irbrc"
 - README.md
 - bin/kirei
+- cops/layout.yml
+- cops/lint.yml
+- cops/metrics.yml
+- cops/naming.yml
+- cops/rspec.yml
+- cops/style.yml
+- cops/types.yml
 - kirei.gemspec
 - lib/cli.rb
 - lib/cli/commands/new_app/base_directories.rb
@@ -189,6 +182,10 @@ files:
 - lib/kirei/logging/level.rb
 - lib/kirei/logging/logger.rb
 - lib/kirei/logging/metric.rb
+- lib/kirei/metrics/backend.rb
+- lib/kirei/metrics/logging_backend.rb
+- lib/kirei/metrics/null_backend.rb
+- lib/kirei/metrics/statsd_backend.rb
 - lib/kirei/model.rb
 - lib/kirei/model/base_class_interface.rb
 - lib/kirei/model/class_methods.rb
@@ -201,7 +198,6 @@ files:
 - lib/kirei/routing/route.rb
 - lib/kirei/routing/router.rb
 - lib/kirei/routing/verb.rb
-- lib/kirei/services/array_comparison.rb
 - lib/kirei/services/result.rb
 - lib/kirei/services/runner.rb
 - lib/kirei/version.rb
@@ -209,6 +205,7 @@ files:
 - sorbet/rbi/shims/base_model.rbi
 - sorbet/rbi/shims/domain.rbi
 - sorbet/rbi/shims/ruby.rbi
+- sorbet/rbi/shims/statsd.rbi
 homepage: https://github.com/swiknaba/kirei
 licenses:
 - MIT
@@ -229,7 +226,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Kirei is a typed Ruby micro/REST-framework for building scalable and performant
   microservices.

data/lib/kirei/services/array_comparison.rb

@@ -1,35 +0,0 @@
-# typed: strict
-# frozen_string_literal: true
-
-module Kirei
-  module Services
-    class ArrayComparison
-      extend T::Sig
-
-      class Mode < T::Enum
-        enums do
-          STRICT = new("strict")
-          IGNORE_ORDER = new("ignore_order")
-          IGNORE_ORDER_AND_DUPLICATES = new("ignore_order_and_duplicates")
-        end
-      end
-
-      sig do
-        params(
-          array_one: T::Array[T.untyped],
-          array_two: T::Array[T.untyped],
-          mode: Mode,
-        ).returns(T::Boolean)
-      end
-      def self.call(array_one, array_two, mode: Mode::STRICT)
-        case mode
-        when Mode::STRICT then array_one == array_two
-        when Mode::IGNORE_ORDER then array_one.sort == array_two.sort
-        when Mode::IGNORE_ORDER_AND_DUPLICATES then array_one.to_set == array_two.to_set
-        else
-          T.absurd(mode)
-        end
-      end
-    end
-  end
-end