kirei 0.6.3 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dec07a03cbf5ed8ceb535f60fef750df94039a2bd3880f219ccccefa4335f60
-  data.tar.gz: f2a2796a4bcbe2aa6b8a526887c33ee22095c0afedf95e7e467b01b1e033b0ae
+  metadata.gz: f72e562a33b62988fd08b474ad821c50c35e7439a2fe6eb0e5909b7310099ddc
+  data.tar.gz: c1550bab74543280e4314b1847c8cc2ac80c575e2175efdb2c57bddeb0cd7f95
 SHA512:
-  metadata.gz: 1eab2d1497a5592d5a7fe55d669d94a55aeecbc44744bf46b1d5349658916584d6eace11032ef723f9d034bcac834d41acf8acc90f9d87922f38802bf1793567
-  data.tar.gz: dc84e7e1bb9125909c81e40e66fc6e687abe8b1de928423d48b5a26a6c4ea23fd67e02953708bea25fbe448e5ce952f294ec54a6c8b74477f3dd269f891195ce
+  metadata.gz: ff42246d1757114996bf8094d80b47ebe2945e1df8551837389cad6c8dc7b96138ac398131d3b6ad07c7c0360b7758a77a06c3557716f22a07e6e4f99085a8bb
+  data.tar.gz: c7ff2ebedf28620e1ec16774b3ff07eb4007fdc76c59c925aa9f3161c452075123e8e4ae17e2786c1a3016f81df0e0c93528813fb879a950a9cec41952351619

data/README.md

@@ -55,6 +55,10 @@ Find a test app in the [spec/test_app](spec/test_app) directory. It is a fully f
 
 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)`.
 
+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.
+
+In a domain-driven design, `Kirei::Model` serves as the persistence layer, while domain concepts are expressed through `Entity` and `ValueObject`. The domain layer might combine or transform data from multiple models to match the domain's understanding, keeping the internal data structure separate from the public interface.
+
 ```ruby
 class User < T::Struct
   extend T::Sig
@@ -99,6 +103,61 @@ first_user = User.resolve_first(query) # T.nilable(User)
 first_user = User.from_hash(query.first.stringify_keys)
 ```
 
+#### Domain Objects
+
+Kirei provides support for Domain-Driven Design patterns through `Kirei::Domain::Entity` and `Kirei::Domain::ValueObject`. Here's how to use them:
+
+```ruby
+# An Entity is identified by its ID
+class Flight < T::Struct
+  include Kirei::Domain::Entity
+
+  const :id, Integer
+
+  const :flight_number, String
+  const :departure_airport_id, Integer
+  const :arrival_airport_id, Integer
+  const :scheduled_departure_at, Time
+  const :status, String
+
+  sig { returns(T::Boolean) }
+  def can_board?
+    Time.now.utc <= scheduled_departure_at && status == 'on_time'
+  end
+end
+
+# A Value Object is identified by its attributes
+# I.e. two Coordinates with the same lat/long will be equal
+# regardless of object identity
+class Coordinates < T::Struct
+  include Kirei::Domain::ValueObject
+
+  const :latitude, Float
+  const :longitude, Float
+
+  sig { returns(String) }
+  def to_s
+    "#{latitude},#{longitude}"
+  end
+
+  sig { params(other_coords: Coordinates).returns(Float) }
+  def distance_to(other_coords)
+    # Implement e.g. Haversine here.
+  end
+end
+
+# Usage example
+coords = Coordinates.new(latitude: 37.6188, longitude: -122.3750)
+coords2 = Coordinates.new(latitude: 37.6188, longitude: -122.3750)
+
+coords == coords2 # true
+
+flight = Flight.new(id: 123, flight_number: 'UA123', status: 'on_time', scheduled_departure_at: Time.now.utc)
+flight2 = Flight.new(id: 123, flight_number: 'UA123', status: 'delayed', scheduled_departure_at: Time.now.utc)
+
+flight == flight2 # true - same entity even with different status
+```
+
 #### Database Migrations
 
 Read the [Sequel Migrations](https://github.com/jeremyevans/sequel/blob/5.78.0/doc/schema_modification.rdoc) documentation for detailed information.
@@ -226,6 +285,31 @@ module Airports
 end
 ```
 
