module_utils_macros/
lib.rs

1// Copyright 2024 Wladimir Palant
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # Macros for module-utils crate
16//!
17//! You normally shouldn’t use this crate directly but the `module-utils` crate instead.
18
19mod derive_request_filter;
20mod merge_conf;
21mod merge_opt;
22
23use proc_macro::TokenStream;
24
25/// This attribute macro merges the command-line arguments from all structs identified as field of
26/// the current struct. The result will implement `structopt::StructOpt` and `Debug` automatically.
27/// All field types are required to implement `structopt::StructOpt` and `Debug`.
28///
29/// ```rust
30/// use pingora_core::server::configuration::Opt as ServerOpt;
31/// use module_utils::merge_opt;
32/// use static_files_module::StaticFilesOpt;
33/// use structopt::StructOpt;
34///
35/// #[derive(Debug, StructOpt)]
36/// struct MyAppOpt {
37///     /// IP address and port for the server to listen on
38///     #[structopt(long, default_value = "127.0.0.1:8080")]
39///     listen: String,
40/// }
41///
42/// /// Starts my great application.
43/// ///
44/// /// Additional application description just to make a structopt bug work-around work.
45/// #[merge_opt]
46/// struct Opt {
47///     app: MyAppOpt,
48///     server: ServerOpt,
49///     static_files: StaticFilesOpt,
50/// }
51///
52/// let opt = Opt::from_args();
53/// println!("Application options: {:?}", opt.app);
54/// println!("Pingora server options: {:?}", opt.server);
55/// println!("Static files options: {:?}", opt.static_files);
56/// ```
57#[proc_macro_attribute]
58pub fn merge_opt(_args: TokenStream, input: TokenStream) -> TokenStream {
59    merge_opt::merge_opt(input).unwrap_or_else(|err| err.into_compile_error().into())
60}
61
62/// This attribute macro merges the configuration settings from all structs identified as field of
63/// the current struct. The result will implement `serde::Deserialize`, `Debug` and `Default`
64/// automatically. All field types are required to implement `serde::Deserialize`, `Debug` and
65/// `Default`.
66///
67/// ```rust
68/// use pingora_core::server::configuration::ServerConf;
69/// use module_utils::{merge_conf, FromYaml};
70/// use static_files_module::StaticFilesConf;
71/// use serde::Deserialize;
72///
73/// #[derive(Debug, Default, Deserialize)]
74/// struct MyAppConf {
75///     /// IP address and port for the server to listen on
76///     listen: String,
77/// }
78///
79/// #[merge_conf]
80/// struct Conf {
81///     app: MyAppConf,
82///     server: ServerConf,
83///     static_files: StaticFilesConf,
84/// }
85///
86/// let conf = Conf::load_from_yaml("test.yaml").ok().unwrap_or_else(Conf::default);
87/// println!("Application settings: {:?}", conf.app);
88/// println!("Pingora server settings: {:?}", conf.server);
89/// println!("Static files settings: {:?}", conf.static_files);
90/// ```
91#[proc_macro_attribute]
92pub fn merge_conf(_args: TokenStream, input: TokenStream) -> TokenStream {
93    merge_conf::merge_conf(input).unwrap_or_else(|err| err.into_compile_error().into())
94}
95
96/// This macro will automatically implement `RequestFilter` by chaining the handlers identified
97/// in the struct’s fields.
98///
99/// Each handler has to implement `RequestFilter` trait. The handlers will be called in the order
100/// in which they are listed. Each handler can prevent the subsequent handlers from being called by
101/// returning `RequestFilterResult::ResponseSent` or `RequestFilterResult::Handled`.
102///
103/// The configuration and context for the struct will be implemented implicitly. These will have
104/// the configuration/context of the respective handler in a field with the same name as the
105/// handler in this struct.
106///
107/// ```rust,no_run
108/// use module_utils::{FromYaml, RequestFilter};
109/// use compression_module::CompressionHandler;
110/// use static_files_module::StaticFilesHandler;
111///
112/// #[derive(Debug, RequestFilter)]
113/// struct Handler {
114///     compression: CompressionHandler,
115///     static_files: StaticFilesHandler,
116/// }
117///
118/// type Conf = <Handler as RequestFilter>::Conf;
119///
120/// let conf = Conf::load_from_yaml("test.yaml").ok().unwrap_or_else(Conf::default);
121/// let handler: Handler = conf.try_into().unwrap();
122/// ```
123#[proc_macro_derive(RequestFilter)]
124pub fn derive_request_filter(input: TokenStream) -> TokenStream {
125    derive_request_filter::derive_request_filter(input)
126        .unwrap_or_else(|err| err.into_compile_error().into())
127}
module_utils_macros/lib.rs

module_utils_macros/
lib.rs
