otto 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fabc1e8d6f7eef1d982b1f298fd0fe68382417aedd4b250ded28e5c7ba39a588
-  data.tar.gz: 02f4509daad92151895100c75339d82e3f8b76106dbcaa04b2db34f7b4d39976
+  metadata.gz: b4e62574b6cb588f8dd99890758af5689dc23732d7a920c0023627a128a5ab5a
+  data.tar.gz: 658e3f7cf3feedf1ee8a120bcb4a5121d2b70c0d5f584b96115ded86d6d2132c
 SHA512:
-  metadata.gz: 2c5f1958418f70a429bfc2379f7407387ca4a1a6cdd129160ff6bf3e416f33a637c0d14049bd97ab0c7abce02ab5b11eb943aff330b5c1c0425d55c387ff3351
-  data.tar.gz: '08e5ec5c3278adeced0dd3c1cffb7452129a12ad742c381b29a29bd569be4d013a67a660ad111bfe51631672e21d96cf2c0f39c69ab595758aa0e7e1d562ed32'
+  metadata.gz: f4426d3362c6f2ceb81ca1d8c1dfd55dad7b404218b6a3715394bec29e466b6bf0f09d290bb11fa157eaaa6c2889e702ccac97ba4f5496e947005cc083046332
+  data.tar.gz: dca5f99161a47a01514f58a7959062d215b5371f2e8165f57399f77cece4529f57ae4e0cb83224fe5fd93acdd4575dc1b04bbb9682afa82f2ad4e98258b9786d

data/.github/workflows/claude-code-review.yml

