otto 2.0.0.pre8 → 2.0.0.pre10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b094c2fc179b84631bf53b1e4b7f3cbcd661f83e1f8a88ab6c1f22d3e8b11cbd
-  data.tar.gz: 70a7588c86b8b3f31968b577a298f05c09cad5ef5d9fcf028f0feece2963e8fb
+  metadata.gz: d5e7fb7a7177b6488a5a3cdacc8e3a929d58f92d44fb03bb506effca3f6c3550
+  data.tar.gz: 351a23a9c8e12aff50296cde108e73478dac7cf052d687deb5855f3ccb35cd79
 SHA512:
-  metadata.gz: c9e8f2f46cf51bc0799dd6030e52a48c1665b9978efb8bc686977be722e61b3c553f17db91d9fd795447b5b4882ac95af404a71e14f9b65d3935a992ecb768f1
-  data.tar.gz: d0c6f98edf2f468297dcb19bb9743b1a2858f2497cf40d2fc4332550a883542f2b7e1a1de8ac4b9f9d352b40c53e974d6c99aecee2679abc6b38868c02ae5bd6
+  metadata.gz: 651edcf79562877a2046132ccc876f747545d1bed8f4821352af4c16f8e795bec5d02e82afcf27320b368af9e25853df3c71d26c4fa6b6f81878704322d0f29d
+  data.tar.gz: e763f2d28e2ff4dd0d16a98ff8ab9eda6d495d32e7be10b31a1c21516a075fb1f49a44464eeaf66d92f701821ab3fce91ab72c25d18430efa70e65b2a435cb94

data/.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
             experimental: true
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         continue-on-error: ${{ matrix.experimental }}

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

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

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@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

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

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

data/CHANGELOG.rst

@@ -7,71 +7,109 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
-.. _changelog-2.0.0.pre8:
+.. _changelog-2.0.0.pre10:
 
-2.0.0.pre8 — 2025-11-27
-=======================
+2.0.0.pre10 — 2025-12-09
+========================
 
-Fixed
+Added
 -----
 
-- Routes declaring ``response=json`` now return 401 JSON errors instead of 302 redirects when authentication fails, regardless of Accept header. The route's explicit configuration takes precedence over content negotiation.
+- ``Otto::Request`` and ``Otto::Response`` classes extending Rack equivalents
+- ``register_request_helpers`` and ``register_response_helpers`` for application-specific helpers
+- Helper modules included at class level (not per-request extension)
 
-.. _changelog-2.0.0.pre7:
+Changed
+-------
 
-2.0.0.pre7 — 2025-11-24
+- Moved ``lib/otto/helpers/request.rb`` → ``lib/otto/request.rb``
+- Moved ``lib/otto/helpers/response.rb`` → ``lib/otto/response.rb``
+- All internal code now uses ``Otto::Request``/``Otto::Response`` instead of ``Rack::Request``/``Rack::Response``
+
+.. _changelog-2.0.0.pre9:
+
+2.0.0.pre9 — 2025-12-06
 =======================
 
 Added
 -----
 
-- Error handler registration system for expected business logic errors. Register handlers with ``otto.register_error_handler(ErrorClass, status: 404, log_level: :info)`` to return proper HTTP status codes and avoid logging expected errors as 500s with backtraces. Supports custom response handlers via blocks for complete control over error responses.
+- Base HTTP error classes (``Otto::NotFoundError``, ``Otto::BadRequestError``, ``Otto::ForbiddenError``, ``Otto::UnauthorizedError``, ``Otto::PayloadTooLargeError``) that implementing projects can subclass for consistent error handling
+- Auto-registration of all framework error classes during ``Otto#initialize`` - framework errors now automatically return correct HTTP status codes without manual registration
 
 Changed
 -------
 
-- Backtrace logging now always logs at ERROR level (was DEBUG) with sanitized file paths for security. Backtraces for unhandled 500 errors are always logged regardless of ``OTTO_DEBUG`` setting, with paths sanitized to prevent exposing system information (project files show relative paths, gems show ``[GEM] name-version/path``, Ruby stdlib shows ``[RUBY] filename``).
-- Increased backtrace limit from 10 to 20 lines for critical errors to provide better debugging context.
+- Framework error classes now inherit from new base classes: ``Otto::Security::AuthorizationError`` < ``Otto::ForbiddenError``, ``Otto::Security::CSRFError`` < ``Otto::ForbiddenError``, ``Otto::Security::RequestTooLargeError`` < ``Otto::PayloadTooLargeError``, ``Otto::Security::ValidationError`` < ``Otto::BadRequestError``, ``Otto::MCP::ValidationError`` < ``Otto::BadRequestError``
+- ``Otto::Security::RequestTooLargeError`` now returns HTTP 413 (Payload Too Large) instead of 500, semantically correct per RFC 7231
+
+- Consolidated route handler implementation using Template Method pattern, reducing duplication by ~120 lines while improving maintainability
+
+Fixed
+-----
+
+- Error handlers now respect route's ``response=json`` parameter for content
+  negotiation, ensuring API routes always return JSON error responses regardless
+  of the Accept header.
+
+- Rate limiters now respect route ``response=json`` declarations when returning
+  throttled responses, matching the error handler fix for consistent content
+  negotiation across all error paths.
+
+- ClassMethodHandler direct testing context now respects route ``response_type``
+  when generating error responses.
+
+- Unified error handling across ClassMethodHandler and InstanceMethodHandler to consistently support JSON content negotiation
 
 AI Assistance
 -------------
 
