rou3/
lib.rs

1//! # rou3
2//!
3//! rou3 is a lightweight and performant HTTP routing library for Rust.
4//! It focuses on fast route matching, including support for static paths,
5//! parameters (e.g., `/:id`), and wildcards (e.g., `/*` or `/**`).
6//!
7//! The primary goal is to provide a flexible routing solution that is easy to
8//! integrate into various web frameworks or custom server implementations.
9//! It uses a tree-based routing algorithm for efficient lookups.
10//!
11//! ## Features
12//!
13//! - Static, parameterized, and wildcard route matching.
14//! - Method-based routing (GET, POST, etc.), including an "any" method.
15//! - Route removal.
16//! - Parameter extraction.
17//! - Thread-safe router using `parking_lot::RwLock`.
18//! - Efficient data structures (`AHashMap`, `IndexMap`) for performance.
19//! - Structured error handling with `thiserror`.
20//!
21//! ## Example
22//!
23//! ```rust
24//! use rou3::{Router, add_route, find_route, MatchedRoute, RouterError};
25//!
26//! // Create a new router instance.
27//! let router = Router::new();
28//!
29//! // Add some routes.
30//! add_route(&router, "GET", "/home", "Welcome Home!").expect("Failed to add /home");
31//! add_route(&router, "GET", "/users/:id", "User Profile").expect("Failed to add /users/:id");
32//! add_route(&router, "POST", "/users", "Create User").expect("Failed to add /users POST");
33//! add_route(&router, "GET", "/files/**:filepath", "Serve File").expect("Failed to add /files/**:filepath");
34//!
35//! // Find a route.
36//! // The `capture` argument (boolean) determines if parameters should be extracted.
37//! match find_route(&router, "GET", "/users/123", true) {
38//!     Ok(matched_route) => {
39//!         assert_eq!(matched_route.data, "User Profile");
40//!         if let Some(params) = matched_route.params {
41//!             assert_eq!(params.get("id").unwrap(), "123");
42//!         }
43//!     }
44//!     Err(e) => panic!("Expected to find route, but got error: {}", e),
45//! }
46//!
47//! match find_route(&router, "GET", "/files/path/to/my/file.txt", true) {
48//!     Ok(matched_route) => {
49//!         assert_eq!(matched_route.data, "Serve File");
50//!         if let Some(params) = matched_route.params {
51//!             assert_eq!(params.get("filepath").unwrap(), "path/to/my/file.txt");
52//!         }
53//!     }
54//!     Err(e) => panic!("Expected to find file route, but got error: {}", e),
55//! }
56//!
57//! // If a route is not found, `find_route` returns `Err(RouterError::RouteNotFound)`.
58//! match find_route(&router, "GET", "/nonexistent", false) {
59//!     Err(RouterError::RouteNotFound { method, path }) => {
60//!         assert_eq!(method, "GET");
61//!         assert_eq!(path, "/nonexistent"); // Path normalization happens, so original might differ slightly
62//!     }
63//!     _ => panic!("Expected RouteNotFound error"),
64//! }
65//! ```
66
67pub mod context;
68pub mod error;
69pub mod operations;
70pub mod types;
71
72pub use context::Router;
73pub use error::RouterError;
74pub use operations::add_route;
75pub use operations::find_all_routes;
76pub use operations::find_route;
77pub use operations::remove_route;
78pub use types::MatchedRoute;
rou3/lib.rs

rou3/
lib.rs
