plexus-macros
Procedural macros for Plexus RPC activations. The macros are the source of truth for the client generation pipeline: your Rust function signature is the schema.
Versions: use plexus-macros and plexus-core from the same minor line (0.7 with 0.7). The macro emits paths into plexus-core but cannot depend on it, so cargo cannot enforce the pairing from this side; plexus-core requires plexus-macros on its own line and re-exports activation and method.
Overview: macros → schema → clients
#[plexus_macros::activation] Rust macros (this crate)
↓ schemars::schema_for!() + MethodRole / DeprecationInfo metadata
PluginSchema (serde JSON, pinned in plexus-core)
↓ Synapse (Haskell) fetches over Plexus RPC
Synapse IR (deduplicated, compiler-ready)
↓ plexus-codegen-{rust,typescript,python}
Client libraries (type-safe, documented, deprecation-aware)
Everything downstream — generated clients, OpenAPI docs, deprecation warnings in TypeScript IDEs — is derived from what #[plexus_macros::activation] emits into PluginSchema. Do not hand-write schemas; the macro owns them.
For Rust consumers there is a shorter path: the macro emits the client itself.
#[plexus_macros::activation(client)] // impl Tickets — namespace "tickets", implicitly
↓ same expansion, same information
TicketsClient<T: plexus_client::Transport> ← typed params, each method's precise item
TicketsEvent ← the activation's aggregate, one variant per method
The Synapse → IR → codegen pipeline above stays the path for TypeScript, Python and everything non-Rust. See The typed client.
Documentation is primary: /// everywhere
/// doc comments are the primary source of every description that reaches the wire. The macros extract them at expansion time and emit them into PluginSchema. Generated clients (TypeScript, Rust, Python) render them as TSDoc / rustdoc / docstrings. Synapse shows them in the CLI tree.
Where you write /// |
Where it appears on the wire |
|---|---|
On the impl block annotated with #[plexus_macros::activation] |
PluginSchema.description |
On each #[plexus_macros::method] fn |
MethodSchema.description |
On each #[plexus_macros::child] fn |
MethodSchema.description (role: StaticChild / DynamicChild) |
On a struct / enum that derives JsonSchema |
JSON Schema description for that type |
| On a field of such a struct | JSON Schema description for that field |
| On an enum variant | JSON Schema description for that variant |
Parameters are the only exception — individual parameter descriptions must use the params(name = "...", other = "...") attr on #[plexus_macros::method] (Rust has no per-argument doc-comment syntax).
Precedence — if both an explicit attr arg and a /// doc comment are present, the explicit attr arg wins. In practice, prefer ///; reach for the attr arg only when you need to diverge (e.g., a deliberately terser wire description than the internal Rust docs).
A method's return type is its contract (0.7)
Write the narrowest signature that tells the truth; the macro reads everything else from it — cardinality, item, error and progress — and never needs a flag to know what a method does.
// namespace "tickets", implicitly
The full table — schema fields and the frames each item becomes — is in the
per-macro reference. Progress and Note are
plexus_client::{Progress, Note} (re-exported as plexus_core::plexus::{Progress, Note}).
Minimal example — best practices
The smallest realistic activation. Uses /// for every description, has one method with a params(...) attr, and exposes a static #[plexus_macros::child] into a nested namespace. No description = "..." attr args anywhere — the macros pick up doc comments automatically.
use stream;
use Stream;
use JsonSchema;
use ;
/// A message echoed back to the caller.
/// Echo service — returns messages verbatim and exposes a nested `stats` child.
;
/// Echo messages back verbatim; nested `stats` child exposes call introspection.
// namespace "echo", implicitly
/// Call-count introspection for the `echo` service.
;
/// Introspection for the Echo service — invocation counts and timing.
What this demonstrates:
///on theimplblock (line with#[plexus_macros::activation]) suppliesPluginSchema.description. Nodescription = "..."attr arg needed.///on each method fn suppliesMethodSchema.description. Again, nodescription = "..."attr arg.params(message = "...")is the only way to document individual params — Rust has no per-argument doc-comment syntax.#[plexus_macros::child]on a zero-arg accessor fn creates a static child namespace.synapse lforge echo stats totalroutes into the nested activation.- Stream item type derives
JsonSchema, so its variant and field///doc comments flow through to the wire. - The namespace is implicit for
Echo(echo);EchoStatsnames its own (stats) because its implicit one would beecho_stats. totalreturns a plainu64— one item, so one data frame;echoreturns a stream — many.
Synapse invocations:
Upgrade path from this minimal form: add params(...) as more methods gain documented params; add more #[plexus_macros::child] accessors for nested namespaces; introduce #[derive(PlexusRequest)] + request = ... once you need auth / cookies / per-request context; add #[deprecated] + #[plexus_macros::removed_in] when rotating methods. Each of those is covered in the comprehensive example below.
Comprehensive example
A single realistic activation that exercises every macro in the crate. Every attribute shown is supported on 0.8. Features that are less common are called out inline.
The example below uses several
description = "..."attr args explicitly — partly for readability in a reference doc, partly because the comprehensive activation description is the easier way to show thelong_descriptioncompanion. In your own code prefer///doc comments per the Documentation is primary section above.
use stream;
use Stream;
use ;
use JsonSchema;
use ;
use Arc;
// -------------------------------------------------------------------
// 1. Stream item type — a plain domain enum.
// The caller-wraps streaming architecture means you do NOT need a
// `StreamEvent` derive. Standard serde + JsonSchema is enough.
// -------------------------------------------------------------------
// -------------------------------------------------------------------
// 2. Typed handles — generated by `#[derive(HandleEnum)]`.
// Handles are opaque strings on the wire; this derive makes them
// typed on the Rust side. `plugin_id_type` pins the instantiation
// when the owning activation is generic (IR-21).
// -------------------------------------------------------------------
// -------------------------------------------------------------------
// 3. Typed request — generated by `#[derive(PlexusRequest)]`.
// This struct describes the per-request HTTP context: cookies,
// headers, query params, peer address, auth context. The
// activation-level `request = CounterRequest` attr below wires it
// into the dispatch path; fields become injectable via
// `#[activation_param]` on method parameters.
// -------------------------------------------------------------------
// -------------------------------------------------------------------
// 4. The activation itself.
// -------------------------------------------------------------------
; // stand-in for the child activation
;
The example above is the full attribute surface of plexus-macros 0.8 (the six return-type forms are in the per-macro reference). Real activations typically use a subset — see plexus-substrate for concrete, minimally-documented usage (echo and bash are the smallest; cone, claudecode, and solar exercise children, handles, and generics).
Request forwarding: PlexusRequest + request = ...
A typed view of an inbound HTTP request. Without it, your method sees only the RPC arguments; with it, you get cookies / headers / query params / peer address / auth context as first-class Rust fields — extracted, validated, and type-checked at dispatch time.
What it is
plexus_core::request::PlexusRequest is a trait implemented by #[derive(PlexusRequest)]. It has two methods:
RawRequestContext is the raw inputs — http::HeaderMap, Uri, optional AuthContext, optional SocketAddr. The derive generates both extract (run per-call by the dispatch code) and request_schema (included in the activation's PluginSchema with x-plexus-source hints).
Why it exists
Auth tokens live in cookies. CSRF checks need the Origin header. Tenancy lives in query strings. Per-peer rate limits need the socket address. Before PlexusRequest, every activation had to hand-parse this out of a RawRequestContext — boilerplate, inconsistent errors, no schema. With the derive:
- Typed extraction: one
#[from_cookie("...")]replaces several lines of header parsing. - Consistent errors: missing required fields return
PlexusError::Unauthenticated. - Schema metadata: generated clients know which inputs come from cookies vs. body.
- Composition: the same struct is reused across every method of the activation.
Field attributes
| Attribute | Source | Required? | Notes |
|---|---|---|---|
#[from_cookie("name")] |
Named Cookie header value |
Non-Option → required (401 if missing) |
Multi-value cookie headers are parsed correctly. |
#[from_header("name")] |
Named HTTP header | Non-Option → required |
Case-insensitive per http crate. |
#[from_query("name")] |
Named URI query parameter | Non-Option → required |
Uses form_urlencoded::parse. |
#[from_peer] |
ctx.peer (socket addr) |
Option<SocketAddr> recommended |
Transports without peer addr → None. |
#[from_auth_context] |
ctx.auth (AuthContext) |
Option<AuthContext> recommended |
Populated by auth middleware. |
| (no attribute) | PlexusRequestField::extract_from_raw |
Defined by the field type | Use for newtypes like ValidOrigin. |
Option<T> fields treat "absent" as None and never fail; non-Option fields return PlexusError::Unauthenticated on missing input. Parse failures (e.g. a cookie value that cannot parse into the declared type) also return Unauthenticated.
Wiring it into an activation
The activation attribute takes a request = <Type> argument:
Two ways to consume the extracted fields in methods:
-
#[activation_param]— the named parameter is pulled from the request struct by field name. The Rust type must match the declared field type (the macro enforces this):async + Send + 'static -
#[from_auth(expr)]— runs an arbitrary resolver expression against the extracted auth context. Useful when you want a validated user type, not raw auth:async + Send + 'staticThe resolver's error decides the refusal (MACRO-14). A resolver returning
Result<_, PlexusError>is answered with that error unchanged —Forbidden { MissingGrant { … } }reaches the wire as-32003witherror_kind: "forbidden"and itsgrant/scope/roles/held_on,Unauthenticatedas-32001— so a refusal stays typed. Any otherDisplayerror isExecutionError(e.to_string())(-32000).
To opt a method out of activation-level extraction (e.g. a public health probe), use request = ():
async + Send + 'static
Wire-level: x-plexus-source
The derive augments the generated JSON Schema with a non-standard x-plexus-source key on each property, so generated clients know which input channel to use:
End-to-end example
Given this activation:
A request:
POST /rpc HTTP/1.1
Cookie: access_token=eyJhbGci...
Origin: https://app.example.com
Content-Type: application/json
{ "method": "app.me", "params": {} }
is dispatched as:
- Transport builds a
RawRequestContextfrom headers + URI. - Dispatch calls
AppRequest::extract(&raw)→AppRequest { token: "eyJhbGci…", origin: Some("https://app.example.com") }. - The
tokenfield is threaded intomeas itstokenparameter. meruns; streamed output is serialised back over the transport.
When to use PlexusRequest vs. method params
Rule of thumb:
- Method params — per-call inputs that belong to the business logic:
item_id,query,body. PlexusRequest+#[activation_param]— per-request context that crosses every method: auth tokens, session cookies, tenancy, peer addr.
If a value would be the same for every method call in a request, it belongs in the request struct.
#[activation] needs nothing (MACRO-13, RETURNS-47)
The type names the namespace and the client — impl Tickets by itself,
impl TicketsActivation by its stem Tickets: namespace tickets, client
TicketsClient<T> — and a trait is emitted only when named. Descriptions
come from /// (and /** … */ before a parameter); plexus-core is found in
the manifest. Every key below is an override, and none is needed:
/// Tickets.
// emitted: the server half, `TicketsClient<T>` (`total()` answers
// `Result<u64, ClientError>`, `list()` a `MethodStream`), `TicketsEvent`. No trait.
A contract written by hand is served by implementing it (GRAFT-1's form):
// namespace "forge", `ForgeClient<T>`; the type names nothing.
| rule | |
|---|---|
| the name | impl Foo names itself; impl FooActivation its stem Foo; impl Trait for Type the trait. Namespace: the name in snake_case (TicketsApi → tickets_api); namespace = "…" overrides it. An activation written before MACRO-13 — a type not named …Activation that says its namespace — expands as it did (only #[method]s on the wire, the client on the client flag), with a deprecation warning |
| the trait every time | NEST-17 (owner, 2026-11-09, reversing RETURNS-47's "only when named"): impl Shop and impl ShopActivation emit trait ShopActivationSchema; trait = "Bar" renames it (and names the client BarClient and, absent namespace, the namespace bar); a contract is its trait (Foo). Each method under its own return type, boxed: -> T / -> Result<T, E> as BoxFuture<'static, …>, a stream form as BoxStream<'static, item> (RETURNS-36), with nothing the server injects. The activation implements it by cloning itself into each stream (the default trait only where the type is Clone: a type that is not gets the trait and no impl). A method that takes auth, reach or a #[from_auth] value reads it from the call's context in the trait form (plexus_core::call::caller(), as impl Trait for Type does): a caller required and missing is the method's error (E: From<PlexusError>, else E: From<PeerError> as forbidden), reach outside a call Reach::nowhere(), an optional auth None. An #[activation_param] is in no context, so an activation with one does not implement its trait; nor does a generic impl get the default trait |
impl Trait for Type |
every async fn on &self is a wire method, called as <Type as Trait>::m; the trait needs no object safety to be served. Its methods reach their caller through the call's context, plexus_core::call::caller() (a trait's signature cannot carry #[from_auth]). Under auth = "required" the dispatch refuses an anonymous caller before the body of every method not public, out of band and typed, as #[from_auth] does; #[plexus_macros::from_auth(self.access.verify)] on the method runs the verifier before the body (its error the call's typed refusal, its value the body's: plexus_core::call::verified::<User>()). It has no direct JSON-RPC methods, only {ns}.call. trait = "…" beside it, a bodiless method and #[child] are refused |
| wire methods | every pub async fn on &self returning impl Stream<Item = E>, no #[method] needed (it stays for its overrides, and marks a one-item method); a pub async fn on &self returning anything else unmarked is a compile error; methods = marked restores the #[method]-only rule |
served = written |
KEEL-27, opt-in per block: an unmarked fn is what its signature says. Not pub, or not on &self (new): a helper. pub fn x(&self) -> A: a mount; pub fn x(&self, name: &str) -> Option<A>: a slot — each checked by the compiler (A: ChildRouter), a wrong type refused at the return type, naming the fn and what a mount returns. pub async fn x(&self, name: &str) -> Result<Box<dyn I>, PeerError>: a fallible mount (#[peer]). Any other pub async fn on &self: a method, one item or a stream (a bare #[method]). A marked fn is what its marker says; what no signature carries keeps the marker: #[method(…)]'s options, #[child(list, search, forward, opaque)], a mount behind a type alias, a private served fn. Refused with methods = marked and on impl Trait for Type |
| the client | emitted whenever the crate depends on plexus-client, no flag (client is accepted with a deprecation warning). A one-item method answers Result<T, ClientError>, a many-item one its {Ns}{Method}Stream; no item type needs FromClientError, so -> u64, -> bool, -> Vec<T> are methods like any other (RETURNS-47, superseding RETURNS-43). NEST-17: when every method answers one Result<T, E> with E: From<PeerError>, the client implements the activation's trait as well (a call failing in transit is E::from(PeerError)), so Box<dyn ShopActivationSchema> is a local shop or a remote one |
the server feature |
a crate whose manifest declares server gets the server half under #[cfg(feature = "server")]; server_cfg overrides; the trait and the client are never gated |
| a contract | every wire method bodiless (pub async fn f(&self) -> impl Stream<…>;) and no struct written, on impl FooActivation (trait Foo) or with trait = "…": the macro emits pub struct FooActivation<D: Foo>(Arc<D>), delegating, and Foo::server(self), so service.register(Local::new().server()) serves an implementation. A remote one is its client become a peer (FooClient::peer(transport), NEST-7), which implements Foo when every method answers one Result<T, E>. A mix of bodied and bodiless is refused at the first bodiless method |
The typed client (client + server_cfg)
The macro sees every method's wire name, its parameters and its precise
contract — cardinality, item, error, progress — at the moment it runs. With
the client flag it emits a typed client from that same information, and
the activation's aggregate event type, so a Rust consumer never
hand-writes a call site or hand-mirrors an item type.
// namespace "tickets", implicitly
emits, beside the activation's own items:
// L: RETURNS-46, the lift .events() applies
Requires the consuming crate to depend on
plexus-client — the wasm-safe runtime the emitted code
links against (and derives the aggregate through, so nothing else is needed
in Cargo.toml). A missing dependency is reported at the client flag, not
as an unresolved import in code you did not write.
What you get
| method form (server) | client method | yields |
|---|---|---|
one: -> T / -> Result<T, E> |
async fn m(&self, ..) -> Result<I, ClientError> |
I = T / Result<T, E> |
many: -> impl Stream<Item = …> |
fn m(&self, ..) -> MethodStream<'_, I, P, {Ns}Event> |
Result<I, ClientError>; progress frames dropped undecoded |
.with_progress() on a many call |
— | Result<Frame<I, P>, ClientError>, in arrival order |
.events() on a many call |
— | Result<{Ns}Event, ClientError>, {Ns}Event::M(item) |
I is the method's item: T, or Result<T, E> decoded from its
{"ok"} / {"err"} wire form. P is its progress type — Note for
Progress<T>, the declared P for Progress<T, P>, and the uninhabited
NoProgress when the item is not a Progress (so .with_progress() exists
on every many call and never yields progress the schema does not declare).
A one-item method never reports progress, so it has no stream to opt in on.
The one rule for a receiver: ? is the call failing; a match on the item
is the activation's answer (RETURNS-1 decision 8):
match client.get.await?
let rows: = client.list.try_collect.await?; // a plain TryStream
let mut s = client.import.with_progress; // opted in
while let Some = s.next.await
let mut all = select_all;
while let Some = all.next.await // ev: TicketsEvent
| Typed params | the method's own parameter types, in signature order. #[activation_param], #[from_auth] and auth: params are absent — the server injects those. Option params that are None are omitted, not sent as null. |
| Precise items | each method's own item type — not a shared enum, not a copy. A Result method's err is a value (Ok(Err(e)) in a stream) and does not end it. |
| Typed call failures | ClientError::Remote(RemoteError) — the server's error frame, kind-tagged and exhaustive (method_not_found, invalid_params { param, problem }, unauthenticated, forbidden { reason }, …) — vs ClientError::Transport (the connection failed), Decode (the answer does not fit the contract) and Encode (an argument would not serialize; nothing was sent). A failed call is an item of the stream, so a cut-off stream cannot pass for a finished one. |
| The aggregate | {Ns}Event: one variant per method, named Pascal(method), tagged with the wire name, carrying the item; then one per #[child], carrying the child's own aggregate (RETURNS-46, below). Derived, never sent. Every .events() has the same type, so merging calls is ordinary stream plumbing. |
| Transport-generic | any plexus_client::Transport — in-process, WebSocket JSON-RPC, REST + SSE. The emitted code names none of them. |
| Two error layers | ClientError::Transport (the connection failed) vs ClientError::Remote(RemoteError) (the server answered with a typed error frame). An activation's own Err item stays data. |
| Zero drift | rename a field on an item type and every consumer of the client stops compiling. |
| Children (MACRO-16, RETURNS-46) | a static #[child] fn inputs(&self) -> Inputs gives the parent's client fn inputs(&self) -> InputsClient<&T, Static<L, __TicketsClientInputs>>, whose calls go to tickets.inputs.<method>, the path the service routes. A dynamic #[child] fn item(&self, name: &str) -> Option<Item> gives fn item(&self, name: &str) -> ItemClient<&T, Named<L, ItemEvent, TicketsEvent>>, whose calls go to tickets.<name>.<method>. #[child(opaque)] and a #[peer] slot: the untyped and peer accessors below (NEST-14). Accessors nest, so client.inputs().history().tail(..) goes to tickets.inputs.history.tail. The child must have a client too, or InputsClient does not resolve at the accessor's return type. InputsClient::new(t) alone still sends inputs.<method>; InputsClient::at(t, "tickets.inputs") mounts it by hand; both yield the child's own aggregate. |
The aggregate up the tree (RETURNS-46)
An activation's aggregate nests its children's, at every level:
// one per static child
{"method":"branch","event":{"method":"leaf","event":{"method":"fall","event":{"leaf":1}}}}
{"method":"item","event":{"name":"a","event":{"method":"watch","event":{"seen":"a","n":1}}}}
A static child's variant is tagged with its route segment; a dynamic
child's with the child method's name, its content {name, event}, the
instance's name beside its event. A child's aggregate is named through its
client (<BranchClient<()> as plexus_client::Aggregated>::Event), the rule
the accessor names the client by, so a child whose namespace is not its stem
is found all the same.
A dynamic child's event is boxed; a static child's is not. Every cycle
a service can serve passes through a dynamic child — a cycle of static
children is a tree with no bottom, whose schema the service never finishes
describing — so boxing the dynamic variant breaks every cycle (ping with
the static child pong, pong with the dynamic child ping), and a static
level costs no allocation. A child that is the activation itself (-> Self,
-> Option<Self>, its own name) is boxed too.
A client reached through a parent's accessor yields the parent's
aggregate. Every client is XClient<T, L = plexus_client::Root>; L is
its lift, a type: Root (nothing), Static (the parent's lift and a
zero-sized Wrap, the variant) or Named (the instance's name too, an
Arc<str> every event shares). A many-item method's stream names its
variant as a zero-sized EventOf too (MethodStream<'_, I, P, XEvent, L, __XClientM>), so the variant and the lift inline into one step per event:
a static level costs what the level's own client does. Each many-item
method's stream has a name to hold it by, {Ns}{Method}Stream<'a, L = Root>
(TreeCountStream<'a>, BranchGrowStream<'a, L>; {Ns}{Method}MethodStream
when an item type already has that name), and the method returns it. One listener over a subtree is one select_all,
matched with no wildcard:
let tree = new;
let = ;
let leaf = branch.leaf;
let mut all = select_all;
while let Some = all.next.await
A child's own client (BranchClient::at(t, "tree.branch")) yields
BranchEvent, and lifts one level with TreeEvent::from. No From is
emitted for a dynamic child (the variant needs the name), for two static
children of one type (which variant?), or for a child that is the activation
itself.
Instance names. tree.item(name) reaches tree.<name>; a dynamic
instance's path is the client's own (RoutePath, an Arc<str>), freed with
it — no process-wide set, no lock. A name that cannot reach the instance —
empty, holding a ., outside the service's path grammar ([a-z][a-z0-9_]*),
a static child's segment — does not fail the accessor; every call through
it, and through anything below it, fails at once with
ClientError::InvalidName { name, reason }, and nothing is sent. A name
that is one of the parent's methods is the instance: the service takes the
segment after the parent as a child. The static siblings checked are the
ones this client was built against: a sibling a newer service adds is not
known to an older client, whose instance of that name the service routes to
the new sibling.
#[child(opaque)] — a child whose type has no client (a hand-written
ChildRouter, an activation without one): no variant, routed as before,
and (NEST-14) an untyped accessor — fn raw(&self) -> Untyped<&T> at
<path>.raw, a dynamic one fn item(&self, name: &str) -> Untyped<&T> at
<path>.<name>. A child of a client activation without a client and without
opaque is a compile error that says so.
Peer slots and the untyped client (NEST-14). One client reaches every node of the tree:
| child | accessor |
|---|---|
static #[child] fn x(&self) -> X |
x() → XClient<&T, Static<…>> |
dynamic #[child] fn x(&self, name) -> Option<X> |
x(name) → XClient<&T, Named<…>> |
typed #[peer] async fn x(&self, name) -> Result<Box<dyn forge::ForgePeer>, PeerError> |
async x(name) → Result<forge::ForgeClient<PeerTransport<T>>, PeerError> at <path>.x.<name>: the contract's client become a peer (ForgeClient::peer_at), its interface checked against the client's stamp — ShapeMismatch when a method it calls moved. Needs T: Clone + Send + Sync + 'static; emitted in the server half (the stamp is plexus-core's) |
untyped #[peer] async fn x(&self, name) -> Result<Box<dyn Peer>, PeerError> |
x(name) → Untyped<&T> at <path>.x.<name> |
#[child(opaque)] |
x() / x(name) → Untyped<&T> |
plexus_client::Untyped<T> is a transport and a dotted path, for a node
whose interface is not known when the program is written: call(method, params) → MethodStream<'_, Value>, call_one(method, params),
child(name) / into_child(name) one level down, schema(), and
typed::<XClient<_>>() — the node's schema checked against XClient's
methods by their shape hashes (NEST-7's Interface): every method the client
calls served under the same shape (a node that serves more is fine), else
ClientError::ShapeMismatch { path, wanted, got, methods } and nothing else
is called. typed_unchecked() skips the check (a client-only build, whose
clients have no ShapeCheck). Every generated client implements
plexus_client::FromRoute<T>, and — in the server half — ShapeCheck.
An untyped node's items are serde_json::Values and lift into no parent's
aggregate. It works over every Transport: a socket, HubTransport, a
host's transport handed to a child.
let shop: = dyn_client.peer.typed.await?;
let gh = host.integration.await?; // forge::ForgeClient<PeerTransport<T>>
let repos = repos.await?;
``` A method whose wire name is a
child's segment is refused: they share one route namespace and one tag.
`fixtures/aggregate-tree` holds the JSON at every level;
`fixtures/aggregate-probe` the shapes the tree must survive.
A one-item call reads the call to its `done` before it returns, so a
transport that cancels a dropped call never
cancels one that finished; no item, or a second one, is a `Decode` error.
The aggregate derives `Debug` and `Clone`, so every item type of a `client`
activation implements both. **A crate that already has a type named
`Event`** — the hand-written shared
A consumer then needs one dependency line:
= { = "0.1", = false }
and gets the types and the client with no tokio, jsonrpsee or plexus-core anywhere in its tree. Gating your own struct definition and server-only imports is still yours to do — the macro only gates its own output.
Worked end to end in fixtures/tickets-api (the
activation) and
fixtures/tickets-wasm-consumer (a
consumer with no wire code of its own). Both build for
wasm32-unknown-unknown.
Transports
| Transport | Where | Status |
|---|---|---|
MemoryTransport |
plexus-client |
scripted test double; wasm-safe by construction |
InProcessTransport |
plexus-core (plexus::in_process) |
drives an Activation directly — no server; a call it cannot dispatch is the typed error frame a service would send |
WsTransport |
plexus-client, feature ws-native / ws-web |
WebSocket JSON-RPC; one connection, subscriptions multiplexed |
| REST + SSE | — | not yet built |
WsTransport::connect(url, hub_namespace) is the wire transport, and the
only one that carries the full StreamMetadata. It is behind a feature
so that plexus-client's default stays the four-dependency wasm-clean core:
ws-native builds on tokio-tungstenite, ws-web on web_sys::WebSocket,
and both expose the same type and the same constructor — a consumer picks
the backend in Cargo.toml and changes no code. The protocol itself (ids,
routing, cancellation, both frame shapes) is written once and shared, so the
backends cannot drift.
let transport = connect.await?;
let tickets = new; // …and reuse it for every activation
hub_namespace is the server's DynamicHub::new(ns) namespace, not an
activation namespace: the same tickets.list goes to menger.call on one
deployment and to another hub's call elsewhere. Worked end to end against a
real server by menger itself: its tickets activation carries client and
server_cfg, the browser app takes the crate with default-features = false, and tests/wire_client.rs there drives the emitted TicketsClient
over WsTransport against the in-process server. (A client-only mirror of
menger's declarations lived under fixtures/ while menger was still on the
0.5 line; it is gone — one declaration, nothing to drift.)
Both flags are opt-in: an activation naming neither expands exactly as before.
A graft that knows its parent: parent = ShopClient (NEST-16)
An activation written to be grafted onto a service names that service's client, and a method takes it, injected by the server (not a param, not in its own client):
The macro reads the body: every call chain rooted at parent is a need
(parent.items() → shop.items, parent.ui().slots().list() →
shop.ui.slots.list), published as the schema's needs with each method's
shape hash. Applying the graft checks them against the service (a static
mount, ServiceRoot::insert, plexus-dyn's connect/grow), and the service lets
the child call back nothing else beyond host.schema, host.whoami,
host.log and host.notify. parent used other than as a chain's root is
a compile error at that use, unless the method lists what it calls:
#[plexus_macros::method(uses("shop.items"))].
Security model
This documents the actual generated behavior, not an aspiration. Read it before assuming a method is protected.
- Auth is fail-open by default. A method whose signature carries no auth signal — no
auth: &AuthContext, noauth: Option<&AuthContext>, no#[from_auth(...)]resolver — is generated with no auth check at all and is callable unauthenticated. The dispatch arm only injects an auth check when the method requested one (src/codegen/activation.rs, theauth_injectionlogic ingenerate_dispatch_arms). - Default activation posture is
Optional— it enforces nothing.auth = "required"is opt-in and is the only fail-closed posture. Even underrequired, a method declaringOption<&AuthContext>is downgraded to a warning (it still receivesNonerather than being rejected). - Roles, scopes, and credential metadata are schema metadata only. Declared roles/scopes and
#[credential(...)]clauses are reflected into the schema for clients and tooling. They are never enforced at dispatch — the framework does not check them before invoking your method. - A
#[from_auth(expr)]resolver must itself fail closed. The macro splicesexprverbatim into the dispatch arm and binds its result with?. It does not verify that the resolver actually denies unauthorized callers. If your resolver returnsOk(...)for an unauthenticated/under-privileged principal, the call proceeds. Enforcement is entirely the resolver's responsibility.
The practical consequence: authorization is opt-in, per-method, and only as strong as the code you write. The macro provides plumbing, not a policy.
Per-macro reference
#[plexus_macros::activation(...)]
Attached to an impl block to generate the activation's Activation trait impl, method enum, RPC trait, and (when #[child] methods are present) ChildRouter impl.
| Arg | Type | Default | Notes |
|---|---|---|---|
namespace = "..." |
string | the stem of impl FooActivation, snake_case |
Activation namespace. Appears as plugin_schema.namespace. MACRO-13: an override. |
trait = "..." |
string | {Name}ActivationSchema |
MACRO-13: names the trait and the client whatever the type is called. NEST-17: without it the trait is {Name}ActivationSchema (a contract's, its stem). |
methods = marked |
word | every pub async fn on &self returning a signature form |
MACRO-13: only #[method]s are on the wire. |
served = written |
word | (off) | KEEL-27: an unmarked fn is what its signature says — a method, a mount, a slot, a fallible mount or a helper (see the rules above). |
version = "..." |
string | CARGO_PKG_VERSION |
Semver; used by handles and deprecation schemas. |
description = "..." |
string | (none) | Max 15 words — macro errors on overflow. Use long_description for more. |
long_description = "..." |
string | (none) | Unbounded documentation; projected into PluginSchema. |
request = MyType |
type | (none) | Typed request struct; see the Request forwarding section. |
resolve_handle |
flag | (off) | Generates Activation::resolve_handle that delegates to self.resolve_handle_impl(handle). You implement the impl. |
crate_path = "..." |
string | auto (via proc-macro-crate) |
Override the plexus-core import path. Rarely needed after CHILD-6. |
plugin_id = "UUID" |
string | deterministic UUIDv5 from namespace | Explicit plugin UUID. Must parse as a UUID. |
namespace_fn = "method" |
string | (none) | Advanced: generate namespace() as a method call instead of a constant. |
client |
flag | (off) | Also emit the typed client — see The typed client. Requires a plexus-client dependency. MACRO-13: under the name rule the client is emitted whenever plexus-client is a dependency, and client is ignored with a deprecation warning. |
server_cfg = "<pred>" |
string | (none) | Compile the server half of the expansion only under that cfg (e.g. feature = "server"). Requires client (MACRO-13: not under the name rule, where feature = "server" is the default when the crate declares it). This is what makes an activation crate reachable from wasm32. |
typed_params |
flag | (off) | MACRO-12: a method parameter typed literally String, &str, Option<String>, Option<&str> or Vec<String> is a compile error on that parameter: `<method>.<param>`: a bare string parameter; give it a type (typed_params). Injected parameters (auth, reach, #[from_auth], #[activation_param]) are exempt. An alias (type Name = String) is not seen through. MACRO-31: and a key of the params object that names no wire parameter is refused at dispatch, before the method runs — -32602 invalid_params, Invalid params: unknown field `sumary`; tickets.list takes: after, limit, summary (every unknown key named, sorted; the parameters sorted; … takes no parameters for a method of none). unknown field is synapse's word for a stale cached schema (it re-reads the schema and runs the call again), so it is said verbatim. The method is named by its activation's own namespace (a child's, not the path it is mounted at). null, {} and a bare value are answered as before; keys inside a parameter's value are its type's serde's. Off by default for 0.7; on by default is MACRO-8's call. |
hub |
flag | (off, deprecated) | Deprecated — hub mode is inferred from #[child] methods. Still accepted in 0.7. |
children = [ident, ...] |
ident list | (empty, deprecated) | Deprecated — use #[child] methods. Still accepted in 0.7. |
#[plexus_macros::method(...)]
Attached to methods inside an #[activation] impl. Marks the method as an RPC endpoint and collects schema metadata.
| Arg | Type | Default | Notes |
|---|---|---|---|
description = "..." |
string | first /// doc-comment block (CHILD-5) |
Explicit arg wins over doc comments. |
name = "..." |
string | method identifier | Override the RPC name without renaming the Rust fn. |
http_method = "..." |
string | (none) | One of GET|POST|PUT|DELETE|PATCH. Hint for REST generators. |
params(name = "doc", ...) |
key/value list | (empty) | Per-parameter descriptions. Less common now that field-level /// extraction works; retained for cases where parameters have no natural Rust doc site. |
group = "..." |
string | (none) | SYNAPSE-13: the method's group in a listing ("read", "write", …) — OpenAPI's tag, one per method. MethodSchema.group; synapse lists a group's methods together, the groups in the order they first appear. |
values(param = ["A", "B"], ...) |
key / string-array list | (none) | SYNAPSE-13: the values a param is meant to take — a hint, never enforced (the method may accept synonyms). Emitted as x-plexus-values on the param's property; synapse shows [values: …]. A name that is no param is a compile error. |
example(note = "...", params = r#"{...}"#) |
repeatable | (none) | SYNAPSE-13: a worked call — a JSON object of the method's params (checked at expansion: JSON, an object, naming only its params) and a note. MethodSchema.examples; synapse renders each as a command line. Use r##"…"## when the JSON holds "#. |
request = () |
tuple | (inherits) | Skip activation-level request extraction for this method (public endpoint escape hatch). |
request = OtherType |
type | (inherits) | Reserved — per-method request type override is not yet wired end-to-end. |
Removed in 0.7 (compile errors that name the replacement):
| Arg | Error says | Instead |
|---|---|---|
streaming |
"cardinality comes from the return type — remove streaming" |
-> T / -> Result<T, E> is one item; -> impl Stream<Item = …> is many |
returns(Variant, ...) |
"give each method its own return type" | a per-method item type, e.g. -> Result<Ticket, GetError> |
Method parameter attributes (applied inside the fn signature):
#[activation_param]— inject a field from the activation-level request struct; name + type must match.#[from_auth(expr)]— callexpr(&auth_context)and bind the result; useful for validated user types.
Params are decoded one at a time, so a bad call names its param: a missing
required one is an error frame invalid_params { param, problem: "missing" },
one of the wrong JSON type invalid_params { param, problem: "malformed", detail }.
The six signature forms
A method's return type is its whole contract. The macro reads it and fills
MethodSchema's returns (T), error (E), progress (P) and
cardinality, and dispatches each item to its frames:
| signature | cardinality | schema returns / error / progress |
frames per item |
|---|---|---|---|
-> T |
one | T / — / — | data content: T, then done |
-> Result<T, E> |
one | T / E / — | data {"ok": t} or {"err": e}, then done |
-> impl Stream<Item = T> |
many | T / — / — | data content: T … done |
-> impl Stream<Item = Result<T, E>> |
many | T / E / — | data {ok} / {err} … done; an Err does not end the stream |
-> impl Stream<Item = Progress<T, P>> |
many | T / — / P | Update(p) → progress content: p; Item(t) → data content: t |
-> impl Stream<Item = Result<Progress<T, P>, E>> |
many | T / E / P | Ok(Update(p)) → progress; Ok(Item(t)) → data {ok}; Err(e) → data {err} |
- An err is data.
Err(e)is the activation saying no, not the call failing; a stream carries on past it unless the method ends it (yield Err(e); return;). A call failure (bad params, unknown method, auth) is the error frame. - Progress needs a stream.
Progress<T>defaultsPtoNote { message, percentage };Progress<T, P>declares it.-> Progress<T>(one item) is a compile error. - Recognition is syntactic: a type whose last path segment is
Resultwith two type arguments, orProgresswith one or two. An alias (anyhow::Result<T>,type R = …) is a plainT.impl Stream<Item = …>may carry any extra bounds (+ Send + 'static), andstream! { … }bodies work as before. - Anything else is a compile error that lists the six forms — notably
BoxStream<'_, T>,Pin<Box<dyn Stream<…>>>andPlexusStream: returnimpl Stream<Item = …> + Send + 'staticinstead. - A plain-
Tstream (impl Stream<Item = OneEnum>, 0.6's only form) compiles and sends exactly what it did.
#[child] list/search methods, #[activation_param]
/ #[from_auth] parameters and request = … work with every form.
The namespace, the trait and the client (MACRO-13, RETURNS-47)
impl Foo and impl FooActivation name the namespace (foo) and the client
(FooClient<T>), as impl Trait for Type does from the trait;
namespace = "..." overrides the namespace. The trait is emitted every time
(NEST-17): FooActivationSchema unless trait = "..." names it, each method
in it under its own return type (RETURNS-36), beside the client and its
aggregate {Ns}Event.
#[plexus_macros::child] / #[plexus_macros::child(list = …, search = …, forward = …)]
Attached to methods inside an #[activation] impl to register them in the generated ChildRouter. Two accepted shapes:
| Shape | Role | Notes |
|---|---|---|
fn NAME(&self) -> Child |
Static child | Routing name is the method identifier. Sync or async. |
fn NAME(&self, name: &str) -> Option<Child> |
Dynamic fallback | Called for any name not matched by a static child. Sync or async. |
Optional arguments on dynamic #[child]:
| Arg | Type | Advertises capability | Sibling method shape |
|---|---|---|---|
list = method |
path | ChildCapabilities::LIST |
(async) fn METHOD(&self) -> impl Stream<Item = String> (or BoxStream<'_, String>) |
search = method |
path | ChildCapabilities::SEARCH |
(async) fn METHOD(&self, query: &str) -> impl Stream<Item = String> |
Sibling methods are validated at macro-expansion time — typos in list = … or a wrong signature become compile errors pointing at the attribute. NEST-17: the sibling is named by its path (list = item_ids); the string form (list = "item_ids") is accepted for one release with a deprecation warning. forward = identity_only takes the policy as a bare word or a string.
#[child] methods do not appear as RPC endpoints in the schema; they contribute to routing only. The presence of any #[child] method flips the activation into hub mode (replacing the deprecated hub flag).
How a child inherits its caller (MACRO-20). A call routed into a child gets a context derived by a forward policy, emitted as ChildRouter::forward_policy_for. A static child is the same service as its parent (a value built from the parent's own fields, in-process), so by default it gets SameService: the caller whole, with the verified user, the session, and the metadata that holds the principal stamp, the session key and expiry, and the gate's ceiling. Under login, that's what lets a child's #[from_auth] / Access::verify see who called and keeps a ceilinged session from widening inside the child. A child that must not see the caller's session says so:
forward = … |
the child keeps |
|---|---|
"same_service" (a static child's default) |
everything (plexus_core::plexus::SameService) |
"identity_only" |
the user id and session id only; the metadata (principal stamp, session, ceiling) is dropped (IdentityOnly) |
"pass_through" |
everything, named as a pass-through (PassThrough) |
"anonymous" |
nothing (Anonymous) |
A dynamic child keeps the framework default (IdentityOnly) unless it names a policy. The parent also describes its static children (ChildRouter::router_static_child_schemas, Activation::static_child_schemas), so a DynamicHub gates a child's method by its whole path (tickets.commits.link, with the child's own target), seeds the child's roles(...) qualified by that path in declared_roles, and lists the methods in auth.requires and the caller's view (plexus-core plexus::children).
#[plexus_macros::removed_in("X")]
Companion to Rust's built-in #[deprecated]. Carries the removal-version field that rustc's #[deprecated] doesn't accept.
async + Send + 'static
The macro writes this into MethodSchema.deprecation as DeprecationInfo { since, removed_in, message }. Without the companion attribute, removed_in defaults to the string "unspecified".
Applying #[plexus_macros::removed_in] to a method without #[deprecated] is a compile error.
#[derive(PlexusRequest)]
See Request forwarding for the full treatment. Generates:
impl PlexusRequest for YourStruct(extraction + schema).impl schemars::JsonSchema for YourStructusingplexus_core::__schemars(no directschemarsdependency required from the caller).
Supported field attributes:
#[from_cookie("name")] #[from_header("name")] #[from_query("name")]
#[from_peer] #[from_auth_context]
Fields without any source attribute must implement PlexusRequestField — used for newtype wrappers that carry their own validation.
#[derive(HandleEnum)]
Generates to_handle(), impl TryFrom<&Handle>, and impl From<_> for Handle for an enum that represents the set of typed handles an activation issues.
Enum-level #[handle(...)] arguments:
| Arg | Required? | Notes |
|---|---|---|
plugin_id = "CONST_OR_PATH" |
yes | Path to the activation's plugin UUID constant — e.g. "Counter::PLUGIN_ID" or "MY_PLUGIN_ID". |
version = "X.Y.Z" |
yes | Semver for handles emitted by this enum. |
plugin_id_type = "Type" |
no | Concrete instantiation to qualify plugin_id when the owning activation is generic (e.g. "Cone<NoParent>"). Fixes E0283 ambiguity. |
crate_path = "..." |
no ("plexus_core") |
Override import path. |
Variant-level #[handle(...)] arguments:
| Arg | Required? | Notes |
|---|---|---|
method = "..." |
yes | The handle.method value on the wire. |
table = "..." |
no | SQLite table name (consumed by future handle-resolution tooling). |
key = "..." |
no | Primary key column. |
key_field = "..." |
no | Which variant field holds the key. Defaults to the first field. |
strip_prefix = "..." |
no | Strip this prefix before looking up by key. |
#[derive(Credentials)]
Marks the credential-bearing fields of a response struct or enum so the
framework can mint, redact, and reflect them. Applied to the item
(struct / enum); individual fields carry an inner #[credential(...)]
helper attribute. The derive is additive — your type is re-emitted
unchanged; the macro emits sibling registry functions plus an
impl HasCredentialMarkers for the type.
A credential-bearing field's type must be Credential<T> (the sealed
wrapper from plexus_auth_core); the macro errors otherwise.
use Credentials;
use Credential;
Field-level #[credential(...)] clauses:
| Clause | Required? | Notes |
|---|---|---|
kind = "..." |
yes | Closed CredentialKind: bearer, cookie, oauth_access, oauth_refresh, oidc_id, aws_sts, macaroon. Validated at compile time (a typo is a compile error). |
kind(other = "name") |
(alt) | Structured escape valve for backend-specific kinds. The bare kind = "other" form is rejected — use this parenthesized form. |
attach_as = "..." |
yes | Where the credential is projected on the wire. Prefixed-string grammar (see below). |
scheme = "..." |
no | Value prefix, e.g. "Bearer ". |
scopes = ["a.b", ...] |
no | Array of scope-name string literals. |
refresh_via = "ns.method" |
no | MethodPath (<namespace>.<method>[.<sub>]*, each segment [a-z][a-z0-9_]*). Validated at macro time. |
revoke_via = "ns.method" |
no | Same MethodPath grammar. |
sensitive |
no | Bare flag or `sensitive = true |
attach_as grammar (one of four prefixed-string forms):
| Form | Meaning |
|---|---|
"header:<name>" |
Project to the named response header (e.g. "header:authorization"). |
"cookie:<name>" |
Project to a Set-Cookie with the named cookie. |
"in_rpc_param:<name>" |
Carried in the named RPC parameter. |
"first_frame:<setup-method>:<param>" |
Supplied as <param> on the first frame of <setup-method>. |
What the macro emits (consumed downstream for schema + redaction):
__plexus_credential_marker_for_<Type>() -> Vec<CredentialFieldMarker>— one entry per credential field, in declaration order, with all parsed metadata. For enums each entry carries its variant name.__plexus_sensitive_fields_for_<Type>() -> Vec<(Option<&str>, &str)>— the(variant, field)pairs treated as sensitive (mirrors the credential set, since credentials are always sensitive — used for log/serialization redaction).impl HasCredentialMarkers for <Type>— opts the type into the specialized marker-slice path read by#[plexus_macros::method]at schema-build time.
#[derive(Credentials)] cannot be applied to a union.
#[derive(plexus_macros::Deserialize)] — a house event read with its type first
An internally tagged event's Deserialize, written where serde's goes (PERF.115-43):
serde reads an internally tagged enum whole into a private buffer before it reads the tag, then reads
the variant out of the buffer. This reads the first key: when it is the tag, the tag's value names the
variant and its fields are read straight from the rest of the object; when it is not, serde reads the
object as it always has. plexus-core writes type first, so a generated client, a hop and a service
reading another's events all read them without the buffer: a ticket row's decode in a generated client
fell from 16,312 instructions to 12,011, the event alone from 12,043 to 7,740.
Everything else is serde's. The derive has serde derive the enum twice more beside it
(#[serde(remote = …)]), once as written and once without its tag, so every #[serde] attribute
(rename_all, rename_all_fields, rename, alias, other, default, skip, with, flatten,
deny_unknown_fields, expecting) is read by serde's own code:
| the object | read |
|---|---|
type first, a struct variant |
its fields straight from the object |
type first, a unit variant |
the rest read and dropped, as serde drops it |
type first, a newtype variant, a flattened field, a variant read with a function |
by serde's read: the object handed to it again, type first |
type anywhere else, a sequence |
by serde's read, as before |
What serde refuses is refused in serde's words: a second type wherever it comes, an unknown variant,
a missing or mistyped field. Two things differ, both because a value is read by the deserializer itself
rather than out of serde's buffer: a value only the input can carry (a RawValue, a map keyed by
numbers) reaches a variant whose type comes first, where serde's buffer refused it; and a fault inside
a field's value is named as the deserializer names it for a struct holding that field (an enum field
given a number: expected value, not expected string or map). Where an object has two faults, the one
met first is named; serde names a second type first. A serde_json::Value keeps its keys sorted, so
type comes first there only when its name sorts first; elsewhere a Value is read by serde, as before.
It is for an internally tagged enum that is not generic and has no untagged variant (one is tried on the
whole object once the tagged ones fail, which needs the buffer); anything else is a compile error
telling you to derive serde's Deserialize. Its runtime is plexus-client's
(plexus_client::__rt::type_first), so the deriving crate depends on plexus-client, as every crate with
a generated client does.
#[derive(StreamEvent)] — removed in 0.7
The derive no longer exists. Item types are plain Serialize + Deserialize + JsonSchema types.
#[derive(JsonSchema)] (compat shim)
Only available when plexus-macros is compiled with the schemars-compat feature and aliased as schemars in a crate's dev-dependencies. Produces a no-op impl JsonSchema, preventing a duplicate-impl conflict with the impl JsonSchema generated by #[derive(PlexusRequest)] when test code writes #[derive(PlexusRequest, schemars::JsonSchema)].
Library crates almost never need this directly; the companion crate plexus-schemars-compat is the public entry point.
Migration from deprecated surfaces
0.7 → 0.8: the return type is the contract
- Drop
streaming— cardinality is the return type. A method that yields one value can now say so:-> T/-> Result<T, E>. - Drop
returns(..)— give the method its own item type instead of a filtered shared enum. #[derive(StreamEvent)]is gone — delete it; nothing replaces it.- Methods returning
impl Stream<Item = OneEnum>compile unchanged, and keep their trait (MACRO-13). - The client: a one-item method is an
async fnreturning its item (m_allis gone); a many-item method returns aMethodStream—.try_collect()where you calledm_all, items directly where you matchedClientEvent::Data(..)(ClientEventis gone; opt in to progress with.with_progress(), which yieldsFrame). A call failure isClientError::Remote(RemoteError), typed, instead of a message string. The client also derives the aggregate{Ns}Event({Ns}Aggregatewhen an item type already has that name).
All deprecations in plexus-macros 0.5 still compile with warnings in 0.7; none has a removal version yet.
#[hub_methods] → #[plexus_macros::activation]
Before:
After:
Identical semantics. #[hub_methods] emits a deprecation warning pointing at the replacement.
#[hub_method] → #[plexus_macros::method]
Before:
async
After:
async
hub = true / children = [...] → #[plexus_macros::child] methods
Before:
After:
Hub mode is now inferred from the presence of #[child] methods (CHILD-8). The hub flag and children = [...] list emit deprecation warnings and still work in 0.7.
Output pipeline
The macro output feeds the same pipeline today as it did in 0.4, but with richer metadata:
#[plexus_macros::activation] (this crate)
↓ emits
PluginSchema { methods: [MethodSchema { role, deprecation, params, ... }] }
↓ served over Plexus RPC (plexus-transport)
Synapse (Haskell) fetches, deduplicates, builds Synapse IR
↓ feeds
plexus-codegen-{rust,typescript,python}
↓ produces
Generated clients with typed methods, streaming iterators, and
deprecation warnings that mirror your `#[deprecated]` annotations
See the substrate reference server (plexus-substrate) for end-to-end examples of every feature in production use:
bash,echo— minimal single-method activations.cone,claudecode— generic activations withHandleEnum, dynamic children, andresolve_handle.solar— hub activation with dynamic child routing +listcapability.changelog,mustache— multi-method flat activations.
License
MIT