otto 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72c7a8fdbc299b202666d5f94532e4eed6d3fc2b2ee6a58234519deba65bfb0c
-  data.tar.gz: d82daec0441d3e9a8c196e6306aa8945292b8a322e3acbdf146294bc55345782
+  metadata.gz: e50cca678689db3e2447e76a8a1b12f3b709305d4f73908cb06dfe6883adc596
+  data.tar.gz: a6093388b74ffbd098c222a026c1f1cf439c8039c75a0d55b663a0874669c6ee
 SHA512:
-  metadata.gz: 64e1787e35c416585076ba4befa922c4306f0f023cba463877a66b821ab9e1518e3afda4edd6e8a319a04750c3c29d5b79196fc4961f807438b1f27eed4d0687
-  data.tar.gz: e6384fc6c848c602ea4c7f2c7eee7aaab7a715df054e404d6660e9c72fb85b52f4ff0a98108121a4995fe401a09bc67bcb459d0e37d00f4897a42df6b90d2d10
+  metadata.gz: ea5a8acda9a29c09d3a16a050050c2e9b9a1517c7f63e24bb7bc910801a7a07874fff1215550a740cef2c9c3698bc77378083b33f47794a7668b77feff9e6e67
+  data.tar.gz: 62cfbe824d5d0d9e159424a6d930217f05b8b01de7142108a6a80953207cca9037a3e63d6ae5c16585dda3ff7b8a9b2d070b593f748563c0a5a20ed852add37f

data/.github/dependabot.yml

@@ -10,6 +10,6 @@ updates:
     schedule:
       interval: "weekly"
   - package-ecosystem: "bundler"
-    directory: "/"
+    directory: "/" # Location of package manifests
     schedule:
       interval: "weekly"

data/.github/workflows/ci.yml

@@ -37,6 +37,9 @@ jobs:
         # `require_relative 'file/write.rb'` against a file deleted in
         # the same release, the reason 2.0.2 exists.
         include:
+          - ruby: "3.2"
+            experimental: false
+            lockfile: "locked"
           - ruby: "3.3"
             experimental: false
             lockfile: "locked"
@@ -49,6 +52,9 @@ jobs:
           - ruby: "4.0"
             experimental: true
             lockfile: "locked"
+          - ruby: "3.2"
+            experimental: false
+            lockfile: "unlocked"
           - ruby: "3.3"
             experimental: false
             lockfile: "unlocked"
@@ -63,7 +69,7 @@ jobs:
             lockfile: "unlocked"
 
     steps:
-      - uses: actions/checkout@v6.0.3
+      - uses: actions/checkout@v7.0.0
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         continue-on-error: ${{ matrix.experimental }}

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

@@ -4,6 +4,16 @@ on:
   pull_request:
     types: [opened, synchronize, labeled]
   workflow_dispatch:
+    inputs:
+      model:
+        description: "Claude model for this run (overrides the CLAUDE_MODEL repo variable)"
+        type: choice
+        required: false
+        default: claude-opus-4-6
+        options:
+          - claude-opus-4-6
+          - claude-sonnet-4-6
+          - claude-haiku-4-5-20251001
 
 jobs:
   claude-review:
@@ -14,10 +24,21 @@ jobs:
     #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
 
     runs-on: ubuntu-latest
-    if: |
-      (github.event.action == 'opened') ||
-      (github.event.action == 'labeled' && github.event.label.name == 'claude-review') ||
-      (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'claude-review'))
+    # Run only when ALL of the following hold:
+    #   1. Author is not a bot (renovate, dependabot, etc. surface as 'name[bot]').
+    #   2. PR head is not from a fork. Fork PRs run without repository secrets, so
+    #      CLAUDE_CODE_OAUTH_TOKEN is empty and the action would fail.
+    #   3. The event is a freshly opened PR, a 'claude-review' label add, or a push
+    #      to a PR that already carries the 'claude-review' label.
+    if: ${{
+      !endsWith(github.actor, '[bot]') &&
+      !github.event.pull_request.head.repo.fork &&
+      (
+        (github.event.action == 'opened') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'claude-review') ||
+        (github.event.action == 'synchronize' && contains(github.event.pull_request.labels.*.name, 'claude-review'))
+      )
+      }}
 
     permissions:
       contents: read
@@ -27,7 +48,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
         with:
           fetch-depth: 1
 
