interceptors 0.1.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '076710813e9e517742bb3a92db2e062d63908d6e66ce2686fba366861dceff78'
-  data.tar.gz: b8dec78267d96a79c68463d912601ec2d5d514cffef9096fa98574fd2f9aa5c1
+  metadata.gz: a4c31ab76d3b09a2a51c674ceb27aaaaf82cda31e6267b56be86b67ee77a9155
+  data.tar.gz: f1a4039246aa384126f1391faa4e879d3f4a8d3b98900f95f88e5b5bbe7aa60e
 SHA512:
-  metadata.gz: ee6a7c1b9036259bd69fd9f2075ccc342b641dae13446a8ec240533ca55c6fa2c37ae6f2ab114cca080837043d1bfcd3a2c809a5db5fa773229b33b2ff422af5
-  data.tar.gz: 3e487d4624bb0f755dc15eadd6e9f42b811a733734dd0a813b6c76550198ab5506d47be56048ebf6abc569ecb016956808224d32c8aee17cc61a12c8e82f087f
+  metadata.gz: 8a5edaa5997b949864f547e50d2226b75af99fd9bc214cbff7b8e4eec4f23e6546e104edc46978aed03d6ae0b860d1955f2125a92b5b7c2a1105d9ceef3ab9fb
+  data.tar.gz: 942e90230e3bd6ecbff48ab19d2bbb81543cf09e805c3dec779731fbab1515537270d522172a97c08c03e7efb9c69031b9920245272beb1c89844e3458fc5842

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+- Initial release of the `interceptors` gem.

data/Gemfile

@@ -1,6 +1,7 @@
 source "https://rubygems.org"
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
-# Specify your gem's dependencies in interceptors.gemspec
 gemspec
+
+gem "rake"

data/{LICENSE.txt → LICENSE}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2019 Laerti Papa
+Copyright (c) 2024 Interceptors Maintainers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,52 +1,145 @@
 # Interceptors
 
