Overview

Any type that implements the Fairing trait is a fairing. Fairings hook into Rocket’s request lifecycle, receiving callbacks for events such as incoming requests and outgoing responses. Rocket passes information about these events to the fairing, and the fairing can do what it wants with the information. This includes rewriting data when applicable, recording information about the event or data, or doing nothing at all.

Rocket’s fairings are a lot like middleware from other frameworks, but they bear a few key distinctions:

• Fairings cannot terminate or respond to an incoming request directly.
• Fairings cannot inject arbitrary, non-request data into a request.
• Fairings can prevent an application from launching.
• Fairings can inspect and modify the application’s configuration.

If you are familiar with middleware from other frameworks, you may find yourself reaching for fairings instinctively. Before doing so, remember that Rocket provides a rich set of mechanisms such as request guards and data guards that can be used to solve problems in a clean, composable, and robust manner.

As a general rule of thumb, only globally applicable actions should be effected through fairings. You should not use a fairing to implement authentication or authorization (preferring to use a request guard instead) unless the authentication or authorization applies to all or most of the application. On the other hand, you should use a fairing to record timing and usage statistics or to enforce global security policies.

Attaching

Fairings are registered with Rocket via the attach method on a Rocket instance. Only when a fairing is attached will its callbacks fire. As an example, the following snippet attached two fairings, req_fairing and res_fairing, to a new Rocket instance:

rocket::ignite()
    .attach(req_fairing)
    .attach(res_fairing)
    .launch();

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.

Callbacks

There are four events for which Rocket issues fairing callbacks. Each of these events is described below:

• Attach (on_attach)

  An attach callback is called when a fairing is first attached via the attach method. An attach callback can arbitrarily modify the Rocket instance being constructed and optionally abort launch. Attach fairings are commonly used to parse and validate configuration values, aborting on bad configurations, and inserting the parsed value into managed state for later retrieval.

• Launch (on_launch)

  A launch callback is called immediately before the Rocket application has launched. A launch callback can inspect the Rocket instance being launched. A launch callback can be a convenient hook for launching services related to the Rocket application being launched.

• Request (on_request)

  A request callback is called just after a request is received. A request callback can modify the request at will and peek into the incoming data. It may not, however, abort or respond directly to the request; these issues are better handled via request guards or via response callbacks.

• Response (on_response)

  A response callback is called when a response is ready to be sent to the client. A response callback can modify part or all of the response. As such, a response fairing can be used to provide a response when the greater applications fails to by rewriting 404 responses as desired. As another example, response fairings can also be used to inject headers into all outgoing responses.