refactor: extract web boot setup

Author: gildesmarais

README.md

@@ -68,6 +68,7 @@ Dev URLs: Ruby app at `http://localhost:4000`, frontend dev server at `http://lo
 
 Backend code under the `Html2rss::Web` namespace now lives under `app/web/**`, so Zeitwerk can mirror constant paths directly instead of relying on directory-specific namespace wiring.
 `make ready` also runs `rake zeitwerk:verify`, which eager-loads the app and fails on loader drift early.
+For contributors and AI agents changing backend structure, follow the placement rules in [docs/ai-agent-app-web.md](docs/ai-agent-app-web.md).
 
 ## Make Targets
 

app.rb

@@ -9,6 +9,7 @@
 require_relative 'app/web/boot'
 
 Html2rss::Web::Boot.setup!(reloadable: ENV['RACK_ENV'] == 'development')
+Html2rss::Web::Boot::Setup.call!
 
 module Html2rss
   module Web
@@ -33,13 +34,6 @@ class App < Roda
       def self.development? = EnvironmentValidator.development?
 
       def development? = self.class.development?
-      EnvironmentValidator.validate_environment!
-      EnvironmentValidator.validate_production_security!
-      Flags.validate!
-
-      Html2rss::RequestService.register_strategy(:ssrf_filter, SsrfFilterStrategy)
-      Html2rss::RequestService.default_strategy_name = :ssrf_filter
-      Html2rss::RequestService.unregister_strategy(:faraday)
       opts.merge!(check_dynamic_arity: false, check_arity: :warn)
       use RequestContextMiddleware
       use Rack::Cache, metastore: 'file:./tmp/rack-cache-meta', entitystore: 'file:./tmp/rack-cache-body',

app/web/boot/setup.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Web
+    module Boot
+      ##
+      # Applies boot-time runtime configuration outside the Roda class body.
+      module Setup
+        class << self
+          # Validates environment configuration and wires the request service.
+          #
+          # @return [void]
+          def call!
+            validate_environment!
+            configure_request_service!
+          end
+
+          private
+
+          # @return [void]
+          def validate_environment!
+            EnvironmentValidator.validate_environment!
+            EnvironmentValidator.validate_production_security!
+            Flags.validate!
+          end
+
+          # @return [void]
+          def configure_request_service!
+            Html2rss::RequestService.register_strategy(:ssrf_filter, SsrfFilterStrategy)
+            Html2rss::RequestService.default_strategy_name = :ssrf_filter
+            Html2rss::RequestService.unregister_strategy(:faraday)
+          end
+        end
+      end
+    end
+  end
+end

docs/ai-agent-app-web.md

@@ -0,0 +1,60 @@
+# `app/web` Rules For AI Agents
+
+This file is intentionally prescriptive. If you are an AI coding agent changing Ruby backend code, follow these rules before adding files or moving code.
+
+## Namespace Contract
+
+- `app/` is the Zeitwerk root for `Html2rss`.
+- `app/web/**` maps to the `Html2rss::Web` namespace.
+- Do not add `require_relative` calls between files under `app/web/**` unless the file is a non-Zeitwerk boot entrypoint.
+- Path, filename, and constant name must match. If a constant is `Html2rss::Web::SecurityLogger`, the file belongs at `app/web/security/security_logger.rb`.
+
+## Directory Placement
+
+Use the narrowest concern folder that fits the object.
+
+- `app/web/api/`: API contract and endpoint implementation objects.
+- `app/web/boot/`: process boot, loader setup, dev reload, runtime setup.
+- `app/web/config/`: environment flags, local config loading, config snapshots.
+- `app/web/domain/`: backend domain helpers that do not belong to API, request, rendering, or security.
+- `app/web/errors/`: error classes and error response serialization.
+- `app/web/feeds/`: feed fetching, rendering orchestration, cache use, feed service contracts.
+- `app/web/http/`: low-level HTTP response/cache helpers.
+- `app/web/rendering/`: content negotiation and feed output builders.
+- `app/web/request/`: request-scoped context and middleware.
+- `app/web/routes/`: Roda route composition only.
+- `app/web/security/`: auth, token handling, account access, SSRF request strategy, security logging.
+- `app/web/telemetry/`: observability event emission only.
+
+## Placement Heuristics
+
+- Put code in `routes/` only if it mounts or composes Roda request branches.
+- Put code in `api/` only if it is specific to `/api/v1` contracts or endpoint behavior.
+- Put code in `feeds/` if it is part of fetching, resolving, rendering, or caching feeds.
+- Put code in `domain/` only as a last resort. If a better concern folder exists, use it.
+- Do not create generic buckets such as `services`, `utils`, `helpers`, or `concerns`.
+
+## Consolidation Rules
+
+- Prefer concern folders over a flat `app/web/` root.
+- Do not merge unrelated objects just to reduce file count.
+- Consolidate only when one file is clearly a thin wrapper around another concept and the merged object still has a single responsibility.
+- If a file defines multiple top-level constants, stop and check whether Zeitwerk naming or the public API would become less clear.
+
+## Boot And Runtime Rules
+
+- `app.rb` should declare the Roda app and its Rack/Roda plugins.
+- Process-level boot side effects belong in `app/web/boot/**`.
+- Register external runtime integrations, validate environment, and configure shared services in boot objects, not inline in the Roda class body.
+
+## Route Rules
+
+- Keep route composition centralized in `app/web/routes/**`.
+- Split route modules by endpoint concern when a route file grows, but preserve matching order.
+- Root metadata routes must use exact matching (`r.is`) so they do not swallow subpaths.
+
+## Change Checklist
+
+- Update or add specs for the behavior you moved.
+- Run `docker compose -f .devcontainer/docker-compose.yml exec -T app make ready`.
+- Smoke the app at `http://127.0.0.1:4001/` when request or UI behavior changed.

spec/html2rss/web/boot/setup_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require_relative '../../../../app/web/boot/setup'
+
+RSpec.describe Html2rss::Web::Boot::Setup do
+  describe '.call!' do
+    before do
+      allow(Html2rss::Web::EnvironmentValidator).to receive(:validate_environment!)
+      allow(Html2rss::Web::EnvironmentValidator).to receive(:validate_production_security!)
+      allow(Html2rss::Web::Flags).to receive(:validate!)
+      allow(Html2rss::RequestService).to receive(:register_strategy)
+      allow(Html2rss::RequestService).to receive(:default_strategy_name=)
+      allow(Html2rss::RequestService).to receive(:unregister_strategy)
+    end
+
+    it 'validates environment state and configures the request service', :aggregate_failures do
+      described_class.call!
+
+      expect(Html2rss::Web::EnvironmentValidator).to have_received(:validate_environment!).once
+      expect(Html2rss::Web::EnvironmentValidator).to have_received(:validate_production_security!).once
+      expect(Html2rss::Web::Flags).to have_received(:validate!).once
+      expect(Html2rss::RequestService).to have_received(:register_strategy)
+        .with(:ssrf_filter, Html2rss::Web::SsrfFilterStrategy).once
+      expect(Html2rss::RequestService).to have_received(:default_strategy_name=).with(:ssrf_filter).once
+      expect(Html2rss::RequestService).to have_received(:unregister_strategy).with(:faraday).once
+    end
+  end
+end