-[Pedestal](http://pedestal.io/reference/interceptors) like interceptors pipe and filter service objects in Ruby. Common use cases like http service objects or multiple steps business workflow. 
+Interceptor-driven use case toolkit for Ruby and Rails applications.
+
+## Features
+- Consistent `Result` object with `ok?`/`err?` helpers and metadata.
+- Base `UseCase` class with interceptor pipeline support.
+- Built-in interceptors for logging, validation, retries, timeouts, transactions, and idempotency.
+- Uniform error taxonomy (`AppError`, `ValidationError`, `AuthError`) with HTTP semantics.
+- Instrumentation via `ActiveSupport::Notifications`.
+- Optional Rails responder helper for controllers or jobs.
 
 ## Installation
 
-Add     this line to your application's Gemfile:
+Add the gem to your bundle:
 
 ```ruby
-gem 'interceptors'
+gem "interceptors"
 ```
 
-And then execute:
-
-    $ bundle
+## Usage
 
-Or install it yourself as:
-
-    $ gem install interceptors
+```ruby
+class CreateUser < Interceptors::UseCase
+  use Interceptors::LoggingInterceptor.new
+  use Interceptors::ValidationInterceptor.new do |ctx|
+    errors = {}
+    errors[:email] = "is required" if ctx[:email].to_s.strip.empty?
+    errors
+  end
+
+  private
+
+  def execute(ctx)
+    user = User.create!(email: ctx[:email])
+    Interceptors::Result.ok(user)
+  rescue ActiveRecord::RecordInvalid => e
+    Interceptors::Result.err(Interceptors::ValidationError.new(e.record.errors.to_hash))
+  end
+end
+
+result = CreateUser.call(email: "user@example.com")
+result.ok? #=> true
+```
 
-## Overview
+### Richer example: checkout flow
 
-TBD
+```ruby
+class CheckoutOrder < Interceptors::UseCase
+  use Interceptors::LoggingInterceptor.new
+  use Interceptors::TimeoutInterceptor.new(seconds: 3)
+  use Interceptors::RetryInterceptor.new(tries: 3, on: [ActiveRecord::Deadlocked])
+  use Interceptors::TransactionInterceptor.new
+  use Interceptors::IdempotencyInterceptor.new(key_proc: ->(ctx) { "checkout:#{ctx[:idempotency_key]}" })
+
+  use Interceptors::ValidationInterceptor.new do |ctx|
+    errors = {}
+    errors[:cart_id] = "is required" if ctx[:cart_id].to_s.empty?
+    errors[:payment_token] = "is required" if ctx[:payment_token].to_s.empty?
+    errors
+  end
+
+  private
+
+  def execute(ctx)
+    guard_policy!(ctx[:actor], ctx[:cart_id])
+
+    cart    = Cart.lock.find(ctx[:cart_id])
+    payment = charge_payment!(ctx[:payment_token], cart.total_cents)
+
+    order = persist_order!(cart, payment, ctx)
+
+    Interceptors::Result.ok(order, meta: { order_id: order.id, payment_id: payment.id })
+  rescue PaymentGateway::Error => e
+    Interceptors::Result.err(
+      Interceptors::AppError.new(e.message, code: "payment_failed", http_status: 422, details: { gateway: e.code })
+    )
+  end
+
+  def guard_policy!(actor, cart_id)
+    allowed = actor&.can?(:checkout, cart_id)
+    raise Interceptors::AuthError.new unless allowed
+  end
+
+  def charge_payment!(token, amount_cents)
+    PaymentGateway.charge!(token: token, amount_cents: amount_cents)
+  end
+
+  def persist_order!(cart, payment, ctx)
+    Order.create!(
+      user: ctx[:actor].user,
+      total_cents: cart.total_cents,
+      payment_reference: payment.id,
+      shipping_address: ctx[:shipping_address]
+    ).tap do |order|
+      cart.line_items.each do |line_item|
+        order.order_lines.create!(sku: line_item.sku, qty: line_item.quantity, price_cents: line_item.price_cents)
+      end
+    end
+  end
+end
+
+result = CheckoutOrder.call(
+  cart_id: params[:cart_id],
+  payment_token: params[:payment_token],
+  shipping_address: params[:shipping_address],
+  idempotency_key: request.headers["Idempotency-Key"],
+  actor: Current.session
+)
+
+if result.ok?
+  render json: { order_id: result.value.id }, status: :created
+else
+  err = result.error
+  render json: { error: err.code, message: err.message, details: err.details }, status: err.http_status
+end
+```
 
-## Usage examples
+Instrument use cases with ActiveSupport:
 
-Create your interceptors by extending `Interceptors::Base` class and define one of `on_enter`, `on_leave` or `on_error` method based on your use case. Register each one of them to an `Interceptors::Executor` instance and send `#call` message on it. Implement your logic in each interceptor service per use case.
+```ruby
+ActiveSupport::Notifications.subscribe("use_case.finish") do |_name, _start, _finish, _id, payload|
+  Rails.logger.info("[UseCase] #{payload[:name]} ok=#{payload[:ok]}")
+end
+```
 
+For Rails controllers, include the responder helper:
 
 ```ruby
+class UsersController < ApplicationController
+  include Interceptors::Rails::UseCaseResponder
 
-``` 
+  def create
+    respond_with_use_case(CreateUser.call(user_params))
+  end
+end
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/laertispappas/interceptors. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+After checking out the repo, run `bin/setup` to install dependencies. Then run `bundle exec rspec` to run the tests.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Code of Conduct
-
-Everyone interacting in the Interceptors project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/interceptors/blob/master/CODE_OF_CONDUCT.md).
-
-## Acknowledgments
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/Rakefile

@@ -1,6 +1 @@
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-task :default => :spec

data/lib/interceptors/app_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class AppError < StandardError
+    attr_reader :code, :details, :http_status
+
+    def initialize(message = "Application error", code: "app_error", http_status: 400, details: {})
+      super(message)
+      @code = code
+      @http_status = http_status
+      @details = details || {}
+    end
+
+    def to_h
+      {
+        message: message,
+        code: code,
+        http_status: http_status,
+        details: details
+      }
+    end
+  end
+end

