poem_grants/
lib.rs

1#![doc(
2    html_logo_url = "https://raw.githubusercontent.com/DDtKey/protect-endpoints/main/poem-grants/logo.png"
3)]
4//! A crate to protect your endpoints in `poem`.
5//!
6//! For built-in configure see: [`GrantsMiddleware`].
7//!
8//! To check user access to specific services, you can use [`proc-macro`] or manual.
9//!
10//! The library can also be integrated with third-party solutions or your custom middlewares, see [`authorities`] module.
11//!
12//! You can find more [`examples`] in the git repository.
13//!
14//! [`GrantsMiddleware`]: GrantsMiddleware
15//! [`examples`]: https://github.com/DDtKey/protect-endpoints/tree/main/poem-grants/examples
16//! [`authorities`]: authorities
17//! [`proc-macro`]: proc_macro
18#![doc = include_str!("../README.md")]
19
20pub mod authorities;
21pub mod error;
22mod middleware;
23
24pub use middleware::GrantsMiddleware;
25
26/// Procedural macros for checking user authorities (permissions or roles).
27///
28/// # Examples
29/// ```
30/// use poem::{Response, http::StatusCode, web};
31///
32/// // User should be ADMIN with OP_GET_SECRET permission
33/// #[poem_grants::protect("ROLE_ADMIN", "OP_GET_SECRET")]
34/// #[poem::handler]
35/// async fn macro_secured() -> Response {
36///     Response::builder().status(StatusCode::OK).body("some secured info")
37/// }
38///
39/// // User should be ADMIN and MANAGER
40/// #[poem_grants::protect("ADMIN", "MANAGER")]
41/// #[poem::handler]
42/// async fn role_macro_secured() -> Response {
43///     Response::builder().status(StatusCode::OK).body("some secured info")
44/// }
45///
46/// // Additional security condition to ensure the protection of the endpoint
47/// #[poem_grants::protect("USER", expr = "*user_id == user.id")]
48/// #[poem::handler]
49/// async fn role_macro_secured_with_params(user_id: web::Path<i32>, user: web::Data<&User>) -> Response {
50///     Response::builder().status(StatusCode::OK).body("some secured info with parameters")
51/// }
52/// struct User { id: i32 }
53///
54/// // You own type is also supported (need to configure middleware for this type as well):
55/// #[poem_grants::protect("Role::Admin", "Role::Manager", ty = "Role")]
56/// #[poem::handler]
57/// async fn role_enum_macro_secured() -> Response {
58///     Response::builder().status(StatusCode::OK).body("some secured info")
59/// }
60/// #[derive(Eq, PartialEq, Hash)] // required bounds
61/// enum Role { Admin, Manager }
62///
63/// ```
64#[cfg(feature = "macro-check")]
65pub mod proc_macro {
66    pub use protect_endpoints_proc_macro::{open_api, protect_poem as protect};
67}
68
69/// Just a shortcut for proc-macros
70#[cfg(feature = "macro-check")]
71pub use proc_macro::*;
poem_grants/lib.rs

poem_grants/
lib.rs
