kirei 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb100f4fb7ab34f19caf8d428e373ac0e94230b126037147108b4826ca08b0c5
-  data.tar.gz: 00efe991393cecf639ffe87ac5407fcf232d068940f55da8cc1696c08bbf75e6
+  metadata.gz: 788221745d889864fe2ec7075cce289f6d44361dece7711fbe91ac24c16f693b
+  data.tar.gz: e03e3cf0c4c6db69bc0106107ccb002b8f472ba077ef457d88a84b92b188371f
 SHA512:
-  metadata.gz: bee31a71691f31363a7ffc4855c2ef9886f1ce3e545aafa5409a8064e7de79ec78670172b6c7e61348fb5b21f61779e080818e25077b9c300ec4f612dda83e28
-  data.tar.gz: 1d4511cbd01bc7f2eb5f03bd3032079232650b30226ca510dce48a07ee4fc7814e0e6e9ac25ba5df1cd14a11ee957a508d2cbededfbf29ee7806b1840d3455b9
+  metadata.gz: 30bef2a1458e1aeeebd774d577df1dc231b0cfa46fb7483b076b69ac05de1529527442599dca18bb278fec42e1a17888eee849feb1b3f81dd502fd92284dd879
+  data.tar.gz: 181df5735f94c222fc29e9bb3c18aa33340995925a324a18a0bb28e1001eaeaee24f8c7442cc5852adf31ae7e5e7a707743441e1c64a585e27039e7b50ba96da

data/README.md

@@ -82,13 +82,13 @@ Delete keeps the original object intact. Returns `true` if the record was delete
 success = user.delete # => T::Boolean
 
 # or delete by any query:
-User.db.where('...').delete # => Integer, number of deleted records
+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 = User.query.where({ name: 'John' })
 query = query.where('...') # "query" is a 'Sequel::Dataset' that you can chain as you like
 query = query.limit(10)
 