@@ -37,10 +58,12 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
-          # Fall back to Sonnet when the primary model is unavailable/overloaded.
-          # Without this, an unavailable primary surfaces as "Claude encountered
-          # an error" and fails the claude-review check.
-          fallback_model: "claude-sonnet-4-6"
+          # Primary model precedence: the workflow_dispatch "model" input (manual
+          # runs) -> the CLAUDE_MODEL repo variable -> this built-in default.
+          # Pinning a current id avoids the action's frozen default, which 404s
+          # ("model: claude-sonnet-4-20250514"). Fall back to Sonnet on overload.
+          model: "${{ inputs.model || vars.CLAUDE_MODEL || 'claude-opus-4-6' }}"
+          fallback_model: "${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}"
 
           # Direct prompt for automated review (no @claude mention needed)
           direct_prompt: |

data/.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
         with:
           fetch-depth: 1
 
@@ -36,10 +36,12 @@ jobs:
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
 
-          # Fall back to Sonnet when the primary model is unavailable/overloaded.
-          # Without this, an unavailable primary surfaces as "Claude encountered
-          # an error" and fails the claude-review check.
-          fallback_model: "claude-sonnet-4-6"
+          # Primary model: set the CLAUDE_MODEL repo variable to override without
+          # editing this file. Pinning a current id avoids the action's frozen
+          # default, which 404s ("model: claude-sonnet-4-20250514"). Fall back to
+          # Sonnet if the primary is unavailable or overloaded.
+          model: "${{ vars.CLAUDE_MODEL || 'claude-opus-4-6' }}"
+          fallback_model: "${{ vars.CLAUDE_FALLBACK_MODEL || 'claude-sonnet-4-6' }}"
 
           # This is an optional setting that allows Claude to read CI results on PRs
           additional_permissions: |

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

@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -88,7 +88,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6.0.3
+        uses: actions/checkout@v7.0.0
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

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

@@ -114,6 +114,16 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
 
+    # `rake` lives in the optional :development group (see Gemfile), so a plain
+    # `bundle install` skips it and rubygems/release-gem's `bundle exec rake
+    # release` dies with "rake is not currently included in the bundle". Opt the
+    # group in for the whole job: setup-ruby's cached `bundle install` reads
+    # BUNDLE_WITH so rake is installed, and the release step's `bundle exec`
+    # reads it too so rake stays in the resolved bundle. This mirrors the
+    # `bundle config set --local with` that ci.yml uses for the same groups.
+    env:
+      BUNDLE_WITH: development
+
     environment:
       name: rubygems.org
       url: https://rubygems.org/gems/otto
@@ -124,7 +134,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
@@ -159,4 +169,4 @@ jobs:
           echo "Releasing otto ${gem_version} from tag ${RELEASE_TAG}"
 
       - name: Build and push gem to RubyGems
-        uses: rubygems/release-gem@6317d8d1f7e28c24d28f6eff169ea854948bd9f7 # v1.2.0
+        uses: rubygems/release-gem@052cc82692552de3ef2b81fd670e41d13cba8092 # v1.4.0

data/.github/workflows/ruby-lint.yml

