kirei 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eaf9be851bf8985a4c169c4ed79c3bc3cc067b247b0cc50e1f742447e019c3d
-  data.tar.gz: 47816fbc66608113d804e9efcbc7267cd3deea522edcdc8c5920d7ac365cd1b6
+  metadata.gz: fb100f4fb7ab34f19caf8d428e373ac0e94230b126037147108b4826ca08b0c5
+  data.tar.gz: 00efe991393cecf639ffe87ac5407fcf232d068940f55da8cc1696c08bbf75e6
 SHA512:
-  metadata.gz: 2f66ca601807ae0f8528f59b0303812d6bf2b644a910284f4caedbe413c5865d3634c12a6a8e30c1a3ae85ff44f7f80fd8b69c48a977e4cec98260b30c09d56e
-  data.tar.gz: 8ec07fe4d0a69c0918026a966e96eb1257767e187c9bde5edc9d5be9f6796269bccc5f989c399df8e211965f1014c51a24739c638a78cee971b4dddb9abdf821
+  metadata.gz: bee31a71691f31363a7ffc4855c2ef9886f1ce3e545aafa5409a8064e7de79ec78670172b6c7e61348fb5b21f61779e080818e25077b9c300ec4f612dda83e28
+  data.tar.gz: 1d4511cbd01bc7f2eb5f03bd3032079232650b30226ca510dce48a07ee4fc7814e0e6e9ac25ba5df1cd14a11ee957a508d2cbededfbf29ee7806b1840d3455b9

data/README.md

@@ -1,6 +1,6 @@
 # Kirei
 
