2 unstable releases
0.2.0 | Oct 4, 2023 |
---|---|
0.1.0 | Oct 3, 2023 |
#17 in #http-router
35KB
585 lines
Front Line
A declarative, zero-copy HTTP router for Rust.
The front-line
crate offers utilities to route HTTP requests based on their
method and path. With declarative macro-driven approach, it's suitable for
both complex and straightforward use cases.
Table of Contents
Features
- Declarative: With the help of proc-macro attributes, you can easily define routes as enums.
- Zero-copy capture: Dynamic segments from paths, such as
/users/{id}
, can be captured without unnecessary data copying, ensuring efficient memory usage. - Dispatch free: The crate focuses purely on route resolution based on the path, leaving dispatch methods up to the user's discretion.
Basic Usage
use front_line::{FrontLine, HttpVersion, RouterResult, Router};
#[derive(FrontLine)]
enum MarketingRoutes {
#[get("/")]
RenderIndex,
#[get("/sign-up")]
RenderSignUp,
#[post("/sign-up")]
ProcessSignUp,
#[get("/log-in")]
RenderLogIn,
#[post("/log-in")]
ProcessLogIn,
#[get("/portal")]
RenderPortal,
}
#[derive(FrontLine)]
#[prefix("/api")]
enum ApiRoutes<'a> {
#[get("/users")]
GetAllUsers,
#[post("/users")]
CreateUser,
#[get("/users/{id}")]
GetUser { id: u32 },
#[get("/users/{id}/roles/{role}")]
GetUserRole { id: u32, role: &'a str },
#[put("/users/{id}/roles/{role}")]
UpdateUserRole { id: u32, role: &'a str },
}
#[derive(FrontLine)]
enum AllRoutes<'a> {
#[flatten]
Marketing(MarketingRoutes),
#[flatten]
Api(ApiRoutes<'a>),
}
// Construct an example http request, typically read from a socket.
let request = b"GET /api/users/42?a=b HTTP/1.1\r\n\r\nContent-Length: 12\r\n\r\nHello World!";
// Parse and resolve the route
let route = AllRoutes::resolve(request);
// For demonstration purposes, assert the resolved route matches expectations
assert!(matches!(route, Ok(RouterResult {
route: Some(AllRoutes::Api(ApiRoutes::GetUser { id: 42 })),
query: "a=b",
version: HttpVersion::OneOne,
head_and_body: b"Content-Length: 12\r\n\r\nHello World!",
})));
Testing
Tests should run fine with the standard cargo test
.
However, for consistency, we recommend using the dockerized test environment.
To use the dockerized test environment the only requirements are make
and
docker
(you don't even need rust installed locally). Simply run the
following command.
make test
Dependencies
~2.5–4MB
~75K SLoC