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.
License
AGPL-3.0-only