kirei 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7eaf9be851bf8985a4c169c4ed79c3bc3cc067b247b0cc50e1f742447e019c3d
-  data.tar.gz: 47816fbc66608113d804e9efcbc7267cd3deea522edcdc8c5920d7ac365cd1b6
+  metadata.gz: 788221745d889864fe2ec7075cce289f6d44361dece7711fbe91ac24c16f693b
+  data.tar.gz: e03e3cf0c4c6db69bc0106107ccb002b8f472ba077ef457d88a84b92b188371f
 SHA512:
-  metadata.gz: 2f66ca601807ae0f8528f59b0303812d6bf2b644a910284f4caedbe413c5865d3634c12a6a8e30c1a3ae85ff44f7f80fd8b69c48a977e4cec98260b30c09d56e
-  data.tar.gz: 8ec07fe4d0a69c0918026a966e96eb1257767e187c9bde5edc9d5be9f6796269bccc5f989c399df8e211965f1014c51a24739c638a78cee971b4dddb9abdf821
+  metadata.gz: 30bef2a1458e1aeeebd774d577df1dc231b0cfa46fb7483b076b69ac05de1529527442599dca18bb278fec42e1a17888eee849feb1b3f81dd502fd92284dd879
+  data.tar.gz: 181df5735f94c222fc29e9bb3c18aa33340995925a324a18a0bb28e1001eaeaee24f8c7442cc5852adf31ae7e5e7a707743441e1c64a585e27039e7b50ba96da

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.query.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 = User.query.where({ name: 'John' })
+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(
+    [
+      Route.new(
+        verb: Verb::GET,
+        path: "/livez",
+        controller: Controllers::Health,
+        action: "livez",
+      ),
+      Route.new(
+        verb: Verb::GET,
+        path: "/airports",
+        controller: Controllers::Airports,
+        action: "index",
+      ),
+    ],
+  )
+end
 ```
 
 #### Controllers
@@ -161,12 +177,16 @@ 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
+      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]
+      end
 
       # or use a serializer
       data = Oj.dump(airports.map(&:serialize))
@@ -177,6 +197,35 @@ module Controllers
 end
 ```
 
+Services can be PORO. You can wrap an execution in `Kirei::Services::Runner` which will emit a standardized logline and track its execution time.
+
+```ruby
+module Airports
+  class Filter
+    extend T::Sig
+
+    sig do
+      params(
+        search: T.nilable(String),
+      ).returns(T::Array[Airport])
+    end
+    def self.call(search)
+      return Airport.all if search.nil?
+
+      #
+      # SELECT *
+      # FROM "airports"
+      # WHERE (("name" ILIKE 'xx%') OR ("id" ILIKE 'xx%'))
+      #
+      query = Airport.query.where(Sequel.ilike(:name, "#{search}%"))
+      query = query.or(Sequel.ilike(:id, "#{search}%"))
+
+      Airport.resolve(query)
+    end
+  end
+end
+```
+
 ## 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/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"
@@ -46,7 +46,9 @@ Gem::Specification.new do |spec|
   # Utilities
   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"
 
   # 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,10 +13,10 @@ 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(
+          Kirei::Logging::Logger.logger.info(
             "Kirei app '#{app_name}' scaffolded successfully!",
           )
         end

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

@@ -1,4 +1,4 @@
-# typed: false
+# typed: true
 
 module Cli
   module Commands
@@ -29,15 +29,28 @@ 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")
+              [
+                "/app",
+                "/app/models",
+                "/app/services",
+              ].each do |root_namespace|
+                # a root namespace skips the auto-infered module for this folder
+                # so we don't have to write e.g. `Models::` or `Services::`
+                loader.push_dir("\#{File.dirname(__FILE__)}\#{root_namespace}")
+              end
+              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(
+                  [
+                    Route.new(
+                      verb: 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/cli/commands/start.rb

@@ -13,7 +13,7 @@ module Cli
           app_name = app_name.split("_").map(&:capitalize).join if app_name.include?("_")
           NewApp::Execute.call(app_name: app_name)
         else
-          Kirei::Logger.logger.info("Unknown command")
+          Kirei::Logging::Logger.logger.info("Unknown command")
         end
       end
     end

data/lib/kirei/app.rb

@@ -1,72 +1,92 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative("middleware")
+module Kirei
+  #
+  # This is the entrypoint into the application; it implements the Rack interface.
+  #
+  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/config.rb

@@ -17,7 +17,10 @@ module Kirei
 
     prop :logger, ::Logger, factory: -> { ::Logger.new($stdout) }
     prop :log_transformer, T.nilable(T.proc.params(msg: T::Hash[Symbol, T.untyped]).returns(T::Array[String]))
-    prop :log_default_metadata, T::Hash[Symbol, String], default: {}
+    prop :log_default_metadata, T::Hash[String, T.untyped], default: {}
+    prop :log_level, Kirei::Logging::Level, default: Kirei::Logging::Level::INFO
+
+    prop :metric_default_tags, T::Hash[String, T.untyped], default: {}
 
     # dup to allow the user to extend the existing list of sensitive keys
     prop :sensitive_keys, T::Array[Regexp], factory: -> { SENSITIVE_KEYS.dup }