data/lib/interceptors/auth_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class AuthError < AppError
+    def initialize(message: "Unauthorized", code: "unauthorized", http_status: 401, details: {})
+      super(message, code: code, http_status: http_status, details: details)
+    end
+  end
+end

data/lib/interceptors/idempotency_interceptor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Interceptors
+  class IdempotencyInterceptor < Interceptor
+    class MemoryStore
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      def read(key)
+        @mutex.synchronize { @data[key] }
+      end
+
+      def write(key, value, ttl: nil)
+        @mutex.synchronize { @data[key] = value }
+        value
+      end
+
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+    end
+
+    DEFAULT_STORE = MemoryStore.new
+
+    def initialize(key_proc:, ttl: 300, store: DEFAULT_STORE)
+      raise ArgumentError, "key_proc must be callable" unless key_proc.respond_to?(:call)
+
+      @key_proc = key_proc
+      @ttl = ttl.to_i
+      @store = store
+    end
+
+    def around(ctx)
+      key = safe_key(ctx)
+      return yield ctx unless key
+
+      cached = @store.read(key)
+      return cached if fresh?(cached)
+
+      result = yield ctx
+      return result unless result.is_a?(Result)
+      return result unless result.ok?
+
+      stored = result.merge_meta(stored_at: Time.now.to_i)
+      @store.write(key, stored, ttl: @ttl)
+      stored
+    end
+
+    private
+
+    def safe_key(ctx)
+      @key_proc.call(ctx)
+    rescue StandardError
+      nil
+    end
+
+    def fresh?(result)
+      return false unless result.is_a?(Result)
+      return false unless @ttl.positive?
+
+      stored_at = result.meta[:stored_at]
+      return false unless stored_at
+
+      (Time.now.to_i - stored_at.to_i) < @ttl
+    end
+  end
+end

data/lib/interceptors/interceptor.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class Interceptor
+    def before(_ctx); end
+
+    def after(_ctx, result); result; end
+
+    def around(ctx)
+      yield ctx
+    end
+  end
+end

data/lib/interceptors/logging_interceptor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class LoggingInterceptor < Interceptor
+    def initialize(logger: nil)
+      @logger = logger
+    end
+
+    def before(ctx)
+      log(:before, ctx: ctx)
+    end
+
+    def after(_ctx, result)
+      log(:after, ok: result.ok?, error: result.error&.message)
+      result
+    end
+
+    private
+
+    def log(stage, payload)
+      event = event_name("log")
+      Interceptors.instrument(event, payload.merge(stage: stage))
+      return unless @logger
+
+      @logger.info("[Interceptors] stage=#{stage} payload=#{payload}")
+    end
+
+    def event_name(suffix)
+      "#{Interceptors.configuration.notification_namespace}.#{suffix}"
+    end
+  end
+end

data/lib/interceptors/pipeline.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class Pipeline
+    def initialize(interceptors)
+      @interceptors = Array(interceptors)
+    end
+
+    def call(ctx, &final_handler)
+      raise ArgumentError, "a final handler block is required" unless final_handler
+
+      chain = @interceptors.reverse.inject(final_handler) do |acc, interceptor|
+        proc do |inner_ctx|
+          interceptor.before(inner_ctx)
+          result = interceptor.around(inner_ctx) { |next_ctx| acc.call(next_ctx) }
+          interceptor.after(inner_ctx, result) || result
+        end
+      end
+
+      chain.call(ctx)
+    end
+  end
+end

data/lib/interceptors/rails/use_case_responder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Interceptors
+  module Rails
+    module UseCaseResponder
+      private
+
+      def respond_with_use_case(result, serializer: nil, status_ok: 200, **render_options)
+        if result.ok?
+          body = serializer ? serializer.new(result.value) : result.value
+          render({ json: body, status: status_ok }.merge(render_options))
+        else
+          error = result.error
+          payload = {
+            error: error.code,
+            message: error.message,
+            details: error.details
+          }
+          render({ json: payload, status: error.http_status }.merge(render_options))
+        end
+      end
+    end
+  end
+end

