refactor(gateway): extract start_server + route composition into platform/router.rs — ironclaw#2599 stage 2

[ilblackdragon]

Summary

Second increment of the ironclaw#2599 platform/feature split (follow-up to #2628). Moves start_server() and the Axum route composition out of src/channels/web/server.rs into a dedicated src/channels/web/platform/router.rs, so the platform-vs-features dependency direction becomes visible: the router depends on handler modules, never the reverse.

Changes

• New platform/router.rs — owns start_server(), the four routers (`public`, `protected`, `statics`, `projects`), and the cross-cutting layer stack (CORS, 10 MB body limit, panic catch, `X-Content-Type-Options`, `X-Frame-Options`, CSP).
• Feature handlers still inline in `server.rs` are now `pub(crate)` so the router can register them without leaking them outside the crate. Two private structs (`HistoryQuery`, `GatewayStatusResponse`) directly referenced by pub(crate) handlers were also raised to `pub(crate)` so the handler signatures type-check from the router module.
• `server.rs` keeps the feature handlers that haven't migrated yet (OAuth callbacks, chat, extensions, pairing, logs, gateway status) and adds `pub use platform::router::start_server` so external callers (`src/channels/web/mod.rs`, `tests/multi_tenant_integration.rs`) keep working. Unused imports (`Router`, `DefaultBodyLimit`, `CorsLayer`, `tokio::sync::mpsc`, etc.) dropped.
• `mod.rs` now calls `platform::router::start_server` directly.
• `CLAUDE.md` file map updated.

Behavior change

None. Route table, middleware stack, CORS policy, body limits, panic handling, security headers, and CSP are byte-identical to origin/staging — verified by visual diff against the pre-move code.

Stats

• `server.rs`: 7463 → 6973 lines (−490)
• New `platform/router.rs`: 537 lines

Test plan

• `cargo fmt --all`
• `cargo clippy --all --benches --tests --examples --all-features` — clean
• `cargo check --lib --tests --all-features` — clean
• `cargo test --lib` — 5068 passed, same 2 pre-existing failures as stage 1 (`pairing::approval::tests::propagate_approval_restores_runtime_state_when_on_start_fails`, `extensions::manager::tests::test_telegram_token_colon_preserved_in_validation_url`) — neither touches any symbol this PR moves
• Manual smoke: reviewer runs `cargo run` and exercises a few routes

Follow-ups

Stage 3: relocate `auth.rs` / `sse.rs` / `ws.rs` into `platform/`.
Stage 4: open `features//` directories and migrate handlers.
Stage 5: CI boundary check.
Stage 6: delete re-export shims.

Unrelated follow-ups remain tracked in issue #2633.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request refactors the web gateway by moving the start_server function and Axum route composition from server.rs to a new platform/router.rs module. This change is part of a migration to decouple the platform layer from feature handlers. One issue was identified regarding the use of .expect() in production code, which violates project rules; a suggestion was provided to replace it with proper error handling during server bootstrap.

[gemini-code-assist]

Avoid using .expect() in production code, as it is banned by project rules. In this context, constructing the CORS origins can fail if the resulting string is not a valid HeaderValue. It is better to handle the error explicitly by mapping it to a semantically specific error variant like ChannelError::StartupFailed to ensure the server fails gracefully during bootstrap. Additionally, using format!("http://{}", addr) is more robust for IPv6 addresses than manually concatenating the IP and port.

Suggested change

	.allow_origin([
	format!("http://{}:{}", addr.ip(), addr.port())
	.parse()
	.expect("valid origin"),
	format!("http://localhost:{}", addr.port())
	.parse()
	.expect("valid origin"),
	])
	.allow_origin([
	format!("http://{}", addr)
	.parse()
	.map_err(|e| crate::error::ChannelError::StartupFailed {
	name: "gateway".to_string(),
	reason: format!("Invalid IP origin: {}", e),
	})?,
	format!("http://localhost:{}", addr.port())
	.parse()
	.map_err(|e| crate::error::ChannelError::StartupFailed {
	name: "gateway".to_string(),
	reason: format!("Invalid localhost origin: {}", e),
	})?,
	])

References

1. Avoid using .expect() in production code, as it is banned by project rules. Prefer alternatives like compile-time macros (e.g., serde_json::json!) or proper error handling.
2. Create specific error variants for different failure modes (e.g., DownloadFailed with a URL string vs. ManifestRead with a file path) to provide semantically correct and clear error messages.

[ilblackdragon]

Fixed in 31735cc. Replaced the two .expect() calls with .map_err(|e| ChannelError::StartupFailed { .. }) so a malformed bound address fails the gateway bootstrap instead of panicking. Also switched to format!("http://{addr}") so IPv6 binds produce the correctly bracketed origin. This also resolves the No panics in production code CI failure.

[Copilot]

Pull request overview

Refactors the web gateway to make the platform/feature split (ironclaw#2599 stage 2) explicit by moving Axum route wiring and server bootstrap out of the server.rs feature-handler module and into platform/router.rs.

Changes:

• Added src/channels/web/platform/router.rs to own start_server() and all route composition + shared middleware layers.
• Converted remaining inline handlers (and a couple referenced DTO structs) in server.rs to pub(crate) so the new router can register them.
• Updated platform/mod.rs exports and refreshed the web gateway file map docs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/channels/web/server.rs	Removes start_server() implementation; keeps unmigrated feature handlers and re-exports start_server from platform::router; adjusts handler visibility for router registration.
src/channels/web/platform/router.rs	New module containing TCP bind + route composition (public/protected/statics/projects) and shared middleware stack.
src/channels/web/platform/mod.rs	Exposes the new router submodule.
src/channels/web/CLAUDE.md	Updates the file map to document the new router module.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

platform/mod.rs docstring says feature handlers depend on platform "not the other way around", but platform::router now imports feature handlers from handlers/* and server.rs. Please update this doc comment to clarify the router is the intentional coupling point (or relocate the router out of platform/ if the no-back-edges rule is still intended).

[ilblackdragon]

Fixed in 31735cc. Rewrote the platform/mod.rs docstring to name router as the single, intentional exception to the no-back-edges rule, and explicitly list the platform submodules the rule still applies to (state, static_files, and the future auth/sse/ws once they move here).

[Copilot]

The file map now describes platform/router.rs as the coupling point between platform and features, but the later "Platform vs. feature layering" section still states the platform/ subtree has "no back-edges". Please reconcile the layering docs so readers understand whether the router is an exception or the rule has changed.

[ilblackdragon]

Fixed in 31735cc. Rewrote the "Platform vs. feature layering" section in CLAUDE.md to reconcile with the File Map: router is the coupling point; every other platform submodule must stay handler-agnostic; the CI check planned for ironclaw#2599 stage 5 will forbid cross-imports between platform/{state,static_files,auth,sse,ws}.rs and handlers/* / features/* while explicitly allowing platform/router.rs to reference both sides.