proxmox/proxmox-api-macro/src/api_macro/function.rs
Wolfgang Bumiller 589cb7e296 macro: enforce Send
Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
2019-10-04 14:11:33 +02:00

392 lines
14 KiB
Rust

//! Module for function handling.
use proc_macro2::{Ident, Span, TokenStream};
use failure::{bail, format_err, Error};
use quote::{quote, quote_spanned, ToTokens};
use syn::{spanned::Spanned, Expr, Token};
use crate::parsing::{Expression, Object};
use crate::util;
pub fn handle_function(
def_span: Span,
mut definition: Object,
mut item: syn::ItemFn,
) -> Result<TokenStream, Error> {
if item.sig.generics.lt_token.is_some() {
c_bail!(
item.sig.generics.span(),
"cannot use generic functions for api macros currently",
);
// Not until we stabilize our generated representation!
}
// We cannot use #{foo.bar} in quote!, we can only use #foo, so these must all be local
// variables. (I'd prefer a struct and using `#{func.description}`, `#{func.protected}` etc.
// but that's not supported.
let fn_api_description = definition
.remove("description")
.ok_or_else(|| c_format_err!(def_span, "missing 'description' in method definition"))?
.expect_lit_str()?;
let fn_api_protected = definition
.remove("protected")
.map(|v| v.expect_lit_bool())
.transpose()?
.unwrap_or_else(|| syn::LitBool {
span: Span::call_site(),
value: false,
});
let fn_api_reload_timezone = definition
.remove("reload-timezone")
.map(|v| v.expect_lit_bool())
.transpose()?
.unwrap_or_else(|| syn::LitBool {
span: Span::call_site(),
value: false,
});
let body_type = definition
.remove("body")
.map(|v| v.expect_type())
.transpose()?
.map_or_else(|| quote! { ::hyper::Body }, |v| v.into_token_stream());
let mut parameters = definition
.remove("parameters")
.map(|v| v.expect_object())
.transpose()?
.unwrap_or_else(|| Object::new(Span::call_site()));
let mut parameter_entries = TokenStream::new();
let mut parameter_verifiers = TokenStream::new();
let vis = std::mem::replace(&mut item.vis, syn::Visibility::Inherited);
let span = item.sig.ident.span();
let name_str = item.sig.ident.to_string();
//let impl_str = format!("{}_impl", name_str);
//let impl_ident = Ident::new(&impl_str, span);
let impl_checked_str = format!("{}_checked_impl", name_str);
let impl_checked_ident = Ident::new(&impl_checked_str, span);
let impl_unchecked_str = format!("{}_unchecked_impl", name_str);
let impl_unchecked_ident = Ident::new(&impl_unchecked_str, span);
let name = std::mem::replace(&mut item.sig.ident, impl_unchecked_ident.clone());
let mut return_type = match item.sig.output {
syn::ReturnType::Default => syn::Type::Tuple(syn::TypeTuple {
paren_token: syn::token::Paren {
span: Span::call_site(),
},
elems: syn::punctuated::Punctuated::new(),
}),
syn::ReturnType::Type(_, ref ty) => ty.as_ref().clone(),
};
let mut extracted_args = syn::punctuated::Punctuated::<Ident, Token![,]>::new();
let mut passed_args = syn::punctuated::Punctuated::<Ident, Token![,]>::new();
let mut arg_extraction = Vec::new();
let inputs = item.sig.inputs.clone();
for arg in item.sig.inputs.iter() {
let arg = match arg {
syn::FnArg::Typed(ref arg) => arg,
other => bail!("unhandled type of method parameter ({:?})", other),
};
let arg_type = &arg.ty;
let name = match &*arg.pat {
syn::Pat::Ident(name) => &name.ident,
other => bail!("invalid kind of parameter pattern: {:?}", other),
};
passed_args.push(name.clone());
let name_str = name.to_string();
let arg_name = Ident::new(&format!("arg_{}", name_str), name.span());
extracted_args.push(arg_name.clone());
arg_extraction.push(quote! {
let #arg_name = ::serde_json::from_value(
args
.remove(#name_str)
.unwrap_or(::serde_json::Value::Null)
)?;
});
let info = parameters
.remove(&name_str)
.ok_or_else(|| format_err!("missing parameter '{}' in api defintion", name_str))?;
parameter_verifiers.extend(quote_spanned! { name.span() =>
::proxmox::api::ApiType::verify(&#name)?;
});
match info {
Expression::Expr(Expr::Lit(lit)) => {
parameter_entries.extend(quote! {
::proxmox::api::Parameter {
name: #name_str,
description: #lit,
type_info: <#arg_type as ::proxmox::api::ApiType>::type_info,
},
});
}
Expression::Expr(_) => bail!("description must be a string literal!"),
Expression::Object(mut param_info) => {
let description = param_info
.remove("description")
.ok_or_else(|| format_err!("missing 'description' in parameter definition"))?
.expect_lit_str()?;
parameter_entries.extend(quote! {
::proxmox::api::Parameter {
name: #name_str,
description: #description,
type_info: <#arg_type as ::proxmox::api::ApiType>::type_info,
},
});
make_parameter_verifier(
&name,
&name_str,
&mut param_info,
&mut parameter_verifiers,
)?;
}
}
}
if !parameters.is_empty() {
let mut list = String::new();
for param in parameters.keys() {
if !list.is_empty() {
list.push_str(", ");
}
list.push_str(param.as_str());
}
bail!(
"api definition contains parameters not found in function declaration: {}",
list
);
}
use std::iter::FromIterator;
let arg_extraction = TokenStream::from_iter(arg_extraction.into_iter());
// The router expects an ApiMethod, or more accurately, an object implementing ApiHandler.
// This is because we need access to a bunch of additional attributes of the functions both at
// runtime and when doing command line parsing/completion/help output.
//
// When manually implementing methods, we usually just write them out as an `ApiMethod` which
// is a type requiring all the info made available by the ApiHandler trait as members.
//
// While we could just generate a `const ApiMethod` for our functions, we would like them to
// also be usable as functions simply because the syntax we use to create them makes them
// *look* like functions, so it would be nice if they also *behaved* like real functions.
//
// Therefore all the fields of an ApiMethod are accessed via methods from the ApiHandler trait
// and we perform the same trick lazy_static does: Create a new type implementing ApiHandler,
// and make its instance Deref to an actual function.
// This way the function can still be used normally. Validators for parameters will be
// executed, serialization happens only when coming from the method's `handler`.
let name_str = name.to_string();
let struct_name = Ident::new(&util::to_camel_case(&name_str), name.span());
let mut body = Vec::new();
body.push(quote! {
// This is our helper struct which Derefs to a wrapper of our original function, which
// applies the added validators.
#vis struct #struct_name;
#[allow(non_upper_case_globals)]
const #name: &#struct_name = &#struct_name;
// Namespace some of our code into the helper type:
impl #struct_name {
// This is the original function, renamed to `#impl_unchecked_ident`
#item
// This is the handler used by our router, which extracts the parameters out of a
// serde_json::Value, running the actual method, then serializing the output into an
// API response.
fn wrapped_api_handler(
args: ::serde_json::Value,
) -> ::proxmox::api::ApiFuture<#body_type> {
async fn handler(
mut args: ::serde_json::Value,
) -> ::proxmox::api::ApiOutput<#body_type> {
let mut empty_args = ::serde_json::map::Map::new();
let args = args.as_object_mut()
.unwrap_or(&mut empty_args);
#arg_extraction
if !args.is_empty() {
let mut extra = String::new();
for arg in args.keys() {
if !extra.is_empty() {
extra.push_str(", ");
}
extra.push_str(arg);
}
::failure::bail!("unexpected extra parameters: {}", extra);
}
let output = #struct_name::#impl_checked_ident(#extracted_args).await?;
::proxmox::api::IntoApiOutput::into_api_output(output)
}
Box::pin(handler(args))
}
}
});
if item.sig.asyncness.is_some() {
// An async function is expected to return its value, so we wrap it a bit:
body.push(quote! {
impl #struct_name {
async fn #impl_checked_ident(#inputs) -> #return_type {
#parameter_verifiers
Self::#impl_unchecked_ident(#passed_args).await
}
}
// Our helper type derefs to a wrapper performing input validation and returning a
// Pin<Box<Future>>.
// Unfortunately we cannot return the actual function since that won't work for
// `async fn`, since an `async fn` cannot appear as a return type :(
impl ::std::ops::Deref for #struct_name {
type Target = fn(#inputs) -> ::std::pin::Pin<Box<
dyn ::std::future::Future<Output = #return_type> + Send
>>;
fn deref(&self) -> &Self::Target {
const FUNC: fn(#inputs) -> ::std::pin::Pin<Box<dyn ::std::future::Future<
Output = #return_type,
> + Send>> = |#inputs| {
Box::pin(#struct_name::#impl_checked_ident(#passed_args))
};
&FUNC
}
}
});
} else {
// Non async fn must return an ApiFuture already!
return_type = syn::Type::Verbatim(
definition
.remove("returns")
.ok_or_else(|| {
format_err!(
"non async-fn must return a Response \
and specify its return type via the `returns` property",
)
})?
.expect_type()?
.into_token_stream(),
);
body.push(quote! {
impl #struct_name {
fn #impl_checked_ident(#inputs) -> ::proxmox::api::ApiFuture<#body_type> {
let check = (|| -> Result<(), Error> {
#parameter_verifiers
Ok(())
})();
if let Err(err) = check {
return Box::pin(async move { Err(err) });
}
Self::#impl_unchecked_ident(#passed_args)
}
}
// Our helper type derefs to a wrapper performing input validation and returning a
// Pin<Box<Future>>.
// Unfortunately we cannot return the actual function since that won't work for
// `async fn`, since an `async fn` cannot appear as a return type :(
impl ::std::ops::Deref for #struct_name {
type Target = fn(#inputs) -> ::proxmox::api::ApiFuture<#body_type>;
fn deref(&self) -> &Self::Target {
&(Self::#impl_checked_ident as Self::Target)
}
}
});
}
body.push(quote! {
// We now need to provide all the info required for routing, command line completion, API
// documentation, etc.
//
// Note that technically we don't need the `description` member in this trait, as this is
// mostly used at compile time for documentation!
impl ::proxmox::api::ApiMethodInfo for #struct_name {
fn description(&self) -> &'static str {
#fn_api_description
}
fn parameters(&self) -> &'static [::proxmox::api::Parameter] {
// FIXME!
&[ #parameter_entries ]
}
fn return_type(&self) -> &'static ::proxmox::api::TypeInfo {
<#return_type as ::proxmox::api::ApiType>::type_info()
}
fn protected(&self) -> bool {
#fn_api_protected
}
fn reload_timezone(&self) -> bool {
#fn_api_reload_timezone
}
}
impl ::proxmox::api::ApiHandler for #struct_name {
type Body = #body_type;
fn call(&self, params: ::serde_json::Value) -> ::proxmox::api::ApiFuture<#body_type> {
#struct_name::wrapped_api_handler(params)
}
fn method_info(&self) -> &dyn ::proxmox::api::ApiMethodInfo {
self as _
}
}
});
let body = TokenStream::from_iter(body);
//dbg!("{}", &body);
Ok(body)
}
// FIXME: Unify with the struct version of this to avoid duplicate code!
fn make_parameter_verifier(
var: &Ident,
var_str: &str,
info: &mut Object,
out: &mut TokenStream,
) -> Result<(), Error> {
match info.remove("minimum") {
None => (),
Some(Expression::Expr(expr)) => out.extend(quote! {
let cmp = #expr;
if #var < cmp {
bail!("parameter '{}' is out of range (must be >= {})", #var_str, cmp);
}
}),
Some(_) => bail!("invalid value for 'minimum'"),
}
match info.remove("maximum") {
None => (),
Some(Expression::Expr(expr)) => out.extend(quote! {
let cmp = #expr;
if #var > cmp {
bail!("parameter '{}' is out of range (must be <= {})", #var_str, cmp);
}
}),
Some(_) => bail!("invalid value for 'maximum'"),
}
Ok(())
}