@@ -54,7 +54,7 @@ jobs:
       - name: Remove claude-review label
         # Remove label whether success or failure - prevents getting stuck
         if: always() && github.event.action != 'opened'
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             try {

data/.github/workflows/code-smells.yml

@@ -71,7 +71,7 @@ jobs:
         continue-on-error: true
 
       - name: Upload Reek report as artifact
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: reek-report

data/.github/workflows/release-gem.yml

@@ -0,0 +1,158 @@
+# Release Gem Workflow
+#
+# Automatically builds and publishes the otto gem to RubyGems.org when a
+# GitHub release is published with a semantic version tag (vMAJOR.MINOR.PATCH,
+# e.g. v0.6.1, v1.2.3).
+#
+# Follows the canonical RubyGems Trusted Publishing workflow:
+#   https://guides.rubygems.org/trusted-publishing/
+#
+# ============================================================================
+# SETUP INSTRUCTIONS (one-time)
+# ============================================================================
+#
+# This workflow uses RubyGems Trusted Publishing (OIDC). No long-lived API
+# key needs to be stored in GitHub.
+#
+# ----------------------------------------------------------------------------
+# 1. Configure the trusted publisher on RubyGems.org
+# ----------------------------------------------------------------------------
+#
+#   a. Sign in to https://rubygems.org and enable MFA on your account
+#      (required for trusted publishing).
+#
+#   b. Open the gem's trusted publisher page (works for both existing gems
+#      and the first-ever publish):
+#        Existing gem: https://rubygems.org/gems/otto/trusted_publishers
+#        First publish: https://rubygems.org/profile/oidc/pending_trusted_publishers/new
+#
+#   c. Click "Create" and fill in:
+#        Publisher type:    GitHub Actions
+#        Repository owner:  delano
+#        Repository name:   otto
+#        Workflow filename: release-gem.yml
+#        Environment:       rubygems.org   (must match `environment.name` below)
+#
+#   d. Save. RubyGems will now accept short-lived OIDC tokens issued by this
+#      workflow running in this repository.
+#
+# ----------------------------------------------------------------------------
+# 2. Configure the GitHub environment
+# ----------------------------------------------------------------------------
+#
+#   a. In GitHub: Settings -> Environments -> New environment
+#      Name: `rubygems.org`   (must match `environment.name` below)
+#
+#   b. Under "Deployment branches and tags", restrict to tags matching:
+#        v*.*.*
+#      This prevents the environment (and its OIDC token) from being used
+#      from any branch or non-release tag.
+#
+#   c. Optional but recommended: add required reviewers to gate publishes
+#      behind manual approval.
+#
+#   No GitHub secrets are required - OIDC handles authentication.
+#
+# ----------------------------------------------------------------------------
+# 3. Cutting a release
+# ----------------------------------------------------------------------------
+#
+#   a. Bump Otto::VERSION in lib/otto/version.rb (semver: MAJOR.MINOR.PATCH).
+#   b. Update CHANGELOG.md and commit on main.
+#   c. On GitHub, draft a Release with tag `vX.Y.Z` (matching the constant)
+#      and publish it. This workflow runs automatically: it verifies the tag
+#      matches the gemspec version, builds the gem, and pushes it.
+#
+# ----------------------------------------------------------------------------
+# Fallback: API key (only if Trusted Publishing isn't an option)
+# ----------------------------------------------------------------------------
+#
+#   1. Create an API key at https://rubygems.org/profile/api_keys with scope
+#      "Push rubygem" restricted to the `otto` gem.
+#   2. Store it as a repo secret named `RUBYGEMS_API_KEY`.
+#   3. Drop the `id-token: write` permission and `environment:` block, and
+#      replace the `rubygems/release-gem` step with:
+#
+#        - name: Publish to RubyGems
+#          env:
+#            GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+#          run: gem push otto-*.gem
+#
+# ----------------------------------------------------------------------------
+# Action provenance (SHA pins)
+# ----------------------------------------------------------------------------
+#
+# All third-party actions below are pinned to a full commit SHA, per GitHub's
+# secure-use guidance for release-critical workflows. The accompanying
+# comment records the tag the SHA was resolved from so renovate/dependabot
+# can keep them current.
+#
+#   actions/checkout      - official GitHub action
+#   ruby/setup-ruby       - official Ruby org action (GitHub-verified creator)
+#   rubygems/release-gem  - official RubyGems action for trusted publishing
+#
+# ============================================================================
+
+name: Release Gem
+
+on:
+  release:
+    types: [published]
+
+# Coarse default. Each job re-declares the narrowest permissions it needs.
+permissions:
+  contents: read
+
+# Don't allow two release runs to race - one published tag, one publish.
+concurrency:
+  group: release-gem-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Build and push gem
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    environment:
+      name: rubygems.org
+      url: https://rubygems.org/gems/otto
+
+    permissions:
+      contents: write   # rubygems/release-gem attaches built .gem to the GitHub release
+      id-token: write   # OIDC token for RubyGems Trusted Publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@afeafc3d1ab54a631816aba4c914a0081c12ff2f # v1.310.0
+        with:
+          bundler-cache: true
+          ruby-version: ruby   # latest stable Ruby installed by setup-ruby
+
+      - name: Verify release tag matches Otto::VERSION
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          case "${RELEASE_TAG}" in
+            v[0-9]*.[0-9]*.[0-9]*) ;;
+            *)
+              echo "Release tag '${RELEASE_TAG}' is not a vMAJOR.MINOR.PATCH semver tag." >&2
+              exit 1
+              ;;
+          esac
+          tag_version="${RELEASE_TAG#v}"
+          gem_version="$(ruby -r ./lib/otto/version.rb -e 'print Otto::VERSION')"
+          if [ "${tag_version}" != "${gem_version}" ]; then
+            echo "Release tag ${RELEASE_TAG} (${tag_version}) != Otto::VERSION (${gem_version})." >&2
+            exit 1
+          fi
+          echo "Releasing otto ${gem_version} from tag ${RELEASE_TAG}"
+
+      - name: Build and push gem to RubyGems
+        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0

data/CHANGELOG.rst

