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 = "..." - The activation namespace (the name rule below gives it from impl FooActivation)
  • 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.

§#[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 is FooClient<T>. trait = "Bar" names the trait and the client (and, absent namespace, the namespace bar) whatever the type is called. A type not named …Activation, without trait = "…" or namespace, 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::FromClientError when there is a client: the client’s implementation yields an Err(ClientError) as E::from_client_error(err) and ends (String has it). The activation implements its own trait by cloning itself into each stream (register already asks for Clone) — unless a wire method takes what the server injects (auth, reach, #[from_auth], #[activation_param], a bidirectional ctx): then only the client implements it.
  • Every public method a wire method. Every pub async fn on &self returning impl Stream<Item = E> is on the wire with no #[method] (which stays for its overrides); one returning anything else is a compile error; methods = marked restores the #[method]-only rule.
  • The client without a flag, whenever the crate depends on plexus-client; client is accepted with a deprecation warning.
  • The server feature default. A crate whose manifest declares a server feature gets its server half under #[cfg(feature = "server")]; server_cfg overrides. 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 emits pub struct FooActivation<D: Foo>(Arc<D>) delegating to D, impl<D: Foo> Foo for FooActivation<D>, and Foo::server(self): hub.register(Local::new().server()), or hub.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.