kirei 0.6.3 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dec07a03cbf5ed8ceb535f60fef750df94039a2bd3880f219ccccefa4335f60
-  data.tar.gz: f2a2796a4bcbe2aa6b8a526887c33ee22095c0afedf95e7e467b01b1e033b0ae
+  metadata.gz: df4eacd42ab9ef8cc4b3474e4c58b5ccdc0dc7c7b3631fdf4640a5ea38febc3b
+  data.tar.gz: 3203e23caa1ffa4cc1352b3d87bc30df0639c4434cfa26ae8b5cb3133a8586d7
 SHA512:
-  metadata.gz: 1eab2d1497a5592d5a7fe55d669d94a55aeecbc44744bf46b1d5349658916584d6eace11032ef723f9d034bcac834d41acf8acc90f9d87922f38802bf1793567
-  data.tar.gz: dc84e7e1bb9125909c81e40e66fc6e687abe8b1de928423d48b5a26a6c4ea23fd67e02953708bea25fbe448e5ce952f294ec54a6c8b74477f3dd269f891195ce
+  metadata.gz: 9bffc31e1489abec7e249e6f9328f0cd1337ee2a007bab192583de9b2d98c8bf2816ad743991f8c1ef073235da8fb072804a0a9d1af0248b28b3cd520bbfb8fe
+  data.tar.gz: e7ecfe6be3594b7ea70d12646d38a1b4e11e824453c63adfda37d96877791ca30fe2748098336cab13f25b774be92700065bbafeee84e648679242c2c1d47ad7

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"
@@ -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

@@ -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

@@ -38,6 +38,8 @@ module Kirei
         route = router.get(http_verb, req_path)
         return NOT_FOUND if route.nil?
 
+        router.current_env = env # expose the env to the controller
+
         params = case route.verb
                  when Verb::GET
                    query = T.cast(env.fetch("QUERY_STRING"), String)

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.7.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,29 @@
 --- !ruby/object:Gem::Specification
 name: kirei
 version: !ruby/object:Gem::Version
-  version: 0.6.3
+  version: 0.7.0
 platform: ruby
 authors:
 - Ludwig Reinmiedl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-20 00:00:00.000000000 Z
+date: 2025-03-18 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 +153,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 +183,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 +202,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: