Skip to main content

Crate plexus_macros

Crate plexus_macros 

Source
Expand description

§plexus-macros

Procedural macros for Plexus RPC activations. Your Rust function signature IS the schema — the macros extract method names, parameter types, return types, doc comments, deprecation metadata, child routing, and typed request extraction from the source.

See the crate-level README for a comprehensive example covering every option, a deep-dive on request forwarding (PlexusRequest + request = ...), and a per-macro reference.

§Quick example

ⓘ
use futures::Stream;
use async_stream::stream;
use plexus_macros::PlexusRequest;

#[derive(PlexusRequest)]
pub struct BashRequest {
    #[from_cookie("access_token")]
    auth_token: String,
}

pub struct Bash;

#[plexus_macros::activation(            // namespace "bash", implicitly
    version = "1.0.0",
    description = "Execute bash commands and stream output",
    request = BashRequest,
)]
impl Bash {
    /// Execute a bash command and stream output.
    #[plexus_macros::method]
    async fn execute(
        &self,
        command: String,
        #[activation_param] auth_token: String,
    ) -> impl Stream<Item = String> + Send + 'static {
        let _ = (command, auth_token);
        stream! { yield "ok".into(); }
    }
}

§Macros at a glance

MacroPurpose
#[plexus_macros::activation]Turn an impl block into a Plexus RPC activation — and, with client, emit its typed client.
#[plexus_macros::method]Mark a method as an RPC endpoint.
#[plexus_macros::child]Register a child activation for ChildRouter dispatch.
#[plexus_macros::removed_in]Companion to #[deprecated] carrying the removal version.
#[derive(PlexusRequest)]Typed extraction from RawRequestContext.
#[derive(HandleEnum)]Type-safe handle enums for an activation.
#[derive(plexus_macros::Deserialize)]An internally tagged event’s Deserialize, its type read first (serde’s Deserialize otherwise).

§A method’s return type is its contract (0.7)

signaturecardinalityschema returns / error / progress
-> ToneT / — / —
-> Result<T, E>oneT / E / —
-> impl Stream<Item = T>manyT / — / —
-> impl Stream<Item = Result<T, E>>manyT / E / —
-> impl Stream<Item = Progress<T, P>>manyT / — / P
-> impl Stream<Item = Result<Progress<T, P>, E>>manyT / E / P

A Result item travels as data, {"ok": t} or {"err": e}; a Progress::Update(p) as a progress frame. The namespace is the type’s name — impl Foo, or the stem of impl FooActivation — or the trait’s, on impl Foo for Type (MACRO-13, RETURNS-47; namespace = "..." overrides it). #[method(returns(..))] and #[derive(StreamEvent)] are gone, and #[method(streaming)] is a deprecated no-op on a stream form. See the README’s per-macro reference.

Deprecated surfaces still accepted: #[hub_methods], #[hub_method], the hub and children = [...] flags on #[activation]. See the migration section of the README.

§Crate version (UMB-2)

This crate is proc-macro = true, which means it can only export macro attributes — pub const VERSION etc. are forbidden by the compiler. The plexus-rpc umbrella reads plexus-macros’s version via a build-time environment variable populated from Cargo.toml’s dependency pin (see plexus-rpc/build.rs).

Attribute Macros§

activation
Attribute macro for impl blocks defining a Plexus activation.
child
Attribute macro for individual child methods within a #[plexus_macros::activation] impl block.
hub_methodDeprecated
Deprecated: use plexus::method instead.
hub_methodsDeprecated
Deprecated: use plexus::activation instead.
method
Attribute macro for individual methods within a #[plexus::activation] impl block.
removed_in
Companion attribute to Rust’s built-in #[deprecated] for carrying a removed_in = "VERSION" hint that rustc doesn’t recognize.

Derive Macros§

Credentials
Derive macro for declaring credential-bearing fields on a return-type struct or enum (per AUTHZ-CRED-MACRO-1).
Deserialize
PERF.115-43 · an internally tagged enum’s Deserialize, its tag read first: in place of serde’s, on a house event.
HandleEnum
Derive macro for type-safe handle creation and parsing.
PlexusRequest
Derive macro for typed HTTP/WebSocket request extraction.