Crate wayfind

Expand description

§`wayfind`

A speedy, flexible router for Rust.

§Why another router?

wayfind attempts to bridge the gap between existing Rust router options:

fast routers, lacking in flexibility
flexible routers, lacking in speed

Real-world projects often need fancy routing capabilities, such as projects ported from frameworks like Ruby on Rails, or those adhering to specifications like the Open Container Initiative (OCI) Distribution Specification.

The goal of wayfind is to remain competitive with the fastest libraries, while offering advanced routing features when needed. Unused features shouldn’t impact performance - you only pay for what you use.

§Features

§Dynamic Routing

Dynamic parameters allow matching for any byte, excluding the path delimiter /.

We support both:

whole segment parameters: /{name}/
inline parameters: /{year}-{month}-{day}/

Inline dynamic parameters are greedy in nature, similar to a regex .*, and will attempt to match as many bytes as possible.

§Example

use std::error::Error;
use wayfind::{Path, Router};

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();
    router.insert("/users/{id}", 1)?;
    router.insert("/users/{id}/files/{filename}.{extension}", 2)?;

    let path = Path::new("/users/123")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/users/{id}".into());
    assert_eq!(search.parameters[0].key, "id");
    assert_eq!(search.parameters[0].value, "123");

    let path = Path::new("/users/123/files/my.document.pdf")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/users/{id}/files/{filename}.{extension}".into());
    assert_eq!(search.parameters[0].key, "id");
    assert_eq!(search.parameters[0].value, "123");
    assert_eq!(search.parameters[1].key, "filename");
    assert_eq!(search.parameters[1].value, "my.document");
    assert_eq!(search.parameters[2].key, "extension");
    assert_eq!(search.parameters[2].value, "pdf");

    Ok(())
}

§Wildcard Routing

Wildcard parameters enable matching of one or more segments within a path.

We support both:

mid-route wildcards: /api/{*path}/help
end-route catch-all: /{*catch_all}

§Example

use std::error::Error;
use wayfind::{Path, Router};

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();
    router.insert("/files/{*slug}/delete", 1)?;
    router.insert("/{*catch_all}", 2)?;

    let path = Path::new("/files/documents/reports/annual.pdf/delete")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/files/{*slug}/delete".into());
    assert_eq!(search.parameters[0].key, "slug");
    assert_eq!(search.parameters[0].value, "documents/reports/annual.pdf");

    let path = Path::new("/any/other/path")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/{*catch_all}".into());
    assert_eq!(search.parameters[0].key, "catch_all");
    assert_eq!(search.parameters[0].value, "any/other/path");

    Ok(())
}

§Optional Parameters

wayfind supports marking a parameter as optional.

We support:

optional dynamic segments: /users/{user?}
optional dynamic inlines: /release/v{major}.{minor?}.{patch?}
optional wildcard segments: /files/{*file?}/info

Optional parameters work as syntactic sugar for equivilant, simplified routes.

/users/{user?}:

/users/{user}
/users

/release/v{major}.{minor?}.{patch?}:

/release/v{major}.{minor}.{patch}
/release/v{major}.{minor}
/release/v{major}

/files/{*file?}/info:

/files/{*file}/info
/files/info

There is a small overhead to using optionals, due to Arc usage internally for data storage.

§Example

use std::error::Error;
use wayfind::{Path, Router};

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();
    router.insert("/users/{id?}", 1)?;
    router.insert("/files/{*slug}/{file}.{extension?}", 2)?;

    let path = Path::new("/users")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/users/{id?}".into());
    assert_eq!(search.expanded, Some("/users".into()));

    let path = Path::new("/users/123")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/users/{id?}".into());
    assert_eq!(search.expanded, Some("/users/{id}".into()));
    assert_eq!(search.parameters[0].key, "id");
    assert_eq!(search.parameters[0].value, "123");

    let path = Path::new("/files/documents/folder/report.pdf")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/files/{*slug}/{file}.{extension?}".into());
    assert_eq!(search.expanded, Some("/files/{*slug}/{file}.{extension}".into()));
    assert_eq!(search.parameters[0].key, "slug");
    assert_eq!(search.parameters[0].value, "documents/folder");
    assert_eq!(search.parameters[1].key, "file");
    assert_eq!(search.parameters[1].value, "report");
    assert_eq!(search.parameters[2].key, "extension");
    assert_eq!(search.parameters[2].value, "pdf");

    let path = Path::new("/files/documents/folder/readme")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/files/{*slug}/{file}.{extension?}".into());
    assert_eq!(search.expanded, Some("/files/{*slug}/{file}".into()));
    assert_eq!(search.parameters[0].key, "slug");
    assert_eq!(search.parameters[0].value, "documents/folder");
    assert_eq!(search.parameters[1].key, "file");
    assert_eq!(search.parameters[1].value, "readme");

    Ok(())
}

§Constraints

Constraints allow for custom logic to be injected into the routing process.

We support constraints for all types of parameters:

Dynamic constraint: /{name:constraint}
Wildcard constraint: /{*name:constraint}