-- Implemented error handler registration architecture with comprehensive test coverage (17 test cases) using sequential thinking to work through security implications and design decisions. AI assisted with path sanitization strategy, error classification patterns, and ensuring backward compatibility with existing error handling.
+- Implementation design and architecture developed with AI pair programming
+- Comprehensive test coverage (31 new base class tests, 12 auto-registration tests) developed with AI assistance
+- Error class hierarchy and inheritance patterns refined through AI-guided architectural discussion
 
-Improved backtrace sanitization security and readability
---------------------------------------------------------
+.. _changelog-2.0.0.pre8:
 
-**Security Enhancements:**
+2.0.0.pre8 — 2025-11-27
+=======================
 
-- Fixed bundler gem path detection to correctly sanitize git-based gems
-- Now properly handles nested gem paths like ``/gems/3.4.0/bundler/gems/otto-abc123/``
-- Strips git hash suffixes from bundler gems (``otto-abc123def456`` → ``otto``)
-- Removes version numbers from regular gems (``rack-3.2.4`` → ``rack``)
-- Prevents exposure of absolute paths, usernames, and project names in logs
+Fixed
+-----
+
+- Routes declaring ``response=json`` now return 401 JSON errors instead of 302 redirects when authentication fails, regardless of Accept header. The route's explicit configuration takes precedence over content negotiation.
+
+.. _changelog-2.0.0.pre7:
+
+2.0.0.pre7 — 2025-11-24
+=======================
+
+Added
+-----
+
+- Error handler registration system for expected business logic errors via ``otto.register_error_handler(ErrorClass, status:, log_level:)``. Supports custom response handlers via blocks.
 
-**Improvements:**
+Changed
+-------
+
+- Backtrace logging now always logs at ERROR level with sanitized file paths (was DEBUG level with full paths)
+- Increased backtrace limit from 10 to 20 lines for better debugging context
+- Improved gem path formatting in backtraces (e.g., ``[GEM] rack/lib/rack.rb:20``)
+
+Fixed
+-----
 
-- Bundler gems now show as ``[GEM] otto/lib/otto/route.rb:142`` instead of ``[GEM] 3.4.0/bundler/gems/...``
-- Regular gems show cleaner output: ``[GEM] rack/lib/rack.rb:20`` instead of ``[GEM] rack-3.2.4/lib/rack.rb:20``
-- Multi-hyphenated gem names handled correctly (``active-record-import-1.5.0`` → ``active-record-import``)
-- Better handling of version-only directory names in gem paths
+- Fixed path sanitization for bundler git-based gems and multi-hyphenated gem names
 
-**Documentation:**
+Documentation
+-------------
 
-- Added comprehensive backtrace sanitization section to CLAUDE.md
 - Documented security guarantees and sanitization rules
 - Added examples showing before/after path transformations
-- Created comprehensive test suite for backtrace sanitization
-
-**Rationale:**
 
-Raw backtraces expose sensitive information:
-- Usernames (``/Users/alice/``, ``/home/admin/``)
-- Project structure and internal organization
-- Gem installation paths and Ruby versions
-- System architecture details
+AI Assistance
+-------------
 
-This improvement ensures all backtraces are sanitized automatically, preventing accidental leakage of sensitive system information while maintaining readability for debugging.
+- Implemented error handler registration architecture with comprehensive test coverage (17 test cases) using sequential thinking to work through security implications and design decisions. AI assisted with path sanitization strategy, error classification patterns, and ensuring backward compatibility with existing error handling.
 
 .. _changelog-2.0.0.pre6:
 

data/CLAUDE.md

@@ -14,6 +14,40 @@ otto.register_error_handler(YourApp::RateLimited, status: 429, log_level: :warn)
 
 Must be registered before first request (before configuration freezing).
 