data/lib/interceptors/result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class Result
+    attr_reader :value, :error, :meta
+
+    def initialize(value: nil, error: nil, meta: {})
+      @value = value
+      @error = error
+      @meta = meta || {}
+    end
+
+    def ok?
+      error.nil?
+    end
+
+    def err?
+      !ok?
+    end
+
+    def self.ok(value = nil, meta: {})
+      new(value: value, meta: meta)
+    end
+
+    def self.err(error, meta: {})
+      raise ArgumentError, "error must be provided" if error.nil?
+
+      new(error: error, meta: meta)
+    end
+
+    def merge_meta(extra)
+      self.class.new(value: value, error: error, meta: meta.merge(extra))
+    end
+
+    def to_h
+      { value: value, error: error, meta: meta }
+    end
+  end
+end

data/lib/interceptors/retry_interceptor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class RetryInterceptor < Interceptor
+    def initialize(tries: 3, on: [StandardError], base_delay: 0.05, max_delay: 0.5)
+      raise ArgumentError, "tries must be >= 1" unless tries.to_i >= 1
+
+      @tries = tries.to_i
+      @exceptions = Array(on)
+      @base_delay = base_delay.to_f
+      @max_delay = max_delay.to_f
+    end
+
+    def around(ctx)
+      attempt = 0
+
+      begin
+        attempt += 1
+        yield ctx
+      rescue => e
+        raise unless @exceptions.any? { |klass| e.is_a?(klass) }
+
+        return Result.err(e) if attempt >= @tries
+
+        Kernel.sleep(delay_for_attempt(attempt))
+        retry
+      end
+    end
+
+    private
+
+    def delay_for_attempt(attempt)
+      [@base_delay * (2**(attempt - 1)), @max_delay].min
+    end
+  end
+end

data/lib/interceptors/timeout_interceptor.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Interceptors
+  class TimeoutInterceptor < Interceptor
+    def initialize(seconds:)
+      raise ArgumentError, "seconds must be positive" unless seconds.to_f.positive?
+
+      @seconds = seconds.to_f
+    end
+
+    def around(ctx)
+      Timeout.timeout(@seconds) { yield ctx }
+    rescue Timeout::Error
+      Result.err(AppError.new("Timeout", code: "timeout", http_status: 504))
+    end
+  end
+end

data/lib/interceptors/transaction_interceptor.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class TransactionInterceptor < Interceptor
+    def initialize(adapter: default_adapter)
+      @adapter = adapter
+    end
+
+    def around(ctx)
+      return yield ctx unless @adapter
+
+      @adapter.call { yield ctx }
+    end
+
+    private
+
+    def default_adapter
+      return nil unless defined?(ActiveRecord::Base)
+      return nil unless ActiveRecord::Base.respond_to?(:connection)
+
+      lambda do |&block|
+        ActiveRecord::Base.transaction(&block)
+      end
+    end
+  end
+end

