kirei 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1926e641bc2fa378b9444e97f33c7aef0bd97ce3c277a38fc572f12d501acb77
-  data.tar.gz: 2cdaff92504ea20fac445d791da1f9557fe3fbe6f4f780eab70c9022feacb3e1
+  metadata.gz: 85f4c3fa6b6cc6dd3492be32c1fbc959b15b7dce43ab2de1435ce9129c757474
+  data.tar.gz: d80206078da55131d0c1c5c33212303f6eccc5492727093e172b4926673ff201
 SHA512:
-  metadata.gz: 4111679c635210bd6a9389c839c2665e5fea9a1e4bd3e6186725e89022a8964cf7a2dc8c2b5347eaf76962b327a7c0a77243cfc7c6ac214e01f59592a08a132f
-  data.tar.gz: 8aaf9c748f52d790cc2be69cb29087c96f1ad1001ee629555b5727d93770a1b73be72fbb62a8d1b3993a3ef75676832463b401cb265e5dd18a277d9706b9fc68
+  metadata.gz: f48edabdddd9a567ad85f26bbf6bedc723258148426f9125cb45c48799d14695c6ad360bff9c9fa9ce29ea6b1804dd991b09d32b212f076de1ac1ef71c4abd79
+  data.tar.gz: dcdb445a12d614ff37a5396856bcade43e133546163f5adbe3a30b114e1973977de613d2ea486bf8081cdf410776835413f9a6fe2b786deb53586e87e273d00a

data/README.md

@@ -55,7 +55,7 @@ Find a test app in the [spec/test_app](spec/test_app) directory. It is a fully f
 
 #### Models
 
-All models must inherit from `T::Struct` and include `Kirei::Model`. They must implement `id` which must hold the primary key of the table. The primary key must be named `id` and be of type `T.any(String, Integer)`.
+All models must inherit from `T::Struct` and include `Kirei::Model`. They must implement `id` which must hold the primary key of the table. The primary key must be named `id` and be a `String`. Kirei generates it on `create` with `generate_human_id` (for example `user_K7mQ2xRtB9vN`) unless the caller passes one; database sequences are not supported. Override `human_id_length` or `human_id_prefix` per model to change the format.
 
 Kirei models are immutable by convention - all properties are defined using `const` and updating a record returns a new instance rather than mutating the original. This immutability, combined with strict typing, makes them naturally suitable for both traditional data-centric applications and domain-driven design approaches.
 
@@ -66,7 +66,7 @@ class User < T::Struct
   extend T::Sig
   include Kirei::Model
 
-  const :id, T.any(String, Integer)
+  const :id, String
   const :name, String
 end
 
@@ -114,11 +114,11 @@ Kirei provides support for Domain-Driven Design patterns through `Kirei::Domain:
 class Flight < T::Struct
   include Kirei::Domain::Entity
 
-  const :id, Integer
+  const :id, String
 
   const :flight_number, String
-  const :departure_airport_id, Integer
-  const :arrival_airport_id, Integer
+  const :departure_airport_id, String
+  const :arrival_airport_id, String
   const :scheduled_departure_at, Time
   const :status, String
 
@@ -354,6 +354,43 @@ 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`.
 
