rust_webx_host/
diagnostics.rs

1//! Route/handler startup diagnostics (uses tracing — host layer only).
2
3use rust_webx_core::route::diagnostics::{
4    duplicate_handlers, orphan_handlers, orphan_route_details, route_snapshots,
5};
6use rust_webx_core::route::scan::{RouteDispatch, RouteEntry};
7
8/// Fail fast when route/handler configuration is inconsistent.
9///
10/// Panics at `HostBuilder::build()` when:
11/// - a route exists without a matching `#[handler]` registration
12/// - a `#[handler]` exists without a matching route
13/// - a route has a handler but no generated `RouteDispatch` bridge
14pub fn assert_route_configuration_valid() {
15    let orphan_route_rows = orphan_route_details();
16    let missing_routes = orphan_handlers();
17
18    let mut missing_dispatch: Vec<(&'static str, &'static str, &'static str)> = Vec::new();
19    let cache = rust_webx_core::route::scan::HandlerCache::build();
20    let dispatch_types: std::collections::HashSet<&'static str> =
21        inventory::iter::<RouteDispatch>()
22            .map(|d| d.handler_type)
23            .collect();
24
25    for entry in inventory::iter::<RouteEntry> {
26        if cache.get(entry.handler_type).is_some() && !dispatch_types.contains(entry.handler_type) {
27            missing_dispatch.push((entry.method.as_str(), entry.path, entry.handler_type));
28        }
29    }
30
31    if orphan_route_rows.is_empty() && missing_routes.is_empty() && missing_dispatch.is_empty() {
32        return;
33    }
34
35    let mut message = String::from("Route configuration errors:\n");
36    if !orphan_route_rows.is_empty() {
37        message.push_str("\nRoutes without #[handler]:\n");
38        message.push_str(
39            "  Fix: add #[handler] or #[handler(inject)] impl IRequestHandler<Request, Response>\n",
40        );
41        for route in &orphan_route_rows {
42            message.push_str(&format!(
43                "  - {} {} ({})\n",
44                route.method, route.path, route.request_type
45            ));
46        }
47    }
48    if !missing_routes.is_empty() {
49        message.push_str("\nHandlers without route:\n");
50        message.push_str(
51            "  Fix: add #[get]/#[post]/... impl IRequest<R> for the request type, or remove the orphan #[handler]\n",
52        );
53        for req in &missing_routes {
54            message.push_str(&format!("  - {req}\n"));
55        }
56    }
57    if !missing_dispatch.is_empty() {
58        message.push_str("\nRoutes with handler but no RouteDispatch:\n");
59        message.push_str(
60            "  Fix: ensure the request type has a route macro (#[get]/#[post]/...) on its IRequest impl\n",
61        );
62        for (method, path, req) in &missing_dispatch {
63            message.push_str(&format!("  - {method} {path} ({req})\n"));
64        }
65    }
66    message.push_str("\nRun: cargo run -p <host-crate> -- --doctor");
67    panic!("{message}");
68}
69
70/// Log route table and warn on orphan routes/handlers.
71pub fn log_startup_diagnostics() {
72    let routes = route_snapshots();
73    tracing::info!(count = routes.len(), "Registered HTTP routes");
74    for route in &routes {
75        if route.has_handler {
76            tracing::debug!(
77                method = %route.method,
78                path = route.path,
79                request = route.request_type,
80                response = route.response_type,
81                "route"
82            );
83        } else {
84            tracing::warn!(
85                method = %route.method,
86                path = route.path,
87                request = route.request_type,
88                "route has no #[handler] registration — add #[handler] on IRequestHandler impl"
89            );
90        }
91    }
92
93    for handler in orphan_handlers() {
94        tracing::warn!(
95            request = handler,
96            "handler has no matching route — add #[get]/#[post] on IRequest impl or remove #[handler]"
97        );
98    }
99
100    for (handler, count) in duplicate_handlers() {
101        tracing::warn!(
102            request = handler,
103            count,
104            "duplicate #[handler] registration; last inventory entry wins"
105        );
106    }
107}
rust_webx_host/diagnostics.rs

rust_webx_host/
diagnostics.rs