data/lib/interceptors/use_case.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class UseCase
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@interceptors, interceptors.dup)
+      end
+
+      def interceptors
+        @interceptors ||= []
+      end
+
+      def use(interceptor)
+        interceptors << interceptor
+        self
+      end
+
+      def call(input = {}, **kwargs)
+        new.call(input, **kwargs)
+      end
+    end
+
+    def call(input = {}, **kwargs)
+      ctx = build_context(input, **kwargs)
+
+      instrument(event_name("start"), name: self.class.name, ctx: ctx)
+
+      result = pipeline.call(ctx) { |context| normalize_result(execute(context)) }
+      result = normalize_result(result)
+
+      instrument(event_name("finish"),
+                 name: self.class.name,
+                 ctx: ctx,
+                 ok: result.ok?,
+                 error: result.error&.message)
+
+      result
+    rescue AppError => e
+      instrument(event_name("error"),
+                 name: self.class.name,
+                 ctx: ctx,
+                 code: e.code,
+                 message: e.message)
+
+      Result.err(e, meta: base_meta)
+    rescue StandardError => e
+      instrument(event_name("error"),
+                 name: self.class.name,
+                 ctx: ctx,
+                 code: "unhandled_exception",
+                 message: e.message,
+                 error_class: e.class.name)
+
+      err = AppError.new("Unhandled exception",
+                         code: "unhandled_exception",
+                         http_status: 500,
+                         details: { cause: e.class.name })
+      Result.err(err, meta: base_meta.merge(error_class: e.class.name))
+    end
+
+    private
+
+    def execute(_ctx)
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
+
+    def normalize_result(result)
+      case result
+      when Result
+        result
+      when nil
+        Result.ok
+      else
+        Result.ok(result)
+      end
+    end
+
+    def base_meta
+      { use_case: self.class.name }
+    end
+
+    def build_context(input, **kwargs)
+      ctx = default_context.merge(normalize_input(input))
+      ctx.merge!(kwargs) unless kwargs.empty?
+      ctx.with_indifferent_access
+    end
+
+    def normalize_input(input)
+      return input if input.is_a?(Hash)
+      return input.to_h if input.respond_to?(:to_h)
+
+      raise ArgumentError, "use case input must be a Hash or respond to #to_h (got #{input.class})"
+    end
+
+    def default_context
+      {}
+    end
+
+    def pipeline
+      Pipeline.new(self.class.interceptors)
+    end
+
+    def notification_namespace
+      Interceptors.configuration.notification_namespace
+    end
+
+    def instrument(event_name, payload, &block)
+      Interceptors.instrument(event_name, payload, &block)
+    end
+
+    def event_name(suffix)
+      "#{notification_namespace}.#{suffix}"
+    end
+  end
+end

data/lib/interceptors/validation_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class ValidationError < AppError
+    def initialize(details = nil, message: "Validation failed", code: "validation_failed", http_status: 422, **keywords)
+      payload = if details.nil?
+                  {}
+                elsif details.respond_to?(:to_hash)
+                  details.to_hash
+                else
+                  { base: Array(details) }
+                end
+
+      payload.merge!(keywords) unless keywords.empty?
+
+      super(message, code: code, http_status: http_status, details: payload)
+    end
+  end
+end

data/lib/interceptors/validation_interceptor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Interceptors
+  class ValidationInterceptor < Interceptor
+    def initialize(&block)
+      raise ArgumentError, "validation block is required" unless block
+
+      @validator = block
+    end
+
+    def before(ctx)
+      errors = normalize_errors(@validator.call(ctx))
+      raise ValidationError.new(errors) if errors.any?
+    end
+
+    private
+
+    def normalize_errors(value)
+      return {} if value.nil?
+      return value if value.is_a?(Hash)
+      return value.to_hash if value.respond_to?(:to_hash)
+      return value.to_h if value.respond_to?(:to_h)
+
+      { base: Array(value) }
+    end
+  end
+end

data/lib/interceptors/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Interceptors
-  VERSION = "0.1.1"
+  VERSION = "1.0.2"
 end

data/lib/interceptors.rb

@@ -1,14 +1,58 @@
-require "interceptors/version"
+# frozen_string_literal: true
 
-require "interceptors/ds/node"
-require "interceptors/ds/stack"
-require "interceptors/middleware"
-require "interceptors/executor"
-require "interceptors/base"
-require "interceptors/context"
+require "zeitwerk"
+require "active_support/notifications"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/isolated_execution_state"
 
 module Interceptors
-  def self.root
-    Pathname.new(File.expand_path('../..', __FILE__))
+  class << self
+    def loader
+      @loader ||= Zeitwerk::Loader.for_gem.tap do |loader|
+        loader.inflector.inflect("version" => "VERSION")
+      end
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def instrument(event_name, payload)
+      if block_given?
+        ActiveSupport::Notifications.instrument(event_name, payload) { yield }
+      else
+        ActiveSupport::Notifications.instrument(event_name, payload)
+      end
+    end
+
+    private
+
+    def log_instrumentation_failure(exception, event_name, payload)
+      message = "[Interceptors] instrumentation failure for #{event_name}: #{exception.class} - #{exception.message}"
+      logger = configuration.logger
+      if logger&.respond_to?(:error)
+        logger.error(message)
+      else
+        Kernel.warn(message)
+      end
+      if logger&.respond_to?(:debug)
+        logger.debug("payload=#{payload.inspect}")
+      end
+    end
+  end
+
+  class Configuration
+    attr_accessor :notification_namespace, :logger
+
+    def initialize
+      @notification_namespace = "use_case"
+      @logger = nil
+    end
   end
 end