@@ -7,6 +7,31 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.1.0:
+
+2.1.0 — 2026-05-27
+==================
+
+- Add ``Otto#on_route_matched`` lifecycle hook. Callbacks fire after a
+  route matches but before the handler dispatches, with signature
+  ``(env, route_definition)``. Mirrors ``on_request_complete`` for
+  registration and freezing, but exceptions raised from a callback
+  propagate through ``handle_error`` rather than being swallowed, so
+  consumers can route custom error classes through
+  ``register_error_handler`` for short-circuit gating. Skipped for
+  static file routes and the 404 fallback; fires on both literal and
+  dynamic matches. Per-instance state, zero overhead when no callbacks
+  are registered. (#129)
+
+- Add ``Otto#register_handler_wrapper`` API for per-request handler
+  composition. Registers factory blocks composed around each route
+  handler at request time; wrappers nest outermost-first in
+  registration order, with ``RouteAuthWrapper`` preserved as the
+  innermost wrapper so consumers see ``env['otto.strategy_result']``.
+  ``freeze_configuration!`` now exercises every registered wrapper
+  against every loaded route, surfacing ``TypeError`` and factory bugs
+  at boot rather than on the first matching request. (#130)
+
 .. _changelog-2.0.2:
 
 2.0.2 — 2026-04-15

data/Gemfile

@@ -27,7 +27,7 @@ group :development do
   gem 'benchmark'
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
-  gem 'rubocop', '~> 1.81.7', require: false
+  gem 'rubocop', '~> 1.86.2', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.0.2)
+    otto (2.1.0)
       concurrent-ruby (~> 1.3, < 2.0)
       ipaddr (~> 1, < 2.0)
       logger (~> 1, < 2.0)
@@ -18,8 +18,8 @@ GEM
     bigdecimal (4.1.1)
     concurrent-ruby (1.3.6)
     crass (1.0.6)
-    date (3.4.1)
-    debug (1.11.0)
+    date (3.5.1)
+    debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
@@ -52,15 +52,16 @@ GEM
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
-    erb (5.1.1)
+    erb (6.0.4)
     hana (1.3.7)
-    io-console (0.8.1)
-    ipaddr (1.2.8)
-    irb (1.15.2)
+    io-console (0.8.2)
+    ipaddr (1.2.9)
+    irb (1.18.0)
       pp (>= 0.6.0)
+      prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.3)
+    json (2.19.5)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -100,7 +101,7 @@ GEM
     prettier_print (1.2.1)
     prettyprint (0.2.0)
     prism (1.9.0)
-    psych (5.2.6)
+    psych (5.3.1)
       date
       stringio
     racc (1.8.1)
@@ -118,7 +119,7 @@ GEM
       logger
       prism (>= 1.6.0)
       tsort
-    rdoc (6.15.0)
+    rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -129,7 +130,7 @@ GEM
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
     regexp_parser (2.12.0)
-    reline (0.6.2)
+    reline (0.6.3)
       io-console (~> 0.5)
     rexml (3.4.4)
     rspec (3.13.2)
@@ -145,15 +146,15 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.81.7)
+    rubocop (1.86.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.49.1)
@@ -176,8 +177,8 @@ GEM
       rbs (>= 3, < 5)
     ruby-progressbar (1.13.0)
     simpleidn (0.2.3)
-    stackprof (0.2.27)
-    stringio (3.1.7)
+    stackprof (0.2.28)
+    stringio (3.2.0)
     syntax_tree (6.3.0)
       prettier_print (>= 1.2.0)
     tryouts (3.7.1)
@@ -219,7 +220,7 @@ DEPENDENCIES
   rackup
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.81.7)
+  rubocop (~> 1.86.2)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety

data/lib/otto/core/configuration.rb

@@ -170,6 +170,11 @@ class Otto
         deep_freeze_value(@auth_config) if @auth_config
         deep_freeze_value(@option) if @option
 
+        # Validate registered handler-wrapper factories against every loaded
+        # route before locking the config. Surfaces TypeError / factory bugs
+        # at boot instead of on the first request that happens to match.
+        validate_handler_wrappers!
+
         # Deep freeze route structures (prevent modification of nested hashes/arrays)
         deep_freeze_value(@routes) if @routes
         deep_freeze_value(@routes_literal) if @routes_literal