The typical use-case for constraints would be to run a regex, or a simple FromStr implementation, against a path segment.

A common mistake would be to use these for validation of parameters. This should be avoided.

If a constraint fails to match, and no other suitable match exists, it results in a Not Found response, rather than any sort of Bad Request.

They act as an escape-hatch for when you need to disambiguate routes.

The current constraint implementation has a number of limitations:

constraints cannot take parameters
checks cannot make use of any prior state
checks cannot store data after a successful check

§Default Constraints

wayfind ships with a number of default constraints.

Curently, these can’t be disabled.

Name	Method
`u8`	`u8::from_str`
`u16`	`u16::from_str`
`u32`	`u32::from_str`
`u64`	`u64::from_str`
`u128`	`u128::from_str`
`usize`	`usize::from_str`
`i8`	`i8::from_str`
`i16`	`i16::from_str`
`i32`	`i32::from_str`
`i64`	`i64::from_str`
`i128`	`i128::from_str`
`isize`	`isize::from_str`
`f32`	`f32::from_str`
`f64`	`f64::from_str`
`bool`	`bool::from_str`
`ipv4`	`Ipv4Addr::from_str`
`ipv6`	`Ipv6Addr::from_str`

§Example

use std::error::Error;
use wayfind::{Constraint, Path, Router};

struct NamespaceConstraint;
impl Constraint for NamespaceConstraint {
    const NAME: &'static str = "namespace";

    fn check(segment: &str) -> bool {
        segment
            .split('/')
            .all(|part| {
                !part.is_empty() && part.chars().all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
            })
    }
}

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();
    router.constraint::<NamespaceConstraint>()?;

    router.insert("/v2", 1)?;
    router.insert("/v2/{*name:namespace}/blobs/{type}:{digest}", 2)?;

    let path = Path::new("/v2")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/v2".into());

    let path = Path::new("/v2/my-org/my-repo/blobs/sha256:1234567890")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/v2/{*name:namespace}/blobs/{type}:{digest}".into());
    assert_eq!(search.parameters[0].key, "name");
    assert_eq!(search.parameters[0].value, "my-org/my-repo");
    assert_eq!(search.parameters[1].key, "type");
    assert_eq!(search.parameters[1].value, "sha256");
    assert_eq!(search.parameters[2].key, "digest");
    assert_eq!(search.parameters[2].value, "1234567890");

    let path = Path::new("/v2/invalid repo/blobs/uploads")?;
    assert!(router.search(&path)?.is_none());

    Ok(())
}

§Optional Trailing Slashes

wayfind supports optional trailing slashes.

This works via adding {/} to the end of a route.

§Example

use std::error::Error;
use wayfind::{Path, Router};

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();
    router.insert("/users{/}", 1)?;
    router.insert("/posts/{id}{/}", 2)?;

    let path = Path::new("/users")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/users{/}".into());
    assert_eq!(search.expanded, Some("/users".into()));

    let path = Path::new("/users/")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 1);
    assert_eq!(search.route, "/users{/}".into());
    assert_eq!(search.expanded, Some("/users/".into()));

    let path = Path::new("/posts/123")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/posts/{id}{/}".into());
    assert_eq!(search.expanded, Some("/posts/{id}".into()));
    assert_eq!(search.parameters[0].key, "id");
    assert_eq!(search.parameters[0].value, "123");

    let path = Path::new("/posts/123/")?;
    let search = router.search(&path)?.unwrap();
    assert_eq!(*search.data, 2);
    assert_eq!(search.route, "/posts/{id}{/}".into());
    assert_eq!(search.expanded, Some("/posts/{id}/".into()));
    assert_eq!(search.parameters[0].key, "id");
    assert_eq!(search.parameters[0].value, "123");

    Ok(())
}

§User-Friendly Error Messages

Where possible, we try to provide user-friendly error messages.

§Example

use std::error::Error;
use wayfind::{Constraint, Router, errors::ConstraintError};

const ERROR_DISPLAY: &str = "
duplicate constraint name

The constraint name 'my_constraint' is already in use:
    - existing constraint type: 'rust_out::ConstraintA'
    - new constraint type: 'rust_out::ConstraintB'

help: each constraint must have a unique name

try:
    - Check if you have accidentally added the same constraint twice
    - Ensure different constraints have different names
";

struct ConstraintA;
impl Constraint for ConstraintA {
    const NAME: &'static str = "my_constraint";

    fn check(segment: &str) -> bool {
        segment == "a"
    }
}

struct ConstraintB;
impl Constraint for ConstraintB {
    const NAME: &'static str = "my_constraint";

    fn check(segment: &str) -> bool {
        segment == "b"
    }
}

fn main() -> Result<(), Box<dyn Error>> {
    let mut router: Router<usize> = Router::new();
    router.constraint::<ConstraintA>()?;

    let error = router.constraint::<ConstraintB>().unwrap_err();
    assert_eq!(error.to_string(), ERROR_DISPLAY.trim());

    Ok(())
}

§Router Display

Routers can print their routes as an tree diagram.

▽ represents the root node.
○ represents nodes within the tree that can be matched against.