+
+Interceptors.loader.setup

metadata

@@ -1,23 +1,23 @@
 --- !ruby/object:Gem::Specification
 name: interceptors
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 1.0.2
 platform: ruby
 authors:
-- Laerti Papa
-autorequire: 
-bindir: exe
+- Laerti papa
+autorequire:
+bindir: bin
 cert_chain: []
-date: 2019-05-04 00:00:00.000000000 Z
+date: 2025-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -25,13 +25,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -52,41 +52,43 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Pedestal like interceptors service objects in Ruby, aka pipe and filter
-  architecture
+description: Interceptors provides a production-ready pattern for building use case
+  objects with consistent results, interceptor pipelines, and instrumentation.
 email:
-- laerti.papa@xing.com
+- laertis.pappas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
-- CODE_OF_CONDUCT.md
+- CHANGELOG.md
 - Gemfile
-- Gemfile.lock
-- LICENSE.txt
+- LICENSE
 - README.md
 - Rakefile
-- bin/console
-- bin/setup
-- interceptors.gemspec
 - lib/interceptors.rb
-- lib/interceptors/base.rb
-- lib/interceptors/context.rb
-- lib/interceptors/ds/errors.rb
-- lib/interceptors/ds/node.rb
-- lib/interceptors/ds/stack.rb
-- lib/interceptors/executor.rb
-- lib/interceptors/middleware.rb
+- lib/interceptors/app_error.rb
+- lib/interceptors/auth_error.rb
+- lib/interceptors/idempotency_interceptor.rb
+- lib/interceptors/interceptor.rb
+- lib/interceptors/logging_interceptor.rb
+- lib/interceptors/pipeline.rb
+- lib/interceptors/rails/use_case_responder.rb
+- lib/interceptors/result.rb
+- lib/interceptors/retry_interceptor.rb
+- lib/interceptors/timeout_interceptor.rb
+- lib/interceptors/transaction_interceptor.rb
+- lib/interceptors/use_case.rb
+- lib/interceptors/validation_error.rb
+- lib/interceptors/validation_interceptor.rb
 - lib/interceptors/version.rb
-homepage: https://www.github.com/laertispappas/interceptors
+homepage: https://github.com/laertispappas/interceptors
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
-post_install_message: 
+  homepage_uri: https://github.com/laertispappas/interceptors
+  source_code_uri: https://github.com/laertispappas/interceptors
+  changelog_uri: https://github.com/laertispappas/interceptors/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -94,15 +96,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.5.23
+signing_key:
 specification_version: 4
-summary: Pedestal like interceptors service objects in Ruby
+summary: Interceptor-driven use case toolkit for Ruby and Rails applications.
 test_files: []

data/.gitignore

@@ -1,13 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-.idea
-
-# rspec failure tracking
-.rspec_status

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.travis.yml

@@ -1,5 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.4.3
-before_install: gem install bundler -v 1.16.1

data/CODE_OF_CONDUCT.md

@@ -1,74 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-nationality, personal appearance, race, religion, or sexual identity and
-orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at laerti.papa@xing.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile.lock

@@ -1,35 +0,0 @@
-PATH
-  remote: .
-  specs:
-    interceptors (0.1.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    diff-lcs (1.3)
-    rake (12.3.2)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.3)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler
-  interceptors!
-  rake
-  rspec
-
-BUNDLED WITH
-   1.17.3

data/bin/console

@@ -1,14 +0,0 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "interceptors"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here

data/interceptors.gemspec

