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§

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.
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.