zappb-exceptions 1.0.0

data/lib/zappb_exception/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ZappbException
+  class Railtie < ::Rails::Railtie
+    initializer "zappb_exception.i18n" do
+      ::I18n.load_path |= ZappbException::LOCALE_FILES
+    end
+
+    config.after_initialize { ZappbException.finalize! }
+  end
+end

data/lib/zappb_exception/registry.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module ZappbException
+  class Registry
+    def initialize(view: nil)
+      @definitions = {}
+      @aliases = {}
+      @class_aliases = {}
+      @frozen = false
+      @view = view
+      @index = nil
+    end
+
+    def load_base
+      BASE_CATALOG.each { |entry| register(entry[:name], **entry.except(:name), base: true) }
+      self
+    end
+
+    def register(name, aliases: [], override: false, **attrs)
+      raise FrozenRegistryError, frozen_message(name) if @frozen
+
+      definition = Definition.new(name: name, **attrs)
+      alias_names = Array(aliases).map { |a| validate_alias!(a, definition) }
+      check_name!(definition, override)
+      check_numbering!(definition)
+
+      ClassFactory.call(definition, alias_names)
+      @definitions[definition.name] = definition
+      alias_names.each { |a| @aliases[a] = definition.name }
+      changed!
+      definition
+    end
+
+    def alias_external(class_name, to:)
+      raise FrozenRegistryError, frozen_message(class_name) if @frozen
+
+      class_name = validate_class_alias!(class_name)
+      target = lookup(to)
+      raise ConfigurationError, "alias_external '#{class_name}': target entry '#{to}' does not exist" unless target
+
+      @class_aliases[class_name] = target.name
+      changed!
+      target
+    end
+
+    def freeze!
+      @frozen = true
+      self
+    end
+
+    def frozen?
+      @frozen
+    end
+
+    def definitions
+      @definitions.values
+    end
+
+    def aliases
+      @aliases.dup
+    end
+
+    def class_aliases
+      @class_aliases.dup
+    end
+
+    def lookup(name)
+      name = name.to_s.delete_prefix("ZappbException::")
+      @definitions[name] || (@aliases[name] && @definitions[@aliases[name]]) ||
+        (@class_aliases[name] && @definitions[@class_aliases[name]])
+    end
+
+    def definition_for_class(klass)
+      name = klass.name
+      found = index[name] if name
+      return found if found
+
+      @definitions.each_value do |definition|
+        return definition if definition.klass && definition.resolve_klass.equal?(klass)
+      end
+      nil
+    end
+
+    def to_exceptions
+      @definitions.transform_values do |d|
+        entry = { status: d.status, error_code: d.number, message: d.message }
+        entry[:code] = d.code if d.code
+        entry[:external] = true if d.external
+        entry[:payload] = d.payload if d.payload
+        entry.freeze
+      end
+    end
+
+    private
+
+    def changed!
+      @index = nil
+      @view&.replace(to_exceptions)
+    end
+
+    def frozen_message(name)
+      "Cannot register '#{name}': the catalog is already frozen (it is frozen in after_initialize " \
+        "or by ZappbException.finalize!). Register errors in config/initializers."
+    end
+
+    def validate_alias!(alias_name, definition)
+      alias_name = alias_name.to_s
+      if alias_name.start_with?("ZappbException::")
+        raise ConfigurationError, "The alias '#{alias_name}' must not have the 'ZappbException::' prefix"
+      end
+      if alias_name == definition.name
+        raise ConfigurationError, "The alias '#{alias_name}' matches the definition name"
+      end
+      if @definitions.key?(alias_name) || (@aliases.key?(alias_name) && @aliases[alias_name] != definition.name)
+        raise ConfigurationError, "The alias '#{alias_name}' is already registered"
+      end
+      unless alias_name.include?("::") || alias_name.match?(/\A[A-Z]\w*\z/)
+        raise ConfigurationError, "#{alias_name}: invalid alias name"
+      end
+
+      alias_name
+    end
+
+    def validate_class_alias!(class_name)
+      class_name = class_name.to_s
+      if class_name.start_with?("ZappbException::")
+        raise ConfigurationError, "The alias '#{class_name}' must not have the 'ZappbException::' prefix"
+      end
+      unless class_name.split("::", -1).all? { |segment| segment.match?(NAME_SEGMENT) }
+        raise ConfigurationError, "#{class_name}: invalid class name"
+      end
+      if @definitions.key?(class_name) || @aliases.key?(class_name) || @class_aliases.key?(class_name)
+        raise ConfigurationError, "The alias '#{class_name}' is already registered"
+      end
+
+      class_name
+    end
+
+    def check_name!(definition, override)
+      if @class_aliases.key?(definition.name)
+        raise ConfigurationError, "'#{definition.name}' is already registered as an alias of #{@class_aliases[definition.name]}"
+      end
+      existing = @definitions[definition.name]
+      if @aliases.key?(definition.name)
+        raise ConfigurationError, "'#{definition.name}' is already registered as an alias of #{@aliases[definition.name]}"
+      end
+      return unless existing
+      return if override
+
+      origin = existing.base ? "a base entry" : "a registered entry"
+      raise ConfigurationError, "'#{definition.name}' already exists as #{origin}; use override: true to redefine it"
+    end
+
+    def check_numbering!(definition)
+      return if definition.code
+
+      clash = @definitions.values.find do |other|
+        other.name != definition.name && other.code.nil? &&
+          other.status == definition.status && other.number == definition.number
+      end
+      return unless clash
+
+      raise ConfigurationError, "#{definition.name}: #{definition.status}-#{definition.number} is already used by " \
+                                "#{clash.name}; use another number or define a code:"
+    end
+
+    def index
+      @index ||= build_index
+    end
+
+    def build_index
+      idx = {}
+      @definitions.each_value do |d|
+        next if d.klass
+
+        idx[d.external ? d.name : "ZappbException::#{d.name}"] = d
+        idx[d.name] = d if !d.external && d.name != "Exception" && !d.name.include?("::") && core_class?(d.name)
+      end
+      @class_aliases.each { |class_name, target| idx[class_name] = @definitions.fetch(target) }
+      @aliases.each do |alias_name, target|
+        idx[alias_name.include?("::") ? alias_name : "ZappbException::#{alias_name}"] = @definitions.fetch(target)
+      end
+      idx
+    end
+
+    def core_class?(name)
+      ::Object.const_defined?(name, false) && ::Object.const_get(name, false).is_a?(::Class) &&
+        ::Object.const_source_location(name) == []
+    end
+  end
+end

