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
| Macro | Purpose |
|---|---|
#[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)
| signature | cardinality | schema returns / error / progress |
|---|---|---|
-> T | one | T / — / — |
-> Result<T, E> | one | T / E / — |
-> impl Stream<Item = T> | many | T / — / — |
-> impl Stream<Item = Result<T, E>> | many | T / E / — |
-> impl Stream<Item = Progress<T, P>> | many | T / — / P |
-> impl Stream<Item = Result<Progress<T, P>, E>> | many | T / 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_
method Deprecated - Deprecated: use
plexus::methodinstead. - hub_
methods Deprecated - Deprecated: use
plexus::activationinstead. - method
- Attribute macro for individual methods within a
#[plexus::activation]impl block. - removed_
in - Companion attribute to Rust’s built-in
#[deprecated]for carrying aremoved_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. - Handle
Enum - Derive macro for type-safe handle creation and parsing.
- Plexus
Request - Derive macro for typed HTTP/WebSocket request extraction.