+### Web servers and request bodies
+
+Kirei runs on any Rack server. It routes by `PATH_INFO`, accepts any readable `rack.input`, and keeps the request env fiber-local, so both thread-based servers (Puma) and fiber-based servers (Falcon) work. With Falcon, also set `config.db_global_extensions = [:fiber_concurrency]` (see below).
+
+JSON and form bodies are buffered in memory. Bound them per app:
+
+```ruby
+class MyApp < Kirei::App
+  config.max_request_body_bytes = 65_536 # nil (default) means unlimited
+end
+```
+
+A larger body gets a `413` JSON:API error with code `payload_too_large`. Multipart uploads stream to tempfiles through Rack and are not limited by this setting. Malformed JSON returns `400` with code `malformed_json`, and a JSON body that is not an object returns `400` with code `invalid_json_body`.
+
+### Database connection
+
+`Kirei::App.raw_db_connection` opens one Sequel database per process. Configure it in your app:
+
+```ruby
+class MyApp < Kirei::App
+  # Global extensions change Sequel itself and are loaded via `Sequel.extension`
+  # before the connection exists. Use `:fiber_concurrency` with Async/Falcon.
+  config.db_global_extensions = [:fiber_concurrency]
+
+  # Database extensions are loaded on the connection via `Sequel::Database#extension`.
+  config.db_extensions += [:pgvector]
+
+  # Pool bounds and per-connection session setup; `nil` keeps the Sequel default.
+  config.db_max_connections = Integer(ENV.fetch("DB_POOL_SIZE", "5"))
+  config.db_pool_timeout = Float(ENV.fetch("DB_POOL_TIMEOUT", "2"))
+  config.db_connect_timeout = 5
+  config.db_connect_sqls = ["SET statement_timeout = '10s'"]
+end
+```
+
+A global extension passed to `db_extensions` is silently ignored by Sequel, so keep the two lists apart.
+
 ### Goes well with these gems
 
 * [pagy](https://github.com/ddnexus/pagy) for pagination

data/lib/kirei/app.rb

@@ -73,19 +73,34 @@ module Kirei
         @raw_db_connection = T.let(@raw_db_connection, T.nilable(Sequel::Database))
         return @raw_db_connection unless @raw_db_connection.nil?
 
+        config.db_global_extensions.each { |ext| Sequel.extension(ext) }
+
         # calling "Sequel.connect" creates a new connection
-        @raw_db_connection = Sequel.connect(App.config.db_url || default_db_url)
+        database = Sequel.connect(App.config.db_url || default_db_url, db_connect_options)
+        @raw_db_connection = apply_db_extensions(database)
+      end
 
-        config.db_extensions.each do |ext|
-          T.cast(@raw_db_connection, Sequel::Database).extension(ext)
-        end
+      sig { params(database: Sequel::Database).returns(Sequel::Database) }
+      private def apply_db_extensions(database)
+        config.db_extensions.each { |ext| database.extension(ext) }
 
         if config.db_extensions.include?(:pg_json)
           # https://github.com/jeremyevans/sequel/blob/5.75.0/lib/sequel/extensions/pg_json.rb#L8
-          @raw_db_connection.wrap_json_primitives = true
+          database.wrap_json_primitives = true
         end
 
-        @raw_db_connection
+        database
+      end
+
+      sig { returns(T::Hash[Symbol, T.any(Integer, Float, T::Array[String])]) }
+      private def db_connect_options
+        connect_sqls = config.db_connect_sqls
+        {
+          max_connections: config.db_max_connections,
+          pool_timeout: config.db_pool_timeout,
+          connect_timeout: config.db_connect_timeout,
+          connect_sqls: connect_sqls.empty? ? nil : connect_sqls,
+        }.compact
       end
     end
   end

data/lib/kirei/config.rb

@@ -28,11 +28,29 @@ module Kirei
 
     prop :app_name, String, default: "kirei"
 
+    # Database extensions are loaded on the connection via `Sequel::Database#extension`.
+    # They add behaviour to one database object, e.g. column type parsing.
+    #
     # must use "pg_json" to parse jsonb columns to hashes
     #
     # Source: https://github.com/jeremyevans/sequel/blob/5.75.0/lib/sequel/extensions/pg_json.rb
-    prop :db_extensions, T::Array[Symbol], default: %i[pg_json pg_array] # add "fiber_concurrency" by default, too?
+    prop :db_extensions, T::Array[Symbol], default: %i[pg_json pg_array]
+    # Global extensions are loaded via `Sequel.extension` before the connection is created.
+    # They change Sequel itself, not a database object, e.g. `:fiber_concurrency` switches the
+    # concurrency primitive from `Thread.current` to `Fiber.current` for Async/Falcon servers.
+    # Loading one on a database object is silently ignored.
+    #
+    # Source: https://github.com/jeremyevans/sequel/blob/5.75.0/doc/extensions.rdoc
+    prop :db_global_extensions, T::Array[Symbol], default: []
     prop :db_url, T.nilable(String)
