zappb-exceptions 1.0.0

data/lib/zappb_exception/class_factory.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module ClassFactory
+    module Namespace; end
+
+    module_function
+
+    def call(definition, aliases = [])
+      unless definition.external || definition.klass
+        keys = definition.payload if definition.declared_payload?
+        ensure_constant(definition.name, base_class(definition), keys)
+      end
+
+      parent = parent_for(definition)
+      aliases.each do |alias_name|
+        next if alias_name.include?("::")
+
+        ensure_constant(alias_name, parent)
+      end
+    end
+
+    def parent_for(definition)
+      return base_class(definition) if definition.external || definition.klass
+
+      ZappbException.const_get(definition.name, false)
+    rescue ::NameError
+      base_class(definition)
+    end
+
+    def base_class(definition)
+      definition.payload && !definition.external && !definition.klass ? PayloadError : BaseError
+    end
+
+    def ensure_constant(name, superclass, payload_keys = nil)
+      *path, leaf = name.split("::")
+      namespace = path.inject(ZappbException) { |parent, segment| namespace_for(parent, segment) }
+
+      if namespace.const_defined?(leaf, false)
+        existing = namespace.const_get(leaf, false)
+        return existing if existing.is_a?(::Class) && existing <= ::Exception
+        return promote(namespace, leaf, existing, superclass, payload_keys) if existing.is_a?(Namespace)
+
+        raise ConfigurationError, "ZappbException::#{name} already exists and is not an error class"
+      end
+      namespace.const_set(leaf, build(superclass, payload_keys))
+    end
+
+    def namespace_for(parent, segment)
+      unless parent.const_defined?(segment, false)
+        return parent.const_set(segment, ::Module.new.extend(Namespace))
+      end
+
+      existing = parent.const_get(segment, false)
+      return existing if existing.is_a?(::Module)
+
+      raise ConfigurationError, "#{parent.name}::#{segment} already exists and is neither a module nor a class"
+    end
+
+    def promote(namespace, leaf, old, superclass, payload_keys)
+      klass = build(superclass, payload_keys)
+      old.constants(false).each { |const| klass.const_set(const, old.const_get(const, false)) }
+      namespace.send(:remove_const, leaf)
+      namespace.const_set(leaf, klass)
+    end
+
+    def build(superclass, payload_keys)
+      klass = ::Class.new(superclass)
+      klass.payload_keys = payload_keys if payload_keys
+      klass
+    end
+  end
+end

data/lib/zappb_exception/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module ZappbException
+  class Configuration
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    attr_reader :code_prefix, :safe_detail, :meta_key, :locale
+    attr_writer :logger
+
+    def initialize(registry)
+      @registry = registry
+      @code_prefix = ""
+      @service_label = UNSET
+      @meta_key = nil
+      @safe_detail = false
+      @locale = nil
+      @logger = nil
+    end
+
+    def code_prefix=(value)
+      @code_prefix = value.to_s
+    end
+
+    def meta_key=(value)
+      unless value.nil? || ((value.is_a?(::String) || value.is_a?(::Symbol)) && !value.to_s.empty?)
+        raise ConfigurationError, "meta_key must be nil, or a non-empty String or Symbol"
+      end
+
+      @meta_key = value&.to_sym
+    end
+
+    def service_label
+      return @service_label unless @service_label.equal?(UNSET)
+
+      default_service_label
+    end
+
+    def service_label=(value)
+      @service_label = value
+    end
+
+    def safe_detail=(value)
+      unless [true, false].include?(value) || value.respond_to?(:call)
+        raise ConfigurationError, "safe_detail must be true, false or a callable"
+      end
+
+      @safe_detail = value
+    end
+
+    def locale=(value)
+      unless value.nil? || ((value.is_a?(::String) || value.is_a?(::Symbol)) && !value.to_s.empty?)
+        raise ConfigurationError, "locale must be nil, or a non-empty String or Symbol"
+      end
+
+      @locale = value&.to_sym
+    end
+
+    def logger
+      @logger || default_logger
+    end
+
+    def register(name, **options)
+      @registry.register(name, **options)
+    end
+
+    def alias_external(class_name, to:)
+      @registry.alias_external(class_name, to: to)
+    end
+
+    private
+
+    def default_service_label
+      return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+      ::Rails.application.class.module_parent_name
+    end
+
+    def default_logger
+      rails_logger = ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+      rails_logger || (@fallback_logger ||= ::Logger.new($stdout))
+    end
+  end
+end

