#[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 a trait is emitted only when 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`. No trait.- 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. - A trait only when named.
trait = "Bar"emitstrait Bar(and names the clientBarClientand, absentnamespace, the namespacebar), each wire method in it under its own return type, boxed; the activation implements it by cloning itself into each stream — unless a wire method takes what the server injects (auth,reach,#[from_auth],#[activation_param], a bidirectionalctx). The client implements no trait: its methods answerResult<T, ClientError>(one item) or the{Ns}{Method}Streamalias (many), so no item type needsplexus_client::FromClientError. 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.