Module rocket::fairing

Fairings: callbacks at attach, launch, request, and response time.

Fairings allow for structured interposition at various points in the application lifetime. Fairings can be seen as a restricted form of “middleware”. A fairing is an arbitrary structure with methods representing callbacks that Rocket will run at requested points in a program. You can use fairings to rewrite or record information about requests and responses, or to perform an action once a Rocket application has launched.

To learn more about writing a fairing, see the Fairing trait documentation. You can also use AdHoc to create a fairing on-the-fly from a closure or function.

Attaching

You must inform Rocket about fairings that you wish to be active by calling Rocket::attach() method on the application’s Rocket instance and passing in the appropriate Fairing. For instance, to attach fairings named req_fairing and res_fairing to a new Rocket instance, you might write:

let rocket = rocket::ignite()
    .attach(req_fairing)
    .attach(res_fairing);

Once a fairing is attached, Rocket will execute it at the appropriate time, which varies depending on the fairing implementation. See the Fairing trait documentation for more information on the dispatching of fairing methods.

Ordering

Fairings are executed in the order in which they are attached: the first attached fairing has its callbacks executed before all others. Because fairing callbacks may not be commutative, the order in which fairings are attached may be significant. Because of this, it is important to communicate to the user every consequence of a fairing.

Furthermore, a Fairing should take care to act locally so that the actions of other Fairings are not jeopardized. For instance, unless it is made abundantly clear, a fairing should not rewrite every request.

Structs

AdHoc

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

Info

Information about a Fairing.

Kind

A bitset representing the kinds of callbacks a Fairing wishes to receive.

Traits

Fairing

Trait implemented by fairings: Rocket’s structured middleware.