@@ -1,36 +0,0 @@
-
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "interceptors/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "interceptors"
-  spec.version       = Interceptors::VERSION
-  spec.authors       = ["Laerti Papa"]
-  spec.email         = ["laerti.papa@xing.com"]
-
-  spec.summary       = %q{Pedestal like interceptors service objects in Ruby}
-  spec.description   = %q{Pedestal like interceptors service objects in Ruby, aka pipe and filter architecture}
-  spec.homepage      = "https://www.github.com/laertispappas/interceptors"
-  spec.license       = "MIT"
-
-  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata["allowed_push_host"] = "https://rubygems.org"
-  else
-    raise "RubyGems 2.0 or newer is required to protect against " \
-      "public gem pushes."
-  end
-
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
-end

data/lib/interceptors/base.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Interceptors
-  class Base
-    def on_enter(ctx)
-      ctx
-    end
-
-    def on_leave(ctx)
-      ctx
-    end
-
-    def on_error(ctx)
-      ctx
-    end
-  end
-end

data/lib/interceptors/context.rb

@@ -1,6 +0,0 @@
-require "ostruct"
-
-module Interceptors
-  class Context < OpenStruct
-  end
-end

data/lib/interceptors/ds/errors.rb

@@ -1,15 +0,0 @@
-module Interceptors
-  module DS
-    module Errors
-      Error = Class.new(StandardError)
-      class NullValueNotAllowedError < Error; end
-      class NoSuchElementException < Error; end
-
-      private
-
-      def assert!(item)
-        raise NullValueNotAllowedError, "A value must not be null in the dequeue" if item.nil?
-      end
-    end
-  end
-end

data/lib/interceptors/ds/node.rb

@@ -1,12 +0,0 @@
-module Interceptors
-  module DS
-    class Node
-      attr_accessor :next, :item
-
-      def initialize(item)
-        @item = item
-        @next = nil
-      end
-    end
-  end
-end

data/lib/interceptors/ds/stack.rb

@@ -1,30 +0,0 @@
-require_relative "./errors"
-
-module Interceptors
-  module DS
-    class Stack
-      include DS::Errors
-
-      def initialize
-        @head = nil
-      end
-
-      def push(item)
-        assert!(item)
-        old_head = @head
-        @head = Node.new(item)
-        @head.next = old_head
-      end
-
-      def pop
-        raise NoSuchElementException if empty?
-
-        @head.item.tap { @head = @head.next }
-      end
-
-      def empty?
-        @head.nil?
-      end
-    end
-  end
-end

data/lib/interceptors/executor.rb

@@ -1,45 +0,0 @@
-module Interceptors
-  class Executor
-    attr_reader :middleware, :context
-
-    def initialize(context = Context.new)
-      @middleware = Middleware.new
-      @context = context
-    end
-
-    def register(interceptor)
-      middleware.enqueue(interceptor)
-    end
-
-    def call
-      while (interceptor, step = fetch_next)
-        with_exception_handling(interceptor) do
-          interceptor.public_send(step, context)
-        end
-      end
-
-      context
-    end
-
-    private
-
-    def fetch_next
-      if context[:error]
-        [middleware.pop, :on_error] unless middleware.on_leave.empty?
-      elsif !middleware.on_enter.empty?
-        interceptor = middleware.dequeue
-        middleware.push(interceptor)
-        [interceptor, :on_enter]
-      elsif !middleware.on_leave.empty?
-        [middleware.pop, :on_leave]
-      end
-    end
-
-    def with_exception_handling(interceptor)
-      yield
-    rescue StandardError => e
-      context[:error] = e
-      context[:error_raised_at] = interceptor.class.name
-    end
-  end
-end

data/lib/interceptors/middleware.rb

@@ -1,28 +0,0 @@
-module Interceptors
-  class Middleware
-    attr_reader :on_enter, :on_leave
-
-    def initialize
-      @on_enter = Queue.new
-      @on_leave = DS::Stack.new
-    end
-
-    # Queue operations
-    def enqueue(element)
-      on_enter.push(element)
-    end
-
-    def dequeue
-      on_enter.pop
-    end
-
-    # Stack operations
-    def push(element)
-      on_leave.push(element)
-    end
-
-    def pop
-      on_leave.pop
-    end
-  end
-end