Templated Uri

Standards-compliant URI handling with templating, validation, and data classification.

This crate provides comprehensive URI manipulation capabilities designed for HTTP clients and servers that need type-safe, efficient, and data classification-aware URI handling. It builds on top of the standard http crate while adding additional validation guarantees, templating capabilities, and data classification features.

Core Types

The crate centers around several key abstractions:

Uri - Flexible URI type composed of an optional BaseUri and an optional path/query
BaseUri - Lightweight type representing scheme, authority, and optional base path (BasePath)
PathAndQueryTemplate - RFC 6570 Level 3 compliant URI templating
Escaped and EscapedString - Generic newtype wrapper proving a value is properly escaped for URI components by not containing any reserved characters

Basic Usage

Simple URI Construction

use templated_uri::{BaseUri, PathAndQuery, Uri};

// Create the base (scheme + authority, optionally a path prefix)
let base_uri = BaseUri::from_static("https://api.example.com");

// Create a path (can be static for zero-allocation)
let path: PathAndQuery = PathAndQuery::from_static("/api/v1/users");

// Combine into complete URI
let uri = Uri::default().with_base(base_uri).with_path_and_query(path);
assert_eq!(
    uri.to_string().declassify_ref(),
    "https://api.example.com/api/v1/users"
);

Templated URIs

For dynamic URIs with variable components, use the templating system:

use templated_uri::{BaseUri, EscapedString, PathAndQueryTemplate, Uri, templated};

#[templated(template = "/users/{user_id}/posts/{post_id}", unredacted)]
#[derive(Clone)]
struct UserPostPath {
    user_id: u32,
    post_id: EscapedString,
}

let path = UserPostPath {
    user_id: 42,
    post_id: EscapedString::escape("my-post"),
};

let uri = Uri::default()
    .with_base(BaseUri::from_static("https://api.example.com"))
    .with_path_and_query(path);

URI Escaping Guarantees

The Escaped<T> newtype wraps values that are guaranteed to contain only valid URI characters. This prevents common URI injection vulnerabilities:

use templated_uri::EscapedString;

// This will succeed - percent-encodes any invalid characters
let encoded = EscapedString::escape("hello world?foo=bar");
assert_eq!(encoded.as_str(), "hello%20world%3Ffoo%3Dbar");

// This will succeed - contains only valid characters
let valid = EscapedString::try_new("hello-world_123").unwrap();
assert_eq!(valid.as_str(), "hello-world_123");

// try_new() fails on URI-reserved characters
let invalid = EscapedString::try_new("hello world?foo=bar");
assert!(invalid.is_err());

Built-in valid types include numeric types (u32, u64, etc.), Uuid (with the uuid feature), IP addresses, and validated EscapedString instances.

Telemetry Labels

For complex templates, use the label attribute to provide a concise identifier for telemetry. When present, the label takes precedence over the template string.

use templated_uri::{EscapedString, templated};

#[templated(
    template = "/{org}/users/{user_id}/reports/{report_type}",
    label = "user_report",
    unredacted
)]
struct ReportPath {
    org: EscapedString,
    user_id: EscapedString,
    report_type: EscapedString,
}

Data Classification

The crate integrates with data_privacy to track data sensitivity levels in URIs. This is particularly important for compliance and data security:

use data_privacy::Sensitive;
use templated_uri::{EscapedString, templated};

#[templated(template = "/{org_id}/user/{user_id}/")]
#[derive(Clone)]
struct UserPath {
    #[unredacted]
    org_id: EscapedString,
    user_id: Sensitive<EscapedString>,
}

RFC 6570 Template Compliance

The templating system implements RFC 6570 Level 3 URI Template specification. Supported expansions include:

Simple string expansion: {var}
Reserved string expansion: {+var}
Path segments: {/var}
Query parameters: {?var}
Query continuation: {&var}

Note: Fragment expansion ({#var}) from RFC 6570 is not supported because URI fragments are stripped by the http crate and ignored by HTTP clients.

Template variables must implement Escape (except for reserved expansions, which use Raw) to ensure the resulting URI is valid.

Undefined Values (`Option<T>`)

Per RFC 6570 section 2.3, template variables may be undefined. Use Option<T> to model this: a None value is treated as undefined and the variable (along with its prefix or separator) is omitted from the rendered URI.

use templated_uri::{EscapedString, PathAndQueryTemplate, templated};

#[templated(template = "/items{?query,limit}", unredacted)]
struct ItemSearch {
    query: EscapedString,
    limit: Option<u32>,
}

// With limit defined:
let path = ItemSearch {
    query: EscapedString::from_static("rust"),
    limit: Some(10),
};
assert_eq!(path.render(), "/items?query=rust&limit=10");

// With limit undefined:
let path = ItemSearch {
    query: EscapedString::from_static("rust"),
    limit: None,
};
assert_eq!(path.render(), "/items?query=rust");

Integration with HTTP Ecosystem

This crate seamlessly integrates with the broader Rust HTTP ecosystem by re-exporting and building upon the standard http crate types. The resulting Uri can be converted to an http::Uri for use with HTTP clients and servers based on hyper like reqwest.

templated_uri 0.2.1