+    # Connection pool bounds passed to `Sequel.connect`. `nil` keeps the Sequel default.
+    #
+    # Source: https://github.com/jeremyevans/sequel/blob/5.75.0/doc/opening_databases.rdoc
+    prop :db_max_connections, T.nilable(Integer)
+    prop :db_pool_timeout, T.nilable(Float)
+    prop :db_connect_timeout, T.nilable(Integer)
+    # SQL statements run on every new connection, e.g. session timeouts.
+    prop :db_connect_sqls, T::Array[String], default: []
     # Extra or unknown properties present in the Hash do not raise exceptions at runtime
     # unless the optional strict argument to from_hash is passed
     #
@@ -40,5 +58,10 @@ module Kirei
     prop :db_strict_type_resolving, T.nilable(T::Boolean), default: nil
 
     prop :allowed_origins, T::Array[String], default: []
+
+    # Upper bound for JSON and form request bodies, which Kirei buffers in memory.
+    # Requests above it get a 413 JSON:API error. `nil` means no limit.
+    # Multipart uploads stream to tempfiles via Rack and are not subject to it.
+    prop :max_request_body_bytes, T.nilable(Integer), default: nil
   end
 end

data/lib/kirei/model/class_methods.rb

@@ -54,20 +54,19 @@ module Kirei
         resolve(query.all)
       end
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
-      # default values defined in the model are used, if omitted in the hash
+      # Default values defined in the model are used if omitted in the hash.
+      # A missing `id` is filled with `generate_human_id`; primary keys are
+      # always application-generated strings, never database sequences.
       sig do
         override.params(
           hash: T::Hash[Symbol, T.untyped],
         ).returns(T.attached_class)
       end
-      def create(hash)
+      def create(hash) # rubocop:disable Metrics/AbcSize
+        attributes = hash.key?(:id) ? hash : hash.merge(id: generate_human_id)
         # instantiate a new object to ensure we use default values defined in the model
-        without_id = !hash.key?(:id)
-        hash[:id] = "kirei-fake-id" if without_id
-        new_record = from_hash(Helpers.deep_stringify_keys(hash))
+        new_record = from_hash(Helpers.deep_stringify_keys(attributes))
         all_attributes = T.let(new_record.serialize, T::Hash[String, T.untyped])
-        all_attributes.delete("id") if without_id && all_attributes["id"] == "kirei-fake-id"
 
         wrap_jsonb_non_primivitives!(all_attributes)
 
@@ -78,11 +77,10 @@ module Kirei
           all_attributes["updated_at"] = Time.now.utc
         end
 
-        pkey = T.let(query.insert(all_attributes), String)
+        query.insert(all_attributes)
 
-        T.must(find_by({ id: pkey }))
+        T.must(find_by({ id: new_record.id }))
       end
-      # 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) # rubocop:disable Metrics/AbcSize
@@ -180,9 +178,10 @@ module Kirei
         resolve(query.limit(1), strict_loading).first
       end
 
-      # defaults to 6
+      # 12 characters from a 55-character alphabet; collisions are negligible
+      # even for large tables. Override per model for shorter, hand-typed ids.
       sig { override.returns(Integer) }
-      def human_id_length = 6
+      def human_id_length = 12
 
       # defaults to "model_name" (table_name without the trailing "s")
       sig { override.returns(String) }

data/lib/kirei/routing/base.rb

@@ -8,6 +8,9 @@ module Kirei
       extend T::Sig
 
       NOT_FOUND = T.let([404, {}, ["Not Found"]], RackResponseType) # rubocop:disable Style/MutableConstant
+      # Oj raises EncodingError for malformed input in the modes Kirei uses, and
+      # Oj::ParseError for other parse failures.
+      JSON_PARSE_ERRORS = T.let([Oj::ParseError, EncodingError].freeze, T::Array[T.class_of(StandardError)])
 
       sig { params(params: T::Hash[String, T.untyped]).void }
       def initialize(params: {})
@@ -28,7 +31,7 @@ module Kirei
         status = 500 # we use it in the "ensure" block, so we need to define early (Sorbet doesn't like `status ||= 418`)
 
         http_verb = Verb.deserialize(env.fetch("REQUEST_METHOD"))