@@ -0,0 +1,66 @@
+# .github/workflows/ruby-lint.yml
+
+name: Ruby Lint
+
+# Runs RuboCop across the supported Ruby versions. Linting is informational:
+# every dependency/lint step is continue-on-error, so style findings surface as
+# annotations without blocking merges.
+
+on:
+  push:
+    branches:
+      - fix/*
+      - rel/*
+  pull_request:
+    branches:
+      - main
+      - develop
+      - feature/*
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    timeout-minutes: 10 # prevent hung jobs
+
+    runs-on: ubuntu-24.04
+
+    strategy:
+      fail-fast: true
+      matrix:
+        ruby: ['3.2', '3.3', '3.4', '3.5', '4.0']
+        continue-on-error: [true]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6.0.3
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+        with:
+          detached: true
+
+      - name: Install dependencies
+        continue-on-error: ${{ matrix.continue-on-error }}
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+
+      - name: Run Rubocop
+        continue-on-error: ${{ matrix.continue-on-error }}
+        run: |
+          bundle exec rubocop --config .rubocop.yml --format json --fail-level warning

data/.github/workflows/yardoc.yml

@@ -0,0 +1,117 @@
+name: Generate and Deploy YARD Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'lib/**/*'
+      - 'docs/**/*'
+      - 'README.md'
+      - 'CHANGELOG.md'
+      - 'CHANGELOG.rst'
+      - 'LICENSE.txt'
+      - '.yardopts'
+      - '.github/workflows/yardoc.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. Do NOT cancel in-progress runs so production
+# deployments can complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    name: Generate YARD Documentation
+    env:
+      # otto declares yard/kramdown in a `group :development` whose name also
+      # appears in an `optional: true` block, so Bundler treats `development`
+      # as optional and the default `bundle install` skips it (yard never
+      # installs -> `bundle exec yard` is "command not found"). Mirror otto's
+      # ci.yml convention so setup-ruby installs the dev/test gems.
+      BUNDLE_WITH: "development:test"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6.0.3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Ruby environment
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Generate documentation
+        # Uses the repository's committed .yardopts as the single source of
+        # truth for the output dir, includes/excludes, markup, and tags.
+        run: |
+          echo "::group::YARD Documentation Generation"
+          bundle exec yard stats --list-undoc || true
+          bundle exec yard doc
+          echo "::endgroup::"
+
+      - name: Disable Jekyll processing
+        # YARD emits files and directories that begin with underscores; the
+        # .nojekyll marker stops GitHub Pages from stripping them.
+        run: touch doc/.nojekyll
+
+      - name: Validate documentation output
+        run: |
+          echo "::group::Documentation Validation"
+          if [ ! -d "doc" ]; then
+            echo "Error: documentation directory 'doc' was not generated." >&2
+            echo "Ensure .yardopts sets '--output-dir doc'." >&2
+            exit 1
+          fi
+          if [ ! -f "doc/index.html" ]; then
+            echo "Warning: doc/index.html not found"
+          fi
+          echo "Generated HTML files: $(find doc -name '*.html' | wc -l)"
+          echo "Total documentation size: $(du -sh doc/ | cut -f1)"
+          echo "::endgroup::"
+
+      - name: Setup GitHub Pages configuration
+        uses: actions/configure-pages@v6
+
+      - name: Upload documentation artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: './doc'
+
+  deploy-pages:
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-docs
+    outputs:
+      page_url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  notify-completion:
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    needs: [build-docs, deploy-pages]
+    if: success()
+
+    steps:
+      - name: Documentation deployment summary
+        run: |
+          echo "::notice title=Documentation Deployed::YARD documentation successfully deployed to GitHub Pages"
+          echo "::notice title=Access URL::Documentation available at: ${{ needs.deploy-pages.outputs.page_url }}"

data/.yardopts

