otto 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7974135aa7b516b1d0424fd1fb7f686524f0d091168a19df5527ec1e69d7314f
-  data.tar.gz: a20a52ce1479f00f880afa3ad43ed43bb85f34e519c9e024cd717a7d873dad5c
+  metadata.gz: 746b45b9ceea5aed255a2d39e578f65bbf4438791bf61aad37641cbd4313c365
+  data.tar.gz: 8e61944be4c19656684c5630bf74024c3738d4ed6b8891686be4beb735aaaddd
 SHA512:
-  metadata.gz: 6a69222b7e5234e487d0098a25bbd36b2e9fc7637f563cf9f6b8562e5b03a314f06b97de755a1ec061310222c8c8ac35f215a8f6ad2b0d3e541ba1eec658f73d
-  data.tar.gz: 503f510059cc42f553981cd5ec27a19c5655d2047e11263eb81c63d7b2a49a09ebcd7f5df83da6f68e295b9927f8859812a2240ad4b1e05e8365702cfb89f91b
+  metadata.gz: 0bd4f87e1d824c2dc6683f6909db32e0e0a460b65a8d1646a35f2ac464a450d8804f72cacad60eae066601867f84b1d97c8bbccb02211ed43e5e408d8b269894
+  data.tar.gz: 999b4b96f74cace0b236dea4ef8f16607713a66960be3301b30b3f3e9e9e7f047b6381820cf701d5385afb10641537c2e1726993ff5c84ae75f6325eefe53cc8

data/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    timeout-minutes: 10
+    runs-on: ubuntu-24.04
+    name: "RSpec Tests (Ruby ${{ matrix.ruby }})"
+    strategy:
+      fail-fast: true
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "3.5"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run RSpec tests
+        run: bundle exec rspec

data/.pre-commit-config.yaml

@@ -0,0 +1,107 @@
+##
+# Pre-Commit Hooks Configuration
+#
+# Fast, lightweight code quality checks that run before each commit
+#
+# Setup:
+#   1. Install pre-commit:
+#       $ pip install pre-commit
+#
+#   2. Install git hooks:
+#       $ pre-commit install
+#
+# Usage:
+#   Hooks run automatically on 'git commit'
+#
+#   Manual commands:
+#   - Check all files:
+#     $ pre-commit run --all-files
+#
+#   - Update hooks:
+#     $ pre-commit autoupdate
+#
+#   - Reinstall after config changes:
+#     $ pre-commit install
+#
+# Best Practices:
+#   - Reinstall hooks after modifying this config
+#   - Commit config changes in isolation
+#   - Keep checks fast to maintain workflow
+#
+# Resources:
+#   - Docs: https://pre-commit.com
+#   - Available hooks: https://pre-commit.com/hooks.html
+#
+# Note: These lightweight checks maintain code quality without
+# slowing down the local development process.
+
+# Hook installation configuration
+default_install_hook_types:
+  - pre-commit # Primary code quality checks
+  - prepare-commit-msg # Commit message preprocessing
+  - post-commit # Actions after successful commit
+  - post-checkout # Triggered after git checkout
+  - post-merge # Triggered after git merge
+
+# Default execution stage
+default_stages: [pre-commit]
+
+# Avoid multiple sequential commit failures
+fail_fast: false
+
+# Ignore generated and dependency directories
+exclude: "^$"
+
+repos:
+  # Meta hooks: basic checks for pre-commit config itself
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
+  # Standard pre-commit hooks: lightweight, universal checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Formatting and basic sanitization
+      - id: trailing-whitespace # Remove trailing whitespaces
+      - id: end-of-file-fixer # Ensure files end with newline
+      - id: check-merge-conflict # Detect unresolved merge conflicts
+      - id: detect-private-key # Warn about committing private keys
+      - id: check-added-large-files # Prevent committing oversized files
+        args: ["--maxkb=2500"] # 2.5MB file size threshold
+      - id: no-commit-to-branch # Prevent direct commits to critical branches
+        args: ["--branch", "main", "--branch", "rel/.*"]
+
+  # # Ruby code quality and style checks (using local bundler environment)
+  # - repo: local
+  # hooks:
+  #   - id: rubocop
+  #     name: RuboCop
+  #     description: Ruby static code analyzer and formatter
+  #     entry: eval "$(rbenv init -)" && bundle exec rubocop
+  #     language: system
+  #     files: \.rb$
+  #     pass_filenames: false
+  # - repo: https://github.com/rubocop-hq/rubocop
+  #   rev: v1.79.1 # Or your desired version
+  #   hooks:
+  #     - id: rubocop
+  #       files: \.rb$
+  #       pass_filenames: false
+  #       additional_dependencies:
+  #         - rubocop-rails # Example of an additional gem
+  #         - rubocop-performance
+  #         - rubocop-rspec
+
+  # Commit message issue tracking integration
+  - repo: https://github.com/avilaton/add-msg-issue-prefix-hook
+    rev: v0.0.12
+    hooks:
+      - id: add-msg-issue-prefix
+        stages: [prepare-commit-msg]
+        description: Automatically prefix commits with issue numbers
+        args:
+          - "--default="
+          - '--pattern=(?:i18n(?=\/)|[a-zA-Z0-9]{0,10}-?[0-9]{1,5})'
+          - "--template=[#{}]"

