#[activation]Expand description
Attribute macro for impl blocks defining a Plexus activation.
Generates:
- Method enum for schema extraction
- Activation trait implementation
- RPC server trait and implementation
§Attributes
namespace = "..."- The activation namespace (the name rule below gives it fromimpl FooActivation)version = "..."(optional, default: “1.0.0”) - Version stringdescription = "..."(optional) - Activation descriptioncrate_path = "..."(optional, default: “crate”) - Path to substrate crateclient(optional flag) - also emit the typed client (MACRO-2, below)server_cfg = "<cfg predicate>"(optional) - compile the server half only under thatcfg(MACRO-2, below)
§Example
#[plexus::activation(namespace = "bash", version = "1.0.0", description = "Execute bash commands")]
impl Bash {
/// Execute a bash command and stream output
#[plexus::method]
async fn execute(&self, command: String) -> impl Stream<Item = BashEvent> + Send + 'static {
self.executor.execute(&command).await
}
}§The typed client (client, server_cfg) — MACRO-2, 0.7 shapes RETURNS-9
The macro already knows, when it runs, every method’s wire name, its
parameters and its precise contract (cardinality, item, error, progress).
With client it also emits a typed client for the activation, and the
activation’s aggregate {Ns}Event (one variant per method, carrying
that method’s item), so a Rust consumer never hand-writes a call site or
hand-mirrors an item type:
#[plexus_macros::activation(client)] // namespace "tickets", implicitly
impl Tickets { /* unchanged */ }
// emitted beside the impl: TicketsClient<T>, and TicketsEvent
let client = TicketsClient::new(transport); // any plexus_client::Transport
let health = client.health().await?; // one item: Health
match client.get("MNG-2".into()).await? { Ok(t) => .., Err(no) => .. } // one, fallible
let rows: Vec<_> = client.list(None, None).try_collect().await?; // many: MethodStream
let mut s = client.import(src).with_progress(); // Frame<item, P>
let mut ev = client.watch(None).events(); // TicketsEvent? is the call failing (ClientError::Remote(RemoteError) for the
server’s typed error frame); a match on the item is the activation’s
answer. The client is generic over the transport, so the emitted code
names none of them; its parameter and item types are the activation’s
own, so a change to either is a compile error in every consumer. A crate
that already defines a type named {Ns}Event renames it before turning
client on.
Requires the consuming crate to depend on plexus-client. A
proc-macro crate cannot check that for you at expansion time in general,
but the path is resolved through proc-macro-crate, so a missing
dependency is reported at the client flag rather than as an unresolved
import in code you did not write.
server_cfg = "..." puts the server half of the expansion — the
impl block, the method enum, the Activation impl, the jsonrpsee trait —
behind a cfg, while the client half stays unconditional. That is what
makes an activation crate reachable from wasm32-unknown-unknown:
// Cargo.toml: server deps are optional and behind `feature = "server"`.
// plexus-macros itself stays non-optional — a proc-macro crate is built
// for the host, so it costs a wasm32 build nothing.
#[plexus_macros::activation(
namespace = "tickets",
client,
server_cfg = "feature = \"server\"",
)]
impl Tickets { /* .. */ }A consumer then says one line — tickets-api = { version = "..", default-features = 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.
Both flags are opt-in: an activation that names neither expands exactly as it did before.
§#[activation] needs nothing — MACRO-13, RETURNS-47
The type names everything, every key is an override, and (NEST-17) the
trait is emitted every time, {Name}ActivationSchema unless named:
/// Tickets. // the activation's description
#[plexus_macros::activation]
impl Tickets {
/// Every ticket. // the method's description
pub async fn list(&self) -> impl Stream<Item = Ticket> + Send + 'static { .. }
#[plexus_macros::method]
pub async fn total(&self) -> u64 { .. } // one item: marked
pub fn new() -> Self { .. } // not async: a plain method
async fn helper(&self) -> u32 { .. } // not pub: a plain method
}
// namespace "tickets"; `TicketsClient<T>`, whose `total()` answers
// `Result<u64, ClientError>` and `list()` a `MethodStream`; the trait
// `TicketsActivationSchema`, implemented by `Tickets` (when `Clone`).- The name rule.
impl Ticketsis named by itself (RETURNS-47: no suffix forced);impl TicketsActivationby its stem,Tickets, as before. The namespace is the name in snake_case (TicketsApi→tickets_api), the clientTicketsClient<T>.namespace = "…"overrides the namespace. - The trait every time (NEST-17, owner 2026-11-09, reversing
RETURNS-47’s “only when named”).
impl Shopandimpl ShopActivationemittrait ShopActivationSchema;trait = "Bar"renames it (and names the clientBarClientand, absentnamespace, the namespacebar); a contract is its trait (Foo). Each wire method is in it under its own return type, boxed, with nothing the server injects. The activation implements it by cloning itself into each stream (the default trait only where the type isClone); a method that takesauth,reachor a#[from_auth]value reads it from the call’s context there (plexus_core::call::caller(), asimpl Trait for Typedoes — a missing caller is the method’s error: itsEfrom aPlexusErroror aPeerError;reachoutside a call isReach::nowhere()). An#[activation_param]is in no context, so an activation with one does not implement its trait. The client’s methods answerResult<T, ClientError>(one item) or the{Ns}{Method}Streamalias (many); it implements the trait too when every method answers oneResult<T, E>withE: From<PeerError>, sodyn ShopActivationSchemais local or remote alike. impl Trait for Type.#[plexus_macros::activation] impl forge::Forge for GitHubserves a trait written by hand: the trait names the namespace (forge) and the client (ForgeClient<T>, emitted here), the type names nothing, and everyasync fnon&selfis a wire method, called as<GitHub as forge::Forge>::m. Its methods reach their caller through the call’s context,plexus_core::call::caller()(a trait’s signature cannot carry#[from_auth]). Underauth = "required"the dispatch refuses an anonymous caller (or a call outside any context) before the body of every method notpublic, out of band and typed, as#[from_auth]does.#[plexus_macros::from_auth(self. access.verify)]on the method is#[from_auth]’s form here: the verifier runs on the signed-in caller before the body, its error the call’s typed refusal by the same route, its value the body’s throughplexus_core::call::verified::<User>(). It has no direct JSON-RPC methods, only the service’s{ns}.call;#[child]in it is not served yet (GRAFT-1).- Every public method a wire method. Every
pub async fnon&selfreturningimpl Stream<Item = E>is on the wire with no#[method](which stays for its overrides, and marks a one-item method); one returning anything else unmarked is a compile error;methods = markedrestores the#[method]-only rule. - The client without a flag, whenever the crate depends on
plexus-client;clientis accepted with a deprecation warning. - The
serverfeature default. A crate whose manifest declares aserverfeature gets its server half under#[cfg(feature = "server")];server_cfgoverrides. The trait and the client are never gated. - A bodiless activation is a contract, and a contract is its trait:
when every wire method is bodiless (
pub async fn f(&self, ..) -> impl Stream<..>;), onimpl FooActivation(traitFoo) or withtrait = "…", the macro emitspub struct FooActivation<D: Foo>(Arc<D>)delegating toD,impl<D: Foo> Foo for FooActivation<D>, andFoo::server(self):service.register(Local::new().server()).
Written before MACRO-13. An activation on a type not named
…Activation that says its namespace expands exactly as it did (no
trait; the client on the client flag; only #[method]s on the wire)
with a deprecation warning saying what to change. A later release
refuses it.