front_line/
lib.rs

1//! `front-line` - A declarative, zero-copy HTTP router for Rust.
2//!
3//! The `front-line` crate provides utilities to route HTTP requests based on their method and path,
4//! offering both manual routing capabilities and a declarative macro-driven approach for simpler use cases.
5//! It emphasizes zero-copy operations to maximize efficiency and performance.
6//!
7//! ## Features:
8//!
9//! - **Declarative:** Define routes as enums with proc-macro attributes.
10//! - **Zero-copy capture:** Easily capture dynamic segments from paths (e.g., `/users/{id}`)
11//!   with opt-in zero-copy capture to avoid unnecessary copying and allocations.
12//! - **Dispatch free:** Only handles path based route resolution and allows the user to choose
13//!   how to perform dispatch.
14//!
15//! ## Basic Usage:
16//!
17//! ```rust
18//! use front_line::{FrontLine, HttpVersion, RouterResult, Router};
19//!
20//! #[derive(FrontLine)]
21//! enum MarketingRoutes {
22//!     #[get("/")]
23//!     RenderIndex,
24//!     #[get("/sign-up")]
25//!     RenderSignUp,
26//!     #[post("/sign-up")]
27//!     ProcessSignUp,
28//!     #[get("/log-in")]
29//!     RenderLogIn,
30//!     #[post("/log-in")]
31//!     ProcessLogIn,
32//!     #[get("/portal")]
33//!     RenderPortal,
34//! }
35//!
36//! #[derive(FrontLine)]
37//! #[prefix("/api")]
38//! enum ApiRoutes<'a> {
39//!     #[get("/users")]
40//!     GetAllUsers,
41//!     #[post("/users")]
42//!     CreateUser,
43//!     #[get("/users/{id}")]
44//!     GetUser { id: u32 },
45//!     #[get("/users/{id}/roles/{role}")]
46//!     GetUserRole { id: u32, role: &'a str },
47//!     #[put("/users/{id}/roles/{role}")]
48//!     UpdateUserRole { id: u32, role: &'a str },
49//! }
50//!
51//! #[derive(FrontLine)]
52//! enum AllRoutes<'a> {
53//!     #[flatten]
54//!     Marketing(MarketingRoutes),
55//!     #[flatten]
56//!     Api(ApiRoutes<'a>),
57//! }
58//!
59//! // Construct an example http request, this would normally just be read off of a socket.
60//! let request = b"GET /api/users/42?a=b HTTP/1.1\r\n\r\nContent-Length: 12\r\n\r\nHello World!";
61//!
62//! // Parse and and resolve the route
63//! let route = AllRoutes::resolve(request);
64//!
65//! // For demonstration purposes, assert the resolved route is what we expect
66//! assert!(matches!(route, Ok(RouterResult {
67//!   route: Some(AllRoutes::Api(ApiRoutes::GetUser { id: 42 })),
68//!   query: "a=b",
69//!   version: HttpVersion::OneOne,
70//!   head_and_body: b"Content-Length: 12\r\n\r\nHello World!",
71//! })));
72//!```
73//!
74//! For more advanced usage and examples, please refer to individual module documentation.
75
76pub use front_line_derive::*;
77pub use front_line_router::*;
front_line/lib.rs

front_line/
lib.rs
