Skip to main content

activation

Attribute Macro activation 

Source
#[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 = "..." (required) - The activation namespace
  • version = "..." (optional, default: “1.0.0”) - Version string
  • description = "..." (optional) - Activation description
  • crate_path = "..." (optional, default: “crate”) - Path to substrate crate
  • client (optional flag) - also emit the typed client (MACRO-2, below)
  • server_cfg = "<cfg predicate>" (optional) - compile the server half only under that cfg (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.