@@ -207,6 +212,35 @@ class Otto
         # Only check the new middleware stack as the single source of truth
         @middleware&.includes?(middleware_class)
       end
+
+      # Walk every loaded route and exercise the registered handler-wrapper
+      # factories against a sentinel inner handler. Each factory must return a
+      # callable; HandlerFactory.apply_handler_wrappers raises TypeError
+      # otherwise. The constructed chain is discarded — this is a fail-fast
+      # validation pass, not memoization.
+      #
+      # Iterates @routes (covers MCP routes added directly) uniquified by
+      # identity. No-op if no wrappers are registered or no routes are loaded.
+      #
+      # @api private
+      # @return [void]
+      def validate_handler_wrappers!
+        return unless @routes && @route_handler_factory
+        return if @handler_wrappers.nil? || @handler_wrappers.empty?
+
+        sentinel = ->(_env, _extra = {}) { [200, {}, []] }
+        seen = {}.compare_by_identity
+        @routes.each_value do |routes_for_verb|
+          routes_for_verb.each do |route|
+            next if seen[route]
+
+            seen[route] = true
+            Otto::RouteHandlers::HandlerFactory.apply_handler_wrappers(
+              sentinel, route.route_definition, self
+            )
+          end
+        end
+      end
     end
   end
 end

data/lib/otto/core/lifecycle_hooks.rb

@@ -58,6 +58,86 @@ class Otto
       def request_complete_callbacks
         @request_complete_callbacks
       end
+
+      # Register a callback fired after a route matches but before the handler dispatches.
+      #
+      # The callback receives two arguments:
+      # - env: the Rack environment hash
+      # - route_definition: the matched Otto::RouteDefinition
+      #
+      # Unlike on_request_complete, exceptions raised inside on_route_matched callbacks
+      # are NOT swallowed: they propagate to Otto#handle_error so consumers can route
+      # custom error classes through register_error_handler.
+      #
+      # Does not fire for static-file routes or for the 404 fallback route.
+      #
+      # @example
+      #   otto.on_route_matched do |env, route_definition|
+      #     raise MyApp::Maintenance if maintenance? && route_definition.auth_requirement
+      #   end
+      #
+      # @yield [env, route_definition] Block to execute after route match
+      # @yieldparam env [Hash] The Rack environment
+      # @yieldparam route_definition [Otto::RouteDefinition] The matched route definition
+      # @return [self] Returns self for method chaining
+      # @raise [FrozenError] if called after configuration is frozen
+      def on_route_matched(&block)
+        ensure_not_frozen!
+        @route_matched_callbacks << block if block_given?
+        self
+      end
+
+      # Get registered route matched callbacks (for internal use)
+      #
+      # @api private
+      # @return [Array<Proc>] Array of registered callback blocks
+      def route_matched_callbacks
+        @route_matched_callbacks
+      end
+
+      # Register a wrapper factory that composes around each route handler.
+      #
+      # The block is invoked once per request, identical to RouteAuthWrapper
+      # instantiation, with the route's definition and the inner (already
+      # wrapped) handler. It must return either the original inner_handler (to
+      # opt out for that route) or a new object responding to :call(env).
+      # Wrappers compose outermost-first in registration order:
+      #
+      #   request -> wrapper_1 -> wrapper_2 -> ... -> RouteAuthWrapper -> base_handler
+      #
+      # RouteAuthWrapper always stays innermost so env['otto.strategy_result'] is set
+      # before any consumer wrapper sees the request.
+      #
+      # Factory blocks are exercised once against every loaded route during
+      # freeze_configuration! (see validate_handler_wrappers!) so factories that
+      # raise unconditionally or return non-callables surface at boot rather
+      # than on the first request that happens to match.
+      #
+      # @example Gate a route by an option set in the routes file
+      #   otto.register_handler_wrapper do |route_definition, inner_handler|
+      #     next inner_handler unless route_definition.option(:scope) == 'canonical'
+      #     MyApp::CanonicalOnlyWrapper.new(inner_handler, route_definition)
+      #   end
+      #
+      # @yield [route_definition, inner_handler] Factory invoked per request
+      # @yieldparam route_definition [Otto::RouteDefinition] The route being wrapped
+      # @yieldparam inner_handler [#call] The handler to wrap (RouteAuthWrapper or base)
+      # @yieldreturn [#call] A callable wrapper, or inner_handler unchanged to skip
+      # @return [self] Returns self for method chaining
+      # @raise [FrozenError] if called after configuration is frozen
+      def register_handler_wrapper(&block)
+        ensure_not_frozen!
+        @handler_wrappers << block if block_given?
+        self
+      end
+
+      # Get registered handler wrapper factories (for internal use)
+      #
+      # @api private
+      # @return [Array<Proc>] Array of registered wrapper factory blocks
+      def handler_wrappers
+        @handler_wrappers
+      end
     end
   end
 end

