plexus-core
Core infrastructure for building Plexus RPC services with optional dynamic routing.
Overview
plexus-core provides the foundation for building Plexus RPC services with hierarchical routing and schema introspection:
- Activation - Trait for implementing Plexus RPC services/plugins
- DynamicHub - Optional routing layer for hosting multiple activations under one namespace
- Handle - Typed references to plugin method results
- plexus-macros - Procedural macro for generating activation boilerplate
Key Insight: Any activation can be hosted directly as a Plexus RPC server. DynamicHub is just an activation with
.register()- it's not required infrastructure.
Note:
Plexushas been renamed toDynamicHubto clarify that it's an activation with dynamic registration, not special infrastructure. ThePlexustype alias remains for backwards compatibility but is deprecated.
Quick Start
Single Activation (Direct Hosting)
For a single Plexus RPC service, host it directly without DynamicHub:
use Echo;
use Arc;
// Single activation - no DynamicHub needed
let echo = new;
// Use with plexus-transport or your own Plexus RPC server
Multiple Activations (Composition)
For composing multiple Plexus RPC activations under one namespace, use DynamicHub:
use DynamicHub;
use ;
use Arc;
// Create a dynamic hub with explicit namespace and register your activations
let hub = new;
// Route calls to activations
let stream = hub.route.await?;
When to use DynamicHub: Only when you need to compose multiple top-level activations. For a single service, host the activation directly.
The service root: a top level that grows while it serves
Underneath the builder, a service's top level is one table of peers
answered by peer(name) (NEST-15): .register(x) and --child add an
entry at build; hub.root() reads and changes the table while the service
serves. Routing, the grant gate's index, <service>.schema / .hash /
.ir and the schema's children all read it; a change moves the
service's hash and is said on root().watch().
let service = new; // no activations yet
let root = service.root;
root.insert?; // svc weather forecast — now
let peer = root.peer.await?; // the primitive: a Box<dyn Peer>
root.insert_peer?; // any Peer, under its own name
root.remove;
An entry added at runtime is reached through <service>.call (what
synapse and the clients send); only entries registered at build also get
direct <ns>.<method> RPC names on a service without a grant gate. The
gate admits it as any activation: by the roles that list its grants.
Migration Note:
DynamicHub::new()now requires an explicit namespace. Choose a namespace that identifies your application (e.g., "myapp", "substrate", "hub"). ThePlexustype alias still works but is deprecated.
Creating Activations
Use the plexus-macros crate to generate activation implementations:
use stream;
;
MCP
plexus-core has no MCP code and no rmcp dependency. To serve a service over MCP, use plexus-transport with its mcp feature, or run plexus-transport-mcp beside it.
Architecture Patterns
Hub Activations
Any Plexus RPC activation can route to children by implementing ChildRouter. This enables nested method routing without DynamicHub:
- Solar - Routes to planets (hardcoded children)
- DynamicHub - Routes to registered activations (dynamic children via
.register()) - Your custom hub - Can route to any children you define
// Solar is a hub activation with hardcoded children
let solar = new;
// Supports: solar.mercury.info, solar.earth.luna.info
// DynamicHub is a hub activation with dynamic children
let hub = new;
// Supports: app.solar.mercury.info, app.echo.echo
When to Use DynamicHub
Use DynamicHub when:
- You need to compose multiple top-level Plexus RPC activations
- You want dynamic registration (add activations at runtime)
- You're building a multi-service Plexus RPC server (like substrate)
Don't use DynamicHub when:
- You have a single Plexus RPC service (host it directly)
- Your activation already routes to children (like Solar)
- You want a simpler deployment
Direct Activation Hosting
The recommended pattern for single Plexus RPC services is direct hosting:
// Good: Direct hosting for single Plexus RPC service
let my_service = new;
builder.serve.await?;
// Unnecessary: DynamicHub for single service
let hub = new;
builder.serve.await?;
Example Activations
plexus-core includes two minimal example activations:
- health - Health check endpoint (manual Activation impl)
- echo - Echo messages back (plexus-macros generated)
See src/activations/ for implementation examples.
The rules a keyed peer and its service apply (KEEL-19)
What the code checks, in order — the text a change to remote_child or
peer_token is checked against.
Before a peer runs a hop ({ns}.call for method M; a schema call needs
none of this):
- A child with a key, or verifying tokens addressed to a key, is served
only by
serve_child_proven, which takes aProven— a type with no constructor from a string, made only byKeyedUpgrade::verifychecking the upgrade'splexus-key.proof (serve_child_wsdoes it) — and is believed from that principal alone.serve_child_withrefuses one, whateverChildPeerit is given. - A keyless, non-verifying child (
serve_child_with) believes every sender itsChildPeertakes. Served asChildPeer::Pipeon a WebSocket, it believes every sender who can reach that socket, as whoever the frame claims to be. Do not do this: a keyless child belongs on its parent's stdin/stdout or a socket only that parent can open; a child reachable over a network has a key and is served withserve_child_ws. OnChildPeer::connectionthe sender is the string it was given, which proves nothing by itself. - With a verifier, the hop's token must verify: an EdDSA JWS signed by a trusted
JWKS key (
iss=kid),audthis child, within its times, naminghop.calland M, itssubthe hop's caller, its scope holding the hop's grant on every scope the hop says. - And its sender must be proven by
hop.proofover (token, M,hop.call): a token bound to this child's own key (or, to a pipe, to none) is the service's forward — the proof by its issuer key, and on a connection a senderChildPeertakes; a token bound to another key is an exchanged one — the proof by that key, over a connection proven as it, which the hop names. Only then is the token'sjtispent (once). - Then the far side's own check (the hop's grant is M or M's slot) and M runs as the hop's caller, within the scopes the hop says.
Before a service mounts a keyed peer (RemoteChild::connect):
- It dials with its own key proof on the upgrade (
ChildOptions::key; plexus-dyn:<data_dir>/dial.keyby default), so its principal is thekey:the peer's transport proves. - It asks
_info {nonce, asker}; a peer that names a key must prove it withplexus-peer-key/v2over (nonce, backend, the asker its connection proved), checked against the service's own principal — refused when that principal is not a key (keyed_mount_needs_a_key) or the proof was made for anyone else. - The key is pinned with the peer's identity: a remount proving another
is refused (
identity_changed); plexus-dyn refuses a key another peer holds, mounted or pinned (identity_changed,key_in_use:), checked where the entry is reserved. - Tokens are minted for that key only while it is mounted and not
revoked — asked at the top of each forward and again, after the dial
it may await, where the token is minted and where its call back is
opened — by a service whose principal is a key; each forwarded hop
carries the service's proof (
TokenIssuer::prove_forward). - An exchange (
dyn.exchange) is decided as a call back is: the presenter mounted, not revoked, holding a consented need for the audience and the method, within the consent of now; once per (jti, audience, method); the token bound to the presenter's key.
Replay: an upgrade's key proof is taken once while its 60 s window lasts,
and a token's jti once while it lives. KeyedUpgrade holds at most 4096
proofs (UPGRADE_LEDGER_MAX); full, it refuses a new upgrade — never
forgets a proof early — until proofs leave their window: the dialer gets
HTTP 401 with this child holds 4096 key proofs in their 60 s window: a new upgrade is refused until some expire, and the child logs a warning on
target plexus::audit (child upgrade ledger full, with the count held
and refused) at most once per 10 s. So at most 4096 upgrades a minute are
taken per child (about 68 a second, sustained); a flood can deny upgrades
for a minute, never replay one. Both are kept in memory: a restarted child
forgets, so a proof or token captured in the 60 s before a restart can be
replayed to it once after it (a token only while it lives, at most its
exp).
Key files and the data directory are the user's own, 0600 and 0700, never read through a symbolic link.
A child dial's key proof is spec/00's one form, signed as the reserved agent
plexus.child-dial (CHILD_DIAL_AGENT; agent is in the signed bytes): a
child takes only that agent, so a sign-in proof replayed to a child at
the same URL is refused. A server's sign-in (plexus-auth-core's
KeyProofAdapter) takes a dial proof as the dialing key's sign-in, by
design: a dial proof is addressed to the dialed URL and usable only there,
and it is how a service mounts another service behind key sign-in
(--child far=wss://…, dyn.connect). A context of its own would be a
plexus-wire spec/00 change, not made.
License
AGPL-3.0-only