Skip to main content

HandlerContext

Struct HandlerContext 

Source
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 the policy 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, and meta;
  • the optional Store the handler reads/writes through;
  • its own scratch bag — a fresh Extensions the 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 by Context::merge_scratch after 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>

Source

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.

Source

pub fn domain(&self) -> &'a Domain

The domain this operation runs within — for introspection now, re-entry later.

Source

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…
}
Source

pub fn id(&self) -> &ContextId

The parent context’s correlation id.

Source

pub fn actor(&self) -> Option<&Record>

The acting principal, if the parent context had one (read-only).

Source

pub fn tenant(&self) -> Option<&Value>

The tenant this operation is scoped to, if any (read-only).

Source

pub fn meta(&self) -> &Record

The parent context’s string-keyed metadata (read-only).

Source

pub fn get_meta(&self, key: &str) -> Option<&Value>

Look up a parent metadata value by key.

Source

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.

Source

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.

Source

pub fn scratch_mut(&mut self) -> &mut Extensions

Mutably borrow the scratch bag to record enrichment.

Source

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.

Source

pub fn get<T: Send + Sync + 'static>(&self) -> Option<&T>

Borrow a value of type T from the scratch bag, if present.

Source

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.

Source

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
}

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for HandlerContext<'a>

§

impl<'a> !UnwindSafe for HandlerContext<'a>

§

impl<'a> Forget for HandlerContext<'a>

§

impl<'a> Freeze for HandlerContext<'a>

§

impl<'a> Move for HandlerContext<'a>

§

impl<'a> Send for HandlerContext<'a>

§

impl<'a> Sync for HandlerContext<'a>

§

impl<'a> Unpin for HandlerContext<'a>

§

impl<'a> UnsafeUnpin for HandlerContext<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.