otto 2.9.0 → 2.10.0

data/docs/reference/route-syntax.md

@@ -0,0 +1,181 @@
+# Route syntax
+
+This page is the compact contract for Otto's plain-text route definitions. It
+covers the syntax needed to choose a route target and attach route options. For
+application examples, start with the [routing guide](../guides/routing.md).
+
+## Route line
+
+A route line has this shape:
+
+```text
+VERB /path-pattern Target option=value option=value
+```
+
+For example:
+
+```text
+GET  /                         App#index
+GET  /products/:id             App#show_product response=view
+POST /api/products             ProductCreate response=json csrf=exempt
+GET  /admin                    Admin::Dashboard auth=session role=admin
+GET  /health                   &health_check
+```
+
+Whitespace separates the verb, path, target, and each option token. Option
+values cannot contain unquoted whitespace. Values may contain `=` characters;
+Otto splits each option at its first `=`.
+
+## HTTP verbs and paths
+
+The verb is normalized to uppercase. A path can contain named segments and a
+splat:
+
+```text
+GET /products/:id          Products#show
+GET /assets/*path          Assets#show
+```
+
+Named segments become route parameters. The splat is available under the
+`"splat"` parameter name. Route matching is anchored to the complete path, and
+Otto normalizes paths before matching, including trailing slashes and URL
+encoding according to the router's path-normalization rules.
+
+## Targets
+
+The target determines how Otto invokes application code:
+
+| Syntax | Kind | Invocation |
+| --- | --- | --- |
+| `App.index` | Class method | Calls `App.index(req, res)`. |
+| `App#index` | Instance method | Builds `App.new(req, res)`, then calls `index`. |
+| `Admin::Dashboard` | Logic class | Builds `Admin::Dashboard.new(strategy_result, params, locale)`, then runs its Logic lifecycle. |
+| `&health_check` | Registered lambda | Looks up `"health_check"` in the boot-time `lambda_handlers` registry and calls it with `(req, res, extra_params)`. |
+
+Class and instance targets must resolve to safe Ruby constants. Lambda targets
+are registry keys, not Ruby constants: Otto does not evaluate route text or
+resolve a lambda name dynamically.
+
+### Logic classes
+
+A bare class target is a Logic route. Logic classes receive a constrained
+application context rather than the Rack request and environment:
+
+```ruby
+class ProductShow
+  def initialize(strategy_result, params, locale)
+    @context = strategy_result
+    @params = params
+    @locale = locale
+  end
+
+  def raise_concerns
+    # Load resources and perform resource-level authorization here.
+  end
+
+  def process
+    { id: @params[:id], locale: @locale }
+  end
+end
+```
+
+The route handler supplies the authenticated `StrategyResult` even for a public
+route; public routes receive an anonymous result. Use a class or instance
+handler when code needs direct access to cookies, headers, or the Rack request.
+
+### Registered lambda handlers
+
+Register lambdas before the first request:
+
+```ruby
+otto = Otto.new('routes', lambda_handlers: {
+  health_check: lambda do |req, res, _extra_params|
+    res['content-type'] = 'text/plain'
+    res.body = 'ok'
+  end,
+})
+```
+
+The callable must accept three positional arguments. Registration validates the
+name and callable arity at boot; a route referring to an unregistered handler
+fails when it is invoked rather than evaluating arbitrary route text.
+
+## Route options
+
+Options are whitespace-delimited `key=value` tokens after the target.
+Unknown well-formed options are retained for handlers and middleware that use
+them. Malformed non-security options are ignored and logged.
+
+### Response type
+
+`response=` selects the response handler for non-default handler results:
+
+| Option | Behavior |
+| --- | --- |
+| `response=default` | Default response behavior. This is the default. |
+| `response=json` | JSON response handling. |
+| `response=view` | View response handling. |
+| `response=redirect` | Redirect response handling. |
+| `response=auto` | Content-negotiated response handling. |
+
+An unknown response type falls back to the default handler silently. A typo in
+`response=` therefore changes behavior with no diagnostic; check the value here
+rather than expecting a log line.
+
+### CSRF
+
+When CSRF protection is enabled, use the explicit exemption only for routes
+whose request contract does not use browser credentials and therefore has an
+independent protection model:
+
+```text
+POST /webhooks/provider  Webhooks#receive csrf=exempt
+```
+
+`csrf=exempt` is the supported exemption token. A bare `csrf` or an empty CSRF
+value is rejected as a malformed security option.
+
+### Authentication and roles
+
+Use `auth=` for one or more named authentication strategies and `role=` for
+route-level role authorization:
+
+```text
+GET /account       Account#show auth=session
+GET /admin         Admin::Dashboard auth=session role=admin
+GET /editorial     Editorial#show auth=session role=admin,editor
+GET /api/data      Api#show auth=session,api_key response=json
+```
+
+`auth=session,api_key` is OR logic: strategies run left to right, an
+authenticated success stops the chain, and a later strategy can be tried after
+a plain failure. `role=admin,editor` also uses OR logic: any listed role is
+enough. See the [authentication guide](../guides/authentication.md).
+
+Authentication and role options are security-gating options. They must use
+lowercase `auth=`, `role=`, or `csrf=` with a non-empty value. Otto raises
+`Otto::RouteDefinitionError` instead of silently treating a malformed token as
+an unprotected route:
+
+```text
+# Rejected during route definition parsing:
+GET /admin Admin#show auth
+GET /admin Admin#show role=
+POST /submit Form#save CSRF=exempt
+```
+
+## Configuration timing
+
+Routes are loaded during `Otto.new`. Configuration remains available for
+multi-step setup, but Otto freezes configuration on the first request in normal
+operation. Register authentication strategies, lambda handlers, middleware,
+helpers, and security settings before serving traffic.
+
+## Related contracts
+
+- [Routing guide](../guides/routing.md) — application-oriented examples.
+- [Authentication guide](../guides/authentication.md) — strategy and
+  authorization behavior.
+- [Configuration and lifecycle code](../../lib/otto/core/configuration.rb) and
+  [`RouteDefinition`](../../lib/otto/route_definition.rb) — implementation
+  source for the exact contract.