@@ -154,14 +154,14 @@ Define routes anywhere in your app; by convention, they are defined in `config/r
 module Kirei::Routing
   Router.add_routes(
     [
-      Router::Route.new(
-        verb: Router::Verb::GET,
+      Route.new(
+        verb: Verb::GET,
         path: "/livez",
         controller: Controllers::Health,
         action: "livez",
       ),
-      Router::Route.new(
-        verb: Router::Verb::GET,
+      Route.new(
+        verb: Verb::GET,
         path: "/airports",
         controller: Controllers::Airports,
         action: "index",
@@ -182,7 +182,11 @@ module Controllers
 
     sig { returns(T.anything) }
     def index
-      airports = Airport.all # T::Array[Airport]
+      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))
@@ -193,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/kirei.gemspec

@@ -46,6 +46,7 @@ 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"
 

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

@@ -16,7 +16,7 @@ module Cli
           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

@@ -31,8 +31,15 @@ module Cli
               # Fourth: load all application code
               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
+              [
+                "/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

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

@@ -19,8 +19,8 @@ module Cli
               module Kirei::Routing
                 Router.add_routes(
                   [
-                    Router::Route.new(
-                      verb: Router::Verb::GET,
+                    Route.new(
+                      verb: Verb::GET,
                       path: "/livez",
                       controller: Controllers::Health,
                       action: "livez",

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

@@ -2,6 +2,9 @@
 # frozen_string_literal: true
 
 module Kirei
+  #
+  # This is the entrypoint into the application; it implements the Rack interface.
+  #
   class App < Routing::Base
     class << self
       extend T::Sig

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 }

data/lib/kirei/errors/json_api_error.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Errors
+    #
+    # https://jsonapi.org/format/#errors
+    # Error objects MUST be returned as an array keyed by errors in the top level of a JSON:API document.
+    #
+    class JsonApiError < T::Struct
+      #
+      # An application-specific error code, expressed as a string value.
+      #
+      const :code, String
+
+      #
+      # A human-readable explanation specific to this occurrence of the problem.
+      # Like title, this field's value can be localized.
+      #
+      const :detail, T.nilable(String)
+
+      const :source, T.nilable(JsonApiErrorSource)
+    end
+  end
+end

data/lib/kirei/errors/json_api_error_source.rb

@@ -0,0 +1,12 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Errors
+    class JsonApiErrorSource < T::Struct
+      const :attribute, String
+      const :model, T.nilable(String)
+      const :id, T.nilable(String)
+    end
+  end
+end

data/lib/kirei/logging/level.rb

@@ -0,0 +1,33 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Logging
+    class Level < T::Enum
+      extend T::Sig
+
+      enums do
+        UNKNOWN = new(5) # An unknown message that should always be logged.
+        FATAL   = new(4) # An unhandleable error that results in a program crash.
+        ERROR   = new(3) # A handleable error condition.
+        WARN    = new(2) # A warning.
+        INFO    = new(1) # Generic (useful) information about system operation.
+        DEBUG   = new(0) # Low-level information for developers.
+      end
+
+      sig { returns(String) }
+      def to_human
+        case self
+        when UNKNOWN then "UNKNOWN"
+        when FATAL   then "FATAL"
+        when ERROR   then "ERROR"
+        when WARN    then "WARN"
+        when INFO    then "INFO"
+        when DEBUG   then "DEBUG"
+        else
+          T.absurd(self)
+        end
+      end
+    end
+  end
+end

data/lib/kirei/logging/logger.rb

@@ -0,0 +1,198 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  # rubocop:disable Metrics
+
+  #
+  # Example Usage:
+  #
+  #    Kirei::Logging::Logger.call(
+  #      level: Kirei::Logging::Level::INFO,
+  #      label: "Request started",
+  #      meta: {
+  #        key: "value",
+  #      },
+  #    )
+  #
+  # You can define a custom log transformer to transform the logline:
+  #
+  #    Kirei::App.config.log_transformer = Proc.new { _1 }
+  #
+  # By default, "meta" is flattened, and sensitive values are masked using sane defaults that you
+  # can finetune via `Kirei::App.config.sensitive_keys`.
+  #
+  # You can also build on top of the provided log transformer:
+  #
+  #   Kirei::App.config.log_transformer = Proc.new do |meta|
+  #      flattened_meta = Kirei::Logging::Logger.flatten_hash_and_mask_sensitive_values(meta)
+  #      # Do something with the flattened meta
+  #      flattened_meta.map { _1.to_json }
+  #   end
+  #
+  # NOTE:
+  #    * The log transformer must return an array of strings to allow emitting multiple lines per log event.
+  #    * Whenever possible, key names follow OpenTelemetry Semantic Conventions, https://opentelemetry.io/docs/concepts/semantic-conventions/
+  #
+  module Logging
+    class Logger
+      extend T::Sig
+
+      FILTERED = "[FILTERED]"
+
+      @instance = T.let(nil, T.nilable(Kirei::Logging::Logger))
+
+      sig { void }
+      def initialize
+        super
+        @queue = T.let(Thread::Queue.new, Thread::Queue)
+        @thread = T.let(start_logging_thread, Thread)
+      end
+
+      sig { returns(Kirei::Logging::Logger) }
+      def self.instance
+        @instance ||= new
+      end
+
+      sig { returns(::Logger) }
+      def self.logger
+        return @logger unless @logger.nil?
+
+        @logger = T.let(nil, T.nilable(::Logger))
+        @logger ||= ::Logger.new($stdout)
+
+        # we want the logline to be parseable to JSON
+        @logger.formatter = proc do |_severity, _datetime, _progname, msg|
+          "#{msg}\n"
+        end
+
+        @logger
+      end
+
+      sig do
+        params(
+          level: Logging::Level,
+          label: String,
+          meta: T::Hash[String, T.untyped],
+        ).void
+      end
+      def self.call(level:, label:, meta: {})
+        return if ENV["NO_LOGS"] == "true"
+        return if level.serialize < App.config.log_level.serialize
+
+        # must extract data from current thread before passing this down to the logging thread
+        meta["enduser.id"] ||= Thread.current[:enduser_id] # OpenTelemetry::SemanticConventions::Trace::ENDUSER_ID
+        meta["service.instance.id"] ||= Thread.current[:request_id] # OpenTelemetry::SemanticConventions::Resource::SERVICE_INSTANCE_ID
+
+        instance.call(level: level, label: label, meta: meta)
+      end
+
+      sig do
+        params(
+          level: Logging::Level,
+          label: String,
+          meta: T::Hash[String, T.untyped],
+        ).void
+      end
+      def call(level:, label:, meta: {})
+        Kirei::App.config.log_default_metadata.each_pair do |key, value|
+          meta[key] ||= value
+        end
+
+        meta["service.name"] ||= Kirei::App.config.app_name # OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME
+        meta["service.version"] = Kirei::App.version # OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION
+        meta["timestamp"] ||= Time.now.utc.iso8601
+        meta["level"] ||= level.to_human
+        meta["label"] ||= label
+
+        @queue << meta
+      end
+
+      sig { returns(Thread) }
+      def start_logging_thread
+        Thread.new do
+          Kernel.loop do
+            log_data = T.let(@queue.pop, T::Hash[Symbol, T.untyped])
+            log_transformer = App.config.log_transformer
+
+            loglines = if log_transformer
+              log_transformer.call(log_data)
+            else
+              [Oj.dump(
+                Kirei::Logging::Logger.flatten_hash_and_mask_sensitive_values(log_data),
+                Kirei::OJ_OPTIONS,
+              )]
+            end
+
+            loglines.each do |logline|
+              logline = "\n#{logline}\n" if Kirei::App.environment == "development"
+              Kirei::Logging::Logger.logger.unknown(logline)
+            end
+          end
+        end
+      end
+
+      # rubocop:disable Naming/MethodParameterName
+      sig do
+        params(
+          k: String,
+          v: String,
+        ).returns(String)
+      end
+      def self.mask(k, v)
+        App.config.sensitive_keys.any? { k.match?(_1) } ? FILTERED : v
+      end
+      # rubocop:enable Naming/MethodParameterName
+
+      sig do
+        params(
+          hash: T::Hash[T.any(Symbol, String), T.untyped],
+          prefix: String,
+        ).returns(T::Hash[String, T.untyped])
+      end
+      def self.flatten_hash_and_mask_sensitive_values(hash, prefix = "")
+        result = T.let({}, T::Hash[String, T.untyped])
+        Kirei::Helpers.deep_stringify_keys!(hash)
+        hash = T.cast(hash, T::Hash[String, T.untyped])
+
+        hash.each do |key, value|
+          new_prefix = Kirei::Helpers.blank?(prefix) ? key : "#{prefix}.#{key}"
+
+          case value
+          when Hash
+            # Some libraries have a custom Hash class that inhert from Hash, but act differently, e.g. OmniAuth::AuthHash.
+            # This results in `transform_keys` being available but without any effect.
+            value = value.to_h if value.class != Hash
+            result.merge!(flatten_hash_and_mask_sensitive_values(value.transform_keys(&:to_s), new_prefix))
+          when Array
+            value.each_with_index do |element, index|
+              if element.is_a?(Hash) || element.is_a?(Array)
+                result.merge!(flatten_hash_and_mask_sensitive_values({ index => element }, new_prefix))
+              else
+                result["#{new_prefix}.#{index}"] = element.is_a?(String) ? mask(key, element) : element
+              end
+            end
+          when String then result[new_prefix] = mask(key, value)
+          when Numeric, FalseClass, TrueClass, NilClass then result[new_prefix] = value
+          else
+            if value.respond_to?(:serialize)
+              serialized_value = value.serialize
+              if serialized_value.is_a?(Hash)
+                result.merge!(
+                  flatten_hash_and_mask_sensitive_values(serialized_value.transform_keys(&:to_s), new_prefix),
+                )
+              else
+                result[new_prefix] = serialized_value&.to_s
+              end
+            else
+              result[new_prefix] = value&.to_s
+            end
+          end
+        end
+
+        result
+      end
+    end
+    # rubocop:enable Metrics
+  end
+end

data/lib/kirei/logging/metric.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Logging
+    class Metric
+      extend T::Sig
+
+      sig do
+        params(
+          metric_name: String,
+          value: Integer,
+          tags: T::Hash[String, T.untyped],
+        ).void
+      end
+      def self.call(metric_name, value = 1, tags: {})
+        return if ENV["NO_METRICS"] == "true"
+
+        inject_defaults(tags)
+
+        # Do not `compact_blank` tags, since one might want to track empty strings/"false"/NULLs.
+        # NOT having any tag doesn't tell the user if the tag was empty or not set at all.
+        StatsD.increment(metric_name, value, tags: tags)
+      end
+
+      sig { params(tags: T::Hash[String, T.untyped]).returns(T::Hash[String, T.untyped]) }
+      def self.inject_defaults(tags)
+        App.config.metric_default_tags.each_pair do |key, default_value|
+          tags[key] ||= default_value
+        end
+
+        tags["enduser.id"] ||= Thread.current[:enduser_id]
+        tags["service.name"] ||= Kirei::App.config.app_name # OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME
+        tags["service.version"] = Kirei::App.version # OpenTelemetry::SemanticConventions::Resource::SERVICE_VERSION
+
+        tags
+      end
+    end
+  end
+end

data/lib/kirei/model/base_class_interface.rb

@@ -0,0 +1,55 @@
+# typed: strict
+# frozen_string_literal: true
+
+# rubocop:disable Style/EmptyMethod
+
+module Kirei
+  module Model
+    module BaseClassInterface
+      extend T::Sig
+      extend T::Helpers
+      interface!
+
+      sig { abstract.params(hash: T.untyped).returns(T.untyped) }
+      def find_by(hash); end
+
+      sig { abstract.params(hash: T.untyped).returns(T.untyped) }
+      def where(hash); end
+
+      sig { abstract.returns(T.untyped) }
+      def all; end
+
+      sig { abstract.params(hash: T.untyped).returns(T.untyped) }
+      def create(hash); end
+
+      sig { abstract.params(attributes: T.untyped).void }
+      def wrap_jsonb_non_primivitives!(attributes); end
+
+      sig { abstract.params(hash: T.untyped).returns(T.untyped) }
+      def resolve(hash); end
+
+      sig { abstract.params(hash: T.untyped).returns(T.untyped) }
+      def resolve_first(hash); end
+
+      sig { abstract.returns(T.untyped) }
+      def table_name; end
+
+      sig { abstract.returns(T.untyped) }
+      def query; end
+
+      sig { abstract.returns(T.untyped) }
+      def db; end
+
+      sig { abstract.returns(T.untyped) }
+      def human_id_length; end
+
+      sig { abstract.returns(T.untyped) }
+      def human_id_prefix; end
+
+      sig { abstract.returns(T.untyped) }
+      def generate_human_id; end
+    end
+  end
+end
+
+# rubocop:enable Style/EmptyMethod