Currenty, this doesn’t handle split multi-byte characters well.

§Example

use std::error::Error;
use wayfind::Router;

const ROUTER_DISPLAY: &str = "
▽
├─ /
│  ├─ pet ○
│  │    ╰─ /
│  │       ├─ findBy
│  │       │       ├─ Status ○
│  │       │       ╰─ Tags ○
│  │       ╰─ {petId} ○
│  │                ╰─ /uploadImage ○
│  ├─ store/
│  │       ├─ inventory ○
│  │       ╰─ order ○
│  │              ╰─ /
│  │                 ╰─ {orderId} ○
│  ╰─ user ○
│        ╰─ /
│           ├─ createWithList ○
│           ├─ log
│           │    ├─ in ○
│           │    ╰─ out ○
│           ╰─ {username} ○
╰─ {*catch_all} ○
";

fn main() -> Result<(), Box<dyn Error>> {
    let mut router = Router::new();

    router.insert("/pet", 1)?;
    router.insert("/pet/findByStatus", 2)?;
    router.insert("/pet/findByTags", 3)?;
    router.insert("/pet/{petId}", 4)?;
    router.insert("/pet/{petId}/uploadImage", 5)?;

    router.insert("/store/inventory", 6)?;
    router.insert("/store/order", 7)?;
    router.insert("/store/order/{orderId}", 8)?;

    router.insert("/user", 9)?;
    router.insert("/user/createWithList", 10)?;
    router.insert("/user/login", 11)?;
    router.insert("/user/logout", 12)?;
    router.insert("/user/{username}", 13)?;

    router.insert("{*catch_all}", 14)?;

    assert_eq!(router.to_string(), ROUTER_DISPLAY.trim());
    Ok(())
}

§Performance

wayfind is fast, and appears to be competitive against other top performers in all benchmarks we currently run.

However, as is often the case, your mileage may vary (YMMV). Benchmarks, especially micro-benchmarks, should be taken with a grain of salt.

§Benchmarks

All benchmarks ran on a M1 Pro laptop.

Check out our codspeed results for a more accurate set of timings.

§Context

For all benchmarks, we percent-decode the path before matching. After matching, we convert any extracted parameters to strings.

Some routers perform these operations automatically, while others require them to be done manually.

We do this to try and match behaviour as best as possible. This is as close to an “apples-to-apples” comparison as we can get.

§`matchit` inspired benches

In a router of 130 routes, benchmark matching 4 paths.

Library	Time	Alloc Count	Alloc Size	Dealloc Count	Dealloc Size
matchit	470.40 ns	4	416 B	4	448 B
wayfind	499.12 ns	7	649 B	7	649 B
xitca-router	567.11 ns	7	800 B	7	832 B
path-tree	579.33 ns	4	416 B	4	448 B
ntex-router	1.7468 µs	18	1.248 KB	18	1.28 KB
route-recognizer	4.6578 µs	160	8.515 KB	160	8.547 KB
routefinder	6.5084 µs	67	5.024 KB	67	5.056 KB
actix-router	21.377 µs	214	13.93 KB	214	13.96 KB

§`path-tree` inspired benches

In a router of 320 routes, benchmark matching 80 paths.

Library	Time	Alloc Count	Alloc Size	Dealloc Count	Dealloc Size
wayfind	7.2267 µs	117	9.991 KB	117	9.991 KB
matchit	8.9524 µs	140	17.81 KB	140	17.83 KB
path-tree	9.4107 µs	59	7.447 KB	59	7.47 KB
xitca-router	10.948 µs	209	25.51 KB	209	25.53 KB
ntex-router	29.514 µs	201	19.54 KB	201	19.56 KB
routefinder	100.21 µs	525	48.4 KB	525	48.43 KB
route-recognizer	107.15 µs	2872	191.8 KB	2872	205 KB
actix-router	185.69 µs	2201	128.8 KB	2201	128.8 KB

§License

wayfind is licensed under the terms of both the MIT License and the Apache License (Version 2.0).

§Inspirations

poem: Initial experimentations started out as a Poem router fork
matchit: Performance leader among pre-existing routers
path-tree: Extensive testing and router display feature
ASP.NET Core: Constraints-based approach to routing

Modules§

errors
Error types for wayfind.

Structs§

Match
Stores data from a successful router match.
Parameter
A key-value parameter pair.
Path
Path stores the URI data to be used to search for a matching route in a Router.
Router
The wayfind router.

Traits§

Constraint
A constraint that can be used for custom path routing logic.

Crate wayfindCopy item path

§wayfind

§Why another router?

§Features

§Dynamic Routing

§Example

§Wildcard Routing

§Example

§Optional Parameters

§Example

§Constraints

§Default Constraints

§Example

§Optional Trailing Slashes

§Example

§User-Friendly Error Messages

§Example

§Router Display

§Example

§Performance

§Benchmarks

§Context

§matchit inspired benches

§path-tree inspired benches

§License

§Inspirations

Modules§

Structs§

Traits§

Crate wayfind

§`wayfind`

§`matchit` inspired benches

§`path-tree` inspired benches