Fairings
Fairings are Rocket's approach to structured middleware. With fairings, your application can hook into the request lifecycle to record or rewrite information about incoming requests and outgoing responses.
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; the fairing can do what it wants with the information. This includes rewriting requests or responses, recording information about the event, 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 the overwhelming majority 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:
1 2 3 4 5 6
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.
Callbacks
There are five events for which Rocket issues fairing callbacks. Each of these events is briefly described below and in details in the Fairing
trait docs:
-
Ignite (
on_ignite
)An ignite callback is called during ignition An ignite callback can arbitrarily modify the
Rocket
instance being built. They are commonly used to parse and validate configuration values, aborting on bad configurations, and inserting the parsed value into managed state for later retrieval. -
Liftoff (
on_liftoff
)A liftoff callback is called immediately after a Rocket application has launched. A liftoff callback can inspect the
Rocket
instance being launched. A liftoff 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 application fails by rewriting 404 responses as desired. As another example, response fairings can also be used to inject headers into all outgoing responses.
-
Shutdown (
on_shutdown
)A shutdown callback is called when shutdown is triggered. At this point, graceful shutdown has commenced but not completed; no new requests are accepted but the application may still be actively serving existing requests. All registered shutdown fairings are run concurrently; resolution of all fairings is awaited before resuming shutdown.
Implementing
Recall that a fairing is any type that implements the Fairing
trait. A Fairing
implementation has one required method: info
, which returns an Info
structure. This structure is used by Rocket to assign a name to the fairing and determine the set of callbacks the fairing is registering for. A Fairing
can implement any of the available callbacks: on_ignite
, on_liftoff
, on_request
, on_response
, and on_shutdown
. Each callback has a default implementation that does absolutely nothing.
Requirements
A type implementing Fairing
is required to be Send + Sync + 'static
. This means that the fairing must be sendable across thread boundaries (Send
), thread-safe (Sync
), and have only static references, if any ('static
). Note that these bounds do not prohibit a Fairing
from holding state: the state need simply be thread-safe and statically available or heap allocated.
Example
As an example, we want to record the number of GET
and POST
requests that our application has received. While we could do this with request guards and managed state, it would require us to annotate every GET
and POST
request with custom types, polluting handler signatures. Instead, we can create a simple fairing that acts globally.
The code for a Counter
fairing below implements exactly this. The fairing receives a request callback, where it increments a counter on each GET
and POST
request. It also receives a response callback, where it responds to unrouted requests to the /counts
path by returning the recorded number of counts.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
use Cursor;
use ;
use ;
use ;
use ;
The complete example can be found in the Fairing
documentation.
Ad-Hoc Fairings
For simpler cases, implementing the Fairing
trait can be cumbersome. This is why Rocket provides the AdHoc
type, which creates a fairing from a simple function or closure. Using the AdHoc
type is easy: simply call the on_ignite
, on_liftoff
, on_request
, on_response
, or on_shutdown
constructors on AdHoc
to create a fairing from a function or closure.
As an example, the code below creates a Rocket
instance with two attached ad-hoc fairings. The first, a liftoff fairing named "Liftoff Printer", prints a message indicating that the application has launched. The second named "Put Rewriter", a request fairing, rewrites the method of all requests to be PUT
.
1 2 3 4 5 6 7 8 9 10 11 12 13
use AdHoc;
use Method;
build
.attach
.attach
.attach;