大多数的 Web 框架都会提供中间件(Middleware)机制,使用固定的额外程序来处理每次的 HTTP 请求或是 HTTP 回应。Rocket 框架对于中间件的支持是依靠「整流片」(Fairing)来完成的,我们可以替任意的类型实作 fairing::Fairing 特性,使其能作为「挂钩」(hook)来监听 Rocket 框架收到 HTTP 请求时的事件,或是要送出 HTTP 回应时的事件。
fairing::Fairing 特性的基本实作方式如下:
use rocket::{
data::Data,
fairing::{self, Fairing, Info, Kind},
request::Request,
response::Response,
Build, Orbit, Rocket,
};
struct MyFairing;
#[rocket::async_trait]
impl Fairing for MyFairing {
fn info(&self) -> Info {
Info {
name: "the name of this fairing",
kind: Kind::Ignite | Kind::Liftoff | Kind::Request | Kind::Response | Kind::Shutdown,
}
}
async fn on_ignite(&self, rocket: Rocket<Build>) -> fairing::Result {
info!("on_ignite");
Ok(rocket)
}
async fn on_liftoff(&self, rocket: &Rocket<Orbit>) {
info!("on_liftoff");
}
async fn on_request(&self, request: &mut Request<'_>, data: &mut Data<'_>) {
info!("on_request");
}
async fn on_response<'r>(&self, request: &'r Request<'_>, response: &mut Response<'r>) {
info!("on_response");
}
async fn on_shutdown(&self, rocket: &Rocket<Orbit>) {
info!("on_shutdown");
}
}
在 info 这个由 fairing::Fairing 特性提供的方法中,我们必须要回传一个 fairing::Info 结构实体,里面有现在正在被实作的整流片的名称,以及它所要监听的事件,事件会以 fairing::Kind 结构实体来表示。fairing::Kind 结构体有实作 BitOr 特性,因此可以直接使用 | 进行 OR 运算,来合并多种 fairing::Kind 结构实体,以监听多种不同的事件。
一个整流片可以监听的事件有以下五种:
- Ignite:当
Rocket正要启动前。也就是使用Rocket结构实体的ignite或是launch方法时。 - Liftoff:当
Rocket启动后。也就是使用Rocket结构实体的launch方法后。 - Request:当接收到 HTTP 请求,在寻找可匹配的路由处理程序前时。
- Response:当路由处理程序回传 HTTP 回应后,在其被发送给客户端前时。
- Shutdown:当
Rocket正在被优雅的关机时。
每种事件在被触发的时候会去运行 fairing::Fairing 特性中对应的方法,在实作 fairing::Fairing 特性时,只需要针对有被监听的事件来实作方法即可,不需要将所有事件的对应方法都实作出来(因为这些方法已有预设的实作)。例如,只想监听 Request 和 Response 事件的话,程序可以改写如下:
use rocket::{
data::Data,
fairing::{Fairing, Info, Kind},
request::Request,
response::Response,
};
struct MyFairing;
#[rocket::async_trait]
impl Fairing for MyFairing {
fn info(&self) -> Info {
Info {
name: "the name of this fairing", kind: Kind::Request | Kind::Response
}
}
async fn on_request(&self, request: &mut Request<'_>, data: &mut Data<'_>) {
info!("on_request");
}
async fn on_response<'r>(&self, request: &'r Request<'_>, response: &mut Response<'r>) {
info!("on_response");
}
}
另外,data::Data 这个结构体我们以前并未提到,它其实也是一个数据守卫,可以用来匹配任何格式的 HTTP 主体,能够直接读取 HTTP 主体中的原始数据。
举个例子,实作出一个可以分别统计 GET 和 POST 请求次数的整流片。如下:
use std::{
io::Cursor,
sync::atomic::{AtomicUsize, Ordering},
};
use rocket::{
data::Data,
fairing::{Fairing, Info, Kind},
http::{ContentType, Method, Status},
request::Request,
response::Response,
};
#[derive(Default)]
struct MethodsCounter {
get: AtomicUsize,
post: AtomicUsize,
others: AtomicUsize,
}
#[rocket::async_trait]
impl Fairing for MethodsCounter {
fn info(&self) -> Info {
Info {
name: "The Methods Counter", kind: Kind::Request | Kind::Response
}
}
async fn on_request(&self, request: &mut Request<'_>, _data: &mut Data<'_>) {
match request.method() {
Method::Get => self.get.fetch_add(1, Ordering::Relaxed),
Method::Post => self.post.fetch_add(1, Ordering::Relaxed),
_ => self.others.fetch_add(1, Ordering::Relaxed),
};
}
async fn on_response<'r>(&self, request: &'r Request<'_>, response: &mut Response<'r>) {
if response.status() == Status::NotFound
&& request.method() == Method::Get
&& request.uri().path() == "/counts"
{
let get_count = self.get.load(Ordering::Relaxed);
let post_count = self.post.load(Ordering::Relaxed);
let others_count = self.others.load(Ordering::Relaxed);
let body = format!("Get: {get_count}\nPost: {post_count}\nOthers: {others_count}");
response.set_status(Status::Ok);
response.set_header(ContentType::Plain);
response.set_sized_body(body.len(), Cursor::new(body));
}
}
}
以上程序,我们在 fairing::Fairing 特性的 on_request 方法中,去判断 HTTP 请求方法的类型,并且使 MethodsCounter 结构实体的对应字段值加 1。on_response 方法中,我们拦截了 HTTP 状态码为 404 (NotFound)的所有回应,并判断其 HTTP 请求方法是否为 GET,且路径为 /counts。如果是的话,就将回应的 HTTP 状态码修改为 200 (Ok),Content-Type 标头字段修改为 text/plain; charset=utf-8,主体修改为 MethodsCounter 结构实体的所有字段信息(也就是当前的请求次数的统计结果)。
若要将 MethodsCounter 整流片注册给 Rocket 来使用的话,就使用 Rocket 结构实体提供的 attach 方法,将要注册的整流片实体当作参数传进去即可。如下:
rocket::build().attach(MethodsCounter::default())
直接用闭包当作整流片挂钩
如果觉得实作 fairing::Fairing 特性很麻烦的话,也可以直接透过 fairing::AdHoc 结构体来包裹某个闭包,将其变成整流片来使用。这个方式适用于简单的处理,无法如上面那个例子一样,利用结构体来直接记录状态。
例如:
use rocket::{fairing::AdHoc, http::Method};
...
rocket::build()
.attach(AdHoc::on_ignite("Launch Printer", |rocket| {
Box::pin(async move {
info!("Rocket is about to launch! Exciting! Here we go...");
rocket
})
}))
.attach(AdHoc::on_request("Always-Get Rewriter", |req, _| {
Box::pin(async move {
req.set_method(Method::Get);
})
}))
...
不过,我们也可以在整流片中透过万用的 request::Request 结构实体来访问 Rocket 的「应用程序状态」,例如:
#[macro_use]
extern crate rocket;
use std::{
io::Cursor,
sync::atomic::{AtomicUsize, Ordering},
};
use rocket::{
fairing::AdHoc,
http::{ContentType, Method, Status},
State,
};
#[derive(Default)]
struct MethodsCounter {
get: AtomicUsize,
post: AtomicUsize,
others: AtomicUsize,
}
#[launch]
fn rocket() -> _ {
rocket::build()
.manage(MethodsCounter::default())
.attach(AdHoc::on_request("Request Methods Counter", |req, _| {
Box::pin(async move {
let methods_counter = req.guard::<&State<MethodsCounter>>().await.unwrap();
match req.method() {
Method::Get => methods_counter.get.fetch_add(1, Ordering::Relaxed),
Method::Post => methods_counter.post.fetch_add(1, Ordering::Relaxed),
_ => methods_counter.others.fetch_add(1, Ordering::Relaxed),
};
})
}))
.attach(AdHoc::on_response("Request Methods Getter", |req, res| {
Box::pin(async move {
if res.status() == Status::NotFound
&& req.method() == Method::Get
&& req.uri().path() == "/counts"
{
let methods_counter = req.guard::<&State<MethodsCounter>>().await.unwrap();
let get_count = methods_counter.get.load(Ordering::Relaxed);
let post_count = methods_counter.post.load(Ordering::Relaxed);
let others_count = methods_counter.others.load(Ordering::Relaxed);
let body =
format!("Get: {get_count}\nPost: {post_count}\nOthers: {others_count}");
res.set_status(Status::Ok);
res.set_header(ContentType::Plain);
res.set_sized_body(body.len(), Cursor::new(body));
}
})
}))
}
用整流片处理 Rocket 框架的设置值
在先前的章节中有提到 Rocket 框架的设置档可以传入我们自订的设置项目,由于 Rocket 的主旨在于安全的类型化,因此所有从外面传进来的设置值都必须要在 Rocket 框架启动前,经过程序检查过格式后才可以被拿来使用。而检查设置值最好的时机点,就是在整流片被触发 Ignite 事件时啦!
举例来说,我们有个自订的设置项目名称 buffer_size,可以用来设置堆栈空间中缓冲空间的大小。我们希望这个值必须要大于等于 256,且小于等于 67108864。利用刚才介绍的 fairing::AdHoc 结构体,可以撰写出如以下的检查程序:
use std::{convert::TryFrom, str::FromStr};
const DEFAULT_BUFFER_SIZE: usize = 4096;
pub struct BufferSize(usize);
impl BufferSize {
pub fn get_value(&self) -> usize {
self.0
}
}
impl Default for BufferSize {
fn default() -> Self {
BufferSize(DEFAULT_BUFFER_SIZE)
}
}
impl TryFrom<i64> for BufferSize {
type Error = &'static str;
fn try_from(value: i64) -> Result<Self, Self::Error> {
if value < 256 {
Err("the buffer size is smaller than 256")
} else if value > 67108864 {
Err("the buffer size is bigger than 67108864")
} else {
Ok(BufferSize(value as usize))
}
}
}
impl FromStr for BufferSize {
type Err = &'static str;
fn from_str(value: &str) -> Result<Self, Self::Err> {
let value: i64 = value.parse().map_err(|_| "the buffer size needs to be an integer")?;
Self::try_from(value)
}
}
...
use rocket::fairing::AdHoc;
rocket::build().attach(AdHoc::try_on_ignite("BUFFER_SIZE Checker", |rocket| {
Box::pin(async move {
let buffer_size = rocket.figment().find_value("buffer_size");
let checked_buffer_size = match buffer_size {
Ok(buffer_size) => match buffer_size.deserialize::<i64>() {
Ok(buffer_size) => match BufferSize::try_from(buffer_size) {
Ok(buffer_size) => buffer_size,
Err(error) => {
error!("{error}");
return Err(rocket);
},
},
Err(_) => {
error!("the buffer size needs to be an integer");
return Err(rocket);
},
},
Err(_) => BufferSize::default(),
};
Ok(rocket.manage(checked_buffer_size))
})
}))
...
如此一来,检查过后的 buffer_size 就会被保存成 BufferSize 实体,被注册进 Rocket 的应用程序状态中。注意这边使用到了 fairing::AdHoc 结构体提供的 try_on_ignite 关联函数,而不是 on_ignite,为的是让 BUFFER_SIZE Checker 整流片有能力在发现问题时中止 Rocket 应用程序的启动。
总结
Rocket 框架提供的「整流片」机制即类似其它 Web 框架所提供的「中间件」机制。由于整流片在监听 HTTP 请求和回应事件时,有很大的可能会需要直接操作 request::Request 结构实体和 response::Response 结构实体,算是比较低级的用法,所以在程序实作上会稍微麻烦了一点,对于程序性能的影响也是需要加以考量的。
在下一个章节中,将会回头介绍更高级的处理 HTTP 回应的方式。
