rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Additional changes to fairings guide overview.

This commit is contained in:
Sergio Benitez 2017-08-11 15:29:42 -07:00
parent 536dd39636
commit a58790d6d9
1 changed files with 14 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
site/guide/fairings.md
View File

@ -6,15 +6,15 @@ about incoming requests and outgoing responses.
## Overview ## Overview
_Fairing_ is a name we give to types that implements the [`Fairing`] trait. Any type that implements the [`Fairing`] trait is a _fairing_. Fairings hook
Fairings hook into the request cycle of Rocket, receiving callbacks for events into Rocket's request lifecycle, receiving callbacks for events such as incoming
such as incoming requests. Rocket passes information about the event to the requests and outgoing responses. Rocket passes information about these event to
fairing, and the fairing can do what it wants with the information. This the fairing, and the fairing can do what it wants with the information. This
includes rewriting data when applicable, recording information about the event includes rewriting data when applicable, recording information about the event
or data, or doing nothing at all. or data, or doing nothing at all.
Fairings are a lot like the middleware in other frameworks but with a few key Rocket’s fairings are a lot like middleware from other frameworks, but they bear
distinctions: a few key distinctions:
* Fairings **cannot** terminate or respond to an incoming request directly. * Fairings **cannot** terminate or respond to an incoming request directly.
* Fairings **cannot** inject arbitrary, non-request data into a request. * Fairings **cannot** inject arbitrary, non-request data into a request.
@ -22,17 +22,16 @@ distinctions:
* Fairings _can_ inspect and modify the application's configuration. * Fairings _can_ inspect and modify the application's configuration.
If you are familiar with middleware from other frameworks, you may find yourself If you are familiar with middleware from other frameworks, you may find yourself
reaching for fairings instinctively. Rocket provides a rich set of mechanisms reaching for fairings instinctively. Before doing so, remember that Rocket
such as [request guards] and [data guards] that can be used to solve problems provides a rich set of mechanisms such as [request guards] and [data guards]
in a cleaner, composable, and robust manner. Before considering fairings, that can be used to solve problems in a clean, composable, and robust manner.
consider whether Rocket provides a better solution to your problem.
As a general rule of thumb, only _globally applicable_ actions should be As a general rule of thumb, only _globally applicable_ actions should be
effected through fairings. There are better mechanisms (such as [request guard]) effected through fairings. You should _not_ use a fairing to implement
for implementing things like authentication or authorization _unless_ the authentication or authorization (preferring to use a [request guard] instead)
authentication or authorization applies to the entire application. On the other _unless_ the authentication or authorization applies to all or most of the
hand, fairings are great for tasks such as recording the timing and/or usage application. On the other hand, you _should_ use a fairing to record timing and
statistics, or implementing global security policies. usage statistics or to enforce global security policies.
[`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html [`Fairing`]: https://api.rocket.rs/rocket/fairing/trait.Fairing.html
[request guard]: /guide/requests/#request-guards [request guard]: /guide/requests/#request-guards