path-tree

A lightweight high performance HTTP request router for Rust

Parameters Syntax

| Pattern | Kind | Description | | ------------------------------- | ------------------- | ------------------------------------------------------------------------------ | | :name | Normal | Matches a path piece, excludes / | | :name? | Optional | Matches an optional path piece, excludes / | | /:name?/ /:name? | OptionalSegment | Matches an optional path segment, excludes /, prefix or suffix should be / | | + :name+ | OneOrMore | Matches a path piece, includes / | | * :name* | ZeroOrMore | Matches an optional path piece, includes / | | /*/ /* /:name*/ /:name* | ZeroOrMoreSegment | Matches zero or more path segments, prefix or suffix should be / |

Supports

| Case | Parameters | | ----------------------- | ----------- | | :a:b | a b | | :a:b? | a b | | :a-:b :a.:b :a~:b | a b | | :a_a-:b_b | a_a b_b | | :a\\: :a\\_ | a | | :a\\::b :a\\_:b | a b | | :a* | a | | * | *1 | | *.* | *1 *2 | | :a+ | a | | + | +1 | | +.+ | +1 +2 | | /*/abc/+/def/g | *1 +2 |

Examples

```rust use path_tree::PathTree;

/* / •0 ├── api/ │ └── + •13 ├── login •1 ├── public/ │ └── * •7 ├── s │ ├── ettings •3 │ │ └── / │ │ └── : •4 │ └── ignup •2 └── : •5 └── / └── : •6 └── / ├── actions/ │ └── : │ └── \: │ └── : •10 ├── releases/download/ │ └── : │ └── / │ └── : │ └── . │ └── : •8 ├── tags/ │ └── : │ └── - │ └── : │ └── - │ └── : •9 ├── : •11 └── * •12 */ let mut tree = PathTree::new();

tree.insert("/", 0); tree.insert("/login", 1); tree.insert("/signup", 2); tree.insert("/settings", 3); tree.insert("/settings/:page", 4); tree.insert("/:user", 5); tree.insert("/:user/:repo", 6); tree.insert("/public/:any", 7); tree.insert("/:org/:repo/releases/download/:tag/:filename.:ext", 8); tree.insert("/:org/:repo/tags/:day-:month-:year", 9); tree.insert("/:org/:repo/actions/:name\::verb", 10); tree.insert("/:org/:repo/:page", 11); tree.insert("/:org/:repo/", 12); tree.insert("/api/+", 13);

let (h, p) = tree.find("/").unwrap(); asserteq!(h, &0); asserteq!(p.params(), vec![]);

let (h, p) = tree.find("/login").unwrap(); asserteq!(h, &1); asserteq!(p.params(), vec![]);

let (h, p) = tree.find("/settings/admin").unwrap(); asserteq!(h, &4); asserteq!(p.params(), vec![("page", "admin")]);

let (h, p) = tree.find("/viz-rs").unwrap(); asserteq!(h, &5); asserteq!(p.params(), vec![("user", "viz-rs")]);

let (h, p) = tree.find("/viz-rs/path-tree").unwrap(); asserteq!(h, &6); asserteq!(p.params(), vec![("user", "viz-rs"), ("repo", "path-tree")]);

let (h, p) = tree.find("/rust-lang/rust-analyzer/releases/download/2022-09-12/rust-analyzer-aarch64-apple-darwin.gz").unwrap(); asserteq!(h, &8); asserteq!( p.params(), vec![ ("org", "rust-lang"), ("repo", "rust-analyzer"), ("tag", "2022-09-12"), ("filename", "rust-analyzer-aarch64-apple-darwin"), ("ext", "gz") ] );

let (h, p) = tree.find("/rust-lang/rust-analyzer/tags/2022-09-12").unwrap(); asserteq!(h, &9); asserteq!( p.params(), vec![ ("org", "rust-lang"), ("repo", "rust-analyzer"), ("day", "2022"), ("month", "09"), ("year", "12") ] );

let (h, p) = tree.find("/rust-lang/rust-analyzer/actions/ci:bench").unwrap(); asserteq!(h, &10); asserteq!( p.params(), vec![ ("org", "rust-lang"), ("repo", "rust-analyzer"), ("name", "ci"), ("verb", "bench"), ] );

let (h, p) = tree.find("/rust-lang/rust-analyzer/stargazers").unwrap(); asserteq!(h, &11); asserteq!(p.params(), vec![("org", "rust-lang"), ("repo", "rust-analyzer"), ("page", "stargazers")]);

let (h, p) = tree.find("/rust-lang/rust-analyzer/stargazers/404").unwrap(); asserteq!(h, &12); asserteq!(p.params(), vec![("org", "rust-lang"), ("repo", "rust-analyzer"), ("*1", "stargazers/404")]);

let (h, p) = tree.find("/public/js/main.js").unwrap(); asserteq!(h, &7); asserteq!(p.params(), vec![("any", "js/main.js")]);

let (h, p) = tree.find("/api/v1").unwrap(); asserteq!(h, &13); asserteq!(p.params(), vec![("+1", "v1")]); ```

Hyper hello example can be found here.

Benchmark

shell $ cargo bench

Acknowledgements

It is inspired by the:

[rax]
[httprouter]
[echo] router
[path-to-regexp]
[gofiber] router
[trekjs] router

Other languages

Wrappers for path-tree in other languages:

Python: https://github.com/adriangb/routrie

License

^{Licensed under either of Apache License, Version
2.0 or MIT license at your option.}

_{Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.}