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 (NEST-17) the trait is emitted every time, {Name}ActivationSchema unless 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`; the trait
// `TicketsActivationSchema`, implemented by `Tickets` (when `Clone`).
  • 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.
  • The trait every time (NEST-17, owner 2026-11-09, reversing RETURNS-47’s “only when named”). impl Shop and impl ShopActivation emit trait ShopActivationSchema; trait = "Bar" renames it (and names the client BarClient and, absent namespace, the namespace bar); a contract is its trait (Foo). Each wire method is in it under its own return type, boxed, with nothing the server injects. The activation implements it by cloning itself into each stream (the default trait only where the type is Clone); a method that takes auth, reach or a #[from_auth] value reads it from the call’s context there (plexus_core::call::caller(), as impl Trait for Type does — a missing caller is the method’s error: its E from a PlexusError or a PeerError; reach outside a call is Reach::nowhere()). An #[activation_param] is in no context, so an activation with one does not implement its trait. The client’s methods answer Result<T, ClientError> (one item) or the {Ns}{Method}Stream alias (many); it implements the trait too when every method answers one Result<T, E> with E: From<PeerError>, so dyn ShopActivationSchema is local or remote alike.
  • 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.
  • served = written (KEEL-27, opt-in per block): an unmarked fn is what its signature says — not pub, or not on &self, a helper; a pub fn x(&self) -> A a mount, pub fn x(&self, name: &str) -> Option<A> a slot (each checked by the compiler, A: ChildRouter, the refusal naming the fn and what a mount returns); a pub async fn x(&self, name: &str) -> Result<Box<dyn I>, PeerError> a fallible mount (a #[peer]); any other pub async fn on &self a method (a bare #[method], one item or a stream). A marked fn is what its marker says; an option no signature carries (#[method(name = …)] and the rest, #[child(list = …, search = …, forward = …, opaque)], a mount behind a type alias, a private served fn) keeps its marker. Not with methods = marked, nor on impl Trait for Type.
  • 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.