data/lib/zappb_exception/definition.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ZappbException
+  NAME_SEGMENT = /\A[A-Z]\w*\z/
+  PAYLOAD_KEY = /\A[a-z_]\w*\z/
+  RESERVED_PAYLOAD_KEYS = %i[meta exception detail].freeze
+
+  Definition = Data.define(:name, :status, :number, :message, :code, :external, :payload, :klass, :base, :fallback,
+                           :safe_detail) do
+    def initialize(name:, status:, message:, number: nil, code: nil, external: false, payload: false,
+                   klass: nil, base: false, fallback: false, safe_detail: nil)
+      name = name.to_s
+      raise ConfigurationError, "The error name cannot be empty" if name.empty?
+      if name.start_with?("ZappbException::")
+        raise ConfigurationError, "The name '#{name}' must not have the 'ZappbException::' prefix"
+      end
+      unless status.is_a?(::Integer) && (400..599).cover?(status)
+        raise ConfigurationError, "#{name}: status must be an integer between 400 and 599 (got #{status.inspect})"
+      end
+      unless message.is_a?(::String) && !message.empty?
+        raise ConfigurationError, "#{name}: message is required"
+      end
+      unless code.nil? || (code.is_a?(::String) && !code.empty?)
+        raise ConfigurationError, "#{name}: code must be a non-empty String"
+      end
+      if klass && !(klass.is_a?(::Class) || klass.respond_to?(:call))
+        raise ConfigurationError, "#{name}: klass must be a class or a callable returning one"
+      end
+      unless fallback || code
+        unless number.is_a?(::Integer) && number >= 1
+          raise ConfigurationError, "#{name}: number must be an integer >= 1 (got #{number.inspect})"
+        end
+      end
+      unless number.nil? || (number.is_a?(::Integer) && number >= 0)
+        raise ConfigurationError, "#{name}: number must be an integer >= 1 (got #{number.inspect})"
+      end
+
+      external = external || (klass && name.include?("::")) ? true : false
+      if !external && !name.split("::", -1).all? { |segment| segment.match?(NAME_SEGMENT) }
+        raise ConfigurationError, "#{name}: invalid constant name"
+      end
+      unless safe_detail.nil? || [true, false].include?(safe_detail) || safe_detail.respond_to?(:call)
+        raise ConfigurationError, "#{name}: safe_detail must be true, false or a callable"
+      end
+      payload = self.class.normalize_payload(name, payload)
+
+      super(name: name.dup.freeze, status: status, number: number, message: message.dup.freeze,
+            code: code&.dup&.freeze, external: external, payload: payload,
+            klass: klass, base: base ? true : false, fallback: fallback ? true : false,
+            safe_detail: safe_detail)
+    end
+
+    def self.normalize_payload(name, payload)
+      return payload ? true : false unless payload.is_a?(::Array)
+
+      keys = payload.map do |key|
+        unless key.is_a?(::Symbol) || key.is_a?(::String)
+          raise ConfigurationError, "#{name}: payload keys must be Symbol or String (got #{key.inspect})"
+        end
+
+        key.to_sym
+      end.uniq
+      raise ConfigurationError, "#{name}: payload cannot be an empty Array" if keys.empty?
+
+      keys.each do |key|
+        unless key.match?(PAYLOAD_KEY)
+          raise ConfigurationError, "#{name}: invalid payload key (#{key.inspect})"
+        end
+        if RESERVED_PAYLOAD_KEYS.include?(key) || PayloadError.method_defined?(key)
+          raise ConfigurationError, "#{name}: payload key '#{key}' is reserved"
+        end
+      end
+      keys.freeze
+    end
+
+    def declared_payload?
+      payload.is_a?(::Array)
+    end
+
+    def internal?
+      !external
+    end
+
+    def error_code(prefix = "")
+      return code if code
+
+      "#{status}-#{prefix}#{format("%02d", number || 0)}"
+    end
+
+    def resolve_klass
+      return nil unless klass
+
+      klass.respond_to?(:call) ? klass.call : klass
+    rescue ::NameError
+      nil
+    end
+  end
+
+  Definition::UNHANDLED = Definition.new(name: "Unhandled", status: 500, number: 0,
+                                         message: "Unhandled exception", fallback: true)
+end

