README.md

Templated Uri

Standards-compliant URI handling with templating, safety 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 safety guarantees, templating capabilities, and data classification features.

Core Types

The crate centers around several key abstractions:

• Uri - Flexible URI type with endpoint and path/query components
• BaseUri - Lightweight type representing scheme, authority, and optional base path (BasePath)
• TemplatedPathAndQuery - RFC 6570 Level 3 compliant URI templating
• UriSafe and UriSafeString - Generic newtype wrapper proving a value is safe for URI components by not containing any reserved characters

Basic Usage

Simple URI Construction

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

// Create an endpoint (scheme + authority only)
let base_uri = BaseUri::from_uri_static("https://api.example.com");

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

// Combine into complete URI
let uri = Uri::default().base_uri(base_uri).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, TemplatedPathAndQuery, Uri, UriSafeString, templated};

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

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

let uri = Uri::default()
    .base_uri(BaseUri::from_uri_static("https://api.example.com"))
    .path_and_query(path);

URI Safety Guarantees

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

use templated_uri::UriSafeString;

// This will succeed - encodes unsafe characters into a URI-safe format
let unsafe_string = UriSafeString::encode("hello world?foo=bar");
assert_eq!(unsafe_string.as_str(), "hello%20world%3Ffoo%3Dbar");

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

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

Built-in safe types include numeric types (u32, u64, etc.), Uuid (with the uuid feature), IP addresses, and validated UriSafeString 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::{UriSafeString, templated};

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

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::{UriSafeString, templated};

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

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 UriParam (except for reserved expansions) to ensure the resulting URI is valid.

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.

---

_{This crate was developed as part of The Oxidizer Project. Browse this crate's source code.}