+## Request/Response Helper Registration
+
+Register application helpers that integrate with Otto features (authentication, privacy, locale):
+
+```ruby
+module YourApp::RequestHelpers
+  def current_customer
+    user = strategy_result&.user
+    user.is_a?(YourApp::Customer) ? user : YourApp::Customer.anonymous
+  end
+end
+
+otto = Otto.new('routes.txt')
+otto.register_request_helpers(YourApp::RequestHelpers)
+otto.register_response_helpers(YourApp::ResponseHelpers)
+```
+
+Must be registered before first request.
+
+> [!NOTE]
+> **Helper availability by context:** The base `Otto::Request` and `Otto::Response` classes (with Otto's built-in helpers like `masked_ip`, `geo_country`) are available everywhere, including Rack middleware. However, custom helpers registered via `register_request_helpers` and `register_response_helpers` are only available in route handlers, error handlers, and components that have access to the Otto instance's dynamic request/response classes.
+
+### Reserved Method Names
+
+Helper modules should avoid overriding these methods inherited from Rack::Request/Rack::Response:
+
+**Request reserved methods**: `env`, `params`, `cookies`, `session`, `path`, `path_info`, `query_string`, `request_method`, `content_type`, `content_length`, `media_type`, `get?`, `post?`, `put?`, `delete?`, `head?`, `options?`, `patch?`, `xhr?`, `referer`, `user_agent`, `base_url`, `url`, `fullpath`, `ip`, `host`, `port`, `ssl?`, `scheme`
+
+**Response reserved methods**: `status`, `headers`, `body`, `finish`, `write`, `close`, `set_cookie`, `delete_cookie`, `redirect`, `content_type`, `content_length`, `location`
+
+**Otto-specific methods**: `request` (on Response), `app_path`, `masked_ip`, `hashed_ip`, `client_ipaddress`, `secure?`, `local?`, `ajax?`
+
+No runtime validation is performed for performance reasons. Overriding these methods will cause undefined behavior.
+
 ## Authentication Architecture
 
 Authentication is handled by `RouteAuthWrapper` at the handler level, NOT by middleware.
@@ -115,6 +149,16 @@ bundle exec rubocop
 bundle exec rspec
 ```
 
+## Git Commands
+
+Always use `--no-pager` with git commands to avoid interactive pager issues:
+
+```bash
+git --no-pager diff
+git --no-pager log
+git --no-pager show
+```
+
 ## Key Architecture Principles
 
 - **Security by Default**: IP privacy, configuration freezing, backtrace sanitization

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre8)
+    otto (2.0.0.pre10)
       concurrent-ruby (~> 1.3, < 2.0)
       facets (~> 3.1)
       ipaddr (~> 1, < 2.0)
@@ -62,7 +62,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.2)
+    json (2.16.0)
     json_schemer (2.4.0)
       bigdecimal
       hana (~> 1.3)
@@ -113,7 +113,7 @@ GEM
       rack
     rack-test (2.2.0)
       rack (>= 1.3)
-    rackup (2.2.1)
+    rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
     rbs (3.9.5)
@@ -156,21 +156,21 @@ GEM
       rubocop-ast (>= 1.47.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.48.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.47.1, < 2.0)
-    rubocop-rspec (3.7.0)
+    rubocop-rspec (3.8.0)
       lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
+      rubocop (~> 1.81)
     rubocop-thread_safety (0.7.3)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.2)
+    ruby-lsp (0.26.4)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)

data/README.md

@@ -84,6 +84,26 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+## Error Handling
+
+Otto provides base error classes that automatically return correct HTTP status codes:
+
+```ruby
+# Use built-in error classes directly
+raise Otto::NotFoundError, "Product not found"           # Returns 404
+raise Otto::BadRequestError, "Invalid parameter"         # Returns 400
+raise Otto::UnauthorizedError, "Login required"          # Returns 401
+raise Otto::ForbiddenError, "Access denied"              # Returns 403
+
+# Or subclass them for your application
+class MyApp::ResourceNotFound < Otto::NotFoundError; end
+
+# Optionally customize status or logging (overrides auto-registration)
+app.register_error_handler(MyApp::ResourceNotFound, status: 410, log_level: :warn)
+```
+
+All framework errors are auto-registered during initialization. No manual registration required unless you want custom behavior.
+
 ## Privacy by Default
 
 Otto automatically masks public IP addresses and anonymizes user agents to comply with GDPR, CCPA, and other privacy regulations:

data/docs/.gitignore

@@ -3,3 +3,5 @@
 !migrating/
 !migrating/*.md
 !ipaddr-encoding-quirk.md
+!modern-authentication-authorization-landscape.md
+!multi-strategy-authentication-design.md