-        req_path = T.cast(env.fetch("REQUEST_PATH"), String)
+        req_path = request_path(env)
         #
         # TODO: reject requests from unexpected hosts -> allow configuring allowed hosts in a `cors.rb` file
         #   ( offer a scaffold for this file )
@@ -52,17 +55,7 @@ module Kirei
                      [k, v]
                    end
                  when Verb::POST, Verb::PUT, Verb::PATCH
-                   # TODO: based on content-type, parse the body differently
-                   #       built-in support for JSON & XML
-                   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
+                   parse_request_body(env)
                  when Verb::HEAD, Verb::DELETE, Verb::OPTIONS
                    {}
                  else
@@ -122,6 +115,13 @@ module Kirei
           headers,
           response_body,
         ]
+      rescue RequestRejected => e
+        status = e.status
+        error = Errors::JsonApiError.new(code: e.code, detail: e.message)
+        body = Oj.dump({ "errors" => [error.serialize] }, Kirei::OJ_OPTIONS)
+        response_body = [body]
+
+        [status, { "Content-Type" => "application/json; charset=utf-8" }, response_body]
       rescue StandardError => e
         status = 500
 
@@ -162,10 +162,21 @@ module Kirei
 
         # reset global variables after the request has been served
         # and after all "after" hooks have run to avoid leaking
+        router.current_env = nil
         Thread.current[:enduser_id] = nil
         Thread.current[:request_id] = nil
       end
 
+      # `PATH_INFO` is the Rack-specified key. `REQUEST_PATH` is a Puma
+      # extension that Falcon does not set.
+      sig { params(env: RackEnvType).returns(String) }
+      private def request_path(env)
+        path = T.cast(env.fetch("PATH_INFO", nil), T.nilable(String))
+        return path unless path.nil? || path.empty?
+
+        T.cast(env.fetch("REQUEST_PATH"), String)
+      end
+
       #
       # * "status": defaults to 200
       # * "headers": Kirei adds some default headers for security, but the user can override them
@@ -317,6 +328,81 @@ module Kirei
 
         result
       end
+
+      #
+      # Body parsing by Content-Type:
+      #   - multipart/form-data: form fields plus uploaded files wrapped in Rack::Multipart::UploadedFile
+      #   - application/json: JSON object
+      #   - anything else: JSON first, URL-encoded form data as fallback
+      #
+      # `rack.input` is only required to respond to `read`; Puma passes an IO or
+      # StringIO, Falcon passes a Protocol::Rack::Input.
+      #
+      sig { params(env: RackEnvType).returns(T::Hash[String, T.untyped]) }
+      private def parse_request_body(env)
+        content_type = T.cast(env.fetch("CONTENT_TYPE", ""), String)
+        body = env["rack.input"]
+        return {} if body.nil? || !body.respond_to?(:read)
+
+        return wrap_uploaded_files(Rack::Request.new(env).params) if content_type.include?("multipart/form-data")
+
+        raw = read_bounded_body(body)
+        return {} if raw.empty?
+
+        return parse_json_object(raw) if content_type.include?("application/json")
+
+        begin
+          parsed = Oj.load(raw, Kirei::OJ_OPTIONS)
+          return parsed if parsed.is_a?(Hash)
+        rescue *JSON_PARSE_ERRORS
+          # fall through to form data
+        end
+
+        T.cast(Rack::Request.new(env).params, T::Hash[String, T.untyped])
+      end
+
+      sig { params(body: T.untyped).returns(String) }
+      private def read_bounded_body(body)
+        limit = App.config.max_request_body_bytes
+        raw = limit.nil? ? body.read : body.read(limit + 1)
+        body.rewind if body.respond_to?(:rewind)
+        raw = T.cast(raw || "", String)
+        if !limit.nil? && raw.bytesize > limit
+          raise RequestRejected.new(
+            status: 413,
+            code: "payload_too_large",
+            detail: "Request body exceeds #{limit} bytes",
+          )
+        end
+
+        raw
+      end
+
+      sig { params(raw: String).returns(T::Hash[String, T.untyped]) }
+      private def parse_json_object(raw)
+        parsed = Oj.load(raw, Kirei::OJ_OPTIONS)
+        unless parsed.is_a?(Hash)
+          raise RequestRejected.new(status: 400, code: "invalid_json_body", detail: "JSON body must be an object")
+        end
+
+        parsed
+      rescue *JSON_PARSE_ERRORS => e
+        raise RequestRejected.new(status: 400, code: "malformed_json", detail: e.message)
+      end
+
+      # Rack's multipart parser yields a Hash (symbol keys) per uploaded file; wrap it in a typed object.
+      sig { params(params: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped]) }
+      private def wrap_uploaded_files(params)
+        params.transform_values do |value|
+          next value unless value.is_a?(Hash) && value.key?(:tempfile)
+
+          Rack::Multipart::UploadedFile.new(
+            io: value.fetch(:tempfile),
+            content_type: value.fetch(:type, "application/octet-stream"),
+            filename: value.fetch(:filename),
+          )
+        end
+      end
     end
   end
 end

