pika-git-web-split-5

The original web.rs contained everything: page handlers, view mappers, SSE streams, REST endpoints, auth, chat, webhooks, and admin routes—all in a single file exceeding 6,800 lines.

After this change, web.rs retains only:

• Imports and type/struct definitions (~785 lines)
• The serve() function that builds the Axum router
• Eight include!() calls that textually embed the extracted submodules
• The shutdown_signal() helper
• The #[cfg(test)] mod tests; declaration

Using include!() rather than proper mod declarations is a deliberate choice: it keeps every extracted function inside the web module's flat namespace, so no item needs pub visibility changes and no call-site needs updating. This makes the split a pure file-organization refactor with zero semantic impact.

This file becomes the single source of truth for how raw data becomes displayable content. It contains:

• Feed mappers: map_feed_item, map_nightly_feed_item — convert store records into feed-page view structs.
• Detail/CI template renderers: render_detail_template_with_notices, render_branch_ci_template_with_notices, render_branch_ci_live_html, render_branch_ci_summary_html, render_nightly_live_html — build Askama template structs and render them to HTML.
• CI run/lane view mappers: map_ci_run_view, map_ci_lane_view, map_ci_summary_run, map_nightly_lane_view — used by both HTML templates and JSON API responses.
• API-specific adapters: map_api_ci_run, map_api_ci_lane, map_api_nightly_lane, map_forge_branch_summary — wrap view structs into API response types.
• Utility functions: ci_timing_summary, format_compact_duration, lane_operator_hint, lane_target_health_summary, lane_status_badge_class, parse_ci_timestamp, select_branch_log_lane.
• Active-state predicates: branch_ci_runs_are_active, nightly_run_is_active.

Grouping these together means any change to how data is presented—whether a new CI status tone, a different timing format, or an extra operator hint—touches only this file.

This ~155-line file contains every handler that returns a full HTML page:

Each handler follows the same pattern: fetch data via forge_service, call a render_* function from views.rs, and return Html(rendered) or an error response.

At ~270 lines, live.rs encapsulates the real-time update system:

1. Snapshot structs (BranchCiLiveSnapshot, BranchCiSummarySnapshot, NightlyLiveSnapshot) hold pre-rendered HTML plus an active flag that controls whether the SSE stream stays open.
2. Loaders (load_branch_ci_summary_snapshot, load_branch_ci_live_snapshot, load_nightly_live_snapshot) fetch data and render a snapshot, returning Option for not-found cases.
3. Broadcast listeners (next_branch_ci_summary_snapshot, next_branch_ci_live_snapshot, next_nightly_live_snapshot) loop on a tokio::sync::broadcast::Receiver<CiLiveUpdate>, filtering for the relevant branch/nightly ID and reloading a snapshot on match or lag.
4. SSE handlers (branch_ci_stream_handler, branch_ci_full_stream_handler, nightly_stream_handler) compose the above into Sse::new(stream) responses with 15-second keep-alive.
5. Error formatters (branch_live_update_error_html, nightly_live_update_error_html) produce graceful degradation HTML when a live reload fails.

The largest extracted file at ~540 lines, api.rs groups every JSON-returning endpoint:

Mutation endpoints (all require require_trusted_auth):

• merge_handler, close_handler — branch lifecycle
• rerun_branch_ci_lane_handler, fail_branch_ci_lane_handler, requeue_branch_ci_lane_handler, recover_branch_ci_run_handler — branch CI operations
• rerun_nightly_lane_handler, fail_nightly_lane_handler, requeue_nightly_lane_handler, recover_nightly_run_handler — nightly CI operations
• api_trigger_nightly_handler — scheduling trigger

Query endpoints:

• api_branch_detail_handler, api_branch_resolve_handler — branch lookup
• api_branch_logs_handler — lane log retrieval
• api_branch_ci_runs_handler — CI run listing
• api_nightly_detail_handler, api_nightly_lanes_handler — nightly data

Also includes the request query structs ForgeBranchResolveQuery and ForgeBranchLogsQuery.

At ~85 lines, this is the smallest extracted module. It contains:

• require_trusted_auth — extracts an auth token from request headers and validates it against the configured AuthConfig, returning the caller's npub or an error response.
• require_admin_auth — stricter variant requiring admin-level privileges.
• forge_service_json_error — converts a ForgeServiceError into a JSON error response with appropriate HTTP status code.
• map_forge_service_error — lower-level variant returning (StatusCode, String) tuples, used by page handlers.
• ReviewModeQuery — a small deserializable struct for the ?review=true query parameter.

Keeping these in one place ensures consistent auth behavior across all endpoints.

The ~165-line chat.rs contains two handlers:

• branch_chat_handler — opens an SSE stream for a branch's chat session, streaming Claude AI responses in real time.
• branch_chat_send_handler — accepts a POST with a user message, forwards it to the Claude session, and returns a JSON acknowledgment.

This is a natural extraction boundary because chat is a distinct feature with its own SSE lifecycle, separate from the CI live-update streams in live.rs.

The ~145-line webhook.rs contains the webhook_handler function, which:

1. Reads the raw request body.
2. Validates the HMAC-SHA256 signature from the X-Hub-Signature-256 header against the configured webhook secret.
3. Parses the JSON payload and inspects the X-GitHub-Event header to determine the event type.
4. Dispatches push events and CI status updates to the forge_service for processing.

This is security-sensitive code (signature validation) and benefits from being reviewable in isolation.

The ~115-line admin.rs contains four handlers, all gated behind require_admin_auth:

Separating admin endpoints makes it easy to audit privileged access patterns.

The test module tests.rs becomes a thin hub that declares five child modules via standard mod (not include!):

Each test file uses use super::*; to access everything in the web module, which works seamlessly because the include!() approach keeps all items in a single namespace. The test split mirrors the source split, so when a developer modifies live.rs they know exactly which test file to check.