pub struct HandlerContext<'a> { /* private fields */ }Expand description
A short-lived, derived context handed to a handler for the span of a single operation.
Where a Context<B> is the caller’s long-lived unit of work, a
HandlerContext is the inner view the Domain builds
around one action while its handler runs, and drops when the action returns.
It exists to give handler code a richer, scoped surface than the bare
Changeset + Store pair without exposing (or
letting a handler mutate) the whole parent context.
It carries:
- a borrow of the
Domain, so a handler can introspect registered resources and thepolicy tree— and, later, re-enter the domain to run nested actions; - read-only projections of the parent context’s request state — the
actor,tenant,id, andmeta; - the optional
Storethe handler reads/writes through; - its own
scratchbag — a freshExtensionsthe handler writes enrichment into (policy results it observed, logs, timings). It starts empty rather than inheriting the parent’s bag, so a handler cannot mutate request state mid-action; what it records is merged back into the parent context byContext::merge_scratchafter the handler returns, where the caller can read it.
Once the operation is done the Domain calls
complete, which consumes the context (and
hands back its scratch bag). Spent-context reuse is therefore a compile
error, not a runtime panic: the handler only ever borrows the context, so it
cannot keep it, and after complete there is no context left to misuse. The
lifetime 'a additionally ties the borrows to the parent context and domain,
so a HandlerContext cannot outlive the operation it was derived for.
Implementations§
Source§impl<'a> HandlerContext<'a>
impl<'a> HandlerContext<'a>
Sourcepub fn new(
domain: &'a Domain,
id: &'a ContextId,
actor: Option<&'a Record>,
tenant: Option<&'a Value>,
meta: &'a Record,
store: Option<&'a dyn Store>,
) -> Self
pub fn new( domain: &'a Domain, id: &'a ContextId, actor: Option<&'a Record>, tenant: Option<&'a Value>, meta: &'a Record, store: Option<&'a dyn Store>, ) -> Self
Derive a handler context from its parts. Called by the
Domain when it is about to run a handler; not usually
constructed by consumer code.
Sourcepub fn domain(&self) -> &'a Domain
pub fn domain(&self) -> &'a Domain
The domain this operation runs within — for introspection now, re-entry later.
Sourcepub fn client<T: Send + Sync + 'static>(&self) -> Option<&'a T>
pub fn client<T: Send + Sync + 'static>(&self) -> Option<&'a T>
Borrow a shared client of type T from the domain’s
DomainContext, if one was registered when the
domain was built.
This is how a handler reaches the long-lived, domain-scoped handles — an
HTTP client, a cache pool, an external service client — rather than
receiving them per call. Returns None when no client of that type is
registered.
if let Some(_http) = ctx.client::<HttpClient>() {
// call out through the shared client…
}Sourcepub fn actor(&self) -> Option<&Record>
pub fn actor(&self) -> Option<&Record>
The acting principal, if the parent context had one (read-only).
Sourcepub fn tenant(&self) -> Option<&Value>
pub fn tenant(&self) -> Option<&Value>
The tenant this operation is scoped to, if any (read-only).
Sourcepub fn store(&self) -> Option<&dyn Store>
pub fn store(&self) -> Option<&dyn Store>
The Store the handler runs against, if this operation was invoked on a
persistence-backed context. Mirrors the store argument handlers already
receive.
Sourcepub fn scratch(&self) -> &Extensions
pub fn scratch(&self) -> &Extensions
The handler’s own scratch bag — enrichment produced during this
operation (policy results, logs, timings), keyed by type like
Extensions. The domain merges it back into the request
Context once the handler returns; see
complete.
Sourcepub fn scratch_mut(&mut self) -> &mut Extensions
pub fn scratch_mut(&mut self) -> &mut Extensions
Mutably borrow the scratch bag to record
enrichment.
Sourcepub fn insert<T: Send + Sync + 'static>(&mut self, value: T) -> Option<T>
pub fn insert<T: Send + Sync + 'static>(&mut self, value: T) -> Option<T>
Stash a value in the scratch bag, keyed by
its type. Returns the previous value of the same type, if any.
Sourcepub fn get<T: Send + Sync + 'static>(&self) -> Option<&T>
pub fn get<T: Send + Sync + 'static>(&self) -> Option<&T>
Borrow a value of type T from the scratch
bag, if present.
Sourcepub fn complete(self) -> Extensions
pub fn complete(self) -> Extensions
Mark the operation done by consuming the context, returning its
scratch bag for the domain to merge into the request Context via
Context::merge_scratch. Called by the
Domain once the handler has produced its result.
Because this takes self, a spent context cannot be reused — there is
nothing left to call. Handlers only ever borrow the context (&mut), so
they can neither complete it early nor hold it past their run; the
exclusive right to finish it stays with the domain, enforced by the
compiler rather than a runtime flag.
Sourcepub fn serialize(&self) -> String
pub fn serialize(&self) -> String
Serialize the context’s representable state to a JSON string — the form a handler returns alongside its result. The context is not fed back into the domain; this snapshot is the only thing that travels out.
This is a basic implementation: it captures the fields that have a
natural serial form — the id, actor, tenant,
and meta. The typed scratch bag holds
arbitrary dyn Any values that cannot be serialized generically, so it is
represented only by its entry count (scratch_len). A handler that
wants specific scratch values in the output should serialize them itself,
or a future revision can let entries opt into serialization.
{
"id": "ctx-… ",
"actor": { … } | null,
"tenant": <value> | null,
"meta": { … },
"scratch_len": 2
}