data/lib/kirei/routing/request_rejected.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Routing
+    # Raised while reading a request body when the request itself is at fault.
+    # `Base#call` renders it as a JSON:API error with the given status.
+    class RequestRejected < StandardError
+      extend T::Sig
+
+      sig { returns(Integer) }
+      attr_reader :status
+
+      sig { returns(String) }
+      attr_reader :code
+
+      sig { params(status: Integer, code: String, detail: String).void }
+      def initialize(status:, code:, detail:)
+        @status = status
+        @code = code
+        super(detail)
+      end
+    end
+  end
+end

data/lib/kirei/routing/router.rb

@@ -31,8 +31,18 @@ module Kirei
         T.nilable([Route, T::Hash[String, String]])
       end
 
-      sig { returns(T.nilable(T::Hash[String, T.untyped])) }
-      attr_accessor :current_env
+      # The router is a process-wide singleton, but a request env must be
+      # scoped to the request. `Thread.current[]` is fiber-local, so this is
+      # safe for both thread-based (Puma) and fiber-based (Falcon) servers.
+      sig { returns(T.nilable(RackEnvType)) }
+      def current_env
+        Thread.current[:kirei_current_env]
+      end
+
+      sig { params(env: T.nilable(RackEnvType)).returns(T.nilable(RackEnvType)) }
+      def current_env=(env)
+        Thread.current[:kirei_current_env] = env
+      end
 
       sig { void }
       def initialize

data/lib/kirei/version.rb

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

data/sorbet/rbi/shims/base_model.rbi

@@ -6,7 +6,7 @@ module Kirei
     include Kernel # "self" is a class since we include the module in a class
     include T::Props::Serializable
 
-    sig { returns(T.any(String, Integer)) }
+    sig { returns(String) }
     def id; end
 
     module ClassMethods

data/sorbet/rbi/shims/sequel_pg_json.rbi

@@ -0,0 +1,10 @@
+# typed: strict
+
+# The pg_json database extension adds this setter at runtime via
+# `Sequel::Database#extension(:pg_json)`; Tapioca cannot see it.
+#
+# Source: https://github.com/jeremyevans/sequel/blob/5.75.0/lib/sequel/extensions/pg_json.rb#L8
+class Sequel::Database
+  sig { params(value: T::Boolean).returns(T::Boolean) }
+  def wrap_json_primitives=(value); end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kirei
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Ludwig Reinmiedl
@@ -196,6 +196,7 @@ files:
 - lib/kirei/routing/rack_env_type.rb
 - lib/kirei/routing/rack_response_type.rb
 - lib/kirei/routing/request.rb
+- lib/kirei/routing/request_rejected.rb
 - lib/kirei/routing/route.rb
 - lib/kirei/routing/router.rb
 - lib/kirei/routing/verb.rb
@@ -206,6 +207,7 @@ files:
 - sorbet/rbi/shims/base_model.rbi
 - sorbet/rbi/shims/domain.rbi
 - sorbet/rbi/shims/ruby.rbi
+- sorbet/rbi/shims/sequel_pg_json.rbi
 - sorbet/rbi/shims/statsd.rbi
 homepage: https://github.com/swiknaba/kirei
 licenses:
@@ -227,7 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Kirei is a typed Ruby micro/REST-framework for building scalable and performant
   microservices.