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

Improve overview in fairings guide.

This commit is contained in:
Lori Holden 2017-07-13 11:55:16 -04:00 committed by Sergio Benitez
parent d19ebca685
commit 824240dd30
1 changed files with 13 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
site/guide/fairings.md
View File

@ -6,14 +6,14 @@ about incoming requests and outgoing responses.
## Overview ## Overview
A _fairing_ is a special name for a type that implements the [`Fairing`] trait. _Fairing_ is a name we give to types that implements the [`Fairing`] trait.
Fairings receive callbacks from Rocket when certain events, like that of an Fairings hook into the request cycle of Rocket, receiving callbacks for events
incoming request, occur. Rocket passes information about the event to the such as incoming requests. Rocket passes information about the event to the
fairing, and the fairing can do what it wants with the information. This 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 middleware in other frameworks with a few key Fairings are a lot like the middleware in other frameworks but with a few key
distinctions: distinctions:
* Fairings **cannot** terminate or respond to an incoming request directly. * Fairings **cannot** terminate or respond to an incoming request directly.
@ -22,19 +22,17 @@ 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. Before doing so, consider whether Rocket reaching for fairings instinctively. Rocket provides a rich set of mechanisms
provides a better solution to your problem: While middleware may be the best such as [request guards] and [data guards] that can be used to solve problems
solution to a problem in another framework, it is often a suboptimal solution in in a cleaner, composable, and robust manner. Before considering fairings,
Rocket. Rocket provides richer mechanisms such as [request guards] and [data consider whether Rocket provides a better solution to your problem.
guards] that can be used to solve problems in a cleaner, more composable, and
more robust manner.
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. You should _not_ use a fairing to implement effected through fairings. There are better mechanisms (such as [request guard])
authentication or authorization (preferring to use a [request guard] instead) for implementing things like authentication or authorization _unless_ the
_unless_ the authentication or authorization applies to the entire application. authentication or authorization applies to the entire application. On the other
On the other hand, you _should_ use a fairing to record timing and/or usage hand, fairings are great for tasks such as recording the timing and/or usage
statistics or global security policies. statistics, or implementing 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