Module rocket::fairing

source ·
Expand description

Fairings: callbacks at launch, liftoff, 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::build()
    .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. A fairing can be attached any number of times. Except for singleton fairings, all attached instances are polled at runtime. Fairing callbacks may not be commutative; the order in which fairings are attached may be significant. It is thus important to communicate specific fairing functionality clearly.

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.

Type Aliases