data/lib/zappb_exception/remote_error.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ZappbException
+  class RemoteError
+    PREFIX = "ZappbException::"
+    LABEL = /\A\[[^\]]*\]\s*/
+
+    attr_reader :raw
+
+    def self.from(response)
+      response.is_a?(::Hash) ? new(response) : NoResponse.new
+    end
+
+    def self.read(hash, key)
+      return unless hash.is_a?(::Hash)
+
+      hash.key?(key.to_s) ? hash[key.to_s] : hash[key.to_sym]
+    end
+
+    def self.normalize_name(name)
+      text = name.to_s
+      text.start_with?(PREFIX) ? text.delete_prefix(PREFIX) : text
+    end
+
+    def initialize(raw)
+      @raw = raw
+    end
+
+    def no_response? = false
+
+    def error? = Nats.error_response?(raw)
+
+    def ok? = !error?
+
+    def success?
+      return false unless raw.is_a?(::Hash)
+
+      [true, "true"].include?(self.class.read(raw, :success))
+    end
+
+    def status
+      Integer(self.class.read(raw, :status), exception: false)
+    end
+
+    def code
+      string_or_nil(self.class.read(raw, :code))
+    end
+
+    def message
+      string_or_nil(self.class.read(raw, :message))
+    end
+
+    def exception_name
+      name = string_or_nil(error_hash_value(:exception))
+      name && self.class.normalize_name(name)
+    end
+
+    def kind?(*names)
+      current = exception_name
+      return false if current.nil?
+
+      names.flatten.any? { |name| self.class.normalize_name(name) == current }
+    end
+
+    def detail(strip_label: false)
+      text = string_or_nil(error_hash_value(:detail))
+      strip_label && text ? text.sub(LABEL, "") : text
+    end
+
+    def meta
+      value = self.class.read(raw, :meta)
+      value.is_a?(::Hash) ? value : {}
+    end
+
+    def extra
+      error = self.class.read(raw, :error)
+      return {} unless error.is_a?(::Hash)
+
+      error.each_with_object({}) do |(key, value), acc|
+        name = key.to_sym
+        acc[name] = value unless %i[exception detail].include?(name)
+      end
+    end
+
+    def to_forwarded_error
+      ForwardedError.new(raw)
+    end
+
+    private
+
+    def error_hash_value(key)
+      self.class.read(self.class.read(raw, :error), key)
+    end
+
+    def string_or_nil(value)
+      value.nil? ? nil : value.to_s
+    end
+
+    class NoResponse < RemoteError
+      def initialize(_raw = nil)
+        super(nil)
+      end
+
+      def no_response? = true
+
+      def error? = false
+
+      def ok? = false
+
+      def success? = false
+
+      def extra = {}
+
+      def status = nil
+
+      def code = nil
+
+      def message = nil
+
+      def exception_name = nil
+
+      def kind?(*) = false
+
+      def meta = {}
+
+      def detail(strip_label: false) = nil # rubocop:disable Lint/UnusedMethodArgument
+
+      def to_forwarded_error
+        GatewayTimeout.new
+      end
+    end
+  end
+end

