use std::collections::HashMap;
use quote::ToTokens;
use syn::{
parse::{Parse, ParseStream},
punctuated::Punctuated,
spanned::Spanned,
Expr, ExprLit, ExprPath, ExprTuple, FnArg, GenericArgument, ImplItem, ImplItemFn, Lit, Meta,
MetaList, MetaNameValue, Pat, PathArguments, ReturnType, Token, Type,
};
#[derive(Debug, Clone)]
pub struct AuthResolver {
pub param_name: syn::Ident,
pub resolver_expr: syn::Expr,
}
pub(crate) const DEPRECATION_REMOVED_IN_UNSPECIFIED: &str = "unspecified";
#[derive(Debug, Clone)]
pub struct ParsedDeprecation {
pub since: String,
pub removed_in: String,
pub message: String,
}
pub(crate) const BIDIRECTIONAL_REMOVED: &str =
"`bidirectional` is removed (ASK-1): a method no longer asks its caller mid-call, and \
Plexus has no in-call or protocol-wide confirmation. A method that needs its caller's \
yes builds it from its own parameters (a `dry_run`, a plan id).";
#[derive(Debug, Clone)]
pub enum MethodRequestOverride {
Skip,
#[allow(dead_code)]
Type(syn::Type),
}
pub(crate) const STREAMING_DEPRECATED: &str =
"`streaming` is deprecated: cardinality comes from the return type, which \
already says this method yields many items. Remove `streaming`.";
pub(crate) const RETURNS_REMOVED: &str =
"`returns(..)` is removed: a method's return type is its contract. Instead of \
filtering a shared event enum's variants, give each method its own return type — \
e.g. `-> Result<Ticket, GetError>` or `-> impl Stream<Item = ListItem>`.";
pub struct HubMethodAttrs {
pub name: Option<String>,
pub uses: Vec<String>,
pub description: Option<String>,
pub param_docs: HashMap<String, String>,
pub http_method: Option<String>,
pub request_override: Option<MethodRequestOverride>,
pub public: bool,
pub scopes: Vec<String>,
pub streaming: Option<proc_macro2::Span>,
pub target: Option<syn::LitStr>,
pub answer_by: Option<syn::LitStr>,
pub input_ceiling: InputCeilingAttrs,
pub group: Option<String>,
pub examples: Vec<ParsedExample>,
pub values: Vec<(syn::Ident, Vec<String>)>,
pub everywhere: bool,
}
#[derive(Debug, Clone, Default)]
pub struct InputCeilingAttrs {
pub window: Option<syn::LitInt>,
pub max_items: Option<syn::LitInt>,
pub max_bytes: Option<syn::LitInt>,
pub max_buffered: Option<syn::LitInt>,
}
impl InputCeilingAttrs {
fn first(&self) -> Option<(&'static str, &syn::LitInt)> {
[("input_window", &self.window), ("input_max_items", &self.max_items), ("input_max_bytes", &self.max_bytes), ("input_max_buffered", &self.max_buffered)]
.into_iter()
.find_map(|(n, v)| v.as_ref().map(|v| (n, v)))
}
}
#[derive(Debug, Clone)]
pub struct InputInfo {
pub name: syn::Ident,
pub item: Type,
pub at: usize,
pub description: Option<String>,
pub ceiling: InputCeilingAttrs,
}
fn input_item_type(ty: &Type) -> Option<Type> {
let Type::Path(tp) = ty else { return None };
let last = tp.path.segments.last()?;
if last.ident != "Input" {
return None;
}
let PathArguments::AngleBracketed(args) = &last.arguments else { return None };
match args.args.iter().collect::<Vec<_>>().as_slice() {
[GenericArgument::Type(item)] => Some(item.clone()),
_ => None,
}
}
fn names_input(tokens: proc_macro2::TokenStream) -> bool {
use proc_macro2::TokenTree;
let tokens: Vec<TokenTree> = tokens.into_iter().collect();
tokens.iter().enumerate().any(|(i, t)| match t {
TokenTree::Ident(id) => id == "Input" && matches!(tokens.get(i + 1), Some(TokenTree::Punct(p)) if p.as_char() == '<'),
TokenTree::Group(g) => names_input(g.stream()),
_ => false,
})
}
#[derive(Debug, Clone)]
pub struct ParsedExample {
pub note: Option<String>,
pub params_json: String,
pub keys: Vec<String>,
pub span: proc_macro2::Span,
}
fn parse_example(path: &syn::Path, tokens: proc_macro2::TokenStream) -> syn::Result<ParsedExample> {
let usage = "example(...) takes note = \"what it does\" and params = r#\"{ JSON object }\"#, \
e.g. example(note = \"set MENGER-40 to Coding\", params = r#\"{\"id\": \"MENGER-40\", \"status\": \"Coding\"}\"#)";
let parser = Punctuated::<MetaNameValue, Token![,]>::parse_terminated;
let nested = syn::parse::Parser::parse2(parser, tokens)
.map_err(|e| syn::Error::new(e.span(), format!("{e}; {usage}")))?;
let mut note = None;
let mut params: Option<syn::LitStr> = None;
for nv in nested {
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = &nv.value else {
return Err(syn::Error::new_spanned(&nv.value, format!("expected a string literal; {usage}")));
};
if nv.path.is_ident("note") {
if note.is_some() {
return Err(syn::Error::new_spanned(&nv.path, "example(...) takes one note"));
}
note = Some(s.value());
} else if nv.path.is_ident("params") {
if params.is_some() {
return Err(syn::Error::new_spanned(&nv.path, "example(...) takes one params"));
}
params = Some(s.clone());
} else {
return Err(syn::Error::new_spanned(&nv.path, format!("unknown key in example(...); {usage}")));
}
}
let Some(lit) = params else {
return Err(syn::Error::new_spanned(path, format!("example(...) needs params; {usage}")));
};
let text = lit.value();
let value: serde_json::Value = serde_json::from_str(&text).map_err(|e| {
syn::Error::new(lit.span(), format!("example params are not JSON: {e}"))
})?;
let serde_json::Value::Object(map) = &value else {
return Err(syn::Error::new(lit.span(), "example params must be a JSON object of the method's params, e.g. {\"id\": \"MENGER-40\"}"));
};
let keys = map.keys().cloned().collect();
Ok(ParsedExample { note, params_json: value.to_string(), keys, span: lit.span() })
}
fn parse_values(tokens: proc_macro2::TokenStream) -> syn::Result<Vec<(syn::Ident, Vec<String>)>> {
let usage = "values(...) takes param = [\"A\", \"B\", …] pairs, e.g. values(status = [\"Pending\", \"Ready\"])";
let parser = Punctuated::<MetaNameValue, Token![,]>::parse_terminated;
let nested = syn::parse::Parser::parse2(parser, tokens)
.map_err(|e| syn::Error::new(e.span(), format!("{e}; {usage}")))?;
let mut out: Vec<(syn::Ident, Vec<String>)> = Vec::new();
for nv in nested {
let Some(ident) = nv.path.get_ident().cloned() else {
return Err(syn::Error::new_spanned(&nv.path, format!("expected a parameter name; {usage}")));
};
if out.iter().any(|(i, _)| *i == ident) {
return Err(syn::Error::new_spanned(&ident, format!("values for `{ident}` are given twice")));
}
let Expr::Array(arr) = &nv.value else {
return Err(syn::Error::new_spanned(&nv.value, format!("expected an array of string literals; {usage}")));
};
let mut vals = Vec::new();
for el in &arr.elems {
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = el else {
return Err(syn::Error::new_spanned(el, format!("expected a string literal; {usage}")));
};
vals.push(s.value());
}
if vals.is_empty() {
return Err(syn::Error::new_spanned(&nv.value, format!("values for `{ident}` are empty; {usage}")));
}
out.push((ident, vals));
}
Ok(out)
}
pub fn validate_scope_literal(s: &str) -> Result<(), String> {
if s == "*" {
return Ok(());
}
if s.is_empty() {
return Err("scope must not be empty".to_string());
}
let segments: Vec<&str> = s.split('.').collect();
for (i, seg) in segments.iter().enumerate() {
let is_last = i == segments.len() - 1;
if *seg == "*" {
if is_last && segments.len() > 1 {
continue; }
return Err(
"`*` is only valid as the entire scope or as the trailing `.*` segment"
.to_string(),
);
}
let mut chars = seg.chars();
let valid = match chars.next() {
Some(c) if c.is_ascii_lowercase() => {
chars.all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
}
_ => false,
};
if !valid {
return Err(format!(
"segment `{}` must match [a-z][a-z0-9_]*",
seg
));
}
}
Ok(())
}
const METHOD_WORDS: &[&str] = &[
"public", "everywhere", "streaming", "name", "description", "http_method", "target", "answer_by", "group",
"scope", "request", "input_window", "input_max_items", "input_max_bytes", "input_max_buffered", "uses",
"params", "example", "examples", "values",
];
const ACTIVATION_WORDS: &[&str] = &[
"namespace", "trait", "version", "description", "long_description", "crate_path", "plugin_id", "namespace_fn",
"server_cfg", "auth", "request", "parent", "methods", "served", "resolve_handle", "hub", "client",
"typed_params", "children", "roles", "required",
];
fn unknown_word(path: &syn::Path, attr: &str, known: &[&str]) -> syn::Error {
let word = path.get_ident().map(|i| i.to_string()).unwrap_or_else(|| quote::quote!(#path).to_string());
let word = if word == TRAIT_KEY { "trait".to_string() } else { word };
syn::Error::new_spanned(path, format!("unknown word `{word}` in {attr}; it takes: {}", known.join(", ")))
}
impl Parse for HubMethodAttrs {
fn parse(input: ParseStream) -> syn::Result<Self> {
let mut name = None;
let mut description: Option<String> = None;
let mut param_docs = HashMap::new();
let mut http_method = None;
let mut request_override: Option<MethodRequestOverride> = None;
let mut public = false;
let mut streaming: Option<proc_macro2::Span> = None;
let mut scopes: Vec<String> = Vec::new();
let mut public_span: Option<proc_macro2::Span> = None;
let mut first_scope_span: Option<proc_macro2::Span> = None;
let mut target: Option<syn::LitStr> = None;
let mut answer_by: Option<syn::LitStr> = None;
let mut input_ceiling = InputCeilingAttrs::default();
let mut group: Option<String> = None;
let mut examples: Vec<ParsedExample> = Vec::new();
let mut values: Vec<(syn::Ident, Vec<String>)> = Vec::new();
let mut uses: Vec<String> = Vec::new();
let mut everywhere: Option<proc_macro2::Span> = None;
if !input.is_empty() {
let metas = Punctuated::<Meta, Token![,]>::parse_terminated(input)?;
for meta in metas {
match meta {
Meta::Path(path) => {
if path.is_ident("override_call") {
return Err(syn::Error::new_spanned(
&path,
"override_call is deprecated. Use the streaming pattern instead:\n\
- Return `impl Stream<Item = YourEvent>` from the method\n\
- Forward PlexusStreamItem variants into your event enum\n\
See plexus.call implementation for an example.",
));
} else if path.is_ident("streaming") {
streaming = Some(path.span());
} else if path.is_ident("bidirectional") {
return Err(syn::Error::new_spanned(&path, BIDIRECTIONAL_REMOVED));
} else if path.is_ident("public") {
public = true;
public_span = Some(path.span());
} else if path.is_ident("everywhere") {
everywhere = Some(path.span());
} else {
return Err(unknown_word(&path, "#[plexus_macros::method]", METHOD_WORDS));
}
}
Meta::NameValue(MetaNameValue { path, value, .. }) => {
if path.is_ident("name") {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
name = Some(s.value());
}
} else if path.is_ident("description") {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
description = Some(s.value());
}
} else if path.is_ident("http_method") {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
let method = s.value().to_uppercase();
match method.as_str() {
"GET" | "POST" | "PUT" | "DELETE" | "PATCH" => {
http_method = Some(method);
}
_ => {
return Err(syn::Error::new_spanned(
s,
format!(
"Invalid HTTP method '{}'. Valid methods: GET, POST, PUT, DELETE, PATCH",
method
),
));
}
}
}
} else if path.is_ident("target") {
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value else {
return Err(syn::Error::new_spanned(
&path,
"target = ... expects the name of a parameter as a string, \
e.g. #[plexus_macros::method(target = \"id\")]",
));
};
target = Some(s);
} else if path.is_ident("answer_by") {
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value else {
return Err(syn::Error::new_spanned(
&path,
"answer_by = ... expects a string: `caller` (the default), `person`, \
or `grant:<activation.method>`, e.g. \
#[plexus_macros::method(answer_by = \"person\")]",
));
};
answer_by = Some(s);
} else if path.is_ident("input_window")
|| path.is_ident("input_max_items")
|| path.is_ident("input_max_bytes")
|| path.is_ident("input_max_buffered")
{
let Expr::Lit(ExprLit { lit: Lit::Int(n), .. }) = value else {
return Err(syn::Error::new_spanned(
&path,
"expects a whole number, e.g. #[plexus_macros::method(input_window = 256)]",
));
};
let slot = if path.is_ident("input_window") {
&mut input_ceiling.window
} else if path.is_ident("input_max_items") {
&mut input_ceiling.max_items
} else if path.is_ident("input_max_bytes") {
&mut input_ceiling.max_bytes
} else {
&mut input_ceiling.max_buffered
};
*slot = Some(n);
} else if path.is_ident("group") {
let usage = "group = ... expects a non-empty string, e.g. \
#[plexus_macros::method(group = \"write\")]";
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value else {
return Err(syn::Error::new_spanned(&path, usage));
};
if s.value().trim().is_empty() {
return Err(syn::Error::new(s.span(), usage));
}
if group.is_some() {
return Err(syn::Error::new(s.span(), "a method has one group"));
}
group = Some(s.value().trim().to_string());
} else if path.is_ident("scope") {
let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value else {
return Err(syn::Error::new_spanned(
&path,
"scope = ... expects a string literal, e.g. \
#[plexus_macros::method(scope = \"facet.write\")]",
));
};
let literal = s.value();
if let Err(why) = validate_scope_literal(&literal) {
return Err(syn::Error::new(
s.span(),
format!(
"invalid scope literal `{}`: {}. Scopes are ASCII \
dot-separated segments matching [a-z][a-z0-9_]*, \
optionally ending in a `.*` segment wildcard, or \
the bare `*` (AUTHZ-CORE-4 scope grammar; see \
`Scope::try_new`).",
literal, why,
),
));
}
if first_scope_span.is_none() {
first_scope_span = Some(s.span());
}
scopes.push(literal);
} else if path.is_ident("request") {
match value {
Expr::Tuple(ExprTuple { ref elems, .. }) if elems.is_empty() => {
request_override = Some(MethodRequestOverride::Skip);
}
Expr::Path(ExprPath { ref path, .. }) => {
let ty: Type = Type::Path(syn::TypePath {
qself: None,
path: path.clone(),
});
request_override = Some(MethodRequestOverride::Type(ty));
}
_ => {
}
}
} else if path.is_ident("streaming") {
if !matches!(value, Expr::Lit(ExprLit { lit: Lit::Bool(ref b), .. }) if !b.value) {
streaming = Some(path.span());
}
} else {
return Err(unknown_word(&path, "#[plexus_macros::method]", METHOD_WORDS));
}
}
Meta::List(MetaList { path, tokens, .. }) => {
if path.is_ident("uses") {
let parser = Punctuated::<syn::LitStr, Token![,]>::parse_terminated;
for lit in syn::parse::Parser::parse2(parser, tokens.clone())? {
let v = lit.value();
if v.is_empty() || v.starts_with('.') || v.ends_with('.') || !v.contains('.') {
return Err(syn::Error::new(
lit.span(),
format!("uses(\"{v}\"): a method of the parent by its dotted path from the parent's root, e.g. \"shop.items\""),
));
}
uses.push(v);
}
} else if path.is_ident("params") {
let parser = Punctuated::<Meta, Token![,]>::parse_terminated;
let nested = syn::parse::Parser::parse2(parser, tokens.clone())?;
for meta in nested {
if let Meta::NameValue(MetaNameValue { path, value, .. }) = meta {
if let Some(ident) = path.get_ident() {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
param_docs.insert(ident.to_string(), s.value());
}
}
}
}
} else if path.is_ident("example") {
examples.push(parse_example(&path, tokens.clone())?);
} else if path.is_ident("examples") {
return Err(syn::Error::new_spanned(
&path,
"write each example as its own example(note = \"…\", params = r#\"{…}\"#)",
));
} else if path.is_ident("values") {
for (ident, vals) in parse_values(tokens.clone())? {
if values.iter().any(|(i, _)| *i == ident) {
return Err(syn::Error::new_spanned(&ident, format!("values for `{ident}` are given twice")));
}
values.push((ident, vals));
}
} else if path.is_ident("returns") {
return Err(syn::Error::new_spanned(&path, RETURNS_REMOVED));
} else if path.is_ident("bidirectional") {
return Err(syn::Error::new_spanned(&path, BIDIRECTIONAL_REMOVED));
} else {
return Err(unknown_word(&path, "#[plexus_macros::method]", METHOD_WORDS));
}
}
}
}
}
if public && !scopes.is_empty() {
let span = public_span
.or(first_scope_span)
.unwrap_or_else(proc_macro2::Span::call_site);
return Err(syn::Error::new(
span,
"a public method has no required scope; remove `public` or remove `scope = ...`",
));
}
if let Some(span) = everywhere {
if public {
return Err(syn::Error::new(span, "a method that acts `everywhere` is not `public`: remove one"));
}
if target.is_some() {
return Err(syn::Error::new(
span,
"a method that acts `everywhere` has no `target`: it is decided on `*`; remove one",
));
}
}
Ok(HubMethodAttrs { uses, name, description, param_docs, http_method, request_override, public, scopes, streaming, target, answer_by, input_ceiling, group, examples, values, everywhere: everywhere.is_some() })
}
}
const TRAIT_KEY: &str = "__plexus_trait";
const MAX_DESCRIPTION_WORDS: usize = 15;
pub struct HubMethodsAttrs {
pub parent: Option<syn::Path>,
pub namespace: Option<String>,
pub trait_attr: Option<syn::LitStr>,
pub trait_span: Option<proc_macro2::Span>,
pub methods_marked: bool,
pub served_written: Option<proc_macro2::Span>,
pub version: Option<String>,
pub description: Option<String>,
pub long_description: Option<String>,
pub crate_path: Option<String>,
pub resolve_handle: bool,
pub hub: bool,
pub hub_span: Option<proc_macro2::Span>,
pub plugin_id: Option<String>,
pub namespace_fn: Option<String>,
pub request_type: Option<syn::Type>,
pub children: Vec<syn::Ident>,
pub children_span: Option<proc_macro2::Span>,
pub required_fields: Vec<syn::Ident>,
pub required_fields_span: Option<proc_macro2::Span>,
pub auth_posture: Option<AuthPosture>,
pub client: bool,
pub typed_params: bool,
pub client_span: Option<proc_macro2::Span>,
pub server_cfg: Option<String>,
pub server_cfg_span: Option<proc_macro2::Span>,
pub roles: Vec<RoleDecl>,
}
pub struct RoleDecl {
pub name: syn::Ident,
pub entries: Vec<RoleEntry>,
}
pub enum RoleEntry {
Method(syn::LitStr),
Role(syn::Ident),
}
impl Parse for RoleDecl {
fn parse(input: ParseStream) -> syn::Result<Self> {
let name: syn::Ident = input.parse()?;
input.parse::<Token![=]>()?;
let content;
syn::bracketed!(content in input);
let mut entries = Vec::new();
while !content.is_empty() {
if content.peek(syn::LitStr) {
entries.push(RoleEntry::Method(content.parse()?));
} else if content.peek(syn::Ident) {
entries.push(RoleEntry::Role(content.parse()?));
} else {
return Err(content.error(
"a role lists methods as strings (\"get\") and earlier roles by name (viewer)",
));
}
if content.is_empty() {
break;
}
content.parse::<Token![,]>()?;
}
Ok(RoleDecl { name, entries })
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum AuthPosture {
Required,
#[default]
Optional,
Mixed,
None,
}
impl Parse for HubMethodsAttrs {
fn parse(input: ParseStream) -> syn::Result<Self> {
let mut namespace: Option<String> = None;
let mut trait_attr: Option<syn::LitStr> = None;
let mut trait_span: Option<proc_macro2::Span> = None;
let mut methods_marked = false;
let mut served_written: Option<proc_macro2::Span> = None;
let mut version: Option<String> = None;
let mut description = None;
let mut long_description = None;
let mut crate_path: Option<String> = None;
let mut resolve_handle = false;
let mut hub = false;
let mut hub_span: Option<proc_macro2::Span> = None;
let mut plugin_id = None;
let mut namespace_fn = None;
let mut request_type: Option<syn::Type> = None;
let mut children: Vec<syn::Ident> = Vec::new();
let mut children_span: Option<proc_macro2::Span> = None;
let mut required_fields: Vec<syn::Ident> = Vec::new();
let mut required_fields_span: Option<proc_macro2::Span> = None;
let mut auth_posture: Option<AuthPosture> = None;
let mut client = false;
let mut typed_params = false;
let mut client_span: Option<proc_macro2::Span> = None;
let mut server_cfg: Option<String> = None;
let mut server_cfg_span: Option<proc_macro2::Span> = None;
let mut roles: Vec<RoleDecl> = Vec::new();
let mut parent: Option<syn::Path> = None;
if !input.is_empty() {
let tokens: proc_macro2::TokenStream = input.parse()?;
let tokens: proc_macro2::TokenStream = tokens
.into_iter()
.map(|tt| match tt {
proc_macro2::TokenTree::Ident(id) if id == "trait" => {
proc_macro2::TokenTree::Ident(syn::Ident::new(TRAIT_KEY, id.span()))
}
other => other,
})
.collect();
let metas = syn::parse::Parser::parse2(
Punctuated::<Meta, Token![,]>::parse_terminated,
tokens,
)?;
for meta in metas {
match meta {
Meta::NameValue(MetaNameValue { path, value, .. }) => {
if path.is_ident("request") {
let ty: syn::Type = expr_to_type(&value).ok_or_else(|| {
syn::Error::new_spanned(&path, "request = <Type>: expected a type path (e.g. request = MyRequest or request = ())")
})?;
request_type = Some(ty);
continue;
}
if path.is_ident("parent") {
match &value {
Expr::Path(p) if p.qself.is_none() => parent = Some(p.path.clone()),
_ => {
return Err(syn::Error::new_spanned(
&value,
"parent = <Client>: the parent's generated client, by its path (parent = ShopClient)",
))
}
}
continue;
}
if path.is_ident("methods") {
let word = match &value {
Expr::Path(p) if p.path.get_ident().is_some() => {
p.path.get_ident().unwrap().to_string()
}
Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) => s.value(),
_ => String::new(),
};
methods_marked = match word.as_str() {
"marked" => true,
"all" => false,
_ => {
return Err(syn::Error::new_spanned(
&value,
"methods = marked (only #[plexus_macros::method]s are on the wire) \
or methods = all (every `pub async fn` on `&self` returning \
`impl Stream<Item = E>`, the default)",
))
}
};
continue;
}
if path.is_ident("children") {
let Expr::Array(arr) = &value else {
return Err(syn::Error::new_spanned(&value, "children = [field, …]: the fields that are child activations"));
};
for e in &arr.elems {
match e {
Expr::Path(p) if p.path.get_ident().is_some() => children.push(p.path.get_ident().unwrap().clone()),
other => return Err(syn::Error::new_spanned(other, "children = [field, …]: each a field's name")),
}
}
children_span = Some(path.span());
continue;
}
if path.is_ident("served") {
let word = match &value {
Expr::Path(p) if p.path.get_ident().is_some() => {
p.path.get_ident().unwrap().to_string()
}
Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) => s.value(),
_ => String::new(),
};
if word != "written" {
return Err(syn::Error::new_spanned(
&value,
"served = written: what each unmarked fn of the block is, read \
from how it is written (a `pub async fn` a method, a `pub fn` a \
mount, anything not `pub` a helper)",
));
}
served_written = Some(path.span());
continue;
}
const STRING_KEYS: &[&str] = &[
TRAIT_KEY, "namespace", "version", "description", "long_description", "crate_path",
"plugin_id", "namespace_fn", "server_cfg", "auth",
];
if !STRING_KEYS.iter().any(|k| path.is_ident(k)) {
return Err(unknown_word(&path, "#[plexus_macros::activation]", ACTIVATION_WORDS));
}
let Expr::Lit(ExprLit { lit: Lit::Str(_), .. }) = &value else {
let key = if path.is_ident(TRAIT_KEY) { "trait".to_string() } else { path.get_ident().map(|i| i.to_string()).unwrap_or_default() };
return Err(syn::Error::new_spanned(&value, format!("{key} = … expects a string, e.g. {key} = \"…\"")));
};
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
if path.is_ident(TRAIT_KEY) {
if syn::parse_str::<syn::Ident>(&s.value()).is_err() {
return Err(syn::Error::new(
s.span(),
format!("trait = \"{}\" must be an identifier, e.g. trait = \"Driver\"", s.value()),
));
}
trait_span = Some(path.span());
trait_attr = Some(s);
} else if path.is_ident("namespace") {
namespace = Some(s.value());
} else if path.is_ident("version") {
version = Some(s.value());
} else if path.is_ident("description") {
let desc = s.value();
let word_count = desc.split_whitespace().count();
if word_count > MAX_DESCRIPTION_WORDS {
return Err(syn::Error::new(
s.span(),
format!(
"description must be {} words or fewer (found {} words). \
Use long_description for detailed text.",
MAX_DESCRIPTION_WORDS, word_count
),
));
}
description = Some(desc);
} else if path.is_ident("long_description") {
long_description = Some(s.value());
} else if path.is_ident("crate_path") {
crate_path = Some(s.value());
} else if path.is_ident("plugin_id") {
let id_str = s.value();
if uuid::Uuid::parse_str(&id_str).is_err() {
return Err(syn::Error::new(
s.span(),
format!("plugin_id must be a valid UUID, got: {}", id_str),
));
}
plugin_id = Some(id_str);
} else if path.is_ident("namespace_fn") {
namespace_fn = Some(s.value());
} else if path.is_ident("server_cfg") {
server_cfg = Some(s.value());
server_cfg_span = Some(s.span());
} else if path.is_ident("auth") {
let v = s.value();
auth_posture = match v.as_str() {
"required" => Some(AuthPosture::Required),
"optional" => Some(AuthPosture::Optional),
"mixed" => Some(AuthPosture::Mixed),
"none" => Some(AuthPosture::None),
other => return Err(syn::Error::new(
s.span(),
format!(
"auth must be one of \"required\", \"optional\", \"mixed\", \"none\"; got {:?}",
other,
),
)),
};
}
}
}
Meta::Path(path) => {
if path.is_ident("resolve_handle") {
resolve_handle = true;
} else if path.is_ident("hub") {
hub = true;
hub_span = Some(path.span());
} else if path.is_ident(TRAIT_KEY) {
return Err(syn::Error::new(
path.span(),
"a trait is emitted only when named: write `trait = \"Name\"` \
(or write the trait by hand and `impl Name for YourType`)",
));
} else if path.is_ident("client") {
client = true;
client_span = Some(path.span());
} else if path.is_ident("typed_params") {
typed_params = true;
} else {
return Err(unknown_word(&path, "#[plexus_macros::activation]", ACTIVATION_WORDS));
}
}
Meta::List(list) => {
if list.path.is_ident("children") {
let parser = Punctuated::<syn::Ident, Token![,]>::parse_terminated;
let idents = syn::parse::Parser::parse2(parser, list.tokens.clone())?;
children = idents.into_iter().collect();
children_span = Some(list.path.span());
}
else if list.path.is_ident("roles") {
let parser = Punctuated::<RoleDecl, Token![,]>::parse_terminated;
let decls = syn::parse::Parser::parse2(parser, list.tokens.clone())?;
roles.extend(decls);
}
else if list.path.is_ident("required") {
let parser = Punctuated::<syn::Ident, Token![,]>::parse_terminated;
let idents = syn::parse::Parser::parse2(parser, list.tokens.clone())?;
required_fields = idents.into_iter().collect();
required_fields_span = Some(list.path.span());
}
else {
return Err(unknown_word(&list.path, "#[plexus_macros::activation]", ACTIVATION_WORDS));
}
}
}
}
}
if namespace.as_deref() == Some("") {
return Err(syn::Error::new(input.span(), "namespace = \"\" names nothing"));
}
if let (Some(span), true) = (served_written, methods_marked) {
return Err(syn::Error::new(
span,
"served = written and methods = marked say opposite things of an unmarked fn: \
under `served = written` a `pub async fn` is a method, under `methods = marked` \
only a #[plexus_macros::method] is; write one",
));
}
Ok(HubMethodsAttrs {
parent,
namespace,
trait_attr,
trait_span,
methods_marked,
served_written,
version,
description,
long_description,
crate_path,
resolve_handle,
hub,
hub_span,
plugin_id,
namespace_fn,
request_type,
children,
children_span,
required_fields,
required_fields_span,
auth_posture,
client,
typed_params,
client_span,
server_cfg,
server_cfg_span,
roles,
})
}
}
pub struct ParamInfo {
pub name: syn::Ident,
pub ty: Type,
pub description: Option<String>,
pub deprecation: Option<ParsedDeprecation>,
}
#[derive(Debug, Clone)]
pub struct ActivationParamInfo {
pub param_name: syn::Ident,
pub ty: Type,
}
#[derive(Debug, Clone)]
pub enum ChildMethodKind {
Static,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ChildForward {
SameService,
IdentityOnly,
PassThrough,
Anonymous,
}
impl ChildForward {
pub const SPELLINGS: &'static str = "\"same_service\", \"identity_only\", \"pass_through\" or \"anonymous\"";
fn parse(s: &str) -> Option<Self> {
match s {
"same_service" => Some(Self::SameService),
"identity_only" => Some(Self::IdentityOnly),
"pass_through" => Some(Self::PassThrough),
"anonymous" => Some(Self::Anonymous),
_ => None,
}
}
}
#[derive(Debug, Clone)]
pub struct ChildMethodInfo {
pub fn_name: syn::Ident,
#[allow(dead_code)]
pub description: String,
pub kind: ChildMethodKind,
pub is_async: bool,
pub list_fn: Option<syn::Ident>,
pub search_fn: Option<syn::Ident>,
pub deprecation: Option<ParsedDeprecation>,
pub forward: Option<ChildForward>,
pub opaque: bool,
pub return_ty: syn::Type,
pub peer: Option<crate::codegen::peer::PeerShape>,
pub list_is_async: bool,
pub string_args: Vec<(String, proc_macro2::Span)>,
}
impl ChildMethodInfo {
pub fn from_fn(method: &ImplItemFn) -> syn::Result<Self> {
let is_peer = method.attrs.iter().any(|a| a.path().segments.last().is_some_and(|s| s.ident == "peer"));
Self::from_fn_as(method, is_peer)
}
pub fn from_fn_as(method: &ImplItemFn, is_peer: bool) -> syn::Result<Self> {
let fn_name = method.sig.ident.clone();
let is_async = method.sig.asyncness.is_some();
let description = extract_doc_description(&method.attrs).unwrap_or_default();
let (list_fn, search_fn, forward, opaque, string_args) = parse_child_attr_args(&method.attrs)?;
let deprecation = parse_deprecation_attrs(&method.attrs, method.sig.span())?;
let mut typed_params: Vec<&syn::PatType> = Vec::new();
let mut has_receiver = false;
for arg in &method.sig.inputs {
match arg {
FnArg::Receiver(_) => has_receiver = true,
FnArg::Typed(pt) => typed_params.push(pt),
}
}
if !has_receiver {
return Err(syn::Error::new_spanned(
&method.sig,
"unsupported child method signature: a #[child] method must take `&self` \
(shapes: `fn NAME(&self) -> Child` or `fn NAME(&self, name: &str) -> Option<Child>`)",
));
}
let kind = match typed_params.len() {
0 => ChildMethodKind::Static,
1 => {
let pt = typed_params[0];
if !is_str_ref(&pt.ty) {
return Err(syn::Error::new_spanned(
&pt.ty,
"unsupported child method signature: the single parameter of a dynamic \
#[child] method must be `name: &str` \
(shapes: `fn NAME(&self) -> Child` or `fn NAME(&self, name: &str) -> Option<Child>`)",
));
}
ChildMethodKind::Dynamic
}
_ => {
return Err(syn::Error::new_spanned(
&method.sig,
"unsupported child method signature: #[child] methods accept either \
no extra arguments (static child) or a single `name: &str` argument \
(dynamic child)",
));
}
};
let return_ty = match &method.sig.output {
ReturnType::Type(_, ty) => (**ty).clone(),
ReturnType::Default => {
return Err(syn::Error::new_spanned(
&method.sig,
"unsupported child method signature: a #[child] method must declare a return type \
(either `-> Child` for a static child or `-> Option<Child>` for a dynamic child)",
));
}
};
let (peer, opaque) = if is_peer {
if !matches!(kind, ChildMethodKind::Dynamic) || !is_async {
return Err(syn::Error::new_spanned(
&method.sig,
"a #[plexus_macros::peer] method is `async fn NAME(&self, name: &str) -> \
Result<Box<dyn I>, PeerError>`",
));
}
let shape = crate::codegen::peer::peer_shape(&return_ty).map_err(|why| syn::Error::new_spanned(&return_ty, why))?;
(Some(shape), true)
} else {
(None, opaque)
};
Ok(ChildMethodInfo {
fn_name,
description,
kind,
is_async,
list_fn,
search_fn,
opaque,
deprecation,
forward,
return_ty,
peer,
list_is_async: false,
string_args,
})
}
}
#[allow(clippy::type_complexity)]
fn parse_child_attr_args(
attrs: &[syn::Attribute],
) -> syn::Result<(Option<syn::Ident>, Option<syn::Ident>, Option<ChildForward>, bool, Vec<(String, proc_macro2::Span)>)> {
const EXPECTED: &str = "expected `list = method`, `search = method`, `forward = policy` or `opaque`";
let mut list_fn: Option<syn::Ident> = None;
let mut search_fn: Option<syn::Ident> = None;
let mut forward: Option<ChildForward> = None;
let mut opaque = false;
let mut string_args: Vec<(String, proc_macro2::Span)> = Vec::new();
for attr in attrs {
let path = attr.path();
let last = path.segments.last().map(|s| s.ident.to_string());
if !matches!(last.as_deref(), Some("child") | Some("peer")) {
continue;
}
match &attr.meta {
Meta::Path(_) => {}
Meta::List(list) => {
let metas = list.parse_args_with(
Punctuated::<Meta, Token![,]>::parse_terminated,
)?;
for meta in metas {
match meta {
Meta::Path(ref p) if p.is_ident("opaque") => {
if opaque {
return Err(syn::Error::new_spanned(p, "duplicate `opaque` on #[plexus_macros::child]"));
}
opaque = true;
}
Meta::NameValue(MetaNameValue { path, value, .. }) => {
let ident_key = match path.get_ident() {
Some(id) => id.to_string(),
None => {
return Err(syn::Error::new_spanned(
&path,
format!("unknown argument to #[plexus_macros::child]; {EXPECTED}"),
));
}
};
let (word, span, was_string) = match value {
Expr::Lit(ExprLit { lit: Lit::Str(ref s), .. }) => (s.value(), s.span(), true),
Expr::Path(ref p) if p.qself.is_none() && p.path.get_ident().is_some() => {
let id = p.path.get_ident().unwrap();
(id.to_string(), id.span(), false)
}
_ => {
return Err(syn::Error::new_spanned(
&value,
format!(
"#[plexus_macros::child({ident_key} = …)] expects the name of a sibling method \
(`{ident_key} = method`)",
),
));
}
};
if ident_key == "forward" {
if forward.is_some() {
return Err(syn::Error::new(
span,
"duplicate `forward = …` argument on #[plexus_macros::child]",
));
}
forward = Some(ChildForward::parse(&word).ok_or_else(|| {
syn::Error::new(
span,
format!(
"unknown forward policy `{word}` on #[plexus_macros::child]; expected {}",
ChildForward::SPELLINGS
),
)
})?);
continue;
}
let method_ident = syn::parse_str::<syn::Ident>(&word)
.map(|mut i| {
i.set_span(span);
i
})
.map_err(|_| syn::Error::new(span, format!("`{word}` is not a method name")))?;
match ident_key.as_str() {
"list" => {
if list_fn.is_some() {
return Err(syn::Error::new(
span,
"duplicate `list = …` argument on #[plexus_macros::child]",
));
}
list_fn = Some(method_ident);
}
"search" => {
if search_fn.is_some() {
return Err(syn::Error::new(
span,
"duplicate `search = …` argument on #[plexus_macros::child]",
));
}
search_fn = Some(method_ident);
}
other => {
return Err(syn::Error::new_spanned(
&path,
format!("unknown argument `{other}` to #[plexus_macros::child]; {EXPECTED}"),
));
}
}
if was_string {
string_args.push((ident_key, span));
}
}
other => {
let word = other.path().get_ident().map(|i| i.to_string()).unwrap_or_default();
return Err(syn::Error::new_spanned(
other,
format!("unknown word `{word}` in #[plexus_macros::child] / #[plexus_macros::peer]; {EXPECTED}"),
));
}
}
}
}
Meta::NameValue(_) => {
return Err(syn::Error::new_spanned(
attr,
"#[plexus_macros::child = ...] form is not supported; \
use `#[plexus_macros::child]` or `#[plexus_macros::child(list = method, search = method)]`",
));
}
}
}
Ok((list_fn, search_fn, forward, opaque, string_args))
}
#[derive(Debug, Clone, Copy)]
pub enum ListSearchReturnShape {
ImplStream,
BoxStream,
}
#[derive(Debug, Clone)]
pub struct ListSearchMethodInfo {
pub fn_name: syn::Ident,
pub is_async: bool,
#[allow(dead_code)]
pub return_shape: ListSearchReturnShape,
}
#[derive(Debug, Clone, Copy)]
pub enum ListSearchKind {
List,
Search,
}
pub fn find_and_validate_list_search_method(
items: &[ImplItem],
name: &syn::Ident,
kind: ListSearchKind,
attr_owner: &syn::Ident,
) -> syn::Result<ListSearchMethodInfo> {
let method: &ImplItemFn = items
.iter()
.find_map(|it| match it {
ImplItem::Fn(f) if f.sig.ident == *name => Some(f),
_ => None,
})
.ok_or_else(|| {
syn::Error::new(
name.span(),
format!(
"method `{}` referenced by #[plexus_macros::child({} = {})] \
on `{}` not found in impl",
name,
match kind {
ListSearchKind::List => "list",
ListSearchKind::Search => "search",
},
name,
attr_owner,
),
)
})?;
let mut has_receiver = false;
let mut typed_params: Vec<&syn::PatType> = Vec::new();
for arg in method.sig.inputs.iter() {
match arg {
FnArg::Receiver(_) => has_receiver = true,
FnArg::Typed(pt) => typed_params.push(pt),
}
}
if !has_receiver {
return Err(syn::Error::new_spanned(
&method.sig,
format!(
"child method signature mismatch: `{}` must take `&self` (expected shape: `(async) fn {}({}) -> impl Stream<Item = String>` or `-> BoxStream<'_, String>`)",
name,
name,
match kind {
ListSearchKind::List => "&self",
ListSearchKind::Search => "&self, query: &str",
},
),
));
}
match kind {
ListSearchKind::List => {
if !typed_params.is_empty() {
return Err(syn::Error::new_spanned(
&method.sig,
format!(
"child method signature mismatch: list method `{}` must take only `&self` (got {} extra parameter{}); expected `(async) fn {}(&self) -> impl Stream<Item = String>` or `-> BoxStream<'_, String>`",
name,
typed_params.len(),
if typed_params.len() == 1 { "" } else { "s" },
name,
),
));
}
}
ListSearchKind::Search => {
if typed_params.len() != 1 {
return Err(syn::Error::new_spanned(
&method.sig,
format!(
"child method signature mismatch: search method `{}` must take `&self` and exactly one `query: &str` parameter (got {}); expected `(async) fn {}(&self, query: &str) -> impl Stream<Item = String>` or `-> BoxStream<'_, String>`",
name,
typed_params.len(),
name,
),
));
}
if !is_str_ref(&typed_params[0].ty) {
return Err(syn::Error::new_spanned(
&typed_params[0].ty,
format!(
"child method signature mismatch: the query parameter of search method `{}` must be `&str`",
name
),
));
}
}
}
let return_ty = match &method.sig.output {
ReturnType::Default => {
return Err(syn::Error::new_spanned(
&method.sig,
format!(
"child method signature mismatch: `{}` must declare a return type of \
`impl Stream<Item = String>` or `BoxStream<'_, String>`",
name
),
));
}
ReturnType::Type(_, ty) => ty.as_ref(),
};
let return_shape = classify_string_stream_return(return_ty).ok_or_else(|| {
syn::Error::new_spanned(
return_ty,
format!(
"child method signature mismatch: `{}` must return `impl Stream<Item = String>` or `BoxStream<'_, String>`",
name,
),
)
})?;
Ok(ListSearchMethodInfo {
fn_name: method.sig.ident.clone(),
is_async: method.sig.asyncness.is_some(),
return_shape,
})
}
fn classify_string_stream_return(ty: &Type) -> Option<ListSearchReturnShape> {
if let Type::ImplTrait(impl_trait) = ty {
for bound in &impl_trait.bounds {
if let syn::TypeParamBound::Trait(tb) = bound {
let last = tb.path.segments.last()?;
if last.ident == "Stream" {
if let PathArguments::AngleBracketed(args) = &last.arguments {
for arg in &args.args {
if let GenericArgument::AssocType(at) = arg {
if at.ident == "Item" && type_is_string(&at.ty) {
return Some(ListSearchReturnShape::ImplStream);
}
}
}
}
}
}
}
return None;
}
if let Type::Path(tp) = ty {
let last = tp.path.segments.last()?;
if last.ident == "BoxStream" {
if let PathArguments::AngleBracketed(args) = &last.arguments {
for arg in &args.args {
if let GenericArgument::Type(inner) = arg {
if type_is_string(inner) {
return Some(ListSearchReturnShape::BoxStream);
}
}
}
}
}
}
None
}
fn type_is_string(ty: &Type) -> bool {
if let Type::Path(tp) = ty {
if let Some(seg) = tp.path.segments.last() {
return seg.ident == "String" && matches!(seg.arguments, PathArguments::None);
}
}
false
}
pub(crate) fn is_str_ref(ty: &Type) -> bool {
if let Type::Reference(r) = ty {
if r.mutability.is_some() {
return false;
}
if let Type::Path(tp) = &*r.elem {
if let Some(seg) = tp.path.segments.last() {
return seg.ident == "str" && tp.path.segments.len() == 1;
}
}
}
false
}
pub fn parse_deprecation_attrs(
attrs: &[syn::Attribute],
item_span: proc_macro2::Span,
) -> syn::Result<Option<ParsedDeprecation>> {
let deprecated_attr = attrs.iter().find(|a| a.path().is_ident("deprecated"));
let removed_in_attr = attrs.iter().find(|a| {
let segs = &a.path().segments;
segs.last()
.map(|s| s.ident == "removed_in")
.unwrap_or(false)
});
let removed_in_from_sentinel: Option<String> = attrs
.iter()
.filter(|a| a.path().is_ident("doc"))
.filter_map(|a| {
if let Meta::NameValue(MetaNameValue { value, .. }) = &a.meta {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
let v = s.value();
if let Some(rest) = v.strip_prefix("__plexus_removed_in:") {
return Some(rest.to_string());
}
}
}
None
})
.next();
if deprecated_attr.is_none() && removed_in_attr.is_none() && removed_in_from_sentinel.is_none() {
return Ok(None);
}
if deprecated_attr.is_none() {
let err_span = removed_in_attr
.map(|a| a.span())
.unwrap_or_else(proc_macro2::Span::call_site);
return Err(syn::Error::new(
err_span,
"#[plexus_macros::removed_in(\"...\")] requires a companion \
#[deprecated] attribute on the same item — `removed_in` by itself \
has no meaning. Add `#[deprecated(since = \"...\", note = \"...\")]` \
alongside, or remove the `#[removed_in]` attribute.",
));
}
let mut since = String::new();
let mut message = String::new();
let mut removed_in_from_deprecated: Option<String> = None;
let deprecated_attr = deprecated_attr.unwrap();
match &deprecated_attr.meta {
Meta::Path(_) => {}
Meta::List(list) => {
let inner: Punctuated<Meta, Token![,]> =
list.parse_args_with(Punctuated::<Meta, Token![,]>::parse_terminated)?;
for meta in inner {
if let Meta::NameValue(MetaNameValue { path, value, .. }) = meta {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
if path.is_ident("since") {
since = s.value();
} else if path.is_ident("note") {
message = s.value();
} else if path.is_ident("removed_in") {
removed_in_from_deprecated = Some(s.value());
}
}
}
}
}
Meta::NameValue(_) => {
if let Meta::NameValue(MetaNameValue { value, .. }) = &deprecated_attr.meta {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
message = s.value();
}
}
}
}
let mut removed_in_from_companion: Option<String> = None;
if let Some(attr) = removed_in_attr {
match &attr.meta {
Meta::List(list) => {
let s: syn::LitStr = syn::parse2(list.tokens.clone()).map_err(|_| {
syn::Error::new_spanned(
&list.tokens,
"#[plexus_macros::removed_in(\"...\")] expects a single string \
literal argument (e.g. #[plexus_macros::removed_in(\"0.7\")])",
)
})?;
removed_in_from_companion = Some(s.value());
}
Meta::NameValue(MetaNameValue { value, .. }) => {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
removed_in_from_companion = Some(s.value());
} else {
return Err(syn::Error::new_spanned(
value,
"#[plexus_macros::removed_in = \"...\"] expects a string literal",
));
}
}
Meta::Path(_) => {
return Err(syn::Error::new(
attr.span(),
"#[plexus_macros::removed_in] requires an argument (e.g. \
#[plexus_macros::removed_in(\"0.7\")])",
));
}
}
}
let removed_in = removed_in_from_companion
.or(removed_in_from_sentinel)
.or(removed_in_from_deprecated)
.unwrap_or_else(|| DEPRECATION_REMOVED_IN_UNSPECIFIED.to_string());
let _ = item_span; Ok(Some(ParsedDeprecation {
since,
removed_in,
message,
}))
}
pub fn has_child_attr(method: &ImplItemFn) -> bool {
method.attrs.iter().any(|a| {
let path = a.path();
path.segments
.last()
.map(|s| s.ident == "child" || s.ident == "peer")
.unwrap_or(false)
})
}
pub fn has_method_attr(method: &ImplItemFn) -> bool {
method.attrs.iter().any(|a| {
let last = a.path().segments.last().map(|s| s.ident.to_string());
matches!(last.as_deref(), Some("method") | Some("hub_method"))
})
}
#[derive(Clone)]
pub struct ParentParam {
pub name: syn::Ident,
pub at: usize,
pub client: Type,
pub ty: Type,
}
pub(crate) fn parent_client_type(ty: &Type) -> Option<Type> {
let Type::Path(tp) = ty else { return None };
let last = tp.path.segments.last()?;
if last.ident != "Parent" {
return None;
}
let syn::PathArguments::AngleBracketed(args) = &last.arguments else { return None };
match args.args.first()? {
syn::GenericArgument::Type(t) if args.args.len() == 1 => Some(t.clone()),
_ => None,
}
}
pub struct MethodInfo {
pub parent: Option<ParentParam>,
pub uses: Vec<String>,
pub parent_chains: Vec<Vec<String>>,
pub fn_name: syn::Ident,
pub method_name: String,
pub description: String,
pub params: Vec<ParamInfo>,
pub cardinality: Cardinality,
pub streaming_deprecated: Option<proc_macro2::Span>,
pub ok_ty: Type,
pub err_ty: Option<Type>,
pub progress_ty: Option<ProgressTy>,
pub http_method: Option<String>,
pub requires_auth: bool,
pub auth_optional: bool,
pub auth_resolvers: Vec<AuthResolver>,
pub activation_params: Vec<ActivationParamInfo>,
pub request_override: Option<MethodRequestOverride>,
pub public: bool,
pub everywhere: bool,
pub scopes: Vec<String>,
pub deprecation: Option<ParsedDeprecation>,
pub target: Option<String>,
pub answer_by: Option<String>,
pub input: Option<InputInfo>,
pub long_description: Option<String>,
pub group: Option<String>,
pub examples: Vec<ParsedExample>,
pub values: Vec<(String, Vec<String>)>,
pub takes_reach: bool,
pub verifier: Option<syn::Expr>,
pub caller_required: bool,
}
pub(crate) fn long_description_from(doc: &str, description: &str) -> Option<String> {
let doc = doc.trim();
let desc = description.trim();
let rest = if !desc.is_empty() && doc.starts_with(desc) {
doc[desc.len()..].trim_start_matches(|c: char| c == '.' || c == ':' || c == ';' || c.is_whitespace())
} else {
doc
};
let rest = rest.trim();
if rest.is_empty() || rest == desc {
None
} else {
Some(rest.to_string())
}
}
fn is_reach_type(ty: &Type) -> bool {
if let Type::Path(tp) = ty {
if let Some(last) = tp.path.segments.last() {
return last.ident == "Reach" && matches!(last.arguments, syn::PathArguments::None);
}
}
false
}
impl MethodInfo {
pub fn from_fn(method: &ImplItemFn, hub_method_attrs: Option<&HubMethodAttrs>) -> syn::Result<Self> {
let fn_name = method.sig.ident.clone();
let method_name = hub_method_attrs
.and_then(|a| a.name.clone())
.unwrap_or_else(|| fn_name.to_string());
let (description, long_description) = match hub_method_attrs.and_then(|a| a.description.clone()) {
Some(explicit) => {
let long = extract_doc_description(&method.attrs)
.and_then(|doc| long_description_from(&doc, &explicit));
(explicit, long)
}
None => (extract_doc_description(&method.attrs).unwrap_or_default(), None),
};
let param_docs = hub_method_attrs
.map(|a| &a.param_docs)
.cloned()
.unwrap_or_default();
let http_method = hub_method_attrs
.and_then(|a| a.http_method.clone());
let request_override = hub_method_attrs
.and_then(|a| a.request_override.clone());
let mut requires_auth = false;
let mut auth_optional = false;
let mut auth_resolvers: Vec<AuthResolver> = Vec::new();
let mut activation_params: Vec<ActivationParamInfo> = Vec::new();
let mut params = Vec::new();
let mut takes_reach = false;
let mut typed_index = 0usize;
let mut auth_at: Option<usize> = None;
let mut input: Option<InputInfo> = None;
let mut parent: Option<ParentParam> = None;
for arg in &method.sig.inputs {
if let FnArg::Typed(pat_type) = arg {
let this_index = typed_index;
typed_index += 1;
if let Pat::Ident(ident) = &*pat_type.pat {
let name = ident.ident.clone();
let name_str = name.to_string();
if parent.is_some()
&& ((name_str == "reach" && is_reach_type(&pat_type.ty))
|| has_activation_param_attr(&pat_type.attrs)
|| extract_from_auth_attr(&pat_type.attrs).is_some()
|| (name_str == "auth" && classify_auth_context_type(&pat_type.ty).is_some()))
{
return Err(syn::Error::new_spanned(
pat_type,
"`parent: Parent<…>` comes after `auth`, `reach`, `#[from_auth]` and `#[activation_param]` parameters",
));
}
if let Some(client) = parent_client_type(&pat_type.ty) {
if let Some(first) = &parent {
return Err(syn::Error::new_spanned(
pat_type,
format!("`{method_name}` takes a second `Parent` (the first is `{}`): a method takes at most one", first.name),
));
}
let at = params.len() + usize::from(input.is_some());
parent = Some(ParentParam { name, at, client, ty: (*pat_type.ty).clone() });
continue;
}
if name_str == "reach" && is_reach_type(&pat_type.ty) {
let first = this_index == 0 || auth_at == Some(this_index - 1);
if !first {
return Err(syn::Error::new_spanned(
pat_type,
"`reach: Reach` must be the first parameter after `&self`, \
or come right after `auth`",
));
}
takes_reach = true;
continue;
}
if let Some(err) = check_activation_param_attr(&pat_type.attrs)? {
return Err(err);
}
if has_activation_param_attr(&pat_type.attrs) {
activation_params.push(ActivationParamInfo {
param_name: name,
ty: (*pat_type.ty).clone(),
});
continue;
}
if let Some(resolver) = extract_from_auth_attr(&pat_type.attrs) {
requires_auth = true;
auth_resolvers.push(AuthResolver {
param_name: name,
resolver_expr: resolver,
});
continue;
}
if name_str == "auth" {
if let Some(shape) = classify_auth_context_type(&pat_type.ty) {
requires_auth = true;
auth_optional = matches!(shape, AuthParamShape::Optional);
auth_at = Some(this_index);
continue;
}
}
if let Some(item) = input_item_type(&pat_type.ty) {
if let Some(first) = &input {
return Err(syn::Error::new_spanned(
pat_type,
format!("`{method_name}` declares a second `Input` (the first is `{}`): a method takes at most one", first.name),
));
}
let description = param_docs.get(&name_str).cloned().or_else(|| extract_doc_description(&pat_type.attrs));
let ceiling = hub_method_attrs.map(|a| a.input_ceiling.clone()).unwrap_or_default();
input = Some(InputInfo { name, item, at: params.len(), description, ceiling });
continue;
}
if names_input(pat_type.ty.to_token_stream()) {
return Err(syn::Error::new_spanned(
&pat_type.ty,
format!("`{method_name}`: `Input` is a parameter of the method itself, by value: it cannot be nested in another type"),
));
}
let description = param_docs
.get(&name_str)
.cloned()
.or_else(|| extract_doc_description(&pat_type.attrs));
let deprecation =
parse_deprecation_attrs(&pat_type.attrs, pat_type.span())?;
params.push(ParamInfo {
name,
ty: (*pat_type.ty).clone(),
description,
deprecation,
});
}
}
}
let ReturnShape { cardinality, ok_ty, err_ty, progress_ty } =
classify_return(&method.sig)?;
let streaming_deprecated = hub_method_attrs.and_then(|a| a.streaming);
if let (Some(span), Cardinality::One) = (streaming_deprecated, cardinality) {
let returns = match &method.sig.output {
ReturnType::Type(_, ty) => quote::quote!(#ty).to_string(),
ReturnType::Default => "()".to_string(),
};
return Err(syn::Error::new(
span,
format!(
"`streaming` says this method yields many items, but `-> {returns}` yields one. \
Remove `streaming` (cardinality comes from the return type), or return \
`impl Stream<Item = ...>`."
),
));
}
let deprecation = parse_deprecation_attrs(&method.attrs, method.sig.span())?;
let public = hub_method_attrs.map(|a| a.public).unwrap_or(false);
let everywhere = hub_method_attrs.is_some_and(|a| a.everywhere);
let scopes = hub_method_attrs
.map(|a| a.scopes.clone())
.unwrap_or_default();
let target = match hub_method_attrs.and_then(|a| a.target.as_ref()) {
None => None,
Some(lit) => {
let wanted = lit.value();
if !params.iter().any(|p: &ParamInfo| p.name == wanted.as_str()) {
let known: Vec<String> = params.iter().map(|p| p.name.to_string()).collect();
return Err(syn::Error::new(
lit.span(),
format!(
"target = \"{}\" names no parameter of `{}`; its parameters are: {}",
wanted,
fn_name,
if known.is_empty() { "(none)".to_string() } else { known.join(", ") },
),
));
}
Some(wanted)
}
};
let answer_by = match hub_method_attrs.and_then(|a| a.answer_by.as_ref()) {
None => None,
Some(lit) => match answer_by_declared(&lit.value()) {
Ok(declared) => declared,
Err(()) => {
return Err(syn::Error::new(
lit.span(),
format!(
"answer_by = \"{}\" on `{}`: who may answer is one of `caller` (the default), \
`person`, or `grant:<activation.method>`",
lit.value(),
fn_name,
),
))
}
},
};
let ceiling = hub_method_attrs.map(|a| a.input_ceiling.clone()).unwrap_or_default();
if input.is_none() {
if let Some((name, lit)) = ceiling.first() {
return Err(syn::Error::new(lit.span(), format!("{name} on `{fn_name}`, which has no `Input` parameter")));
}
}
if let Some(window) = &ceiling.window {
if window.base10_parse::<u64>()? == 0 {
return Err(syn::Error::new(window.span(), format!("input_window on `{fn_name}`: a window of 0 lets nothing in")));
}
}
let known_params = || -> String {
let known: Vec<String> = params.iter().map(|p: &ParamInfo| p.name.to_string()).collect();
if known.is_empty() { "(none)".to_string() } else { known.join(", ") }
};
let mut values: Vec<(String, Vec<String>)> = Vec::new();
for (ident, vals) in hub_method_attrs.map(|a| a.values.clone()).unwrap_or_default() {
if !params.iter().any(|p: &ParamInfo| p.name == ident) {
return Err(syn::Error::new(
ident.span(),
format!(
"values(...) names `{}`, no parameter of `{}`; its parameters are: {}",
ident, fn_name, known_params(),
),
));
}
values.push((ident.to_string(), vals));
}
let examples = hub_method_attrs.map(|a| a.examples.clone()).unwrap_or_default();
for ex in &examples {
for key in &ex.keys {
if !params.iter().any(|p: &ParamInfo| p.name == key.as_str()) {
return Err(syn::Error::new(
ex.span,
format!(
"example params name `{}`, no parameter of `{}`; its parameters are: {}",
key, fn_name, known_params(),
),
));
}
}
}
let group = hub_method_attrs.and_then(|a| a.group.clone());
Ok(MethodInfo {
parent,
uses: hub_method_attrs.map(|a| a.uses.clone()).unwrap_or_default(),
parent_chains: Vec::new(),
fn_name,
method_name,
description,
params,
cardinality,
streaming_deprecated,
ok_ty,
err_ty,
progress_ty,
http_method,
requires_auth,
auth_optional,
auth_resolvers,
activation_params,
request_override,
public,
everywhere,
scopes,
deprecation,
target,
answer_by,
input,
long_description,
group,
examples,
values,
takes_reach,
verifier: None,
caller_required: false,
})
}
}
fn expr_to_type(expr: &Expr) -> Option<syn::Type> {
match expr {
Expr::Path(ExprPath { attrs: _, qself, path }) => {
Some(syn::Type::Path(syn::TypePath {
qself: qself.as_ref().map(|qs| syn::QSelf {
lt_token: qs.lt_token,
ty: qs.ty.clone(),
position: qs.position,
as_token: qs.as_token,
gt_token: qs.gt_token,
}),
path: path.clone(),
}))
}
Expr::Tuple(ExprTuple { elems, .. }) if elems.is_empty() => {
Some(syn::parse_quote! { () })
}
_ => None,
}
}
fn has_activation_param_attr(attrs: &[syn::Attribute]) -> bool {
attrs.iter().any(|attr| attr.path().is_ident("activation_param"))
}
fn check_activation_param_attr(attrs: &[syn::Attribute]) -> syn::Result<Option<syn::Error>> {
for attr in attrs {
if attr.path().is_ident("activation_param") {
if let syn::Meta::List(list) = &attr.meta {
return Ok(Some(syn::Error::new_spanned(
list,
"activation_param takes no arguments — extraction is defined on the request struct, not the method",
)));
}
}
}
Ok(None)
}
fn extract_from_auth_attr(attrs: &[syn::Attribute]) -> Option<syn::Expr> {
for attr in attrs {
if attr.path().is_ident("from_auth") {
let expr: syn::Expr = attr.parse_args().ok()?;
return Some(expr);
}
}
None
}
pub(crate) fn classify_auth_context_type(ty: &Type) -> Option<AuthParamShape> {
if let Type::Reference(type_ref) = ty {
if let Type::Path(type_path) = &*type_ref.elem {
if let Some(last_segment) = type_path.path.segments.last() {
if last_segment.ident == "AuthContext" {
return Some(AuthParamShape::Required);
}
}
}
}
if let Type::Path(type_path) = ty {
if let Some(last_segment) = type_path.path.segments.last() {
if last_segment.ident == "Option" {
if let PathArguments::AngleBracketed(args) = &last_segment.arguments {
if let Some(GenericArgument::Type(inner_ty)) = args.args.first() {
if classify_auth_context_type(inner_ty)
== Some(AuthParamShape::Required)
{
return Some(AuthParamShape::Optional);
}
}
}
}
}
}
None
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AuthParamShape {
Required,
Optional,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Cardinality {
One,
Many,
}
#[derive(Debug, Clone)]
pub enum ProgressTy {
Note,
Declared(Type),
}
impl ProgressTy {
pub fn to_type(&self, vocabulary: &syn::Path) -> Type {
match self {
ProgressTy::Note => syn::parse_quote!(#vocabulary::Note),
ProgressTy::Declared(ty) => ty.clone(),
}
}
}
pub struct ReturnShape {
pub cardinality: Cardinality,
pub ok_ty: Type,
pub err_ty: Option<Type>,
pub progress_ty: Option<ProgressTy>,
}
const SIX_FORMS: &str = "\
-> T\n \
-> Result<T, E>\n \
-> impl Stream<Item = T>\n \
-> impl Stream<Item = Result<T, E>>\n \
-> impl Stream<Item = Progress<T, P>>\n \
-> impl Stream<Item = Result<Progress<T, P>, E>>";
fn not_a_form(span: impl quote::ToTokens, method: &syn::Ident) -> syn::Error {
syn::Error::new_spanned(
span,
format!(
"#[plexus_macros::method] `{method}`: the return type is not one of the six \
signature forms:\n {SIX_FORMS}\n\
A boxed or named stream (`BoxStream`, `Pin<Box<dyn Stream>>`, `PlexusStream`) is \
not recognised — return `impl Stream<Item = ...> + Send + 'static` instead. \
`Result` (two type arguments) and `Progress` (one or two) are recognised by \
name; an alias of either is a plain `T`."
),
)
}
pub fn classify_return(sig: &syn::Signature) -> syn::Result<ReturnShape> {
let method = &sig.ident;
let ty = match &sig.output {
ReturnType::Default => return Err(not_a_form(sig, method)),
ReturnType::Type(_, ty) => ungroup(ty),
};
let (item, cardinality) = match ty {
Type::ImplTrait(it) => (
impl_stream_item(it).ok_or_else(|| not_a_form(ty, method))?,
Cardinality::Many,
),
_ => (ty, Cardinality::One),
};
let (inner, err_ty) = match result_args(item) {
Some((t, e)) => (t, Some(e)),
None => (item, None),
};
let (ok_ty, progress_ty) = match progress_args(inner) {
Some((t, p)) => (t, Some(p)),
None => (inner, None),
};
if progress_ty.is_some() && cardinality == Cardinality::One {
return Err(syn::Error::new_spanned(
ty,
format!(
"#[plexus_macros::method] `{method}`: a method that reports progress yields \
many items — return `impl Stream<Item = Progress<T, P>>` (or \
`impl Stream<Item = Result<Progress<T, P>, E>>`). A one-item method \
cannot report progress."
),
));
}
for part in [Some(ok_ty), err_ty].into_iter().flatten() {
if !is_plain_item(part) {
return Err(not_a_form(part, method));
}
}
if let Some(ProgressTy::Declared(p)) = &progress_ty {
if !is_plain_item(p) {
return Err(not_a_form(p, method));
}
}
Ok(ReturnShape {
cardinality,
ok_ty: ok_ty.clone(),
err_ty: err_ty.cloned(),
progress_ty,
})
}
fn ungroup(ty: &Type) -> &Type {
match ty {
Type::Paren(p) => ungroup(&p.elem),
Type::Group(g) => ungroup(&g.elem),
other => other,
}
}
fn impl_stream_item(it: &syn::TypeImplTrait) -> Option<&Type> {
it.bounds.iter().find_map(|bound| {
let syn::TypeParamBound::Trait(tb) = bound else { return None };
let last = tb.path.segments.last()?;
if last.ident != "Stream" {
return None;
}
let PathArguments::AngleBracketed(args) = &last.arguments else { return None };
args.args.iter().find_map(|arg| match arg {
GenericArgument::AssocType(at) if at.ident == "Item" => Some(ungroup(&at.ty)),
_ => None,
})
})
}
fn type_args<'a>(ty: &'a Type, name: &str) -> Option<Vec<&'a Type>> {
let Type::Path(tp) = ty else { return None };
if tp.qself.is_some() {
return None;
}
let last = tp.path.segments.last()?;
if last.ident != name {
return None;
}
let PathArguments::AngleBracketed(args) = &last.arguments else { return None };
let tys: Vec<&Type> = args
.args
.iter()
.filter_map(|a| match a {
GenericArgument::Type(t) => Some(ungroup(t)),
_ => None,
})
.collect();
(tys.len() == args.args.len()).then_some(tys)
}
fn result_args(ty: &Type) -> Option<(&Type, &Type)> {
match type_args(ty, "Result")?.as_slice() {
[t, e] => Some((t, e)),
_ => None,
}
}
fn progress_args(ty: &Type) -> Option<(&Type, ProgressTy)> {
match type_args(ty, "Progress")?.as_slice() {
[t] => Some((t, ProgressTy::Note)),
[t, p] => Some((t, ProgressTy::Declared((*p).clone()))),
_ => None,
}
}
fn is_plain_item(ty: &Type) -> bool {
match ungroup(ty) {
Type::ImplTrait(_) | Type::TraitObject(_) => false,
Type::Path(tp) => {
let Some(last) = tp.path.segments.last() else { return true };
let name = last.ident.to_string();
if matches!(
name.as_str(),
"BoxStream" | "LocalBoxStream" | "PlexusStream" | "Stream" | "Pin"
) {
return false;
}
if name == "Box" {
if let Some(args) = type_args(ty, "Box") {
return !args.iter().any(|t| matches!(t, Type::TraitObject(_)));
}
}
true
}
_ => true,
}
}
pub(crate) fn extract_doc_description(attrs: &[syn::Attribute]) -> Option<String> {
let mut raw_lines: Vec<String> = Vec::new();
for attr in attrs {
if attr.path().is_ident("doc") {
if let Meta::NameValue(MetaNameValue { value, .. }) = &attr.meta {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
for line in s.value().split('\n') {
raw_lines.push(line.to_string());
}
}
}
}
}
if raw_lines.is_empty() {
return None;
}
Some(strip_common_leading_whitespace(&raw_lines))
}
fn strip_common_leading_whitespace(lines: &[String]) -> String {
let min_indent = lines
.iter()
.filter(|l| !l.trim().is_empty())
.map(|l| l.chars().take_while(|c| c.is_whitespace()).count())
.min()
.unwrap_or(0);
lines
.iter()
.map(|l| {
if l.trim().is_empty() {
String::new()
} else {
l.chars().skip(min_indent).collect::<String>()
}
})
.collect::<Vec<_>>()
.join("\n")
}
fn answer_by_declared(text: &str) -> Result<Option<String>, ()> {
match text.trim() {
"caller" => Ok(None),
"person" => Ok(Some("person".into())),
t => match t.strip_prefix("grant:") {
Some(g) if g.contains('.') && !g.contains(char::is_whitespace) => Ok(Some(format!("grant:{g}"))),
_ => Err(()),
},
}
}
#[cfg(test)]
mod tests {
use super::*;
use proc_macro2::Span;
use syn::parse_quote;
#[test]
fn parse_deprecation_reads_inline_removed_in_key() {
let attrs: Vec<syn::Attribute> =
vec![parse_quote! { #[deprecated(since = "0.5", note = "use bar", removed_in = "0.7")] }];
let parsed = parse_deprecation_attrs(&attrs, Span::call_site())
.expect("parser accepts unknown key")
.expect("produces Some for a #[deprecated] attr");
assert_eq!(parsed.since, "0.5");
assert_eq!(parsed.removed_in, "0.7");
assert_eq!(parsed.message, "use bar");
}
#[test]
fn parse_deprecation_companion_overrides_inline_key() {
let attrs: Vec<syn::Attribute> = vec![
parse_quote! { #[deprecated(since = "0.5", note = "n", removed_in = "0.7")] },
parse_quote! { #[plexus_macros::removed_in("0.9")] },
];
let parsed = parse_deprecation_attrs(&attrs, Span::call_site()).unwrap().unwrap();
assert_eq!(parsed.removed_in, "0.9");
}
#[test]
fn parse_deprecation_fallback_is_unspecified() {
let attrs: Vec<syn::Attribute> =
vec![parse_quote! { #[deprecated(since = "0.5", note = "n")] }];
let parsed = parse_deprecation_attrs(&attrs, Span::call_site()).unwrap().unwrap();
assert_eq!(parsed.removed_in, DEPRECATION_REMOVED_IN_UNSPECIFIED);
}
#[test]
fn parse_deprecation_bare_emits_empty_since_and_message() {
let attrs: Vec<syn::Attribute> = vec![parse_quote! { #[deprecated] }];
let parsed = parse_deprecation_attrs(&attrs, Span::call_site()).unwrap().unwrap();
assert_eq!(parsed.since, "");
assert_eq!(parsed.message, "");
assert_eq!(parsed.removed_in, DEPRECATION_REMOVED_IN_UNSPECIFIED);
}
#[test]
fn parse_deprecation_companion_without_deprecated_errors() {
let attrs: Vec<syn::Attribute> =
vec![parse_quote! { #[plexus_macros::removed_in("0.6")] }];
let err = parse_deprecation_attrs(&attrs, Span::call_site())
.expect_err("removed_in alone must error");
let msg = err.to_string();
assert!(
msg.contains("#[deprecated]"),
"error must name #[deprecated] as required companion; got: {}",
msg
);
}
#[test]
fn parse_deprecation_no_attrs_yields_none() {
let attrs: Vec<syn::Attribute> = vec![parse_quote! { #[doc = "just a comment"] }];
let parsed = parse_deprecation_attrs(&attrs, Span::call_site()).unwrap();
assert!(parsed.is_none());
}
#[test]
fn param_doc_comment_falls_back_when_params_attr_omits_entry() {
let method: ImplItemFn = parse_quote! {
async fn echo(
&self,
message: String,
) -> impl Stream<Item = MyEvent> + Send + 'static {
stream! { yield MyEvent::Echo { message } }
}
};
let info = MethodInfo::from_fn(&method, None).expect("parses cleanly");
let param = info.params.iter().find(|p| p.name == "message").unwrap();
assert_eq!(
param.description.as_deref(),
Some("The message to echo back"),
"param doc comment should fall back into the description when no params(...) entry exists"
);
}
#[test]
fn explicit_params_attr_wins_over_param_doc_comment() {
let method: ImplItemFn = parse_quote! {
async fn echo(
&self,
message: String,
) -> impl Stream<Item = MyEvent> + Send + 'static {
stream! { yield MyEvent::Echo { message } }
}
};
let attrs = HubMethodAttrs {
uses: vec![],
name: None,
description: None,
param_docs: {
let mut m = HashMap::new();
m.insert("message".to_string(), "explicit description".to_string());
m
},
http_method: None,
request_override: None,
public: false,
scopes: vec![],
streaming: None,
target: None,
answer_by: None,
input_ceiling: InputCeilingAttrs::default(),
group: None,
examples: vec![],
values: vec![],
everywhere: false,
};
let info = MethodInfo::from_fn(&method, Some(&attrs)).expect("parses cleanly");
let param = info.params.iter().find(|p| p.name == "message").unwrap();
assert_eq!(
param.description.as_deref(),
Some("explicit description"),
"explicit params(...) entry must win over /// doc comment on the param"
);
}
#[test]
fn param_with_no_description_yields_none() {
let method: ImplItemFn = parse_quote! {
async fn echo(
&self,
message: String,
) -> impl Stream<Item = MyEvent> + Send + 'static {
stream! { yield MyEvent::Echo { message } }
}
};
let info = MethodInfo::from_fn(&method, None).expect("parses cleanly");
let param = info.params.iter().find(|p| p.name == "message").unwrap();
assert!(
param.description.is_none(),
"no description anywhere should yield None, got: {:?}",
param.description
);
}
#[test]
fn scope_literal_grammar_accepts_and_rejects() {
for ok in [
"facet.write",
"cone.send_message",
"a",
"a.b.c",
"a1.b_2",
"cone.*",
"a.b.*",
"*",
] {
assert!(
validate_scope_literal(ok).is_ok(),
"`{ok}` should satisfy the scope grammar"
);
}
for bad in [
"",
"INVALID-CHARS",
"Facet.write",
"facet..write",
".facet",
"facet.",
"facet write",
"1facet.write",
"*.facet", "facet.*.read", "**",
"facet.wr*te",
] {
assert!(
validate_scope_literal(bad).is_err(),
"`{bad}` should violate the scope grammar"
);
}
}
#[test]
fn method_attrs_parse_scopes_and_reject_public_scope_conflict() {
let attrs: HubMethodAttrs =
syn::parse_str("scope = \"x.y\", scope = \"x.z\"").expect("parses cleanly");
assert_eq!(attrs.scopes, vec!["x.y".to_string(), "x.z".to_string()]);
assert!(!attrs.public);
let err = match syn::parse_str::<HubMethodAttrs>("public, scope = \"x.y\"") {
Ok(_) => panic!("public + scope must be a parse error"),
Err(e) => e,
};
assert!(
err.to_string().contains("a public method has no required scope"),
"unexpected error: {err}"
);
let err = match syn::parse_str::<HubMethodAttrs>("scope = \"BAD CHARS\"") {
Ok(_) => panic!("invalid literal must be a parse error"),
Err(e) => e,
};
assert!(
err.to_string().contains("invalid scope literal"),
"unexpected error: {err}"
);
}
fn shape(sig: syn::Signature) -> syn::Result<ReturnShape> {
classify_return(&sig)
}
fn tokens(ty: &Type) -> String {
quote::quote!(#ty).to_string()
}
#[test]
fn the_six_forms_are_read_from_the_signature() {
let cases: Vec<(syn::Signature, Cardinality, &str, Option<&str>, Option<&str>)> = vec![
(parse_quote! { async fn a(&self) -> Pong }, Cardinality::One, "Pong", None, None),
(
parse_quote! { async fn b(&self) -> Result<Thing, LookupError> },
Cardinality::One,
"Thing",
Some("LookupError"),
None,
),
(
parse_quote! { async fn c(&self) -> impl Stream<Item = Tick> + Send + 'static },
Cardinality::Many,
"Tick",
None,
None,
),
(
parse_quote! { async fn d(&self) -> impl Send + Stream<Item = std::result::Result<Row, ScanError>> },
Cardinality::Many,
"Row",
Some("ScanError"),
None,
),
(
parse_quote! { async fn e(&self) -> impl Stream<Item = Result<Progress<Loaded, LoadStep>, LoadError>> },
Cardinality::Many,
"Loaded",
Some("LoadError"),
Some("LoadStep"),
),
(
parse_quote! { async fn f(&self) -> impl Stream<Item = plexus_client::Progress<Warmed>> },
Cardinality::Many,
"Warmed",
None,
Some("Note"),
),
];
let vocabulary: syn::Path = parse_quote!(v);
for (sig, cardinality, ok, err, progress) in cases {
let name = sig.ident.to_string();
let s = shape(sig).unwrap_or_else(|e| panic!("{name}: {e}"));
assert_eq!(s.cardinality, cardinality, "{name}");
assert_eq!(tokens(&s.ok_ty), ok, "{name}");
assert_eq!(s.err_ty.as_ref().map(tokens).as_deref(), err, "{name}");
let p = s.progress_ty.map(|p| match p {
ProgressTy::Note => "Note".to_string(),
declared => tokens(&declared.to_type(&vocabulary)),
});
assert_eq!(p.as_deref(), progress, "{name}");
}
}
#[test]
fn a_one_argument_result_alias_is_a_plain_item() {
let s = shape(parse_quote! { async fn a(&self) -> anyhow::Result<Pong> }).unwrap();
assert_eq!(s.cardinality, Cardinality::One);
assert_eq!(tokens(&s.ok_ty), "anyhow :: Result < Pong >");
assert!(s.err_ty.is_none());
}
#[test]
fn other_return_types_name_the_six_forms() {
let bad: Vec<syn::Signature> = vec![
parse_quote! { async fn a(&self) -> BoxStream<'static, Tick> },
parse_quote! { async fn a(&self) -> Pin<Box<dyn Stream<Item = Tick> + Send>> },
parse_quote! { async fn a(&self) -> PlexusStream },
parse_quote! { async fn a(&self) -> Result<PlexusStream, PlexusError> },
parse_quote! { async fn a(&self) -> impl Future<Output = Tick> },
parse_quote! { async fn a(&self) -> Box<dyn Stream<Item = Tick>> },
parse_quote! { async fn a(&self) },
];
for sig in bad {
let msg = match shape(sig) {
Ok(_) => panic!("must be rejected"),
Err(e) => e.to_string(),
};
assert!(msg.contains("six signature forms"), "{msg}");
assert!(msg.contains("-> impl Stream<Item = Result<Progress<T, P>, E>>"), "{msg}");
}
}
#[test]
fn progress_needs_a_stream() {
for sig in [
parse_quote! { async fn a(&self) -> Progress<Tick> },
parse_quote! { async fn a(&self) -> Result<Progress<Tick, Step>, E> },
] {
let sig: syn::Signature = sig;
let msg = match shape(sig) {
Ok(_) => panic!("must be rejected"),
Err(e) => e.to_string(),
};
assert!(msg.contains("cannot report progress"), "{msg}");
}
}
#[test]
fn streaming_is_deprecated_and_returns_removed() {
assert!(syn::parse_str::<HubMethodAttrs>("streaming").is_ok(), "`streaming` parses");
let err = match syn::parse_str::<HubMethodAttrs>("returns(Ok, Error)") {
Ok(_) => panic!("`returns(..)` must be rejected"),
Err(e) => e.to_string(),
};
assert!(err.contains("give each method its own return type"), "{err}");
}
}