data/lib/otto/core/router.rb

@@ -110,6 +110,10 @@ class Otto
               handler: route.route_definition.definition,
               auth_strategy: route.route_definition.auth_requirement || 'none'
             ))
+          # Fire route matched hooks before dispatch; raises propagate to handle_error
+          unless @route_matched_callbacks.empty?
+            @route_matched_callbacks.each { |cb| cb.call(env, route.route_definition) }
+          end
           route.call(env)
         elsif static_route && http_verb == :GET && safe_file?(path_info)
           Otto.structured_log(:debug, 'Route matched',
@@ -180,6 +184,12 @@ class Otto
               Otto::LoggingHelpers.request_context(env).merge(
                 fallback_to: '404_route'
               ))
+          else
+            # Fire route matched hooks before dispatch; suppressed for 404 fallback.
+            # Raises propagate to handle_error so custom error classes can be registered.
+            unless @route_matched_callbacks.empty?
+              @route_matched_callbacks.each { |cb| cb.call(env, found_route.route_definition) }
+            end
           end
           found_route.call env, extra_params
         else

data/lib/otto/route_handlers/factory.rb

@@ -37,6 +37,23 @@ class Otto
           )
         end
 
+        apply_handler_wrappers(handler, route_definition, otto_instance)
+      end
+
+      # Compose registered wrappers outermost-first. Built innermost-out so
+      # reverse_each yields a final order of: w1(w2(...(RouteAuthWrapper(base)))).
+      def self.apply_handler_wrappers(handler, route_definition, otto_instance)
+        wrappers = otto_instance&.handler_wrappers
+        return handler if wrappers.nil? || wrappers.empty?
+
+        wrappers.reverse_each do |factory|
+          wrapped = factory.call(route_definition, handler)
+          unless wrapped.respond_to?(:call)
+            raise TypeError,
+                  "handler wrapper must return an object responding to :call, got #{wrapped.class}"
+          end
+          handler = wrapped
+        end
         handler
       end
     end

data/lib/otto/version.rb

@@ -3,5 +3,5 @@
 # frozen_string_literal: true
 
 class Otto
-  VERSION = '2.0.2'
+  VERSION = '2.1.0'
 end

data/lib/otto.rb

@@ -170,7 +170,9 @@ class Otto
     @security          = Otto::Security::Configurator.new(@security_config, @middleware, @auth_config)
     @app               = nil # Pre-built middleware app (built after initialization)
     @request_complete_callbacks = [] # Instance-level request completion callbacks
-    @error_handlers    = {} # Registered error handlers for expected errors
+    @route_matched_callbacks    = [] # Instance-level route matched callbacks
+    @handler_wrappers           = [] # Instance-level handler wrapper factories
+    @error_handlers             = {} # Registered error handlers for expected errors
 
     # Initialize helper module registries
     @request_helper_modules = []

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otto
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -142,6 +142,7 @@ files:
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
 - ".github/workflows/code-smells.yml"
+- ".github/workflows/release-gem.yml"
 - ".gitignore"
 - ".pre-commit-config.yaml"
 - ".pre-push-config.yaml"