use std::collections::HashMap;
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,
}
#[derive(Debug, Clone)]
pub enum BidirType {
None,
Standard,
Custom { request: String, response: String },
}
#[derive(Debug, Clone)]
pub enum MethodRequestOverride {
Skip,
#[allow(dead_code)]
Type(syn::Type),
}
pub struct HubMethodAttrs {
pub name: Option<String>,
pub description: Option<String>,
pub param_docs: HashMap<String, String>,
pub returns_variants: Vec<String>,
pub streaming: bool,
pub bidirectional: BidirType,
pub http_method: Option<String>,
pub request_override: Option<MethodRequestOverride>,
pub public: bool,
pub scopes: Vec<String>,
pub target: Option<syn::LitStr>,
pub answer_by: Option<syn::LitStr>,
pub group: Option<String>,
pub examples: Vec<ParsedExample>,
pub values: Vec<(syn::Ident, Vec<String>)>,
}
#[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(())
}
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 returns_variants = Vec::new();
let mut streaming = false;
let mut bidirectional = BidirType::None;
let mut http_method = None;
let mut request_override: Option<MethodRequestOverride> = None;
let mut public = false;
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 group: Option<String> = None;
let mut examples: Vec<ParsedExample> = Vec::new();
let mut values: Vec<(syn::Ident, Vec<String>)> = Vec::new();
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\
- Add `streaming` attribute if the method yields multiple events\n\
See plexus.call implementation for an example.",
));
} else if path.is_ident("streaming") {
streaming = true;
} else if path.is_ident("bidirectional") {
bidirectional = BidirType::Standard;
} else if path.is_ident("public") {
public = true;
public_span = Some(path.span());
}
}
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("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));
}
_ => {
}
}
}
}
Meta::List(MetaList { path, tokens, .. }) => {
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") {
let parser = Punctuated::<syn::Ident, Token![,]>::parse_terminated;
let nested = syn::parse::Parser::parse2(parser, tokens.clone())?;
for ident in nested {
returns_variants.push(ident.to_string());
}
} else if path.is_ident("bidirectional") {
let parser = Punctuated::<Meta, Token![,]>::parse_terminated;
let nested = syn::parse::Parser::parse2(parser, tokens.clone())?;
let mut request = None;
let mut response = None;
for meta in nested {
if let Meta::NameValue(MetaNameValue { path, value, .. }) = meta {
if let Expr::Lit(ExprLit { lit: Lit::Str(s), .. }) = value {
if path.is_ident("request") {
request = Some(s.value());
} else if path.is_ident("response") {
response = Some(s.value());
}
}
}
}
match (request, response) {
(Some(req), Some(resp)) => {
bidirectional = BidirType::Custom { request: req, response: resp };
}
_ => {
return Err(syn::Error::new_spanned(
&path,
"bidirectional(...) requires both request and response parameters: bidirectional(request = \"MyReq\", response = \"MyResp\")"
));
}
}
}
}
}
}
}
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 = ...`",
));
}
Ok(HubMethodAttrs { name, description, param_docs, returns_variants, streaming, bidirectional, http_method, request_override, public, scopes, target, answer_by, group, examples, values })
}
}
const TRAIT_KEY: &str = "__plexus_trait";
const MAX_DESCRIPTION_WORDS: usize = 15;
pub struct HubMethodsAttrs {
pub namespace: Option<String>,
pub trait_attr: Option<syn::LitStr>,
pub trait_span: Option<proc_macro2::Span>,
pub methods_marked: bool,
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 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();
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("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 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(),
"the trait is always emitted, named from `impl FooActivation`'s \
stem; write `trait = \"Name\"` to name it otherwise",
));
} else if path.is_ident("client") {
client = true;
client_span = Some(path.span());
} else if path.is_ident("typed_params") {
typed_params = true;
}
}
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());
}
}
}
}
}
if namespace.as_deref() == Some("") {
return Err(syn::Error::new(input.span(), "namespace = \"\" names nothing"));
}
Ok(HubMethodsAttrs {
namespace,
trait_attr,
trait_span,
methods_marked,
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 return_ty: syn::Type,
}
impl ChildMethodInfo {
pub fn from_fn(method: &ImplItemFn) -> 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) = 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)",
));
}
};
Ok(ChildMethodInfo {
fn_name,
description,
kind,
is_async,
list_fn,
search_fn,
deprecation,
forward,
return_ty,
})
}
}
fn parse_child_attr_args(
attrs: &[syn::Attribute],
) -> syn::Result<(Option<syn::Ident>, Option<syn::Ident>, Option<ChildForward>)> {
let mut list_fn: Option<syn::Ident> = None;
let mut search_fn: Option<syn::Ident> = None;
let mut forward: Option<ChildForward> = None;
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")) {
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::NameValue(MetaNameValue { path, value, .. }) => {
let ident_key = match path.get_ident() {
Some(id) => id.to_string(),
None => {
return Err(syn::Error::new_spanned(
&path,
"unknown argument to #[plexus_macros::child]; \
expected `list = \"method\"`, `search = \"method\"` or `forward = \"policy\"`",
));
}
};
let s = match value {
Expr::Lit(ExprLit { lit: Lit::Str(ref s), .. }) => s.clone(),
_ => {
return Err(syn::Error::new_spanned(
&value,
format!(
"#[plexus_macros::child({} = \"...\")] expects a string literal naming a sibling method",
ident_key
),
));
}
};
if ident_key == "forward" {
if forward.is_some() {
return Err(syn::Error::new_spanned(
&s,
"duplicate `forward = \"...\"` argument on #[plexus_macros::child]",
));
}
forward = Some(ChildForward::parse(&s.value()).ok_or_else(|| {
syn::Error::new_spanned(
&s,
format!(
"unknown forward policy \"{}\" on #[plexus_macros::child]; expected {}",
s.value(),
ChildForward::SPELLINGS
),
)
})?);
continue;
}
let method_ident = syn::Ident::new(&s.value(), s.span());
match ident_key.as_str() {
"list" => {
if list_fn.is_some() {
return Err(syn::Error::new_spanned(
&s,
"duplicate `list = \"...\"` argument on #[plexus_macros::child]",
));
}
list_fn = Some(method_ident);
}
"search" => {
if search_fn.is_some() {
return Err(syn::Error::new_spanned(
&s,
"duplicate `search = \"...\"` argument on #[plexus_macros::child]",
));
}
search_fn = Some(method_ident);
}
other => {
return Err(syn::Error::new_spanned(
&path,
format!(
"unknown argument `{}` to #[plexus_macros::child]; \
expected `list = \"method\"`, `search = \"method\"` or `forward = \"policy\"`",
other
),
));
}
}
}
other => {
return Err(syn::Error::new_spanned(
other,
"unknown argument to #[plexus_macros::child]; \
expected `list = \"method\"`, `search = \"method\"` or `forward = \"policy\"`",
));
}
}
}
}
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 = \"...\", search = \"...\")]`",
));
}
}
}
Ok((list_fn, search_fn, forward))
}
#[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
}
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")
.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"))
})
}
pub struct MethodInfo {
pub fn_name: syn::Ident,
pub method_name: String,
pub description: String,
pub params: Vec<ParamInfo>,
#[allow(dead_code)]
pub return_type: Type,
pub stream_item_type: Option<Type>,
pub returns_variants: Vec<String>,
pub streaming: bool,
pub bidirectional: BidirType,
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 scopes: Vec<String>,
pub deprecation: Option<ParsedDeprecation>,
pub target: Option<String>,
pub answer_by: Option<String>,
pub long_description: Option<String>,
pub group: Option<String>,
pub examples: Vec<ParsedExample>,
pub values: Vec<(String, Vec<String>)>,
pub takes_reach: 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 returns_variants = hub_method_attrs
.map(|a| a.returns_variants.clone())
.unwrap_or_default();
let streaming = hub_method_attrs
.map(|a| a.streaming)
.unwrap_or(false);
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 bidirectional = hub_method_attrs
.map(|a| a.bidirectional.clone())
.unwrap_or(BidirType::None);
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;
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 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 name_str == "ctx" || name_str == "context" {
if let Some(bidir_types) = extract_bidir_channel_types(&pat_type.ty) {
bidirectional = bidir_types;
continue;
}
}
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 return_type = match &method.sig.output {
ReturnType::Default => {
return Err(syn::Error::new_spanned(
&method.sig,
"hub_method requires a return type",
))
}
ReturnType::Type(_, ty) => (**ty).clone(),
};
let stream_item_type = extract_stream_item_type(&return_type);
if is_result_plexus_stream(&return_type) {
return Err(syn::Error::new_spanned(
&method.sig.output,
format!(
"Method `{}` returns Result<PlexusStream, _> which bypasses schema generation. \
Use the streaming pattern instead:\n\
- Return `impl Stream<Item = YourEvent>` from the method\n\
- Forward PlexusStreamItem variants into your event enum\n\
- Add `streaming` attribute if the method yields multiple events\n\
See plexus.call implementation for an example.",
fn_name
),
));
}
let deprecation = parse_deprecation_attrs(&method.attrs, method.sig.span())?;
let public = hub_method_attrs.map(|a| a.public).unwrap_or(false);
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 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 {
fn_name,
method_name,
description,
params,
return_type,
stream_item_type,
returns_variants,
streaming,
bidirectional,
http_method,
requires_auth,
auth_optional,
auth_resolvers,
activation_params,
request_override,
public,
scopes,
deprecation,
target,
answer_by,
long_description,
group,
examples,
values,
takes_reach,
})
}
}
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,
}
fn extract_bidir_channel_types(ty: &Type) -> Option<BidirType> {
let inner_ty = if let Type::Reference(type_ref) = ty {
&*type_ref.elem
} else {
ty
};
if let Type::Path(type_path) = inner_ty {
let last_segment = type_path.path.segments.last()?;
if last_segment.ident == "Arc" {
if let PathArguments::AngleBracketed(args) = &last_segment.arguments {
if let Some(GenericArgument::Type(inner)) = args.args.first() {
return extract_bidir_from_path(inner);
}
}
return None;
}
return extract_bidir_from_path(inner_ty);
}
None
}
fn extract_bidir_from_path(ty: &Type) -> Option<BidirType> {
if let Type::Path(type_path) = ty {
let last_segment = type_path.path.segments.last()?;
if last_segment.ident == "StandardBidirChannel" {
return Some(BidirType::Standard);
}
if last_segment.ident == "BidirChannel" {
if let PathArguments::AngleBracketed(args) = &last_segment.arguments {
let args_vec: Vec<_> = args.args.iter().collect();
if args_vec.len() == 2 {
if let (GenericArgument::Type(req_ty), GenericArgument::Type(resp_ty)) =
(args_vec[0], args_vec[1])
{
let req_name = type_to_string(req_ty);
let resp_name = type_to_string(resp_ty);
if req_name == "StandardRequest" && resp_name == "StandardResponse" {
return Some(BidirType::Standard);
}
return Some(BidirType::Custom {
request: req_name,
response: resp_name,
});
}
}
}
}
}
None
}
fn type_to_string(ty: &Type) -> String {
if let Type::Path(type_path) = ty {
type_path
.path
.segments
.iter()
.map(|s| s.ident.to_string())
.collect::<Vec<_>>()
.join("::")
} else {
format!("{:?}", ty)
}
}
pub(crate) fn extract_stream_item_type(ty: &Type) -> Option<Type> {
if let Type::ImplTrait(impl_trait) = ty {
for bound in &impl_trait.bounds {
if let syn::TypeParamBound::Trait(trait_bound) = bound {
let last_segment = trait_bound.path.segments.last()?;
if last_segment.ident == "Stream" {
if let PathArguments::AngleBracketed(args) = &last_segment.arguments {
for arg in &args.args {
if let GenericArgument::AssocType(assoc) = arg {
if assoc.ident == "Item" {
return Some(assoc.ty.clone());
}
}
}
}
}
}
}
}
None
}
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 is_result_plexus_stream(ty: &Type) -> bool {
if let Type::Path(type_path) = ty {
if let Some(segment) = type_path.path.segments.last() {
if segment.ident == "Result" {
if let PathArguments::AngleBracketed(args) = &segment.arguments {
if let Some(GenericArgument::Type(first_type)) = args.args.first() {
if let Type::Path(inner_path) = first_type {
if let Some(inner_seg) = inner_path.path.segments.last() {
return inner_seg.ident == "PlexusStream";
}
}
}
}
}
}
}
false
}
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 {
name: None,
description: None,
param_docs: {
let mut m = HashMap::new();
m.insert("message".to_string(), "explicit description".to_string());
m
},
returns_variants: vec![],
streaming: false,
bidirectional: BidirType::None,
http_method: None,
request_override: None,
public: false,
scopes: vec![],
target: None,
answer_by: None,
group: None,
examples: vec![],
values: vec![],
};
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}"
);
}
}