data/lib/zappb_exception/describer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module Describer
+    Description = Data.define(:status, :code, :message) do
+      def level
+        Describer.level_for(status)
+      end
+    end
+
+    module_function
+
+    def level_for(status)
+      status.to_i >= 500 ? :error : :warn
+    end
+
+    def level(exception, config: ZappbException.configuration)
+      call(exception, config: config).level
+    end
+
+    def call(exception, config: ZappbException.configuration)
+      if exception.is_a?(ForwardedError) && exception.error_hash.is_a?(::Hash)
+        hash = exception.error_hash
+        return Description.new(status: Envelope.forwarded_status(hash), code: Envelope.forwarded_code(hash),
+                               message: RemoteError.from(hash).message)
+      end
+
+      definition = Resolver.call(exception)
+      Description.new(status: definition.status, code: definition.error_code(config.code_prefix),
+                      message: Envelope.message_for(definition, config: config))
+    end
+  end
+end

data/lib/zappb_exception/detail_sanitizer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module DetailSanitizer
+    module_function
+
+    def call(exception, setting)
+      case setting
+      when true
+        exception.is_a?(BaseError) ? exception.message : exception.class.name.to_s
+      when false, nil
+        exception.message
+      else
+        setting.call(exception).to_s
+      end
+    end
+  end
+end

data/lib/zappb_exception/envelope.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module Envelope
+    Result = Data.define(:status, :body, :definition)
+
+    I18N_SCOPE = "zappb_exception.errors"
+    RESERVED_ERROR_KEYS = %i[exception detail].freeze
+
+    module_function
+
+    def call(exception, meta: {}, definition: nil, config: ZappbException.configuration)
+      signed = signed_meta(exception, meta, config)
+
+      if exception.is_a?(ForwardedError) && exception.error_hash.is_a?(::Hash)
+        hash = exception.error_hash
+        body = hash.symbolize_keys.except(:meta)
+        final = merge_meta(remote_meta(hash), signed)
+        return Result.new(status: forwarded_status(hash), body: with_meta(body, final), definition: nil)
+      end
+
+      definition ||= Resolver.call(exception)
+      body = {
+        success: false,
+        status: definition.status,
+        code: definition.error_code(config.code_prefix),
+        message: message_for(definition, config: config),
+        error: error_for(exception, config, definition)
+      }
+      Result.new(status: definition.status, body: with_meta(body, signed), definition: definition)
+    end
+
+    def signed_meta(exception, meta, config)
+      own = exception.respond_to?(:meta) ? exception.meta : nil
+      local = deep_symbolize(hash_or_empty(own)).merge(deep_symbolize(hash_or_empty(meta)))
+      return {} if local.empty?
+
+      key = config.meta_key
+      key ? { key.to_sym => local } : local
+    rescue ::StandardError
+      {}
+    end
+
+    def remote_meta(hash)
+      value = hash.key?("meta") ? hash["meta"] : hash[:meta]
+      deep_symbolize(hash_or_empty(value))
+    end
+
+    def merge_meta(remote, local)
+      remote.merge(local) do |_key, remote_value, local_value|
+        if remote_value.is_a?(::Hash) && local_value.is_a?(::Hash)
+          merge_meta(remote_value, local_value)
+        else
+          local_value
+        end
+      end
+    end
+
+    def with_meta(body, meta)
+      meta.empty? ? body : body.merge(meta: meta)
+    end
+
+    def hash_or_empty(value)
+      value.is_a?(::Hash) ? value : {}
+    end
+
+    def deep_symbolize(value)
+      case value
+      when ::Hash
+        value.each_with_object({}) do |(key, item), acc|
+          acc[key.respond_to?(:to_sym) ? key.to_sym : key] = deep_symbolize(item)
+        end
+      when ::Array then value.map { |item| deep_symbolize(item) }
+      else value
+      end
+    end
+
+    def error_for(exception, config, definition = nil)
+      { exception: exception.class.name, detail: detail_for(exception, config, definition) }
+        .merge(extra_for(exception))
+    end
+
+    def extra_for(exception)
+      extra = exception.respond_to?(:extra_data) ? exception.extra_data : nil
+      return {} unless extra.is_a?(::Hash) && !extra.empty?
+
+      extra.transform_keys(&:to_sym).except(*RESERVED_ERROR_KEYS)
+    end
+
+    def forwarded_status(hash)
+      status = Integer(hash["status"] || hash[:status] || 500, exception: false)
+      status && (100..599).cover?(status) ? status : 500
+    end
+
+    def forwarded_code(hash)
+      hash["code"] || hash[:code]
+    end
+
+    def message_for(definition, config: ZappbException.configuration)
+      return definition.message unless defined?(::I18n)
+
+      options = { default: definition.message }
+      options[:locale] = config.locale if config.locale
+      ::I18n.t("#{I18N_SCOPE}.#{definition.name}", **options)
+    rescue ::StandardError
+      definition.message
+    end
+
+    def detail_for(exception, config, definition = nil)
+      setting = definition.nil? || definition.safe_detail.nil? ? config.safe_detail : definition.safe_detail
+      setting = true if definition&.fallback && definition.safe_detail.nil? && !setting
+      text = DetailSanitizer.call(exception, setting)
+      label = config.service_label
+      label.nil? || label.to_s.empty? ? text : "[#{label}] #{text}"
+    end
+  end
+end

