Struct GrantsFairing 

pub struct GrantsFairing<Type> { /* private fields */ }

Built-in fairing for extracting user permission.

Examples

use std::collections::HashSet;
use rocket::{get, Route, Response, http::Status};

use rocket_grants::authorities::{AuthDetails, AuthoritiesCheck};
use rocket_grants::GrantsFairing;

#[rocket::launch]
fn rocket() -> _ {
    rocket::build().mount("/api", rocket::routes![endpoint])
        .attach(GrantsFairing::with_extractor_fn(|req| {
            Box::pin(extract(req)) // example with a separate async function, but you can write a closure right here
        }))
}

// Furthermore, you can use you own type instead of `String` (e.g. Enum).
async fn extract(_req: &rocket::Request<'_>) -> Option<HashSet<String>> {
   // Here is a place for your code to get user permissions/roles/authorities from a request (e.g. from a token or database).

   // Stub example
   Some(HashSet::from(["ROLE_ADMIN".to_string()]))
}

// `proc-macro` crate has additional features, like ABAC security and custom types. See examples and `proc-macro` crate docs.
#[rocket_grants::protect("ROLE_ADMIN")]
#[rocket::get("/")]
async fn endpoint() -> Status {
    Status::Ok
}

Implementations

impl<Type: Eq + Hash + Send + Sync + 'static> GrantsFairing<Type>

pub fn with_extractor_fn<F>(extractor_fn: F) -> Self

where F: for<'a> Fn(&'a mut Request<'_>) -> BoxFuture<'a, Option<HashSet<Type>>> + Send + Sync + 'static,

Creating fairing using your permission extraction function.

You can declare async fn with a suitable signature or you can write a boxed closure in-place (see examples below).

Examples

use std::collections::HashSet;
use rocket_grants::GrantsFairing;
 async fn example() {
    let string_extractor = GrantsFairing::with_extractor_fn(|req| Box::pin(extract(req)));
    let enum_extractor = GrantsFairing::with_extractor_fn(|req| Box::pin(extract_enum(req)));

    let closure_extractor = GrantsFairing::with_extractor_fn(|req| Box::pin(async move {
        Some(HashSet::from(["WRITE_ACCESS".to_string()]))
    }));
}

async fn extract(_req: &rocket::Request<'_>) -> Option<HashSet<String>> {
    // Here is a place for your code to get user permissions/roles/authorities from a request
     // For example from a token or database
    Some(HashSet::from(["WRITE_ACCESS".to_string()]))
}

// Or with you own type:
#[derive(Eq, PartialEq, Hash)] // required bounds
enum Permission { WRITE, READ }
async fn extract_enum(_req: &rocket::Request<'_>) -> Option<HashSet<Permission>> {
    // Here is a place for your code to get user permissions/roles/authorities from a request
     // For example from a token, database or external service
    Some(HashSet::from([Permission::WRITE]))
}

Trait Implementations

impl<Type: Eq + Hash + Send + Sync + 'static> Fairing for GrantsFairing<Type>

fn info(&self) -> Info

Returns an Info structure containing the name and Kind of this fairing. The name can be any arbitrary string. Kind must be an ord set of Kind variants.

fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, req: &'life1 mut Request<'life2>, _data: &'life3 mut Data<'life4>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

The request callback.

fn on_ignite<'life0, 'async_trait>( &'life0 self, rocket: Rocket<Build>, ) -> Pin<Box<dyn Future<Output = Result<Rocket<Build>, Rocket<Build>>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

The ignite callback. Returns Ok if ignition should proceed and Err if ignition and launch should be aborted.

fn on_liftoff<'life0, 'life1, 'async_trait>( &'life0 self, _rocket: &'life1 Rocket<Orbit>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

The liftoff callback.

fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _req: &'r Request<'life1>, _res: &'life2 mut Response<'r>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'r: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

The response callback.

fn on_shutdown<'life0, 'life1, 'async_trait>( &'life0 self, _rocket: &'life1 Rocket<Orbit>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

The shutdown callback.