-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 [Sinatra](https://github.com/sinatra/sinatra) for routing. It strives to have zero magic and to be as explicit as possible.
+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.
 
@@ -53,12 +53,12 @@ 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::BaseModel`. 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 of type `T.any(String, Integer)`.
 
 ```ruby
 class User < T::Struct
   extend T::Sig
-  include Kirei::BaseModel
+  include Kirei::Model
 
   const :id, T.any(String, Integer)
   const :name, String
@@ -76,12 +76,21 @@ user.name         # => 'John'
 updated_user.name # => 'Johnny'
 ```
 
+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.
+
+```ruby
+success = user.delete # => T::Boolean
+
+# or delete by any query:
+User.db.where('...').delete # => Integer, number of deleted records
+```
+
 To build more complex queries, Sequel can be used directly:
 
 ```ruby
 query = User.db.where({ name: 'John' })
-query = query.where('...')
-query = query.limit(10) # query is a Sequel::Dataset, chain as you like
+query = query.where('...') # "query" is a 'Sequel::Dataset' that you can chain as you like
+query = query.limit(10)
 
 users = User.resolve(query)            # T::Array[User]
 first_user = User.resolve_first(query) # T.nilable(User)
@@ -121,11 +130,15 @@ bundle exec rake db:drop
 # apply all pending migrations
 bundle exec rake db:migrate
 
+# annotate the models with the schema
+# this runs automatically after each migration
+bundle exec rake db:annotate
+
 # roll back the last n migration
 STEPS=1 bundle exec rake db:rollback
 
 # run db/seeds.rb to seed the database
-bundle exec rake db:migrate
+bundle exec rake db:seed
 
 # scaffold a new migration file
 bundle exec rake 'db:migration[CreateAirports]'
@@ -138,21 +151,24 @@ Define routes anywhere in your app; by convention, they are defined in `config/r
 ```ruby
 # config/routes.rb
 
-Kirei::Router.add_routes([
-  Kirei::Router::Route.new(
-    verb: "GET",
-    path: "/livez",
-    controller: Controllers::Health,
-    action: "livez",
-  ),
-
-  Kirei::Router::Route.new(
-    verb: "GET",
-    path: "/airports",
-    controller: Controllers::Airports,
-    action: "index",
-  ),
-])
+module Kirei::Routing
+  Router.add_routes(
+    [
+      Router::Route.new(
+        verb: Router::Verb::GET,
+        path: "/livez",
+        controller: Controllers::Health,
+        action: "livez",
+      ),
+      Router::Route.new(
+        verb: Router::Verb::GET,
+        path: "/airports",
+        controller: Controllers::Airports,
+        action: "index",
+      ),
+    ],
+  )
+end
 ```
 
 #### Controllers
@@ -161,12 +177,12 @@ Controllers can be defined anywhere; by convention, they are defined in the `app
 
 ```ruby
 module Controllers
-  class Airports < Kirei::BaseController
+  class Airports < Kirei::Controller
     extend T::Sig
 
-    sig { returns(Kirei::Middleware::RackResponseType) }
+    sig { returns(T.anything) }
     def index
-      airports = Airport.all
+      airports = Airport.all # T::Array[Airport]
 
       # or use a serializer
       data = Oj.dump(airports.map(&:serialize))

data/bin/kirei

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
-require_relative '../lib/cli'
+require_relative "../lib/cli"
 
 Cli::Commands::Start.call(ARGV)

data/kirei.gemspec

@@ -13,11 +13,11 @@ Gem::Specification.new do |spec|
     "oss@dbl.works",
   ]
 
-  spec.summary = "Kirei is a strictly typed Ruby micro/REST-framework for building scaleable and performant microservices." # rubocop:disable Layout/LineLength
+  spec.summary = "Kirei is a typed Ruby micro/REST-framework for building scalable and performant microservices."
   spec.description = <<~TXT
-    Kirei is a strictly typed Ruby micro/REST-framework for building scaleable and performant microservices.
+    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.
-    Kirei is based on Sequel as an ORM, Sorbet for typing, and Sinatra for routing.
+    It is a Rack app, and uses Sorbet for typing, Sequel as an ORM, Zeitwerk for autoloading, and Puma as a web server.
     It strives to have zero magic and to be as explicit as possible.
   TXT
   spec.homepage = "https://github.com/swiknaba/kirei"
@@ -47,6 +47,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "oj", "~> 3.0"
   spec.add_dependency "sorbet-runtime", "~> 0.5"
   spec.add_dependency "tzinfo-data", "~> 1.0" # for containerized environments, e.g. on AWS ECS
+  spec.add_dependency "zeitwerk", "~> 2.5"
 
   # Web server & routing
   spec.add_dependency "puma", "~> 6.0"

data/lib/cli/commands/new_app/base_directories.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands

data/lib/cli/commands/new_app/execute.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 require "fileutils"
 
@@ -13,7 +13,7 @@ module Cli
           Files::DbRake.call(app_name)
           Files::Irbrc.call
           Files::Rakefile.call
-          Files::Routes.call
+          Files::Routes.call(app_name)
           Files::SorbetConfig.call
 
           Kirei::Logger.logger.info(

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands
@@ -29,15 +29,21 @@ module Cli
               Dir[File.join(__dir__, "config/initializers", "*.rb")].each { require(_1) }
 
               # Fourth: load all application code
-              Dir[File.join(__dir__, "app/**/*", "*.rb")].each { require(_1) }
+              loader = Zeitwerk::Loader.new
+              loader.tag = File.basename(__FILE__, ".rb")
+              loader.push_dir("#{File.dirname(__FILE__)}/app")
+              loader.push_dir("#{File.dirname(__FILE__)}/app/models") # make models a root namespace so we don't infer a `Models::` module
+              loader.setup
 
               # Fifth: load configs
               Dir[File.join(__dir__, "config", "*.rb")].each { require(_1) }
 
-              class #{app_name} < Kirei::AppBase
+              class #{app_name} < Kirei::App
                 # Kirei configuration
                 config.app_name = "#{snake_case_app_name}"
               end
+
+              loader.eager_load
             RUBY
           end
         end

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands

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

@@ -21,6 +21,7 @@ module Cli
               #
               #   CREATE DATABASE #{db_name}_${environment};
 
+              require 'zeitwerk/inflector'
               require_relative "../../app"
 
               namespace :db do
@@ -30,7 +31,7 @@ module Cli
                   envs = ENV.key?("RACK_ENV") ? [ENV.fetch("RACK_ENV")] : %w[development test]
                   envs.each do |env|
                     ENV["RACK_ENV"] = env
-                    db_name = "#{db_name}_#{env}"
+                    db_name = "#{db_name}_\#{env}"
                     puts("Creating database \#{db_name}...")
 
                     reset_memoized_class_level_instance_vars(#{app_name})
@@ -84,6 +85,8 @@ module Cli
                     current_version = db[:schema_migrations].order(:filename).last[:filename].to_i
                     puts "Migrated \#{db_name} to version \#{current_version}!"
                   end
+
+                  Rake::Task["db:annotate"].invoke
                 end
 
                 desc "Rollback the last migration"
@@ -128,7 +131,7 @@ module Cli
                   migration_number = Time.now.utc.strftime("%Y%m%d%H%M%S")
 
                   # Sanitize and format the migration name
-                  formatted_name = args[:name].to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+                  formatted_name = args[:name].to_s.gsub(/([a-z])([A-Z])/, '\\1_\\2').downcase
 
                   # Combine them to create the filename
                   filename = "\#{migration_number}_\#{formatted_name}.rb"
@@ -155,6 +158,38 @@ module Cli
 
                   puts "Generated migration: db/migrate/\#{filename}"
                 end
+
+                desc "Write the table schema to each model file, or a single file if filename (without extension) is provided"
+                task :annotate, [:model_file_name] do |_t, args|
+                  require "fileutils"
+
+                  db = #{app_name}.raw_db_connection
+                  model_file_name = args[:model_file_name]&.to_s
+
+                  models_dir = #{app_name}.root
+
+                  Dir.glob("app/models/*.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)
+                    model_name = Zeitwerk::Inflector.new.camelize(File.basename(model_file, ".rb"), model_path)
+                    model_klass = Object.const_get(model_name)
+                    table_name = model_klass.table_name
+                    schema = db.schema(table_name)
+
+                    schema_comments = format_schema_comments(table_name, schema)
+
+                    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)/m, "")
+
+                    # Insert the new schema comments before the class definition
+                    modified_contents = updated_contents.sub(/(\A|\\n)(class \#{model_name})/m, "\\\\1\#{schema_comments}\\n\\n\\\\2")
+
+                    File.write(model_path, modified_contents)
+                  end
+                end
               end
 
               def reset_memoized_class_level_instance_vars(app)
@@ -167,6 +202,19 @@ module Cli
                 end
               end
 
+              def format_schema_comments(table_name, schema)
+                lines = ["# == Schema Info", "#", "# Table name: \#{table_name}", "#"]
+                schema.each do |column|
+                  name, info = column
+                  type = "\#{info[:db_type]}(\#{info[:max_length]})" if info[:max_length]
+                  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}"
+                end
+                lines.join("\\n") + "\\n#"
+              end
+
             RUBY
           end
         end

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands

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

@@ -1,27 +1,64 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands
     module NewApp
       module Files
         class Routes
-          def self.call
-            File.write("config/routes.rb", content)
+          def self.call(app_name)
+            File.write("config/routes.rb", router)
+            File.write("app/controllers/base.rb", base_controller)
+            File.write("app/controllers/health.rb", health_controller(app_name))
           end
 
-          def self.content
+          def self.router
             <<~RUBY
               # typed: strict
               # frozen_string_literal: true
 
-              Kirei::Router.add_routes([
-                # Kirei::Router::Route.new(
-                #   verb: "GET",
-                #   path: "/livez",
-                #   controller: Controllers::HealthController,
-                #   action: "livez",
-                # )
-              ])
+              module Kirei::Routing
+                Router.add_routes(
+                  [
+                    Router::Route.new(
+                      verb: Router::Verb::GET,
+                      path: "/livez",
+                      controller: Controllers::Health,
+                      action: "livez",
+                    ),
+                  ],
+                )
+              end
+            RUBY
+          end
+
+          def self.base_controller
+            <<~RUBY
+              # typed: strict
+              # frozen_string_literal: true
+
+              module Controllers
+                class Base < Kirei::Controller
+                  extend T::Sig
+                end
+              end
+            RUBY
+          end
+
+          def self.health_controller(app_name)
+            <<~RUBY
+              # typed: strict
+              # frozen_string_literal: true
+
+              module Controllers
+                class Health < Base
+                  sig { returns(T.anything) }
+                  def livez
+                    #{app_name}.config.logger.info("Health check")
+                    #{app_name}.config.logger.info(params.inspect)
+                    render(#{app_name}.version, status: 200)
+                  end
+                end
+              end
             RUBY
           end
         end

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands

data/lib/kirei/app.rb

@@ -1,72 +1,89 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative("middleware")
+module Kirei
+  class App < Routing::Base
+    class << self
+      extend T::Sig
 
-# rubocop:disable Metrics/AbcSize, Layout/LineLength
+      #
+      # convenience method since "Kirei.configuration" must be nilable since it is nil
+      # at the beginning of initilization of the app
+      #
+      sig { returns(Kirei::Config) }
+      def config
+        T.must(Kirei.configuration)
+      end
 
-module Kirei
-  class App
-    include Middleware
-    extend T::Sig
+      sig { returns(Pathname) }
+      def root
+        defined?(::APP_ROOT) ? Pathname.new(::APP_ROOT) : Pathname.new(Dir.pwd)
+      end
 
-    sig { params(params: T::Hash[String, T.untyped]).void }
-    def initialize(params: {})
-      @router = T.let(Router.instance, Router)
-      @params = T.let(params, T::Hash[String, T.untyped])
-    end
+      #
+      # Returns the version of the app. It checks in the following order:
+      # * ENV["APP_VERSION"]
+      # * ENV["GIT_SHA"]
+      # * `git rev-parse --short HEAD`
+      #
+      sig { returns(String) }
+      def version
+        @version = T.let(@version, T.nilable(String))
+        @version ||= ENV.fetch("APP_VERSION", nil)
+        @version ||= ENV.fetch("GIT_SHA", nil)
+        @version ||= T.must(
+          `command -v git && git rev-parse --short HEAD`.to_s.split("\n").last,
+        ).freeze # localhost
+      end
 
-    sig { returns(T::Hash[String, T.untyped]) }
-    attr_reader :params
+      #
+      # Returns ENV["RACK_ENV"] or "development" if it is not set
+      #
+      sig { returns(String) }
+      def environment
+        ENV.fetch("RACK_ENV", "development")
+      end
 
-    sig { params(env: RackEnvType).returns(RackResponseType) }
-    def call(env)
-      http_verb = T.cast(env.fetch("REQUEST_METHOD"), String)
-      req_path = T.cast(env.fetch("REQUEST_PATH"), String)
-      # reject requests from unexpected hosts -> allow configuring allowed hosts in a `cors.rb` file
-      #   ( offer a scaffold for this file )
-      # -> use https://github.com/cyu/rack-cors
+      #
+      # Returns the name of the database based on the app name and the environment,
+      # e.g. "myapp_development"
+      #
+      sig { returns(String) }
+      def default_db_name
+        @default_db_name ||= T.let("#{config.app_name}_#{environment}".freeze, T.nilable(String))
+      end
 
-      route = Router.instance.get(http_verb, req_path)
-      return [404, {}, ["Not Found"]] if route.nil?
+      #
+      # Returns the database URL based on the DATABASE_URL environment variable or
+      # a default value based on the default_db_name
+      #
+      sig { returns(String) }
+      def default_db_url
+        @default_db_url ||= T.let(
+          ENV.fetch("DATABASE_URL", "postgresql://localhost:5432/#{default_db_name}"),
+          T.nilable(String),
+        )
+      end
 
-      params = if route.verb == "GET"
-        query = T.cast(env.fetch("QUERY_STRING"), String)
-        query.split("&").to_h do |p|
-          k, v = p.split("=")
-          k = T.cast(k, String)
-          [k, v]
+      sig { returns(Sequel::Database) }
+      def raw_db_connection
+        @raw_db_connection = T.let(@raw_db_connection, T.nilable(Sequel::Database))
+        return @raw_db_connection unless @raw_db_connection.nil?
+
+        # calling "Sequel.connect" creates a new connection
+        @raw_db_connection = Sequel.connect(App.config.db_url || default_db_url)
+
+        config.db_extensions.each do |ext|
+          T.cast(@raw_db_connection, Sequel::Database).extension(ext)
         end
-      else
-        # TODO: based on content-type, parse the body differently
-        #       build-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])
-      end
 
-      instance = route.controller.new(params: params)
-      instance.public_send(route.action)
-    end
+        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
+        end
 
-    sig do
-      params(
-        status: Integer,
-        body: String,
-        headers: T::Hash[String, String],
-      ).returns(RackResponseType)
-    end
-    def render(status:, body:, headers: {})
-      # merge default headers
-      # support a "type" to set content-type header? (or default to json, and users must set the header themselves for other types?)
-      [
-        status,
-        headers,
-        [body],
-      ]
+        @raw_db_connection
+      end
     end
   end
 end
-
-# rubocop:enable Metrics/AbcSize, Layout/LineLength

data/lib/kirei/controller.rb

@@ -0,0 +1,44 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  class Controller < Routing::Base
+    class << self
+      extend T::Sig
+
+      sig { returns(Routing::NilableHooksType) }
+      attr_reader :before_hooks, :after_hooks
+    end
+
+    extend T::Sig
+
+    #
+    # Statements to be executed before every action.
+    #
+    # In development mode, Rack Reloader might reload this file causing
+    # the before hooks to be executed multiple times.
+    #
+    sig do
+      params(
+        block: T.nilable(T.proc.void),
+      ).void
+    end
+    def self.before(&block)
+      @before_hooks ||= T.let(Set.new, Routing::NilableHooksType)
+      @before_hooks.add(block) if block
+    end
+
+    #
+    # Statements to be executed after every action.
+    #
+    sig do
+      params(
+        block: T.nilable(T.proc.void),
+      ).void
+    end
+    def self.after(&block)
+      @after_hooks ||= T.let(Set.new, Routing::NilableHooksType)
+      @after_hooks.add(block) if block
+    end
+  end
+end

data/lib/kirei/logger.rb

@@ -17,12 +17,12 @@ module Kirei
   #
   # You can define a custom log transformer to transform the logline:
   #
-  #    Kirei::AppBase.config.log_transformer = Proc.new { _1 }
+  #    Kirei::App.config.log_transformer = Proc.new { _1 }
   #
-  # By default, "meta" is flattened, and sensitive values are masked using see `Kirei::AppBase.config.sensitive_keys`.
+  # By default, "meta" is flattened, and sensitive values are masked using see `Kirei::App.config.sensitive_keys`.
   # You can also build on top of the provided log transformer:
   #
-  #   Kirei::AppBase.config.log_transformer = Proc.new do |meta|
+  #   Kirei::App.config.log_transformer = Proc.new do |meta|
   #      flattened_meta = Kirei::Logger.flatten_hash_and_mask_sensitive_values(meta)
   #      # Do something with the flattened meta
   #      flattened_meta.map { _1.to_json }
@@ -85,7 +85,7 @@ module Kirei
       ).void
     end
     def call(level:, label:, meta: {})
-      Kirei::AppBase.config.log_default_metadata.each_pair do |key, value|
+      Kirei::App.config.log_default_metadata.each_pair do |key, value|
         meta[key] ||= value
       end
 
@@ -94,7 +94,7 @@ module Kirei
       # Source: https://opentelemetry.io/docs/concepts/semantic-conventions/
       #
       meta[:"service.instance.id"] ||= Thread.current[:request_id]
-      meta[:"service.name"] ||= Kirei::AppBase.config.app_name
+      meta[:"service.name"] ||= Kirei::App.config.app_name
 
       # The Ruby logger only accepts one string as the only argument
       @queue << { level: level, label: label, meta: meta }
@@ -108,12 +108,12 @@ module Kirei
           level = log_data.fetch(:level)
           label = log_data.fetch(:label)
           meta = T.let(log_data.fetch(:meta), T::Hash[Symbol, T.untyped])
-          meta[:"service.version"] ||= Kirei::AppBase.version
+          meta[:"service.version"] ||= Kirei::App.version
           meta[:timestamp] ||= Time.now.utc.iso8601
           meta[:level] ||= level.to_s.upcase
           meta[:label] ||= label
 
-          log_transformer = AppBase.config.log_transformer
+          log_transformer = App.config.log_transformer
 
           loglines = if log_transformer
             log_transformer.call(meta)
@@ -137,7 +137,7 @@ module Kirei
       ).returns(String)
     end
     def self.mask(k, v)
-      return Kirei::Logger::FILTERED if AppBase.config.sensitive_keys.any? { k.match?(_1) }
+      return Kirei::Logger::FILTERED if App.config.sensitive_keys.any? { k.match?(_1) }
 
       v
     end