2021-02-10 12:45:46 +00:00
|
|
|
//! Routing and runtime macros for Actix Web.
|
2020-09-24 22:54:01 +00:00
|
|
|
//!
|
2021-02-10 12:45:46 +00:00
|
|
|
//! # Actix Web Re-exports
|
2020-09-24 22:54:01 +00:00
|
|
|
//! Actix Web re-exports a version of this crate in it's entirety so you usually don't have to
|
|
|
|
//! specify a dependency on this crate explicitly. Sometimes, however, updates are made to this
|
|
|
|
//! crate before the actix-web dependency is updated. Therefore, code examples here will show
|
|
|
|
//! explicit imports. Check the latest [actix-web attributes docs] to see which macros
|
|
|
|
//! are re-exported.
|
|
|
|
//!
|
|
|
|
//! # Runtime Setup
|
2020-12-13 13:28:39 +00:00
|
|
|
//! Used for setting up the actix async runtime. See [macro@main] macro docs.
|
2020-09-24 22:54:01 +00:00
|
|
|
//!
|
2021-02-10 12:45:46 +00:00
|
|
|
//! ```
|
2020-09-24 22:54:01 +00:00
|
|
|
//! #[actix_web_codegen::main] // or `#[actix_web::main]` in Actix Web apps
|
|
|
|
//! async fn main() {
|
|
|
|
//! async { println!("Hello world"); }.await
|
|
|
|
//! }
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! # Single Method Handler
|
|
|
|
//! There is a macro to set up a handler for each of the most common HTTP methods that also define
|
|
|
|
//! additional guards and route-specific middleware.
|
|
|
|
//!
|
|
|
|
//! See docs for: [GET], [POST], [PATCH], [PUT], [DELETE], [HEAD], [CONNECT], [OPTIONS], [TRACE]
|
|
|
|
//!
|
2021-02-10 12:45:46 +00:00
|
|
|
//! ```
|
2020-09-24 22:54:01 +00:00
|
|
|
//! # use actix_web::HttpResponse;
|
|
|
|
//! # use actix_web_codegen::get;
|
|
|
|
//! #[get("/test")]
|
|
|
|
//! async fn get_handler() -> HttpResponse {
|
|
|
|
//! HttpResponse::Ok().finish()
|
|
|
|
//! }
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! # Multiple Method Handlers
|
|
|
|
//! Similar to the single method handler macro but takes one or more arguments for the HTTP methods
|
2020-12-13 13:28:39 +00:00
|
|
|
//! it should respond to. See [macro@route] macro docs.
|
2020-09-24 22:54:01 +00:00
|
|
|
//!
|
2021-02-10 12:45:46 +00:00
|
|
|
//! ```
|
2020-09-24 22:54:01 +00:00
|
|
|
//! # use actix_web::HttpResponse;
|
|
|
|
//! # use actix_web_codegen::route;
|
|
|
|
//! #[route("/test", method="GET", method="HEAD")]
|
|
|
|
//! async fn get_and_head_handler() -> HttpResponse {
|
|
|
|
//! HttpResponse::Ok().finish()
|
|
|
|
//! }
|
|
|
|
//! ```
|
|
|
|
//!
|
|
|
|
//! [actix-web attributes docs]: https://docs.rs/actix-web/*/actix_web/#attributes
|
2020-12-13 13:28:39 +00:00
|
|
|
//! [GET]: macro@get
|
|
|
|
//! [POST]: macro@post
|
|
|
|
//! [PUT]: macro@put
|
|
|
|
//! [HEAD]: macro@head
|
|
|
|
//! [CONNECT]: macro@macro@connect
|
|
|
|
//! [OPTIONS]: macro@options
|
|
|
|
//! [TRACE]: macro@trace
|
|
|
|
//! [PATCH]: macro@patch
|
|
|
|
//! [DELETE]: macro@delete
|
2020-06-22 19:09:48 +00:00
|
|
|
|
2020-09-24 22:54:01 +00:00
|
|
|
#![recursion_limit = "512"]
|
2021-12-08 06:09:56 +00:00
|
|
|
#![deny(rust_2018_idioms, nonstandard_style)]
|
|
|
|
#![warn(future_incompatible)]
|
2019-03-07 19:09:42 +00:00
|
|
|
|
|
|
|
use proc_macro::TokenStream;
|
2021-10-19 16:30:32 +00:00
|
|
|
use quote::quote;
|
2019-03-07 19:09:42 +00:00
|
|
|
|
2020-09-22 21:42:51 +00:00
|
|
|
mod route;
|
2019-03-07 19:09:42 +00:00
|
|
|
|
2020-09-22 21:42:51 +00:00
|
|
|
/// Creates resource handler, allowing multiple HTTP method guards.
|
2019-03-31 07:23:15 +00:00
|
|
|
///
|
2020-09-24 22:54:01 +00:00
|
|
|
/// # Syntax
|
2021-12-02 15:25:39 +00:00
|
|
|
/// ```plain
|
2020-09-22 21:42:51 +00:00
|
|
|
/// #[route("path", method="HTTP_METHOD"[, attributes])]
|
|
|
|
/// ```
|
2019-03-31 07:23:15 +00:00
|
|
|
///
|
2020-09-24 22:54:01 +00:00
|
|
|
/// # Attributes
|
2020-09-22 21:42:51 +00:00
|
|
|
/// - `"path"` - Raw literal string with path for which to register handler.
|
2021-03-04 12:38:47 +00:00
|
|
|
/// - `name="resource_name"` - Specifies resource name for the handler. If not set, the function name of handler is used.
|
2020-09-22 21:42:51 +00:00
|
|
|
/// - `method="HTTP_METHOD"` - Registers HTTP method to provide guard for. Upper-case string, "GET", "POST" for example.
|
|
|
|
/// - `guard="function_name"` - Registers function as guard using `actix_web::guard::fn_guard`
|
|
|
|
/// - `wrap="Middleware"` - Registers a resource middleware.
|
2019-06-04 16:30:43 +00:00
|
|
|
///
|
2020-09-24 22:54:01 +00:00
|
|
|
/// # Notes
|
2020-09-22 21:42:51 +00:00
|
|
|
/// Function name can be specified as any expression that is going to be accessible to the generate
|
|
|
|
/// code, e.g `my_guard` or `my_module::my_guard`.
|
2019-06-04 16:30:43 +00:00
|
|
|
///
|
2020-09-24 22:54:01 +00:00
|
|
|
/// # Example
|
2019-06-04 16:30:43 +00:00
|
|
|
///
|
2021-03-25 08:45:52 +00:00
|
|
|
/// ```
|
2020-09-24 22:54:01 +00:00
|
|
|
/// # use actix_web::HttpResponse;
|
|
|
|
/// # use actix_web_codegen::route;
|
|
|
|
/// #[route("/test", method="GET", method="HEAD")]
|
2020-09-22 21:42:51 +00:00
|
|
|
/// async fn example() -> HttpResponse {
|
|
|
|
/// HttpResponse::Ok().finish()
|
|
|
|
/// }
|
|
|
|
/// ```
|
2019-06-04 16:30:43 +00:00
|
|
|
#[proc_macro_attribute]
|
2020-09-22 21:42:51 +00:00
|
|
|
pub fn route(args: TokenStream, input: TokenStream) -> TokenStream {
|
|
|
|
route::with_method(None, args, input)
|
2019-06-04 16:30:43 +00:00
|
|
|
}
|
|
|
|
|
2020-09-22 21:42:51 +00:00
|
|
|
macro_rules! doc_comment {
|
|
|
|
($x:expr; $($tt:tt)*) => {
|
|
|
|
#[doc = $x]
|
|
|
|
$($tt)*
|
|
|
|
};
|
2019-06-04 16:30:43 +00:00
|
|
|
}
|
|
|
|
|
2020-09-22 21:42:51 +00:00
|
|
|
macro_rules! method_macro {
|
|
|
|
(
|
|
|
|
$($variant:ident, $method:ident,)+
|
|
|
|
) => {
|
|
|
|
$(doc_comment! {
|
|
|
|
concat!("
|
|
|
|
Creates route handler with `actix_web::guard::", stringify!($variant), "`.
|
|
|
|
|
2020-09-24 22:54:01 +00:00
|
|
|
# Syntax
|
2021-12-02 15:25:39 +00:00
|
|
|
```plain
|
2020-09-22 21:42:51 +00:00
|
|
|
#[", stringify!($method), r#"("path"[, attributes])]
|
|
|
|
```
|
|
|
|
|
2020-09-24 22:54:01 +00:00
|
|
|
# Attributes
|
2020-09-22 21:42:51 +00:00
|
|
|
- `"path"` - Raw literal string with path for which to register handler.
|
2021-03-04 12:38:47 +00:00
|
|
|
- `name="resource_name"` - Specifies resource name for the handler. If not set, the function name of handler is used.
|
2020-09-22 21:42:51 +00:00
|
|
|
- `guard="function_name"` - Registers function as guard using `actix_web::guard::fn_guard`.
|
|
|
|
- `wrap="Middleware"` - Registers a resource middleware.
|
|
|
|
|
2020-09-24 22:54:01 +00:00
|
|
|
# Notes
|
2020-09-22 21:42:51 +00:00
|
|
|
Function name can be specified as any expression that is going to be accessible to the generate
|
|
|
|
code, e.g `my_guard` or `my_module::my_guard`.
|
|
|
|
|
2020-09-24 22:54:01 +00:00
|
|
|
# Example
|
2020-09-22 21:42:51 +00:00
|
|
|
|
2021-03-25 08:45:52 +00:00
|
|
|
```
|
2020-09-24 22:54:01 +00:00
|
|
|
# use actix_web::HttpResponse;
|
|
|
|
# use actix_web_codegen::"#, stringify!($method), ";
|
2020-09-22 21:42:51 +00:00
|
|
|
#[", stringify!($method), r#"("/")]
|
|
|
|
async fn example() -> HttpResponse {
|
|
|
|
HttpResponse::Ok().finish()
|
2019-06-04 16:30:43 +00:00
|
|
|
}
|
2020-09-22 21:42:51 +00:00
|
|
|
```
|
|
|
|
"#);
|
|
|
|
#[proc_macro_attribute]
|
|
|
|
pub fn $method(args: TokenStream, input: TokenStream) -> TokenStream {
|
|
|
|
route::with_method(Some(route::MethodType::$variant), args, input)
|
|
|
|
}
|
|
|
|
})+
|
|
|
|
};
|
2019-06-05 02:43:13 +00:00
|
|
|
}
|
2020-06-22 19:09:48 +00:00
|
|
|
|
2020-09-22 21:42:51 +00:00
|
|
|
method_macro! {
|
|
|
|
Get, get,
|
|
|
|
Post, post,
|
|
|
|
Put, put,
|
|
|
|
Delete, delete,
|
|
|
|
Head, head,
|
|
|
|
Connect, connect,
|
|
|
|
Options, options,
|
|
|
|
Trace, trace,
|
|
|
|
Patch, patch,
|
2020-09-16 21:37:41 +00:00
|
|
|
}
|
|
|
|
|
2020-06-22 19:09:48 +00:00
|
|
|
/// Marks async main function as the actix system entry-point.
|
2021-10-19 16:30:32 +00:00
|
|
|
|
2021-02-10 12:10:03 +00:00
|
|
|
/// # Examples
|
2021-03-25 08:45:52 +00:00
|
|
|
/// ```
|
2021-10-19 16:30:32 +00:00
|
|
|
/// #[actix_web::main]
|
2020-06-22 19:09:48 +00:00
|
|
|
/// async fn main() {
|
|
|
|
/// async { println!("Hello world"); }.await
|
|
|
|
/// }
|
|
|
|
/// ```
|
|
|
|
#[proc_macro_attribute]
|
|
|
|
pub fn main(_: TokenStream, item: TokenStream) -> TokenStream {
|
2021-10-19 16:30:32 +00:00
|
|
|
let mut output: TokenStream = (quote! {
|
|
|
|
#[::actix_web::rt::main(system = "::actix_web::rt::System")]
|
|
|
|
})
|
|
|
|
.into();
|
|
|
|
|
|
|
|
output.extend(item);
|
|
|
|
output
|
|
|
|
}
|
|
|
|
|
|
|
|
/// Marks async test functions to use the actix system entry-point.
|
|
|
|
///
|
|
|
|
/// # Examples
|
|
|
|
/// ```
|
|
|
|
/// #[actix_web::test]
|
|
|
|
/// async fn test() {
|
|
|
|
/// assert_eq!(async { "Hello world" }.await, "Hello world");
|
|
|
|
/// }
|
|
|
|
/// ```
|
|
|
|
#[proc_macro_attribute]
|
|
|
|
pub fn test(_: TokenStream, item: TokenStream) -> TokenStream {
|
|
|
|
let mut output: TokenStream = (quote! {
|
|
|
|
#[::actix_web::rt::test(system = "::actix_web::rt::System")]
|
2020-06-22 19:09:48 +00:00
|
|
|
})
|
2021-10-19 16:30:32 +00:00
|
|
|
.into();
|
|
|
|
|
|
|
|
output.extend(item);
|
|
|
|
output
|
2020-06-22 19:09:48 +00:00
|
|
|
}
|