data/.pre-push-config.yaml

@@ -0,0 +1,88 @@
+##
+# Pre-Push Hooks Configuration
+#
+# Quality control checks that run before code is pushed to remote repositories
+#
+# Setup:
+#   1. Install the pre-push hook:
+#       $ pre-commit install --hook-type pre-push
+#
+#   2. Install required dependencies:
+#       - Ruby + Rubocop
+#       - Node.js + ESLint
+#       - TypeScript compiler
+#
+# Usage:
+#   Hooks run automatically on 'git push'
+#
+#   Manual execution:
+#   - Run all checks:
+#     $ pre-commit run --config .pre-push-config.yaml --all-files
+#
+#   - Run single check:
+#     $ pre-commit run <hook-id> --config .pre-push-config.yaml
+#     Example: pre-commit run rubocop --config .pre-push-config.yaml
+#
+# Included Checks:
+#   - Full codebase linting (Rubocop, ESLint)
+#   - YAML/JSON validation
+#   - TypeScript type checking
+#   - Code style enforcement
+#   - Security vulnerability scanning
+#
+# Related Files:
+#   - .pre-commit-config.yaml: Lightweight pre-commit checks
+#   - Documentation: https://pre-commit.com
+#
+# Note: These intensive checks run before pushing to catch issues early
+# but allow faster local development with lighter pre-commit hooks.
+
+# Allow all failures to happen so they can be corrected in one go
+fail_fast: false
+
+# Skip generated/dependency directories
+exclude: "^(vendor|node_modules|dist|build)/"
+
+default_install_hook_types:
+  - pre-push
+  - push
+
+default_stages: [push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+        name: Validate YAML files
+        args: ["--allow-multiple-documents"]
+        files: \.(yaml|yml)$
+
+      - id: check-toml
+        name: Validate TOML files
+        files: \.toml$
+
+      - id: check-json
+        name: Validate JSON files
+        files: \.json$
+
+      - id: pretty-format-json
+        name: Format JSON files
+        args: ["--autofix", "--no-sort-keys"]
+        files: \.json$
+
+      - id: mixed-line-ending
+        name: Check line endings
+        args: [--fix=lf]
+
+      - id: check-case-conflict
+        name: Check for case conflicts
+
+      - id: check-executables-have-shebangs
+        name: Check executable shebangs
+
+      - id: check-shebang-scripts-are-executable
+        name: Check shebang scripts are executable
+
+      - id: forbid-submodules
+        name: Check for submodules

data/.rubocop.yml

@@ -19,7 +19,7 @@ AllCops:
   DisabledByDefault: false # flip to true for a good autocorrect time
   UseCache: true
   MaxFilesInCache: 100
-  TargetRubyVersion: 3.4
+  TargetRubyVersion: 3.2
   Exclude:
     - "spec/**/*.rb"
     - "vendor/**/*"

data/Gemfile

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 source 'https://rubygems.org'
 
 gemspec

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    otto (1.3.0)
+    otto (1.4.0)
+      ostruct
       rack (~> 3.1, < 4.0)
       rack-parser (~> 0.7)
       rexml (>= 3.3.6)
@@ -26,6 +27,7 @@ GEM
     logger (1.7.0)
     method_source (1.1.0)
     minitest (5.25.5)
+    ostruct (0.6.3)
     parallel (1.27.0)
     parser (3.3.9.0)
       ast (~> 2.4.1)

data/README.md

@@ -1,4 +1,4 @@
-# Otto - 1.2 (2025-08-18)
+# Otto - A Ruby Gem
 
 **Define your rack-apps in plain-text with built-in security.**
 
@@ -74,9 +74,65 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+## Internationalization Support
+
+Otto provides built-in locale detection and management:
+
+```ruby
+# Global configuration (affects all Otto instances)
+Otto.configure do |opts|
+  opts.available_locales = { 'en' => 'English', 'es' => 'Spanish', 'fr' => 'French' }
+  opts.default_locale = 'en'
+end
+
+# Or configure during initialization
+app = Otto.new("./routes", {
+  available_locales: { 'en' => 'English', 'es' => 'Spanish', 'fr' => 'French' },
+  default_locale: 'en'
+})
+
+# Or configure at runtime
+app.configure(
+  available_locales: { 'en' => 'English', 'es' => 'Spanish' },
+  default_locale: 'en'
+)
+
+# Legacy support (still works)
+app = Otto.new("./routes", {
+  locale_config: {
+    available_locales: { 'en' => 'English', 'es' => 'Spanish', 'fr' => 'French' },
+    default_locale: 'en'
+  }
+})
+```
+
+In your application, use the locale helper:
+
+```ruby
+class App
+  def initialize(req, res)
+    @req, @res = req, res
+  end
+
+  def show_product
+    # Automatically detects locale from:
+    # 1. URL parameter: ?locale=es
+    # 2. User preference (if provided)
+    # 3. Accept-Language header
+    # 4. Default locale
+    locale = req.check_locale!
+
+    # Use locale for localized content
+    res.body = localized_content(locale)
+  end
+end
+```
+
+The locale helper checks multiple sources in order of precedence and validates against your configured locales.
+
 ## Requirements
 
-- Ruby 3.4+
+- Ruby 3.2+
 - Rack 3.1+
 
 ## Installation

data/examples/helpers_demo/app.rb

@@ -0,0 +1,244 @@
+require 'otto'
+require 'json'
+
+class HelpersDemo
+  def initialize(req, res)
+    @req, @res = req, res
+  end
+
+  attr_reader :req, :res
+
+  def index
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Otto Request & Response Helpers Demo</h1>
+      <p>This demo shows Otto's built-in request and response helpers.</p>
+
+      <h2>Available Demos:</h2>
+      <ul>
+        <li><a href="/request-info">Request Information</a> - Shows client IP, user agent, security info</li>
+        <li><a href="/locale-demo?locale=es">Locale Detection</a> - Demonstrates locale detection and configuration</li>
+        <li><a href="/secure-cookie">Secure Cookies</a> - Sets secure cookies with proper options</li>
+        <li><a href="/headers">Response Headers</a> - Shows security headers and custom headers</li>
+        <li>
+          <form method="POST" action="/csp-demo">
+            <button type="submit">CSP Headers Demo</button> - Content Security Policy with nonce
+          </form>
+        </li>
+      </ul>
+
+      <h2>Try These URLs:</h2>
+      <ul>
+        <li><a href="/locale-demo?locale=fr">French locale</a></li>
+        <li><a href="/locale-demo?locale=invalid">Invalid locale (falls back to default)</a></li>
+      </ul>
+    HTML
+  end
+
+  def request_info
+    # Demonstrate request helpers
+    info = {
+      'Client IP' => req.client_ipaddress,
+      'User Agent' => req.user_agent,
+      'HTTP Host' => req.http_host,
+      'Server Name' => req.current_server_name,
+      'Request Path' => req.request_path,
+      'Request URI' => req.request_uri,
+      'Is Local?' => req.local?,
+      'Is Secure?' => req.secure?,
+      'Is AJAX?' => req.ajax?,
+      'Current Absolute URI' => req.current_absolute_uri,
+      'Request Method' => req.request_method
+    }
+
+    # Show collected proxy headers
+    proxy_headers = req.collect_proxy_headers(
+      header_prefix: 'X_DEMO_',
+      additional_keys: ['HTTP_ACCEPT', 'HTTP_ACCEPT_LANGUAGE']
+    )
+
+    # Format request details for logging
+    request_details = req.format_request_details(header_prefix: 'X_DEMO_')
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Request Information</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Basic Request Info:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        #{info.map { |k, v| "<tr><td><strong>#{k}</strong></td><td>#{v}</td></tr>" }.join("\n        ")}
+      </table>
+
+      <h2>Proxy Headers:</h2>
+      <pre>#{proxy_headers}</pre>
+
+      <h2>Formatted Request Details (for logging):</h2>
+      <pre>#{request_details}</pre>
+
+      <h2>Application Path Helper:</h2>
+      <p>App path for ['api', 'v1', 'users']: <code>#{req.app_path('api', 'v1', 'users')}</code></p>
+    HTML
+  end
+
+  def locale_demo
+    # Demonstrate locale detection with Otto configuration
+    current_locale = req.check_locale!(req.params['locale'], {
+      preferred_locale: 'es', # Simulate user preference
+      locale_env_key: 'demo.locale',
+      debug: true
+    })
+
+    # Show what was stored in environment
+    stored_locale = req.env['demo.locale']
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Locale Detection Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Locale Detection Results:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        <tr><td><strong>Detected Locale</strong></td><td>#{current_locale}</td></tr>
+        <tr><td><strong>Stored in Environment</strong></td><td>#{stored_locale}</td></tr>
+        <tr><td><strong>Query Parameter</strong></td><td>#{req.params['locale'] || 'none'}</td></tr>
+        <tr><td><strong>Accept-Language Header</strong></td><td>#{req.env['HTTP_ACCEPT_LANGUAGE'] || 'none'}</td></tr>
+      </table>
+
+      <h2>Locale Sources (in precedence order):</h2>
+      <ol>
+        <li>URL Parameter: <code>?locale=#{req.params['locale'] || 'none'}</code></li>
+        <li>User Preference: <code>es</code> (simulated)</li>
+        <li>Rack Locale: <code>#{req.env['rack.locale']&.first || 'none'}</code></li>
+        <li>Default: <code>en</code></li>
+      </ol>
+
+      <h2>Try Different Locales:</h2>
+      <ul>
+        <li><a href="/locale-demo?locale=en">English (en)</a></li>
+        <li><a href="/locale-demo?locale=es">Spanish (es)</a></li>
+        <li><a href="/locale-demo?locale=fr">French (fr)</a></li>
+        <li><a href="/locale-demo?locale=invalid">Invalid locale</a></li>
+        <li><a href="/locale-demo">No locale parameter</a></li>
+      </ul>
+    HTML
+  end
+
+  def secure_cookie
+    # Demonstrate secure cookie helpers
+    res.send_secure_cookie('demo_secure', 'secure_value_123', 3600, {
+      path: '/helpers_demo',
+      secure: !req.local?, # Only secure in production
+      same_site: :strict
+    })
+
+    res.send_session_cookie('demo_session', 'session_value_456', {
+      path: '/helpers_demo'
+    })
+
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>Secure Cookies Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Cookies Set:</h2>
+      <ul>
+        <li><strong>demo_secure</strong> - Secure cookie with 1 hour TTL</li>
+        <li><strong>demo_session</strong> - Session cookie (no expiration)</li>
+      </ul>
+
+      <h2>Cookie Security Features:</h2>
+      <ul>
+        <li>Secure flag (HTTPS only in production)</li>
+        <li>HttpOnly flag (prevents XSS access)</li>
+        <li>SameSite=Strict (CSRF protection)</li>
+        <li>Proper expiration handling</li>
+      </ul>
+
+      <p>Check your browser's developer tools to see the cookie headers!</p>
+    HTML
+  end
+
+  def csp_demo
+    # Demonstrate CSP headers with nonce
+    nonce = SecureRandom.base64(16)
+
+    res.send_csp_headers('text/html; charset=utf-8', nonce, {
+      development_mode: req.local?,
+      debug: true
+    })
+
+    res.body = <<~HTML
+      <h1>Content Security Policy Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>CSP Header Generated</h2>
+      <p>This page includes a CSP header with a nonce. Check the response headers!</p>
+
+      <h2>Nonce Value:</h2>
+      <p><code>#{nonce}</code></p>
+
+      <h2>Inline Script with Nonce:</h2>
+      <script nonce="#{nonce}">
+        console.log('This script runs because it has the correct nonce!');
+        document.addEventListener('DOMContentLoaded', function() {
+          document.getElementById('nonce-demo').innerHTML = 'Nonce verification successful!';
+        });
+      </script>
+
+      <div id="nonce-demo" style="padding: 10px; background: #d4edda; border: 1px solid #c3e6cb; color: #155724;">
+        Loading...
+      </div>
+
+      <p><strong>Note:</strong> Without the nonce, inline scripts would be blocked by CSP.</p>
+    HTML
+  end
+
+  def show_headers
+    # Demonstrate response headers and security features
+    res.set_cookie('demo_header', {
+      value: 'header_demo_value',
+      max_age: 1800,
+      secure: !req.local?,
+      httponly: true
+    })
+
+    # Add cache control
+    res.no_cache!
+
+    # Get security headers that would be added
+    security_headers = res.cookie_security_headers
+
+    res.headers['content-type'] = 'text/html'
+    res.headers['X-Demo-Header'] = 'Custom header value'
+
+    res.body = <<~HTML
+      <h1>Response Headers Demo</h1>
+      <p><a href="/">← Back to index</a></p>
+
+      <h2>Custom Headers Set:</h2>
+      <ul>
+        <li><strong>X-Demo-Header:</strong> Custom header value</li>
+        <li><strong>Cache-Control:</strong> no-store, no-cache, must-revalidate, max-age=0</li>
+        <li><strong>Set-Cookie:</strong> demo_header (with security options)</li>
+      </ul>
+
+      <h2>Security Headers Available:</h2>
+      <table border="1" style="border-collapse: collapse;">
+        #{security_headers.map { |k, v| "<tr><td><strong>#{k}</strong></td><td>#{v}</td></tr>" }.join("\n        ")}
+      </table>
+
+      <p>Use your browser's developer tools to inspect all response headers!</p>
+    HTML
+  end
+
+  def not_found
+    res.status = 404
+    res.headers['content-type'] = 'text/html'
+    res.body = <<~HTML
+      <h1>404 - Page Not Found</h1>
+      <p><a href="/">← Back to index</a></p>
+      <p>This is a custom 404 page demonstrating error handling.</p>
+    HTML
+  end
+end

data/examples/helpers_demo/config.ru

@@ -0,0 +1,26 @@
+require_relative '../../lib/otto'
+require_relative 'app'
+
+# Global configuration for all Otto instances
+Otto.configure do |opts|
+  opts.available_locales = {
+    'en' => 'English',
+    'es' => 'Spanish',
+    'fr' => 'French'
+  }
+  opts.default_locale = 'en'
+end
+
+# Configure Otto with security features
+app = Otto.new("./routes", {
+  # Security features
+  csrf_protection: true,
+  request_validation: true,
+  trusted_proxies: ['127.0.0.1', '::1']
+})
+
+# Enable additional security headers
+app.enable_csp_with_nonce!(debug: true)
+app.enable_frame_protection!('SAMEORIGIN')
+
+run app

data/examples/helpers_demo/routes

@@ -0,0 +1,7 @@
+GET   /                         HelpersDemo#index
+GET   /request-info             HelpersDemo#request_info
+GET   /locale-demo              HelpersDemo#locale_demo
+GET   /secure-cookie            HelpersDemo#secure_cookie
+POST  /csp-demo                 HelpersDemo#csp_demo
+GET   /headers                  HelpersDemo#show_headers
+GET   /404                      HelpersDemo#not_found

data/lib/otto/helpers/base.rb

@@ -0,0 +1,27 @@
+# lib/otto/helpers/base.rb
+
+class Otto
+  module BaseHelpers
+    # Build application path by joining path segments
+    #
+    # This method safely joins multiple path segments, handling
+    # duplicate slashes and ensuring proper path formatting.
+    # Includes the script name (mount point) as the first segment.
+    #
+    # @param paths [Array<String>] Path segments to join
+    # @return [String] Properly formatted path
+    #
+    # @example
+    #   app_path('api', 'v1', 'users')
+    #   # => "/myapp/api/v1/users"
+    #
+    # @example
+    #   app_path(['admin', 'settings'])
+    #   # => "/myapp/admin/settings"
+    def app_path(*paths)
+      paths = paths.flatten.compact
+      paths.unshift(env['SCRIPT_NAME']) if env['SCRIPT_NAME']
+      paths.join('/').gsub('//', '/')
+    end
+  end
+end