@@ -0,0 +1,15 @@
+--readme README.md
+--title "Otto Ruby Library Documentation"
+--protected
+--no-private
+--markup markdown
+--markup-provider kramdown
+--output-dir doc
+--exclude lib/otto/version.rb
+lib/**/*.rb
+-
+README.md
+CHANGELOG.rst
+LICENSE.txt
+docs/**/*.md
+examples/*.rb

data/CHANGELOG.rst

@@ -7,6 +7,65 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.4.0:
+
+2.4.0 — 2026-07-01
+==================
+
+Added
+-----
+
+- ``Otto#enable_csp_reporting!(report_uri, endpoint_url: nil, &block)`` —
+  turnkey CSP violation reporting. Emits a ``report-uri`` directive and, with
+  ``endpoint_url:``, a ``report-to`` directive plus ``Reporting-Endpoints``
+  header. Parses legacy ``application/csp-report`` and Reporting API
+  ``application/reports+json`` payloads into ``Otto::Security::CSP::Report``
+  and invokes the callback per violation. Opt-in. (delano/otto#174)
+
+- ``MiddlewareStack`` ``:outermost`` position, for middleware that must run
+  ahead of all others regardless of registration order.
+
+- ``Otto::CaddyTLS``: an opt-in Caddy on-demand TLS permission endpoint,
+  enabled with ``otto.enable_caddy_tls! { |domain| ... }``. (delano/otto#175)
+
+Fixed
+-----
+
+- ``IPPrivacyMiddleware`` no longer writes ``nil`` into CGI-style Rack env
+  keys (e.g. ``HTTP_REFERER``, ``HTTP_USER_AGENT``, ``REMOTE_ADDR``) when
+  redacting request data, which violated the Rack SPEC and tripped
+  ``Rack::Lint``. Empty anonymized values now delete the key instead of
+  setting it to ``nil``, and a request with no resolvable client IP no
+  longer gets a ``nil`` ``REMOTE_ADDR``. (delano/otto#167)
+
+- ``Otto::Security::CSP::ReportMiddleware`` no longer turns a downstream
+  error on a non-report request into an empty ``204``.
+
+Security
+--------
+
+- The ``Otto::CaddyTLS`` permission endpoint is loopback-only by default and
+  fails closed. (delano/otto#175)
+
+- Security middleware registered through the ``otto.security.*``
+  Configurator after ``Otto.new`` now actually runs on the request chain —
+  previously CSRF, request validation, rate limiting, and CSP reporting
+  silently went unenforced.
+
+AI Assistance
+-------------
+
+- CSP violation reporting (``report-uri`` / ``report-to``), the
+  ``:outermost`` middleware position, and the Configurator
+  middleware-registration fix were designed and implemented with AI
+  assistance.
+
+- ``Otto::CaddyTLS`` designed, implemented, and reviewed with AI assistance.
+
+- The Rack SPEC ``nil``-into-CGI-key fix — including the sibling
+  ``REMOTE_ADDR`` masking bug and ``Rack::Lint`` test coverage — diagnosed
+  and fixed with AI assistance.
+
 .. _changelog-2.3.1:
 
 2.3.1 — 2026-06-22

data/Gemfile

@@ -27,8 +27,8 @@ group :development do
   gem 'benchmark'
   gem 'debug'
   gem 'rackup' # Used to boot examples/ apps; not needed by specs
-  gem 'rake', '~> 13.0', require: false # Provides `rake release` for release-gem.yml
-  gem 'rubocop', '~> 1.86.2', require: false
+  gem 'rake', '~> 13.4', require: false # Provides `rake release` for release-gem.yml
+  gem 'rubocop', '~> 1.88.0', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-rspec', require: false
   gem 'rubocop-thread_safety', require: false
@@ -36,4 +36,6 @@ group :development do
   gem 'stackprof', require: false
   gem 'syntax_tree', require: false
   gem 'tryouts', '~> 3.7.1', require: false
+  gem 'yard', '~> 0.9', require: false # API docs for yardoc.yml
+  gem 'kramdown', require: false # Markdown provider for YARD
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.3.1)
+    otto (2.4.0)
       concurrent-ruby (~> 1.3, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
@@ -15,7 +15,7 @@ GEM
     ast (2.4.3)
     benchmark (0.5.0)
     bigdecimal (4.1.1)
-    concurrent-ruby (1.3.6)
+    concurrent-ruby (1.3.7)
     crass (1.0.6)
     date (3.5.1)
     debug (1.11.1)
@@ -59,12 +59,14 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.5)
+    json (2.19.9)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       simpleidn (~> 0.2)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -72,21 +74,21 @@ GEM
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
     minitest (5.26.0)
-    nokogiri (1.19.2-aarch64-linux-gnu)
+    nokogiri (1.19.4-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-aarch64-linux-musl)
+    nokogiri (1.19.4-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-gnu)
+    nokogiri (1.19.4-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm-linux-musl)
+    nokogiri (1.19.4-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.2-arm64-darwin)
+    nokogiri (1.19.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-darwin)
+    nokogiri (1.19.4-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-gnu)
+    nokogiri (1.19.4-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.2-x86_64-linux-musl)
+    nokogiri (1.19.4-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.28.0)
     parser (3.3.11.1)
@@ -113,7 +115,7 @@ GEM
     rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
-    rake (13.1.0)
+    rake (13.4.2)
     rbs (4.0.2)
       logger
       prism (>= 1.6.0)
@@ -145,7 +147,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.86.2)
+    rubocop (1.88.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -163,9 +165,10 @@ GEM
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.47.1, < 2.0)
-    rubocop-rspec (3.9.0)
+    rubocop-rspec (3.10.2)
       lint_roller (~> 1.1)
-      rubocop (~> 1.81)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
     rubocop-thread_safety (0.7.3)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
@@ -197,6 +200,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     user_agent_parser (2.21.0)
+    yard (0.9.44)
     zeitwerk (2.7.3)
 
 PLATFORMS
@@ -213,14 +217,15 @@ DEPENDENCIES
   benchmark
   debug
   json_schemer
+  kramdown
   otto!
   rack-attack
   rack-test
   rackup
-  rake (~> 13.0)
+  rake (~> 13.4)
   reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.86.2)
+  rubocop (~> 1.88.0)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety
@@ -229,6 +234,7 @@ DEPENDENCIES
   syntax_tree
   tryouts (~> 3.7.1)
   user_agent_parser (~> 2.18)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.7.1