data/docs/reference/runtime-and-dependency-security.md

@@ -0,0 +1,86 @@
+# Runtime and dependency security policy
+
+This policy explains what Otto's Ruby and gem version declarations guarantee,
+what they do not guarantee, and what applications using Otto must do to keep a
+deployed bundle patched.
+
+## Ruby compatibility and security maintenance
+
+Otto separates **runtime compatibility** from **interpreter security
+maintenance**. A blocking compatibility target must pass Otto's test suite;
+provisional targets are exercised without blocking releases. Only the Ruby
+project can provide security maintenance for the interpreter.
+
+| Ruby version | Otto compatibility policy | CI status |
+| --- | --- | --- |
+| 3.2 | Retained as a compatibility target for now, despite upstream end of life | Blocking, with locked and freshly resolved dependencies |
+| 3.3–3.4 | Supported compatibility targets | Blocking, with locked and freshly resolved dependencies |
+| 3.5–4.0 | Accepted by the gem's Ruby version range, but compatibility remains provisional | Experimental and non-blocking, with locked and freshly resolved dependencies |
+
+Ruby 3.2 reached upstream end of life on April 1, 2026. It receives no
+interpreter security maintenance. Otto's continued compatibility testing cannot
+correct vulnerabilities in Ruby 3.2 itself. Applications with a security
+maintenance requirement should run Otto on a Ruby version that the Ruby project
+currently maintains. Check the [Ruby branch maintenance
+status](https://www.ruby-lang.org/en/downloads/branches/) when selecting a
+runtime.
+
+The `required_ruby_version` range in `otto.gemspec` controls whether RubyGems
+may install Otto. It does not mean every version in that range has the same CI
+or upstream security status. The table above is the support policy for the
+current matrix.
+
+## What dependency ranges mean
+
+The runtime dependency ranges in `otto.gemspec` express the versions Otto
+expects to be API-compatible with. Their lower bounds are compatibility
+baselines, not a promise that every allowed version is free of known
+vulnerabilities or still receives security fixes.
+
+Otto may exclude a known-bad dependency release or raise a lower bound when a
+vulnerability affects Otto users. Such a constraint is a targeted response, not
+a substitute for auditing the complete resolved dependency graph. A future
+advisory can make any previously acceptable version unsafe while it still
+satisfies the gemspec.
+
+Otto's committed `Gemfile.lock` makes maintainer development and CI resolution
+reproducible. Bundler does not use that lockfile when Otto is installed as a
+dependency of another application. Otto's locked and freshly resolved CI jobs
+test compatibility; neither job selects or certifies a secure dependency set
+for consumer applications.
+
+## Consumer lockfile policy
+
+The deployable application is responsible for the final dependency graph. An
+application using Otto should:
+
+1. Commit its `Gemfile.lock` and deploy that exact resolution.
+2. Make [`bundler-audit`](https://github.com/rubysec/bundler-audit) available
+   in application CI, then run it with an updated advisory database on every
+   lockfile change, on a scheduled weekly job, and before each production
+   deployment:
+
+   ```sh
+   bundle-audit check --update
+   ```
+
+3. Treat a relevant advisory as a release blocker. Update the affected gem and
+   re-run the application's tests and audit. For a conservative targeted
+   update, replace `GEM_NAME` with the affected gem:
+
+   ```sh
+   bundle update --conservative GEM_NAME
+   bundle-audit check --update
+   ```
+
+4. Enable an automated dependency updater, or review `bundle outdated`
+   manually at least weekly, so patched releases reach the application
+   lockfile.
+5. Audit the Ruby interpreter, operating system packages, and native libraries
+   separately. `bundler-audit` checks Ruby gems; it does not make an
+   end-of-life Ruby secure.
+
+If the patched dependency version falls outside Otto's declared range,
+applications should upgrade Otto when a compatible release is available and
+report the blocked update to the maintainers. Do not assume that a successful
+`bundle install` means the resolved bundle has no known vulnerabilities.

data/examples/advanced_routes/README.md

@@ -20,50 +20,54 @@ The example is organized to separate concerns:
 - `app.rb`: Loader that requires all controller and logic files
 - `app/controllers/`: Handler classes (`RoutesApp`, namespaced controllers)
 - `app/logic/`: Business logic classes (simple, nested, namespaced)
-- `run.rb`, `puma.rb`, `test.rb`: Alternative server/test runners
+
 
 ## Key Features Demonstrated
 
 ### Response Types
 Define how responses are formatted directly in routes:
 ```
-GET  /api/users        UserController#list      response=json
-GET  /page             PageController#show      response=view
-GET  /old-url          PageController#new-url   response=redirect
+GET  /api/users        RoutesApp#list_users      response=json
+GET  /dashboard        RoutesApp#dashboard       response=view
+GET  /login            RoutesApp#login_redirect  response=redirect
 ```
 
 ### Logic Classes
 Route to specialized classes that encapsulate business logic:
 ```
-GET  /calculate        DataProcessor   # Otto auto-instantiates and calls #process
-GET  /report           ReportGenerator # Same pattern
+GET  /logic/simple     SimpleLogic
+GET  /logic/data       DataLogic       response=json
 ```
 
+The classes in `app/logic/` expose the logic used by these routes.
+
 ### CSRF Exemption
 Mark routes that don't need CSRF tokens (APIs, webhooks):
 ```
-POST /api/webhook      WebhookHandler#receive   csrf=exempt
+POST /api/webhook      RoutesApp#webhook_handler   csrf=exempt
 ```
 
 ### Namespaced Routing
 Handle complex class hierarchies naturally:
 ```
-GET  /v2/dashboard     V2::Logic::Dashboard
-GET  /admin/panel      Admin::Panel#dashboard
+GET  /logic/v2/dashboard  V2::Logic::Dashboard  response=view
+GET  /logic/admin         Admin::Panel
 ```
 
 ### Custom Parameters
 Add arbitrary key-value pairs for flexible routing:
 ```
-GET  /admin            AdminPanel#dashboard     role=admin
+GET  /feature/flags    RoutesApp#feature_flags  feature=advanced mode=enabled
 ```
 
+These are route configuration values, not query-string parameters.
+
 ### Lambda / Inline Route Handlers (Issue #41)
 Route to a proc that you **pre-register** by name, using the `&` prefix:
 ```
 GET  /ping             &health_check            response=json
-POST /webhook          &receive_webhook         response=json csrf=exempt
-GET  /go               &to_dashboard            response=redirect
+POST /hooks/receive    &receive_webhook         response=json csrf=exempt
+GET  /go/dashboard     &to_dashboard            response=redirect
 ```
 
 The `&name` token is a plain string key looked up (O(1)) in a registry you
@@ -104,67 +108,49 @@ loading**. A route naming an unregistered handler fails with a clear
 instead of executing anything. The registered procs are, of course, trusted
 code that you wrote.
 
-Note: `csrf=exempt` is parse-and-expose parity with controller routes — the CSRF
-middleware does not enforce it for any handler kind.
+This example enables CSRF protection in `config.rb`; the `routes` file marks its API and webhook examples with `csrf=exempt`.
+
+## Run it
 
-## How to Run
+### Prerequisites
 
-### Using rackup (recommended)
+Run this example from an Otto source checkout with Ruby 3.2 through 4.0 and Bundler. `rackup` is a development dependency in the root `Gemfile`, so enable that optional group before installing the bundle.
 
 ```sh
+git clone https://github.com/delano/otto.git
+cd otto
+bundle config set with development
+bundle install
 cd examples/advanced_routes
-rackup config.ru
+bundle exec rackup config.ru
 ```
 
-### Using alternative runners
-
-```sh
-ruby run.rb   # Basic rackup
-ruby puma.rb  # Using puma server
-ruby test.rb  # For testing
-```
+The server listens on `http://localhost:9292`.
 
-The application will be running at `http://localhost:9292`.
+> **Current limitation:** This checked-in example does not finish booting: `app/logic/complex/business/handler.rb` attempts to declare `Complex` as a module, which conflicts with Ruby's built-in `Complex` class. Until that source issue is fixed, `rackup` exits before listening and the checks below cannot be run. They document the routes and expected responses configured by this example.
 
-## Testing Routes
+### Verify routes
 
-Use curl to test the different routes:
+In another terminal, run these checks against routes defined in `routes`:
 
 ```sh
 # JSON response
-curl http://localhost:9292/json/test
+curl -i http://localhost:9292/api/health
 
-# View response
-curl http://localhost:9292/view/test
+# HTML view response
+curl -i http://localhost:9292/dashboard
 
-# Logic class routing
-curl http://localhost:9292/logic/simple
+# Registered lambda handler
+curl -i http://localhost:9292/ping
 
-# Namespaced routing
-curl http://localhost:9292/logic/v2/dashboard
+# Redirect response; inspect the Location header
+curl -i http://localhost:9292/go/dashboard
 
-# Custom parameters
-curl "http://localhost:9292/custom?role=admin"
+# Route configuration values
+curl -i http://localhost:9292/feature/flags
 ```
 
-## Expected Output
-
-```
-Listening on 127.0.0.1:9292, CTRL+C to stop
-
-[JSON response]
-GET /json/test 200 OK
-Content-Type: application/json
-{"status": "success", "data": {...}}
-
-[Logic class routing]
-GET /logic/simple 200 OK
-{"processed": true, "input": "test"}
-
-[Namespaced routing]
-GET /logic/v2/dashboard 200 OK
-{"version": "2.0", "dashboard": {...}}
-```
+Expect `200` responses for the first three and last commands. `/api/health` returns JSON containing `healthy`, `/dashboard` returns HTML containing `Dashboard`, `/ping` returns JSON containing `ok`, and `/feature/flags` returns JSON containing `advanced`. `/go/dashboard` returns `302` with `Location: /dashboard`.
 
 ## File Structure Details
 
@@ -191,9 +177,9 @@ The `routes` file is extensively commented to explain each feature:
 - Review the `routes` file for syntax reference
 - Examine handler methods to see request/response patterns
 - Check logic classes for business logic encapsulation patterns
-- Explore [Authentication](../authentication_strategies/) for protecting routes
-- See [Security Features](../security_features/) for CSRF, validation, file uploads
+- Explore [Authentication](../authentication_strategies/README.md) for protecting routes
+- See [Security Features](../security_features/README.md) for CSRF, validation, and file uploads
 
 ## Further Reading
 
-- [CLAUDE.md](../../CLAUDE.md) - Comprehensive developer guidance
+- [Project README](../../README.md) - Installation and framework overview