大多数的 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 回应的方式。

下一章:高级处理 HTTP 回应(Response)的方式。