arcly_http/web/
context.rs

1//! The single opaque request boundary. Handlers receive `RequestContext` --
2//! axum/tower primitives are private to this module.
3
4use std::sync::Arc;
5
6use axum::http::{HeaderMap, Method};
7use bytes::Bytes;
8use smallvec::SmallVec;
9use smol_str::SmolStr;
10
11use crate::core::engine::{FrozenDiContainer, RouteSpec};
12use crate::session::Session;
13use crate::web::tenant::TenantConfig;
14
15/// Opaque authenticated-principal claims.
16pub type Claims = serde_json::Map<String, serde_json::Value>;
17
18/// The one and only context passed to every handler.
19///
20/// Carries a full W3C distributed-tracing context:
21/// - `trace_id` (16 bytes) -- preserved across the entire distributed call chain.
22/// - `span_id`  (8 bytes)  -- this server hop's span; becomes `parent-id` downstream.
23/// - `parent_span_id` -- the upstream caller's span (all-zeros = root span).
24///
25/// Use [`traceparent`](Self::traceparent) to generate the header for outgoing calls.
26#[derive(Clone)]
27pub struct RequestContext {
28    method: Method,
29    raw_path: SmolStr,
30    query: SmolStr,
31    params: SmallVec<[(SmolStr, SmolStr); 4]>,
32    headers: HeaderMap,
33    body: Bytes,
34    claims: Option<Arc<Claims>>,
35    session: Option<Arc<Session>>,
36    tenant: Option<std::sync::Arc<TenantConfig>>,
37    trace_id: [u8; 16],
38    span_id: [u8; 8],
39    parent_span_id: [u8; 8],
40    container: &'static FrozenDiContainer,
41    /// Matched route pattern (e.g. `/users/:id`). Empty string for plugin routes.
42    /// Used for cardinality-safe metrics labels — never use raw `path` for labels.
43    route_pattern: &'static str,
44    /// `Some` for macro-registered routes; `None` for plugin-registered routes.
45    route_spec: Option<&'static RouteSpec>,
46}
47
48impl RequestContext {
49    #[inline]
50    pub fn method(&self) -> &Method {
51        &self.method
52    }
53    #[inline]
54    pub fn path(&self) -> &str {
55        &self.raw_path
56    }
57
58    #[inline]
59    pub fn query_string(&self) -> Option<&str> {
60        if self.query.is_empty() {
61            None
62        } else {
63            Some(&self.query)
64        }
65    }
66
67    #[inline]
68    pub fn body(&self) -> &Bytes {
69        &self.body
70    }
71    #[inline]
72    pub fn trace_id(&self) -> [u8; 16] {
73        self.trace_id
74    }
75
76    /// This server hop's span ID (64-bit, unique per request).
77    #[inline]
78    pub fn span_id(&self) -> [u8; 8] {
79        self.span_id
80    }
81
82    /// The incoming caller's span ID, or `None` for root (origin) spans.
83    #[inline]
84    pub fn parent_span_id(&self) -> Option<[u8; 8]> {
85        if self.parent_span_id == [0u8; 8] {
86            None
87        } else {
88            Some(self.parent_span_id)
89        }
90    }
91
92    #[inline]
93    pub fn claims(&self) -> Option<&Claims> {
94        self.claims.as_deref()
95    }
96
97    /// The server-side session loaded for this request, if any.
98    ///
99    /// `Some` only when `SessionManager` is provided in the DI container and
100    /// the session-ID cookie was present, valid, and found in the store.
101    #[inline]
102    pub fn session(&self) -> Option<&Arc<Session>> {
103        self.session.as_ref()
104    }
105
106    /// The tenant resolved for this request, if any.
107    ///
108    /// `Some` only when a `TenantRegistry` is provided in the DI container and
109    /// the configured strategy (header / subdomain) matched a known tenant
110    /// (or a fallback tenant is configured). Enforce presence + JWT-claim
111    /// consistency with `web::tenant::TENANT.check(&ctx)?`.
112    #[inline]
113    pub fn tenant(&self) -> Option<&TenantConfig> {
114        self.tenant.as_deref()
115    }
116
117    #[inline]
118    pub fn header(&self, key: &str) -> Option<&str> {
119        self.headers.get(key).and_then(|v| v.to_str().ok())
120    }
121
122    #[inline]
123    pub fn param(&self, name: &str) -> Option<&str> {
124        self.params
125            .iter()
126            .find(|(k, _)| k == name)
127            .map(|(_, v)| v.as_str())
128    }
129
130    /// Resolve a singleton service. O(1), no locks, no allocation.
131    /// Panics if `T` was not provided into the DI container.
132    #[inline]
133    pub fn inject<T: Send + Sync + 'static>(&self) -> &'static T {
134        self.container.get::<T>()
135    }
136
137    /// Non-panicking variant of [`Self::inject`]. Returns `None` when `T` is not
138    /// in the DI container. Used by optional guards and middleware.
139    #[inline]
140    pub fn try_inject<T: Send + Sync + 'static>(&self) -> Option<&'static T> {
141        self.container.try_get::<T>()
142    }
143
144    /// Matched route pattern (e.g. `/users/:id`). Use this — not `path()` — as a
145    /// metrics/trace label to prevent high-cardinality from path parameters.
146    #[inline]
147    pub fn route(&self) -> &'static str {
148        self.route_pattern
149    }
150
151    /// Static route metadata for the matched route, if any.
152    #[inline]
153    pub fn route_spec(&self) -> Option<&'static RouteSpec> {
154        self.route_spec
155    }
156
157    /// Generate the W3C `traceparent` header value suitable for forwarding to
158    /// downstream HTTP services. Uses this hop's `span_id` as the `parent-id`
159    /// field so the downstream span correctly chains to this one.
160    ///
161    /// Format: `00-{trace_id_hex}-{span_id_hex}-01`
162    pub fn traceparent(&self) -> String {
163        format!(
164            "00-{}-{}-01",
165            hex_encode_16(&self.trace_id),
166            hex_encode_8(&self.span_id)
167        )
168    }
169
170    /// The trace ID as a lowercase hex string — for log/audit correlation.
171    /// Replaces app-level calls to `lean_telemetry::hex_encode(&ctx.trace_id())`.
172    pub fn trace_id_hex(&self) -> String {
173        hex_encode_16(&self.trace_id)
174    }
175
176    /// Attach decoded JWT claims to a freshly constructed context.
177    #[doc(hidden)]
178    #[inline]
179    pub(crate) fn __with_claims(mut self, claims: Option<Arc<Claims>>) -> Self {
180        self.claims = claims;
181        self
182    }
183
184    /// Attach a loaded server-side session to a freshly constructed context.
185    #[doc(hidden)]
186    #[inline]
187    pub(crate) fn __with_session(mut self, session: Option<Arc<Session>>) -> Self {
188        self.session = session;
189        self
190    }
191
192    /// Attach the resolved tenant to a freshly constructed context.
193    #[doc(hidden)]
194    #[inline]
195    pub(crate) fn __with_tenant(mut self, tenant: Option<std::sync::Arc<TenantConfig>>) -> Self {
196        self.tenant = tenant;
197        self
198    }
199
200    /// Boundary constructor. Not part of the public API.
201    #[doc(hidden)]
202    #[allow(clippy::too_many_arguments)]
203    pub fn __new(
204        method: Method,
205        raw_path: SmolStr,
206        query: SmolStr,
207        params: SmallVec<[(SmolStr, SmolStr); 4]>,
208        headers: HeaderMap,
209        body: Bytes,
210        trace_id: [u8; 16],
211        span_id: [u8; 8],
212        parent_span_id: [u8; 8],
213        container: &'static FrozenDiContainer,
214        route_pattern: &'static str,
215        route_spec: Option<&'static RouteSpec>,
216    ) -> Self {
217        Self {
218            method,
219            raw_path,
220            query,
221            params,
222            headers,
223            body,
224            claims: None,
225            session: None,
226            tenant: None,
227            trace_id,
228            span_id,
229            parent_span_id,
230            container,
231            route_pattern,
232            route_spec,
233        }
234    }
235}
236
237#[inline]
238pub(crate) fn hex_encode_16(b: &[u8; 16]) -> String {
239    b.iter().map(|x| format!("{x:02x}")).collect()
240}
241
242#[inline]
243pub(crate) fn hex_encode_8(b: &[u8; 8]) -> String {
244    b.iter().map(|x| format!("{x:02x}")).collect()
245}
arcly_http/web/context.rs

arcly_http/web/
context.rs
