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, 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 Tickets is named by itself (RETURNS-47: no suffix forced); impl TicketsActivation by its stem, Tickets, as before. The namespace is the name in snake_case (TicketsApi → tickets_api), the client TicketsClient<T>. namespace = "…" overrides the namespace.
  • A trait only when named. trait = "Bar" emits trait Bar (and names the client BarClient and, absent namespace, the namespace bar), 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 bidirectional ctx). The client implements no trait: its methods answer Result<T, ClientError> (one item) or the {Ns}{Method}Stream alias (many), so no item type needs plexus_client::FromClientError.
  • impl Trait for Type. #[plexus_macros::activation] impl forge::Forge for GitHub serves a trait written by hand: the trait names the namespace (forge) and the client (ForgeClient<T>, emitted here), the type names nothing, and every async fn on &self is 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]). Under auth = "required" the dispatch refuses an anonymous caller (or a call outside any context) before the body of every method not public, 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 through plexus_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 fn on &self returning impl 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 = 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, and a contract is its trait: when every wire method is bodiless (pub async fn f(&self, ..) -> impl Stream<..>;), on impl FooActivation (trait Foo) or with trait = "…", the macro emits pub struct FooActivation<D: Foo>(Arc<D>) delegating to D, impl<D: Foo> Foo for FooActivation<D>, and Foo::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.