data/lib/zappb_exception/errors.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ZappbException
+  class ConfigurationError < ::StandardError; end
+
+  class FrozenRegistryError < ConfigurationError; end
+
+  class BaseError < ::StandardError
+    def extra_data
+      {}
+    end
+
+    def meta
+      @meta ||= {}
+    end
+
+    def initialize(message = nil, meta: {})
+      @meta = meta.is_a?(::Hash) ? meta.dup : {}
+      super(message)
+    end
+
+    def with_meta(hash)
+      meta.merge!(hash) if hash.is_a?(::Hash)
+      self
+    end
+  end
+
+  class PayloadError < BaseError
+    class << self
+      def payload_keys
+        return @payload_keys if defined?(@payload_keys)
+
+        superclass.respond_to?(:payload_keys) ? superclass.payload_keys : nil
+      end
+
+      def payload_keys=(keys)
+        @payload_keys = keys.freeze
+        keys.each { |key| define_method(key) { payload[key] } }
+      end
+    end
+
+    attr_reader :payload
+
+    def initialize(message = nil, meta: {}, **payload)
+      keys = self.class.payload_keys
+      if keys
+        unknown = payload.keys - keys
+        unless unknown.empty?
+          raise ::ArgumentError, "Undeclared payload keys: #{unknown.join(", ")} (declared: #{keys.join(", ")})"
+        end
+
+        payload = keys.to_h { |key| [key, payload[key]] }
+      end
+      @payload = payload
+      super(message, meta: meta)
+    end
+
+    def extra_data
+      payload
+    end
+  end
+
+  class ForwardedError < BaseError
+    attr_reader :error_hash
+
+    def initialize(error_hash = nil, meta: {}, **rest)
+      error_hash = rest if error_hash.nil? && !rest.empty?
+      @error_hash = error_hash
+      message = if error_hash.is_a?(::Hash)
+        error_hash["message"] || error_hash[:message] || error_hash.to_s
+      else
+        error_hash.to_s
+      end
+      super(message, meta: meta)
+    end
+
+    def remote
+      @remote ||= RemoteError.from(error_hash)
+    end
+
+    def status = remote.status
+
+    def code = remote.code
+
+    def kind?(*names) = remote.kind?(*names)
+
+    def success? = remote.success?
+
+    def extra = remote.extra
+
+    def detail(strip_label: false) = remote.detail(strip_label: strip_label)
+
+    def remote_meta = remote.meta
+  end
+end