+### 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
+
+### Middlewares
+
+If you place custom middlewares under `config/middleware/*.rb`, they will be automatically loaded, see [app.rb](spec/test_app/app.rb) "load configs".
+
+However, you still need to `use` them in the `config.ru` file, see the generated [config.ru](spec/test_app/config.ru) file, this gives you full control over the order in which middlewares are executed:
+
+```ruby
+# Load middlewares here
+use(Rack::Reloader, 0) if TestApp.environment == "development"
+
+# add more custom middlewares here, e.g.
+use(Middleware::Example)
+
+# Launch the app
+run(TestApp.new)
+```
+
+Middleware provided by a gem like [rack-session](https://github.com/rack/rack-session) must be added to the `config.ru` file as well if you want to use it.
+
 ## Contributions
 
 We welcome contributions from the community. Before starting work on a major feature, please get in touch with us either via email or by opening an issue on GitHub. "Major feature" means anything that changes user-facing features or significant changes to the codebase itself.

data/kirei.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   spec.description = <<~TXT
     Kirei is a Ruby micro/REST-framework for building scalable and performant microservices.
     It is built from the ground up to be clean and easy to use.
-    It is a Rack app, and uses Sorbet for typing, Sequel as an ORM, Zeitwerk for autoloading, and Puma as a web server.
+    It is a Rack app, and uses Sorbet for typing, Sequel as an ORM, and Zeitwerk for autoloading.
     It strives to have zero magic and to be as explicit as possible.
   TXT
   spec.homepage = "https://github.com/swiknaba/kirei"
@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
     "kirei.gemspec",
     ".irbrc",
     "lib/**/*",
-    # do not include RBIs for gems, because users might use different verions
+    # do not include RBIs for gems, because users might use different versions
     "sorbet/rbi/dsl/**/*.rbi",
     "sorbet/rbi/shims/**/*.rbi",
     "LICENSE",
@@ -44,6 +44,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Utilities
+  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"

data/lib/cli/commands/new_app/files/app.rb

@@ -43,7 +43,9 @@ module Cli
               loader.setup
 
               # Fifth: load configs
-              Dir[File.join(__dir__, "config", "*.rb")].each { require(_1) }
+              Dir[File.join(__dir__, "config", "**", "*.rb")].each do |cnf|
+                require(cnf) unless cnf.split("/").include?("initializers")
+              end
 
               class #{app_name} < Kirei::App
                 # Kirei configuration

data/lib/cli/commands/new_app/files/db_rake.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 # rubocop:disable Metrics/ClassLength
 
@@ -166,33 +166,51 @@ module Cli
                   db = #{app_name}.raw_db_connection
                   model_file_name = args[:model_file_name]&.to_s
 
-                  models_dir = #{app_name}.root
+                  app_root_dir = TestApp.root
+                  app_dir = File.join(TestApp.root, "app")
 
-                  Dir.glob("app/models/**/*.rb").each do |model_file|
+                  Dir.glob("app/**/*.rb").each do |model_file|
                     next if !model_file_name.nil? && model_file == model_file_name
 
-                    model_path = File.expand_path(model_file, models_dir)
-                    modules = model_file.gsub("app/models/", "").gsub(".rb", "").split("/").map { |mod| Zeitwerk::Inflector.new.camelize(mod, model_path) }
-                    const_name = modules.join("::")
-                    model_klass = Object.const_get(const_name)
-                    next unless model_klass.ancestors.include?(Kirei::Model)
+                    model_path = File.expand_path(model_file, app_root_dir)
+                    loader = Zeitwerk::Registry.loaders.find { |l| l.tag == "app" }
+
+                    full_path = File.expand_path(model_file, app_root_dir)
+                    klass_constant_name = loader.inflector.camelize(File.basename(model_file, ".rb"), full_path)
+
+                    #
+                    # root namespaces in Zeitwerk are flattend, e.g. if "app/models" is a root namespace
+                    # then a file "app/models/airport.rb" is loaded as "::Airport".
+                    # if it weren't a root namespace, it would be "::Models::Airport".
+                    #
+                    root_dir_namespaces = loader.dirs.filter_map { |dir| dir == app_dir ? nil : Pathname.new(dir).relative_path_from(Pathname.new(app_dir)).to_s }
+                    relative_path = Pathname.new(full_path).relative_path_from(Pathname.new(app_dir)).to_s
+                    root_dir_of_model = root_dir_namespaces.find { |root_dir| relative_path.start_with?(root_dir) }
+                    relative_path.sub!("\#{root_dir_of_model}/", "") unless root_dir_of_model.nil? || root_dir_of_model.empty?
+
+                    namespace_parts = relative_path.split("/")
+                    namespace_parts.pop
+                    namespace_parts.map! { |part| loader.inflector.camelize(part, full_path) }
+
+                    constant_name = "\#{namespace_parts.join('::')}::\#{klass_constant_name}"
+
+                    model_klass = Object.const_get(constant_name)
+                    next unless model_klass.respond_to?(:table_name)
 
                     table_name = model_klass.table_name
                     schema = db.schema(table_name)
 
                     schema_comments = format_schema_comments(table_name, schema)
+                    file_content = File.read(model_path)
 
-                    file_contents = File.read(model_path)
-
-                    # Remove existing schema info comments if present
-                    updated_contents = file_contents.sub(/# == Schema Info\\n(.*?)(\\n#\\n)?\\n(?=\\s*(?:class|module))/m, "")
+                    file_content_without_schema_info = file_content.sub(/# == Schema Info\\n(.*?)(\\n#\\n)?\\n(?=\\s*(?:class|module))/m, "")
 
                     # Insert the new schema comments before the module/class definition
-                    first_const = modules.first
-                    first_module_or_class = modules.count == 1 ? "class #{first_const}" : "module #{first_const}"
-                    modified_contents = updated_contents.sub(/(A|\n)(#{first_module_or_class})/m, "\\1#{schema_comments}\n\n\\2")
+                    first_module = namespace_parts.first
+                    first_module_or_class = first_module.nil? ? "class \#{klass_constant_name}" : "module \#{first_module}"
+                    modified_content = file_content_without_schema_info.sub(/(A|\\n)(\#{first_module_or_class})/m, "\\\\1\#{schema_comments}\\n\\n\\\\2")
 
-                    File.write(model_path, modified_contents)
+                    File.write(model_path, modified_content)
                   end
                 end
               end
@@ -215,7 +233,7 @@ module Cli
                   type ||= info[:db_type]
                   null = info[:allow_null] ? 'null' : 'not null'
                   primary_key = info[:primary_key] ? ', primary key' : ''
-                  lines << "#  \#{name.to_s.ljust(20)}:\#{type}    \#{null}\#{primary_key}"
+                  lines << "#  \#{name.to_s.ljust(20)}:\#{type.to_s.ljust(20)}\#{null}\#{primary_key}"
                 end
                 lines.join("\\n") + "\\n#"
               end

data/lib/cli/commands/start.rb

@@ -12,6 +12,10 @@ module Cli
           app_name = app_name.gsub(/[-\s]/, "_")
           app_name = app_name.split("_").map(&:capitalize).join if app_name.include?("_")
           NewApp::Execute.call(app_name: app_name)
+        when "test"
+          # for internal testing
+          app_name = args[1] || "TestApp"
+          # test single services here
         else
           Kirei::Logging::Logger.logger.info("Unknown command")
         end

data/lib/kirei/config.rb

@@ -30,7 +30,7 @@ module Kirei
     # 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]
+    prop :db_extensions, T::Array[Symbol], default: %i[pg_json pg_array] # add "fiber_concurrency" by default, too?
     prop :db_url, T.nilable(String)
     # Extra or unknown properties present in the Hash do not raise exceptions at runtime
     # unless the optional strict argument to from_hash is passed

data/lib/kirei/controller.rb

@@ -40,5 +40,38 @@ module Kirei
       @after_hooks ||= T.let(Set.new, Routing::NilableHooksType)
       @after_hooks.add(block) if block
     end
+
+    sig { returns(String) }
+    def req_host
+      env.fetch("HTTP_HOST")
+    end
+
+    sig { returns(String) }
+    def req_domain
+      T.must(req_host.split(":").first).split(".").last(2).join(".")
+    end
+
+    sig { returns(T.nilable(String)) }
+    def req_subdomain
+      parts = T.must(req_host.split(":").first).split(".")
+      return if parts.size <= 2
+
+      T.must(parts[0..-3]).join(".")
+    end
+
+    sig { returns(Integer) }
+    def req_port
+      env.fetch("SERVER_PORT")&.to_i
+    end
+
+    sig { returns(T::Boolean) }
+    def req_ssl?
+      env.fetch("HTTPS", env.fetch("rack.url_scheme", "http")) == "https"
+    end
+
+    sig { returns(T::Hash[String, T.untyped]) }
+    private def env
+      T.cast(@router.current_env, T::Hash[String, T.untyped])
+    end
   end
 end

data/lib/kirei/domain/entity.rb

@@ -0,0 +1,22 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Domain
+    module Entity
+      extend T::Sig
+      extend T::Helpers
+
+      sig { returns(T.class_of(T::Struct)) }
+      def class; super; end # rubocop:disable all
+
+      sig { params(other: T.nilable(Kirei::Domain::Entity)).returns(T::Boolean) }
+      def ==(other)
+        return false unless other.is_a?(Kirei::Domain::Entity)
+        return false unless instance_of?(other.class)
+
+        id == other.id
+      end
+    end
+  end
+end

data/lib/kirei/domain/value_object.rb

@@ -0,0 +1,41 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Domain
+    module ValueObject
+      extend T::Sig
+      extend T::Helpers
+
+      sig { returns(T.class_of(T::Struct)) }
+      def class; super; end # rubocop:disable all
+
+      sig { params(other: T.untyped).returns(T::Boolean) }
+      def ==(other)
+        return false unless instance_of?(other.class)
+
+        instance_variables.all? do |var|
+          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/routing/base.rb

@@ -35,10 +35,13 @@ module Kirei
         # -> use https://github.com/cyu/rack-cors ?
         #
 
-        route = router.get(http_verb, req_path)
+        lookup_verb = http_verb == Verb::HEAD ? Verb::GET : http_verb
+        route = router.get(lookup_verb, req_path)
         return NOT_FOUND if route.nil?
 
-        params = case route.verb
+        router.current_env = env # expose the env to the controller
+
+        params = case http_verb
                  when Verb::GET
                    query = T.cast(env.fetch("QUERY_STRING"), String)
                    query.split("&").to_h do |p|
@@ -48,14 +51,15 @@ module Kirei
                    end
                  when Verb::POST, Verb::PUT, Verb::PATCH
                    # TODO: based on content-type, parse the body differently
-                   #       build-in support for JSON & XML
+                   #       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])
-                 else
-                   Logging::Logger.logger.warn("Unsupported HTTP verb: #{http_verb.serialize} send to #{req_path}")
+                 when Verb::HEAD, Verb::DELETE, Verb::OPTIONS, Verb::TRACE, Verb::CONNECT
                    {}
+                 else
+                   T.absurd(http_verb)
         end
 
         req_id = T.cast(env["HTTP_X_REQUEST_ID"], T.nilable(String))
@@ -84,10 +88,17 @@ module Kirei
         }
         Logging::Metric.inject_defaults(statsd_timing_tags)
 
-        status, headers, response_body = T.cast(
-          controller.new(params: params).public_send(route.action),
-          RackResponseType,
-        )
+        status, headers, response_body = case http_verb
+                                         when Verb::HEAD, Verb::OPTIONS, Verb::TRACE, Verb::CONNECT
+                                           [200, {}, []]
+                                         when Verb::GET, Verb::POST, Verb::PUT, Verb::PATCH, Verb::DELETE
+                                           T.cast(
+                                             controller.new(params: params).public_send(route.action),
+                                             RackResponseType,
+                                           )
+                                         else
+                                           T.absurd(http_verb)
+        end
 
         after_hooks = collect_hooks(controller, :after_hooks)
         run_hooks(after_hooks)

data/lib/kirei/routing/router.rb

@@ -25,6 +25,9 @@ module Kirei
         T::Hash[String, Route]
       end
 
+      sig { returns(T.nilable(T::Hash[String, T.untyped])) }
+      attr_accessor :current_env
+
       sig { void }
       def initialize
         @routes = T.let({}, RoutesHash)

data/lib/kirei/services/array_comparison.rb

@@ -0,0 +1,35 @@
+# 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

data/lib/kirei/version.rb

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

data/sorbet/rbi/shims/domain.rbi

@@ -0,0 +1,16 @@
+# typed: true
+
+module Kirei
+  module Domain
+    module Entity
+      include Kernel
+
+      sig { returns(T.any(String, Integer)) }
+      def id; end
+    end
+
+    module ValueObject
+      include Kernel
+    end
+  end
+end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: kirei
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.8.0
 platform: ruby
 authors:
 - Ludwig Reinmiedl
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: oj
   requirement: !ruby/object:Gem::Requirement
@@ -139,7 +152,7 @@ dependencies:
 description: |
   Kirei is a Ruby micro/REST-framework for building scalable and performant microservices.
   It is built from the ground up to be clean and easy to use.
-  It is a Rack app, and uses Sorbet for typing, Sequel as an ORM, Zeitwerk for autoloading, and Puma as a web server.
+  It is a Rack app, and uses Sorbet for typing, Sequel as an ORM, and Zeitwerk for autoloading.
   It strives to have zero magic and to be as explicit as possible.
 email:
 - lud@reinmiedl.com
@@ -169,6 +182,8 @@ files:
 - lib/kirei/app.rb
 - lib/kirei/config.rb
 - lib/kirei/controller.rb
+- lib/kirei/domain/entity.rb
+- lib/kirei/domain/value_object.rb
 - lib/kirei/errors/json_api_error.rb
 - lib/kirei/errors/json_api_error_source.rb
 - lib/kirei/helpers.rb
@@ -186,11 +201,13 @@ 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
 - lib/tasks/routes.rake
 - sorbet/rbi/shims/base_model.rbi
+- sorbet/rbi/shims/domain.rbi
 - sorbet/rbi/shims/ruby.rbi
 homepage: https://github.com/swiknaba/kirei
 licenses:
@@ -198,7 +215,6 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/swiknaba/kirei
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -213,8 +229,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Kirei is a typed Ruby micro/REST-framework for building scalable and performant
   microservices.