data/lib/zappb_exception/resolver.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ZappbException
+  module Resolver
+    module_function
+
+    def call(exception, registry: ZappbException.registry)
+      exception.class.ancestors.each do |ancestor|
+        next unless ancestor.is_a?(::Class)
+
+        definition = registry.definition_for_class(ancestor)
+        return definition if definition
+      end
+      Definition::UNHANDLED
+    end
+  end
+end

data/lib/zappb_exception/rspec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require "rspec/expectations"
+require "zappb_exception/testing"
+
+module ZappbException
+  module RSpecHelpers
+    module_function
+
+    def resolved_name(exception)
+      ZappbException::Resolver.call(exception).name
+    end
+
+    def envelope_hash(actual)
+      actual = JSON.parse(actual) if actual.is_a?(::String)
+      actual.is_a?(::Hash) ? actual.deep_symbolize_keys : {}
+    end
+
+    def deep_symbolize(value)
+      value.is_a?(::Hash) ? value.deep_symbolize_keys : value
+    end
+
+    def expected_fields(code:, status:, message:, exception:, detail:, meta:)
+      { code: code, status: status, message: message,
+        exception: exception && ZappbException::RemoteError.normalize_name(exception),
+        detail: detail, meta: meta && deep_symbolize(meta) }.compact
+    end
+
+    def actual_fields(hash)
+      error = hash[:error].is_a?(::Hash) ? hash[:error] : {}
+      meta = hash[:meta].is_a?(::Hash) ? hash[:meta] : {}
+      exception = error[:exception] && ZappbException::RemoteError.normalize_name(error[:exception])
+      status = Integer(hash[:status], exception: false)
+      { code: hash[:code], status: status, message: hash[:message], exception: exception,
+        detail: error[:detail], meta: meta }
+    end
+  end
+end
+
+RSpec::Matchers.define :be_zappb_error do |name = nil|
+  match do |actual|
+    if name.nil?
+      actual.is_a?(ZappbException::BaseError)
+    else
+      actual.is_a?(::StandardError) &&
+        ZappbException::RSpecHelpers.resolved_name(actual) == ZappbException::RemoteError.normalize_name(name)
+    end
+  end
+
+  failure_message do |actual|
+    got = actual.is_a?(::StandardError) ? ZappbException::RSpecHelpers.resolved_name(actual) : actual.inspect
+    "expected #{actual.class} to resolve to #{name.inspect}, got #{got}"
+  end
+
+  description { "be a ZappbException error#{" #{name}" if name}" }
+end
+
+RSpec::Matchers.define :raise_zappb_error do |name, message = nil|
+  supports_block_expectations
+
+  match do |block|
+    @error = nil
+    begin
+      block.call
+    rescue ::StandardError => e
+      @error = e
+    end
+    @error &&
+      ZappbException::RSpecHelpers.resolved_name(@error) == ZappbException::RemoteError.normalize_name(name) &&
+      (message.nil? || values_match?(message, @error.message))
+  end
+
+  failure_message do
+    if @error
+      "expected a #{name} error#{" with message #{message.inspect}" if message}, " \
+        "got #{@error.class}: #{@error.message}"
+    else
+      "expected a #{name} error, but nothing was raised"
+    end
+  end
+
+  description { "raise a ZappbException #{name} error" }
+end
+
+RSpec::Matchers.define :match_error_envelope do |code: nil, status: nil, message: nil, exception: nil,
+                                                 detail: nil, meta: nil|
+  match do |actual|
+    helpers = ZappbException::RSpecHelpers
+    @expected = helpers.expected_fields(code: code, status: status, message: message, exception: exception,
+                                        detail: detail, meta: meta)
+    @actual = helpers.actual_fields(helpers.envelope_hash(actual))
+    @expected.all? { |key, value| values_match?(value, @actual[key]) }
+  end
+
+  failure_message do
+    diff = @expected.reject { |key, value| values_match?(value, @actual[key]) }
+    "expected error envelope to match #{diff.inspect}, got #{@actual.slice(*diff.keys).inspect}"
+  end
+
+  description { "match error envelope #{@expected.inspect}" }
+end

data/lib/zappb_exception/testing.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "zappb_exception"
+
+module ZappbException
+  module Testing
+    module_function
+
+    def error_response(name, detail: nil, meta: {}, extra: {}, config: ZappbException.configuration)
+      key = RemoteError.normalize_name(name)
+      definition = ZappbException.registry.lookup(key)
+      raise ::ArgumentError, "Unregistered error: #{key}" unless definition
+
+      text = detail || Envelope.message_for(definition, config: config)
+      label = config.service_label
+      body = {
+        success: false,
+        status: definition.status,
+        code: definition.error_code(config.code_prefix),
+        message: Envelope.message_for(definition, config: config),
+        error: {
+          exception: exception_name(definition),
+          detail: label.nil? || label.to_s.empty? ? text : "[#{label}] #{text}"
+        }.merge(extra.to_h.transform_keys(&:to_sym).except(*Envelope::RESERVED_ERROR_KEYS))
+      }
+      meta.is_a?(::Hash) && !meta.empty? ? body.merge(meta: meta) : body
+    end
+
+    def exception_name(definition)
+      return definition.resolve_klass&.name || definition.name if definition.klass
+      return definition.name unless definition.internal?
+
+      "#{RemoteError::PREFIX}#{definition.name}"
+    end
+    private_class_method :exception_name
+
+    def success_response(data = {})
+      { success: true, status: 200, message: nil, data: data, meta: {} }
+    end
+  end
+end

data/lib/zappb_exception/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ZappbException
+  VERSION = "1.0.0"
+end

data/lib/zappb_exception.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/hash/keys"
+require "active_support/i18n"
+
+require "zappb_exception/version"
+require "zappb_exception/errors"
+require "zappb_exception/definition"
+require "zappb_exception/base_catalog"
+require "zappb_exception/class_factory"
+require "zappb_exception/registry"
+require "zappb_exception/configuration"
+require "zappb_exception/resolver"
+require "zappb_exception/detail_sanitizer"
+require "zappb_exception/envelope"
+require "zappb_exception/describer"
+require "zappb_exception/notifier"
+require "zappb_exception/remote_error"
+require "zappb_exception/nats"
+require "zappb_exception/handler"
+require "zappb_exception/rack"
+
+module ZappbException
+  LOCALE_FILES = Dir[File.expand_path("../config/locales/*.yml", __dir__)].freeze
+
+  EXCEPTIONS = {}
+
+  class << self
+    def registry
+      @registry ||= Registry.new(view: EXCEPTIONS).load_base
+    end
+
+    def configuration
+      @configuration ||= Configuration.new(registry)
+    end
+
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def finalize!
+      registry.freeze!
+      self
+    end
+
+    def reset!
+      @registry = nil
+      @configuration = nil
+      EXCEPTIONS.clear
+      registry
+      self
+    end
+
+    def error_code_for(entry)
+      prefix = configuration.code_prefix
+      return entry.error_code(prefix) if entry.is_a?(Definition)
+
+      entry[:code] || "#{entry[:status]}-#{prefix}#{format("%02d", entry[:error_code])}"
+    end
+
+    def generate_json(exception, name = exception.class.name, meta: {})
+      definition = unless name == exception.class.name
+        registry.lookup(name) || Definition::UNHANDLED
+      end
+      Envelope.call(exception, meta: meta, definition: definition).body
+    end
+
+    def describe(exception, config: configuration)
+      Describer.call(exception, config: config)
+    end
+
+    def log_level(exception, config: configuration)
+      Describer.level(exception, config: config)
+    end
+
+    def define_exceptions!
+      EXCEPTIONS
+    end
+
+    def const_missing(name)
+      definition = registry.lookup(name.to_s)
+      klass = definition&.resolve_klass
+      return const_set(name, klass) if klass
+
+      super
+    end
+  end
+
+  I18n.load_path |= LOCALE_FILES
+
+  registry
+end
+
+require "zappb_exception/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: zappb-exceptions
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- BPO Advisors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Exception handling for microservices in an MSA architecture that communicate
+  through messaging. Each service declares its own error catalog; errors travel between
+  services and to clients as a stable JSON contract. Includes capture for Rails controllers,
+  Rack middlewares and NATS listeners, plus instrumentation events.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/locales/en.yml
+- config/locales/es.yml
+- lib/zappb/exceptions.rb
+- lib/zappb_exception.rb
+- lib/zappb_exception/base_catalog.rb
+- lib/zappb_exception/class_factory.rb
+- lib/zappb_exception/configuration.rb
+- lib/zappb_exception/definition.rb
+- lib/zappb_exception/describer.rb
+- lib/zappb_exception/detail_sanitizer.rb
+- lib/zappb_exception/envelope.rb
+- lib/zappb_exception/errors.rb
+- lib/zappb_exception/handler.rb
+- lib/zappb_exception/nats.rb
+- lib/zappb_exception/notifier.rb
+- lib/zappb_exception/rack.rb
+- lib/zappb_exception/railtie.rb
+- lib/zappb_exception/registry.rb
+- lib/zappb_exception/remote_error.rb
+- lib/zappb_exception/resolver.rb
+- lib/zappb_exception/rspec.rb
+- lib/zappb_exception/testing.rb
+- lib/zappb_exception/version.rb
+homepage: https://rubygems.org/gems/zappb-exceptions
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: 'Exception handling for messaging-based microservices: per-service error
+  catalog and a stable JSON contract.'
+test_files: []