Skip to main content

Module call

Module call 

Source
Expand description

RETURNS-47 · the call’s context: who is calling, as the gate admitted them, how far the call reaches, and the hop it came through.

A method reaches its caller through the call it runs in, never through its signature, so a method of a hand-written trait (whose signature is the same for every implementation) reaches it the same way an inherent method does:

ⓘ
#[plexus_macros::activation]
impl forge::Forge for GitHub {
    async fn repos(&self) -> Vec<Repo> {
        let Ok(caller) = plexus_core::call::caller() else { return vec![] };   // fail closed
        self.repos_within(caller.reach()).await
    }
}
  • Typed and verified. caller() answers the AuthContext the service’s gate admitted (after AUTH-11’s liveness: a sign-in that ended is anonymous here, as at the gate) and the Reach it answered for the call. A service’s own verifier turns it into its own verified user, as #[from_auth] does (VerifiedUser::current(&self.access).await?). Nothing outside this crate builds one: a DynamicHub sets it as it dispatches.
  • Fail closed. Outside a call there is no caller: caller(), hop() and crate::plexus::current_reach are errors, never a default. A service without a gate dispatches every call with Reach::everywhere — what no gate has always meant — said by the dispatch, not assumed by the reader.
  • Through a hop. In a child service reached through the seam (crate::plexus::remote_child::serve_child), the call’s context is the hop’s (spec/12: the acting service, the caller it acts for, the gate’s verdict as a ceiling, the call id): hop() answers it, and Hop::allows bounds a read by it. caller() there is an error: no gate of this process admitted anyone, and the hop is not a credential.
  • With the call’s stream. The context goes with the stream the call answers: each poll of it runs inside the context (InCall), so a method’s stream body reads caller() as its first line does.
  • Across spawned work, only when handed. A task the method spawns does not inherit the context: it carries it only when handed it explicitly, scope(context()?, fut). Nothing inherits a caller by accident.

#[plexus_macros::from_auth] stays for inherent methods: the dispatch hands it the same identity it puts here.

Structs§

CallContext
The context of one call: the caller as the gate admitted them and the reach it answered — or, in a child, the hop the call came through. Cheap to clone. Built only by the dispatch (and the child seam), never by hand; a method gets it with context(), to hand to work it spawns.
Caller
The caller of the call being run, as the service’s gate admitted them: caller().
Hop
spec/12’s hop, as a child reads it: who acts, for whom, within what. for grants nothing; limit is a ceiling, never a grant.
HopLimit
The near side’s decision, as a ceiling (spec/12 limit).
InCall
A stream polled inside a call’s context: what the dispatch hands its caller, so a method’s stream reads caller() as its first line does.

Enums§

CallError
Why there is no caller (or no hop) to answer. Fail closed: each is an error, never a default; as a PlexusError it is Unauthenticated.

Functions§

admits_everywhere
KEEL-31: may the call this runs in run grant, a method that acts on the whole service (#[plexus_macros::method(everywhere)])? Only when the reach it was admitted with is held on *: a gated service’s verdict (the gate decided it on * — or, through an untyped slot, on the slot’s grant, which must then be held on *), the hop’s ceiling in a child reached through the seam (limit.held_on naming *), or a service without a gate (its dispatch admits everywhere). The macro calls it before such a method runs, wherever it is called from, so neither a near side that decided on a slot nor an older near side lets a scoped holder through. Outside any call — code calling the activation directly, with no dispatch and no hop — it allows, as before: no gate decided anything to consult.
caller
The caller of the call this runs in, as the gate admitted them, with the reach it answered. An error outside a call, and in a child (read hop() there).
context
The whole context of the call this runs in — to hand to a task it spawns, scope(context()?, fut). An error outside a call.
follows_its_reach
KEEL-59: the call this runs in answers for its own reach when the grants move, so the dispatch does not end it.
hop
The hop the call this runs in came through (spec/12), in a child reached through the seam. An error outside a call, and in a call that did not come through a hop.
scope
Run fut inside ctx: how a task a method spawns carries its caller.
ungated
Dispatch a call to one activation as a service with no gate dispatches it: in a context admitting auth everywhere — said here, by the caller of this function, never assumed by the method. The leaf path of a bridge that serves a single activation (plexus-transport’s REST and MCP bridges call Activation::call straight, outside any context, where a method that needs its caller is refused). Inside a call already, that call’s reach and hop are kept, with this call’s identity.
verified
What the method’s verifier answered for this call: on impl Trait for Type, #[plexus_macros::from_auth(self.access.verify)] on the method runs the verifier before the body — its error the call’s refusal, out of band and typed, as a #[from_auth] parameter’s is — and keeps its value here for the body. An error outside a call, and when the method declared no verifier of type T.