#[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
The macro already knows, when it runs, every method’s wire name, its
parameters and its Stream<Item = E> event type. With client it also
emits a typed client for the activation, so a Rust consumer never
hand-writes a call site or hand-mirrors an event type:
#[plexus_macros::activation(namespace = "tickets", client)]
impl Tickets { /* unchanged */ }
// emitted beside the impl:
let client = TicketsClient::new(transport); // any plexus_client::Transport
let mut watch = client.watch(Some("MACRO".into())); // EventStream<'_, TicketsEvent>
let all = client.list_all(None, None, None).await?; // Vec<TicketsEvent>The client is generic over the transport, so the emitted code names none of them; its parameter and event types are the activation’s own, so a change to either is a compile error in every consumer.
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
On impl FooActivation the stem Foo names everything, every key is an
override, and the trait is always emitted (the owner’s always):
/// A deploy driver. // the activation's description
#[plexus_macros::activation]
impl DriverActivation {
/// What this driver can do. // the method's description
pub async fn describe(&self) -> impl Stream<Item = DriverEvent> + Send + 'static { .. }
pub fn new() -> Self { .. } // not async: a plain method
async fn helper(&self) -> u32 { .. } // not pub: a plain method
}
// namespace "driver"; `pub trait Driver: Send + Sync + 'static` with
// `fn describe(&self) -> BoxStream<'static, DriverEvent>`;
// `impl Driver for DriverActivation`; `DriverClient<T>`, and
// `impl<T: Transport + Clone + Send + Sync + 'static> Driver for DriverClient<T>`.- The name rule. The namespace defaults to the stem in snake_case
(
TicketsApiActivation→tickets_api); the client isFooClient<T>.trait = "Bar"names the trait and the client (and, absentnamespace, the namespacebar) whatever the type is called. A type not named…Activation, withouttrait = "…"ornamespace, does not compile. - The trait, always. Each wire method is on it with the parameters a
caller passes. Each event type must implement
plexus_client::FromClientErrorwhen there is a client: the client’s implementation yields anErr(ClientError)asE::from_client_error(err)and ends (Stringhas it). The activation implements its own trait by cloning itself into each stream (registeralready asks forClone) — unless a wire method takes what the server injects (auth,reach,#[from_auth],#[activation_param], a bidirectionalctx): then only the client implements it. - 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); one returning anything else 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. When every wire method is
bodiless (
pub async fn f(&self, ..) -> impl Stream<..>;), the macro emitspub struct FooActivation<D: Foo>(Arc<D>)delegating toD,impl<D: Foo> Foo for FooActivation<D>, andFoo::server(self):hub.register(Local::new().server()), orhub.register(FooClient::new(transport).server())for a proxy.
Before the renames land. An activation written before MACRO-13 — a
type not named …Activation, no trait = "…", its namespace given —
expands exactly as it did (no trait; the client on the client flag;
only #[method]s on the wire) with a deprecation warning asking for the
rename. A later release refuses it.