plexus-core 0.11.2

Core infrastructure for Plexus RPC: Activation trait, DynamicHub, schemas
Documentation
# 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**: `Plexus` has been renamed to `DynamicHub` to clarify that it's an activation with dynamic registration, not special infrastructure. The `Plexus` type 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:

```rust
use plexus_core::activations::echo::Echo;
use std::sync::Arc;

// Single activation - no DynamicHub needed
let echo = Arc::new(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:

```rust
use plexus_core::plexus::DynamicHub;
use plexus_core::{Activation, PlexusError};
use std::sync::Arc;

// Create a dynamic hub with explicit namespace and register your activations
let hub = Arc::new(
    DynamicHub::new("myapp")
        .register(MyActivation::new())
        .register(AnotherActivation::new())
);

// Route calls to activations
let stream = hub.route("myactivation.method", json!({})).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()`.

```rust
let service = Arc::new(DynamicHub::new("svc"));               // no activations yet
let root = service.root();
root.insert(Weather)?;                                       // svc weather forecast — now
let peer = root.peer("weather").await?;                      // the primitive: a Box<dyn Peer>
root.insert_peer("sky", Arc::new(Weather) as Arc<dyn Peer>, false)?; // any Peer, under its own name
root.remove("weather");
```

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"). The `Plexus` type alias still works but is deprecated.

## Creating Activations

Use the `plexus-macros` crate to generate activation implementations:

```rust
use async_stream::stream;

#[derive(Clone)]
pub struct MyApp;

#[plexus_macros::activation(
    namespace = "myapp",
    version = "1.0.0",
    description = "My application"
)]
impl MyApp {
    /// Say hello
    #[plexus_macros::method]
    async fn hello(&self, name: String) -> impl Stream<Item = MyEvent> + Send + 'static {
        stream! {
            yield MyEvent::Greeting { message: format!("Hello, {}!", name) };
        }
    }
}
```

## MCP

plexus-core has no MCP code and no rmcp dependency. To serve a service over MCP, use [plexus-transport](https://github.com/hypermemetic-ai/plexus-transport) with its `mcp` feature, or run [plexus-transport-mcp](https://github.com/hypermemetic-ai/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

```rust
// Solar is a hub activation with hardcoded children
let solar = Arc::new(Solar::new());
// Supports: solar.mercury.info, solar.earth.luna.info

// DynamicHub is a hub activation with dynamic children
let hub = Arc::new(
    DynamicHub::new("app")
        .register(solar)
        .register(echo)
);
// 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:

```rust
// Good: Direct hosting for single Plexus RPC service
let my_service = Arc::new(MyService::new());
TransportServer::builder(my_service, converter).serve().await?;

// Unnecessary: DynamicHub for single service
let hub = Arc::new(DynamicHub::new("app").register(MyService::new()));
TransportServer::builder(hub, converter).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):

1. A child with a key, or verifying tokens addressed to a key, is served
   only by `serve_child_proven`, which takes a `Proven` — a type with no
   constructor from a string, made only by `KeyedUpgrade::verify` checking
   the upgrade's `plexus-key.` proof (`serve_child_ws` does it) — and is
   believed from that principal alone. `serve_child_with` refuses one,
   whatever `ChildPeer` it is given.
2. A keyless, non-verifying child (`serve_child_with`) believes every
   sender its `ChildPeer` takes. Served as `ChildPeer::Pipe` on 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 with
   `serve_child_ws`. On `ChildPeer::connection` the sender is the string it
   was given, which proves nothing by itself.
3. With a verifier, the hop's token must verify: an EdDSA JWS signed by a trusted
   JWKS key (`iss` = `kid`), `aud` this child, within its times, naming
   `hop.call` and M, its `sub` the hop's caller, its scope holding the
   hop's grant on every scope the hop says.
4. And its sender must be proven by `hop.proof` over (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
   sender `ChildPeer` takes; 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's `jti` spent (once).
5. 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`):

1. It dials with its own key proof on the upgrade (`ChildOptions::key`;
   plexus-dyn: `<data_dir>/dial.key` by default), so its principal is the
   `key:` the peer's transport proves.
2. It asks `_info {nonce, asker}`; a peer that names a key must prove it
   with `plexus-peer-key/v2` over (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.
3. 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.
4. 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`).
5. 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