Struct rocket::fairing::AdHoc

pub struct AdHoc { /* private fields */ }

A ad-hoc fairing that can be created from a function or closure.

This enum can be used to create a fairing from a simple function or closure without creating a new structure or implementing Fairing directly.

Usage

Use AdHoc::on_ignite, AdHoc::on_liftoff, AdHoc::on_request(), or AdHoc::on_response() to create an AdHoc structure from a function or closure. Then, simply attach the structure to the Rocket instance.

Example

The following snippet creates a Rocket instance with two ad-hoc fairings. The first, a liftoff fairing named “Liftoff Printer”, simply prints a message indicating that Rocket has launched. The second named “Put Rewriter”, a request fairing, rewrites the method of all requests to be PUT.

use rocket::fairing::AdHoc;
use rocket::http::Method;

rocket::build()
    .attach(AdHoc::on_liftoff("Liftoff Printer", |_| Box::pin(async move {
        println!("...annnddd we have liftoff!");
    })))
    .attach(AdHoc::on_request("Put Rewriter", |req, _| Box::pin(async move {
        req.set_method(Method::Put);
    })));

Implementations

impl AdHoc

pub fn on_ignite<F, Fut>(name: &'static str, f: F) -> AdHoc where
    F: FnOnce(Rocket<Build>) -> Fut + Send + 'static,
    Fut: Future<Output = Rocket<Build>> + Send + 'static, 

Constructs an AdHoc ignite fairing named name. The function f will be called by Rocket during the Rocket::ignite() phase.

This version of an AdHoc ignite fairing cannot abort ignite. For a fallible version that can, see AdHoc::try_on_ignite().

Example

use rocket::fairing::AdHoc;

// The no-op ignite fairing.
let fairing = AdHoc::on_ignite("Boom!", |rocket| async move {
    rocket
});

pub fn try_on_ignite<F, Fut>(name: &'static str, f: F) -> AdHoc where
    F: FnOnce(Rocket<Build>) -> Fut + Send + 'static,
    Fut: Future<Output = Result> + Send + 'static, 

Constructs an AdHoc ignite fairing named name. The function f will be called by Rocket during the Rocket::ignite() phase. Returning an Err aborts ignition and thus launch.

For an infallible version, see AdHoc::on_ignite().

Example

use rocket::fairing::AdHoc;

// The no-op try ignite fairing.
let fairing = AdHoc::try_on_ignite("No-Op", |rocket| async { Ok(rocket) });

pub fn on_liftoff<F: Send + Sync + 'static>(name: &'static str, f: F) -> AdHoc where
    F: for<'a> FnOnce(&'a Rocket<Orbit>) -> BoxFuture<'a, ()>, 

Constructs an AdHoc liftoff fairing named name. The function f will be called by Rocket just after Rocket::launch().

Example

use rocket::fairing::AdHoc;

// A fairing that prints a message just before launching.
let fairing = AdHoc::on_liftoff("Boom!", |_| Box::pin(async move {
    println!("Rocket has lifted off!");
}));

pub fn on_request<F: Send + Sync + 'static>(name: &'static str, f: F) -> AdHoc where
    F: for<'a> Fn(&'a mut Request<'_>, &'a Data<'_>) -> BoxFuture<'a, ()>, 

Constructs an AdHoc request fairing named name. The function f will be called and the returned Future will be awaited by Rocket when a new request is received.

Example

use rocket::fairing::AdHoc;

// The no-op request fairing.
let fairing = AdHoc::on_request("Dummy", |req, data| {
    Box::pin(async move {
        // do something with the request and data...
    })
});

pub fn on_response<F: Send + Sync + 'static>(name: &'static str, f: F) -> AdHoc where
    F: for<'b, 'r> Fn(&'r Request<'_>, &'b mut Response<'r>) -> BoxFuture<'b, ()>, 

Constructs an AdHoc response fairing named name. The function f will be called and the returned Future will be awaited by Rocket when a response is ready to be sent.

Example

use rocket::fairing::AdHoc;

// The no-op response fairing.
let fairing = AdHoc::on_response("Dummy", |req, resp| {
    Box::pin(async move {
        // do something with the request and pending response...
    })
});

pub fn on_shutdown<F: Send + Sync + 'static>(name: &'static str, f: F) -> AdHoc where
    F: for<'a> FnOnce(&'a Rocket<Orbit>) -> BoxFuture<'a, ()>, 

Constructs an AdHoc shutdown fairing named name. The function f will be called by Rocket when shutdown is triggered.

Example

use rocket::fairing::AdHoc;

// A fairing that prints a message just before launching.
let fairing = AdHoc::on_shutdown("Bye!", |_| Box::pin(async move {
    println!("Rocket is on its way back!");
}));

pub fn config<'de, T>() -> AdHoc where
    T: Deserialize<'de> + Send + Sync + 'static, 

Constructs an AdHoc launch fairing that extracts a configuration of type T from the configured provider and stores it in managed state. If extractions fails, pretty-prints the error message and aborts launch.

Example

use serde::Deserialize;
use rocket::fairing::AdHoc;

#[derive(Deserialize)]
struct Config {
    field: String,
    other: usize,
    /* and so on.. */
}

#[launch]
fn rocket() -> _ {
    rocket::build().attach(AdHoc::config::<Config>())
}

Trait Implementations

impl Fairing for AdHoc

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_ignite<'life0, 'async_trait>(
    &'life0 self,
    rocket: Rocket<Build>
) -> Pin<Box<dyn Future<Output = Result> + 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_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
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,
    'life3: 'async_trait,
    'life4: 'async_trait,
    Self: 'async_trait, 

The request 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.