Skip to main content

Module parent

Module parent 

Source
Expand description

NEST-16 · a graft that knows its parent.

An activation written against its parent’s interface — #[plexus_macros::activation(parent = ShopClient)] — takes the parent’s client into a method as parent: Parent<ShopClient>, injected by the server (never on the wire, never in its own client), and calls inward as if the parent were local:

ⓘ
#[plexus_macros::activation(parent = ShopClient)]
impl Restock {
    /// The items running low.
    pub async fn low(&self, parent: Parent<ShopClient>, under: u32) -> Vec<Item> {
        parent.items().collect::<Vec<_>>().await … // needs: [shop.items]
    }
}

The client runs over a ParentTransport: the mount’s connection back to the service (NEST-11’s host()) when the child runs behind a mount, or the service’s own routing when it is registered in the same process. Either way each call is the original caller’s, through the service’s gate.

What the child calls of its parent is its schema’s needs (Need), which the macro infers from the method bodies. Three places hold to it:

  • the graft — mounting the child (a static --child, plexus-dyn’s connect/grow, ServiceRoot::insert) checks each need against the service’s own schema by the method’s shape hash, refusing with every missing or changed method named (NeedsMiss);
  • the host — a call the child makes up that is neither the standard upward interface (STANDARD) nor a need is refused, typed (forbidden, reason not_needed), and a need is routed with one more ceiling layer, its own grant (TM-1, DYNAUTH-4);
  • the client — ParentTransport refuses the same before sending.

Structs§

NeedsMiss
Why a graft was refused: what the child needs that the service does not serve, or serves in another shape.
Notice
What a child said to its service through host.notify.
Parent
The parent’s client, injected into a graft’s method: parent: Parent<ShopClient> (the macro writes the transport, ShopClient<ParentTransport>). It derefs to the client, so parent.items() is the parent’s items; Parent::host is the standard upward interface.
ParentTransport
A Transport to the service a graft is mounted in, for the methods it needs and the standard upward interface alone.
Upward
The standard upward interface (D10), every child’s: Parent::host.
UpwardError
Why an upward call through Upward failed.

Constants§

HOST_LOG
host.log { level, message }: a line in the service’s log.
HOST_NOTIFY
host.notify { topic, data }: a message to the service (DynamicHub::notices).
HOST_SCHEMA
host.schema: the service’s whole description (also any <path>.schema).
HOST_WHOAMI
host.whoami: whom the call the child is serving is for.
STANDARD
D10: the standard upward interface — what every child may call of its service, with no declaration. Every other upward call is a Need.

Functions§

check_needs
Check needs against what a service serves: served(path) is the shape hash of the method at path (empty: served, its shape unknown — below an untyped slot), None when it serves none there. An empty need hash checks presence alone.
is_standard
Whether method is one of the STANDARD four, or a schema read (<path>.schema, which host.schema stands for).
not_needed
The refusal of an upward call outside the standard interface and the child’s needs.