data/lib/zappb_exception/handler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module Handler
+    HANDLER = proc { |exception| ZappbException::Handler.handle(self, exception) }
+
+    def self.included(base)
+      return unless base.respond_to?(:rescue_from)
+
+      base.rescue_from ::StandardError, with: HANDLER
+    end
+
+    def self.handle(controller, exception, meta: {}, config: ZappbException.configuration)
+      result = Envelope.call(exception, meta: meta, config: config)
+
+      Notifier.notify(exception, result, config: config)
+
+      render(controller, result)
+    end
+
+    def self.render(controller, result)
+      return unless controller.respond_to?(:render)
+
+      controller.render status: result.status, json: result.body.compact
+    rescue ::StandardError => e
+      config = ZappbException.configuration
+      config.logger.error "ZappbException::Handler render failed: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/zappb_exception/nats.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module Nats
+    module_function
+
+    def reply(meta: {}, notify: true, config: ZappbException.configuration)
+      yield
+    rescue ::StandardError => e
+      result = Envelope.call(e, meta: meta, config: config)
+      notify_safely(e, result, config) if notify
+      result.body.compact
+    end
+
+    def error_response?(response)
+      return false unless response.is_a?(::Hash)
+
+      success = RemoteError.read(response, :success)
+      return true if success == false || success.to_s == "false"
+
+      present?(RemoteError.read(response, :error))
+    end
+
+    def raise_on_error!(response, on_nil: GatewayTimeout, meta: {})
+      if response.nil?
+        valid = on_nil.is_a?(::Exception) || (on_nil.is_a?(::Class) && on_nil <= ::Exception)
+        raise ::ArgumentError, "on_nil must be an Exception class or instance, got #{on_nil.inspect}" unless valid
+
+        raise on_nil.new(meta: meta) if on_nil.is_a?(::Class) && on_nil <= BaseError
+        raise on_nil.with_meta(meta) if on_nil.is_a?(BaseError)
+
+        raise on_nil
+      end
+      raise ForwardedError.new(response, meta: meta) if error_response?(response)
+
+      response
+    end
+
+    def present?(value)
+      value.respond_to?(:empty?) ? !value.empty? : !!value
+    end
+
+    def notify_safely(exception, result, config)
+      Notifier.notify(exception, result, config: config)
+    rescue ::StandardError => e
+      config.logger.error "ZappbException::Nats notify failed: #{e.class}: #{e.message}"
+    end
+  end
+end

data/lib/zappb_exception/notifier.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ZappbException
+  module Notifier
+    ERROR_EVENT = "zappb_exception.error"
+    FORWARDED_EVENT = "zappb_exception.forwarded_error"
+
+    module_function
+
+    def error(exception, definition, meta: nil, config: ZappbException.configuration)
+      status = definition.status
+      server_error = status >= 500
+      emit(ERROR_EVENT, status, config, {
+        exception_class: exception.class.name,
+        http_status: status,
+        error_code: definition.error_code(config.code_prefix),
+        message: parse_message(exception.message),
+        backtrace: server_error ? exception.backtrace&.first(10) : exception.backtrace&.first(1),
+        meta: presence(meta),
+        extra: presence(Envelope.extra_for(exception))
+      }.compact)
+    end
+
+    def forwarded(exception, status:, error_code:, meta: nil, config: ZappbException.configuration)
+      emit(FORWARDED_EVENT, status, config, {
+        http_status: status,
+        error_code: error_code,
+        message: exception.message,
+        meta: presence(meta),
+        extra: presence(remote_extra(exception))
+      }.compact)
+    end
+
+    def notify(exception, result, config: ZappbException.configuration)
+      if result.definition
+        error(exception, result.definition, meta: result.body[:meta], config: config)
+      elsif exception.is_a?(ForwardedError) && exception.error_hash.is_a?(::Hash)
+        forwarded(exception, status: result.status,
+                  error_code: Envelope.forwarded_code(exception.error_hash),
+                  meta: result.body[:meta], config: config)
+      end
+    end
+
+    def presence(meta)
+      meta.is_a?(::Hash) && !meta.empty? ? meta : nil
+    end
+
+    def remote_extra(exception)
+      hash = exception.respond_to?(:error_hash) ? exception.error_hash : nil
+      hash.is_a?(::Hash) ? RemoteError.from(hash).extra : {}
+    end
+
+    def parse_message(message)
+      JSON.parse(message)
+    rescue ::StandardError
+      message
+    end
+
+    def event_reporter
+      ::Rails.event if defined?(::Rails) && ::Rails.respond_to?(:event)
+    end
+
+    def emit(name, status, config, payload)
+      level = Describer.level_for(status)
+      reporter = event_reporter
+      if reporter
+        reporter.tagged(level: level) { reporter.notify(name, payload) }
+      else
+        config.logger.public_send(level, JSON.generate({ event: name }.merge(payload)))
+      end
+    end
+  end
+end

data/lib/zappb_exception/rack.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ZappbException
+  module Rack
+    module_function
+
+    def render(exception, meta: {}, notify: true, config: ZappbException.configuration)
+      result = Envelope.call(exception, meta: meta, config: config)
+      Notifier.notify(exception, result, config: config) if notify
+      [result.status, { "content-type" => "application/json" }, [JSON.generate(result.body.compact)]]
+    end
+  end
+end