pub struct Context { /* private fields */ }Expand description
Everything one request carries.
Cheap to clone: the fields sit behind an Arc, so handing a Context to
a nested call or another task copies a pointer.
use ash_jsonapi::context::Context;
let ctx = Context::new("01H9K2QZ8V")
.with_principal("alice@example.com")
.with_tenant("acme");
assert_eq!(ctx.correlation_id(), "01H9K2QZ8V");
assert_eq!(ctx.tenant(), Some("acme"));Implementations§
Source§impl Context
impl Context
Sourcepub fn new(correlation_id: impl Into<String>) -> Self
pub fn new(correlation_id: impl Into<String>) -> Self
A context for one request, identified by its correlation id.
The id is what ties a response back to the audit record, so it is
required rather than optional: it comes from the request’s
X-Request-Id where the client sent one, and is generated otherwise.
Sourcepub fn with_principal(self, principal: impl Into<String>) -> Self
pub fn with_principal(self, principal: impl Into<String>) -> Self
Bind the authenticated principal.
Absent until authentication has run — an unauthenticated request has a context, just not a principal.
Sourcepub fn with_tenant(self, tenant: impl Into<String>) -> Self
pub fn with_tenant(self, tenant: impl Into<String>) -> Self
Bind the tenant, extracted per the resource’s TenantStrategy.
Sourcepub fn with_locale(self, locale: Locale) -> Self
pub fn with_locale(self, locale: Locale) -> Self
Sourcepub fn locale(&self) -> Option<&Locale>
pub fn locale(&self) -> Option<&Locale>
The locale the client asked for, if it sent an Accept-Language this
crate could parse.
Sourcepub fn with_metadata(
self,
key: impl Into<String>,
value: impl Into<Value>,
) -> Self
pub fn with_metadata( self, key: impl Into<String>, value: impl Into<Value>, ) -> Self
Bind one metadata field, carried into every event logged under this context.
Sourcepub fn correlation_id(&self) -> &str
pub fn correlation_id(&self) -> &str
The correlation id. Always present.
Sourcepub fn principal(&self) -> Option<&str>
pub fn principal(&self) -> Option<&str>
The authenticated principal, if authentication has run.
Sourcepub fn with<T: Any + Send + Sync + 'static>(self, value: T) -> Self
pub fn with<T: Any + Send + Sync + 'static>(self, value: T) -> Self
Attach a typed value to this request.
For what your own middleware resolves — an authenticated actor, a
tenant handle, a feature flag set — so a handler receives one
Context rather than a widening tuple. One value per type; attaching
a second of the same type replaces the first.
A parsed request body does not travel this way: it is handed to
Create::create as an argument, since
a create always has one and routing it through here would turn an
infallible step into a fallible lookup.
// in middleware, after authenticating
let ctx = ctx.with(actor);
// anywhere downstream
let actor: &Actor = ctx.extract()?;Sourcepub fn get_ext<T: Any + Send + Sync + 'static>(&self) -> Option<&T>
pub fn get_ext<T: Any + Send + Sync + 'static>(&self) -> Option<&T>
The value of type T attached to this request, if any.
Sourcepub fn extract<T: Any + Send + Sync + 'static>(
&self,
) -> Result<&T, JsonApiError>
pub fn extract<T: Any + Send + Sync + 'static>( &self, ) -> Result<&T, JsonApiError>
The value of type T, or a 500 naming what was missing.
An absent extension means a handler ran without the middleware or extractor that should have attached it — a wiring bug, not a bad request, so the client is told nothing beyond the correlation id.
Source§impl Context
impl Context
Sourcepub fn scope(&self) -> ScopeGuard
Available on crate feature audit only.
pub fn scope(&self) -> ScopeGuard
audit only.Enter the ash-log scope for this context.
Every log line and audit event emitted while the returned guard lives inherits the correlation id, the principal and the metadata — with no threading through call signatures, and no scope built by hand at the call site.
Hold the guard across the work, not across an .await that might move
threads: ash_log::Scope is thread-local, so re-enter on the far side
of a spawn instead. The Context itself crosses freely.
let ctx = Context::new("01H9K2QZ8V").with_principal("alice@example.com");
let _guard = ctx.scope();
// ash_info!/ash_audit! here carry the id and the principal.