kirei 0.2.1 → 0.4.0

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

data/lib/kirei/{base_model.rb → model/class_methods.rb}

@@ -2,120 +2,36 @@
 # frozen_string_literal: true
 
 module Kirei
-  module BaseModel
-    extend T::Sig
-    extend T::Helpers
-
-    sig { returns(BaseClassInterface) }
-    def class; super; end # rubocop:disable all
-
-    # An update keeps the original object intact, and returns a new object with the updated values.
-    sig do
-      params(
-        hash: T::Hash[Symbol, T.untyped],
-      ).returns(T.self_type)
-    end
-    def update(hash)
-      hash[:updated_at] = Time.now.utc if respond_to?(:updated_at) && hash[:updated_at].nil?
-      self.class.wrap_jsonb_non_primivitives!(hash)
-      self.class.db.where({ id: id }).update(hash)
-      self.class.find_by({ id: id })
-    end
-
-    # 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.
-    sig { returns(T::Boolean) }
-    def delete
-      count = self.class.db.where({ id: id }).delete
-      count == 1
-    end
-
-    # warning: this is not concurrency-safe
-    # save keeps the original object intact, and returns a new object with the updated values.
-    sig { returns(T.self_type) }
-    def save
-      previous_record = self.class.find_by({ id: id })
-
-      hash = serialize
-      Helpers.deep_symbolize_keys!(hash)
-      hash = T.cast(hash, T::Hash[Symbol, T.untyped])
-
-      if previous_record.nil?
-        self.class.create(hash)
-      else
-        update(hash)
-      end
-    end
-
-    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 db
-      end
-    end
-
+  module Model
     module ClassMethods
       extend T::Sig
       extend T::Generic
 
       # the attached class is the class that extends this module
-      # e.g. "User"
-      # extend T::Generic
-      # has_attached_class!
+      # e.g. "User", "Airport", ..
       has_attached_class!
 
-      include BaseClassInterface
+      include Kirei::Model::BaseClassInterface
 
       # defaults to a pluralized, underscored version of the class name
       sig { override.returns(String) }
       def table_name
-        @table_name ||= T.let(
-          begin
-            table_name_ = Kirei::Helpers.underscore(T.must(name.split("::").last))
-            "#{table_name_}s"
-          end,
-          T.nilable(String),
-        )
+        @table_name ||= T.let("#{model_name}s", T.nilable(String))
+      end
+
+      sig { returns(String) }
+      def model_name
+        Kirei::Helpers.underscore(T.must(name.split("::").last))
       end
 
       sig { override.returns(Sequel::Dataset) }
+      def query
+        db[table_name.to_sym]
+      end
+
+      sig { override.returns(Sequel::Database) }
       def db
-        AppBase.raw_db_connection[table_name.to_sym]
+        App.raw_db_connection
       end
 
       sig do
@@ -124,12 +40,12 @@ module Kirei
         ).returns(T::Array[T.attached_class])
       end
       def where(hash)
-        resolve(db.where(hash))
+        resolve(query.where(hash))
       end
 
       sig { override.returns(T::Array[T.attached_class]) }
       def all
-        resolve(db.all)
+        resolve(query.all)
       end
 
       # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
@@ -156,7 +72,7 @@ module Kirei
           all_attributes["updated_at"] = Time.now.utc
         end
 
-        pkey = T.let(db.insert(all_attributes), String)
+        pkey = T.let(query.insert(all_attributes), String)
 
         T.must(find_by({ id: pkey }))
       end
@@ -166,7 +82,7 @@ module Kirei
       def wrap_jsonb_non_primivitives!(attributes)
         # setting `@raw_db_connection.wrap_json_primitives = true`
         # only works on JSON primitives, but not on blank hashes/arrays
-        return unless AppBase.config.db_extensions.include?(:pg_json)
+        return unless App.config.db_extensions.include?(:pg_json)
 
         attributes.each_pair do |key, value|
           next unless value.is_a?(Hash) || value.is_a?(Array)
@@ -181,7 +97,7 @@ module Kirei
         ).returns(T.nilable(T.attached_class))
       end
       def find_by(hash)
-        resolve_first(db.where(hash))
+        resolve_first(query.where(hash))
       end
 
       # Extra or unknown properties present in the Hash do not raise exceptions at
@@ -196,7 +112,7 @@ module Kirei
         ).returns(T::Array[T.attached_class])
       end
       def resolve(query, strict = nil)
-        strict_loading = strict.nil? ? AppBase.config.db_strict_type_resolving : strict
+        strict_loading = strict.nil? ? App.config.db_strict_type_resolving : strict
 
         query.map do |row|
           row = T.cast(row, T::Hash[Symbol, T.untyped])
@@ -212,12 +128,30 @@ module Kirei
         ).returns(T.nilable(T.attached_class))
       end
       def resolve_first(query, strict = nil)
-        strict_loading = strict.nil? ? AppBase.config.db_strict_type_resolving : strict
+        strict_loading = strict.nil? ? App.config.db_strict_type_resolving : strict
 
         resolve(query.limit(1), strict_loading).first
       end
-    end
 
-    mixes_in_class_methods(ClassMethods)
+      # defaults to 6
+      sig { override.returns(Integer) }
+      def human_id_length = 6
+
+      # defaults to "model_name" (table_name without the trailing "s")
+      sig { override.returns(String) }
+      def human_id_prefix = model_name
+
+      #
+      # Generates a human-readable ID for the record.
+      # The ID is prefixed with the table name and an underscore.
+      #
+      sig { override.returns(String) }
+      def generate_human_id
+        Kirei::Model::HumanIdGenerator.call(
+          length: human_id_length,
+          prefix: human_id_prefix,
+        )
+      end
+    end
   end
 end

data/lib/kirei/model/human_id_generator.rb

@@ -0,0 +1,40 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Kirei
+  module Model
+    class HumanIdGenerator
+      extend T::Sig
+
+      # Removed ambiguous characters 0, 1, O, I, l, 5, S
+      ALLOWED_CHARS = "2346789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrtuvwxyz"
+      private_constant :ALLOWED_CHARS
+
+      ALLOWED_CHARS_COUNT = T.let(ALLOWED_CHARS.size, Integer)
+      private_constant :ALLOWED_CHARS_COUNT
+
+      sig do
+        params(
+          length: Integer,
+          prefix: String,
+        ).returns(String)
+      end
+      def self.call(length:, prefix:)
+        "#{prefix}_#{random_id(length)}"
+      end
+
+      sig { params(key_length: Integer).returns(String) }
+      private_class_method def self.random_id(key_length)
+        random_chars = Array.new(key_length)
+
+        key_length.times do |idx|
+          random_char_idx = SecureRandom.random_number(ALLOWED_CHARS_COUNT)
+          random_char = T.must(ALLOWED_CHARS[random_char_idx])
+          random_chars[idx] = random_char
+        end
+
+        random_chars.join
+      end
+    end
+  end
+end