feat: Introduce the templated_uri crate family

[kate-shine]

No description provided.

[github-actions]

⚠️ Breaking Changes Detected

error: failed to retrieve local crate data from git revision

Caused by:
    0: failed to retrieve manifest file from git revision source
    1: possibly due to errors: [
         failed when reading /home/runner/work/oxidizer/oxidizer/target/semver-checks/git-origin_main/cfdd6907fa17efa8e70de9bf37a1298d6b445f32/scripts/crate-template/Cargo.toml: TOML parse error at line 9, column 26
         |
       9 | keywords = ["oxidizer", {{CRATE_KEYWORDS}}]
         |                          ^
       missing key for inline table element, expected key
       : TOML parse error at line 9, column 26
         |
       9 | keywords = ["oxidizer", {{CRATE_KEYWORDS}}]
         |                          ^
       missing key for inline table element, expected key
       ,
         failed to parse /home/runner/work/oxidizer/oxidizer/target/semver-checks/git-origin_main/cfdd6907fa17efa8e70de9bf37a1298d6b445f32/Cargo.toml: no `package` table,
       ]
    2: package `templated_uri` not found in /home/runner/work/oxidizer/oxidizer/target/semver-checks/git-origin_main/cfdd6907fa17efa8e70de9bf37a1298d6b445f32

Stack backtrace:
   0: anyhow::error::<impl anyhow::Error>::msg
   1: cargo_semver_checks::rustdoc_gen::RustdocFromProjectRoot::get_crate_source
   2: cargo_semver_checks::rustdoc_gen::StatefulRustdocGenerator<cargo_semver_checks::rustdoc_gen::CoupledState>::prepare_generator
   3: cargo_semver_checks::Check::check_release::{{closure}}
   4: cargo_semver_checks::Check::check_release
   5: cargo_semver_checks::exit_on_error
   6: cargo_semver_checks::main
   7: std::sys::backtrace::__rust_begin_short_backtrace
   8: main
   9: <unknown>
  10: __libc_start_main
  11: _start

If the breaking changes are intentional then everything is fine - this message is merely informative.

Remember to apply a version number bump with the correct severity when publishing a version with breaking changes (1.x.x -> 2.x.x or 0.1.x -> 0.2.x).

[codecov]

Codecov Report

❌ Patch coverage is 99.45155% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.8%. Comparing base (bc20e71) to head (0375f38).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/templated_uri/src/uri_safe.rs	90.1%	12 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #265     +/-   ##
========================================
- Coverage   100.0%   99.8%   -0.2%     
========================================
  Files         141     156     +15     
  Lines        8640   10828   +2188     
========================================
+ Hits         8640   10816   +2176     
- Misses          0      12     +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[geeknoid]

Note that the logo I designed for when the crate was named "obscuri". The new name warrants a new logo.

Also, you should update the PR title.

[geeknoid]

Here are a bunch of things the AI recommends fixing:

Analysis of templated_uri Crate Family

Review of all source files across the three crates (templated_uri, templated_uri_macros, templated_uri_macros_impl).

🐛 Correctness Issues

1. UriSafeString::new() rejects percent-encoded values (RFC 6570 compliance gap)

File: crates/templated_uri/src/uri_safe.rs:120

The reserved-character check rejects characters like : and /, but per RFC 6570 §1.5, the output of Simple String Expansion should be percent-encoded. Currently, UriSafeString values are interpolated verbatim via format!() with no percent-encoding step. If a UriSafeString contains a space or other unreserved-but-special character (e.g. ~, which is allowed through validation), it will be placed into the URI without encoding, potentially producing an invalid URI. The crate's blocklist also omits % itself — a string like "foo%ZZbar" (invalid percent-encoding) would pass validation and produce a malformed URI.

2. TryFrom<String> for UriSafeString always copies the string

File: crates/templated_uri/src/uri_safe.rs:213-214

Self::new(&s) calls s.to_string() again inside new(), double-allocating. The owned String is discarded and a fresh clone is created via ToString. The Cow::Owned should reuse the already-owned String.

3. RedactedDisplay for struct templates misses prefix separators in param groups

File: crates/templated_uri_macros_impl/src/struct_template.rs:224-259

The construct_redacted_display function emits Content parts (static template segments) correctly, but for ParamGroup it emits each parameter inline without the group's prefix/separator. For example, a {?q1,q2} group would emit q1={value}&q2={value} in to_uri_string (via format_template), but in RedactedDisplay, each param is emitted without the ?, &, or key= parts. This means the redacted output for query parameters and semicolon-KV parameters will have structurally different output than the non-redacted version — missing ?, &, ; prefixes and key= labels.

4. Typo in Cargo.toml keywords

File: crates/templated_uri/Cargo.toml:9

"psrsing" should be "parsing".

5. Origin::with_port has a typo in expect message

File: crates/templated_uri/src/base_uri/origin.rs:112

"Scheme ahd host are already valid" — "ahd" should be "and".

6. Unclosed doc-comment block on with_origin

File: crates/templated_uri/src/base_uri.rs:420

The #[must_use] attribute follows directly after the example code block without a closing /// doc-comment line, which means the attribute is technically outside the doc block.

⚡ Performance Issues

7. UriSafeString::new() takes &impl ToString instead of accepting owned strings

File: crates/templated_uri/src/uri_safe.rs:112

The signature pub fn new(s: &impl ToString) always calls .to_string(), which allocates even when the caller already has a String. A more efficient API would accept impl Into<String> or have separate new/from_str paths. The TryFrom<String> impl at line 213 passes &s to new(), which calls s.to_string() again — a needless copy.

8. Uri::to_string() allocates without capacity hint

File: crates/templated_uri/src/uri.rs:119-130

to_string() builds a String by first calling ToString::to_string() on BaseUri (which goes through Display::fmt), then appending the path. For frequently called code paths, pre-allocating with String::with_capacity would reduce reallocations.

9. TargetPathAndQuery::template() clones then converts PathAndQuery

File: crates/templated_uri/src/uri.rs:297

Cow::Owned(classified_pq.clone().declassify_ref().to_string()) clones the entire Sensitive<PathAndQuery> just to produce a string. It could use classified_pq.declassify_ref().to_string() directly without cloning.

10. UriSafeString validation uses str::contains per character

File: crates/templated_uri/src/uri_safe.rs:120

For each character in the input, "{}/:?#[]@!$&'()*+,;=".contains(c) does a linear scan through 20 characters. A lookup table or matches!() on byte values (like from_static already uses) would be faster for long strings.

🧩 Usability Issues

11. Uri::to_string() shadows std::fmt::Display

File: crates/templated_uri/src/uri.rs:119

Uri has an inherent to_string() method returning Sensitive<String>, which shadows the usual Display::to_string(). This is intentional for data privacy, but Uri doesn't implement Display at all, which can be surprising. The method name could cause confusion — consider to_sensitive_string() or similar.

12. UriSafe is a sealed trait with no prominent documentation of that fact

File: crates/templated_uri/src/uri_safe.rs:41-58

Users can't implement UriSafe for their own types (sealed trait). For custom newtypes that wrap safe types, users must use UriFragment/UriUnsafeFragment derive macros. The sealed nature is intentional but the docs could mention this more prominently.

13. Missing Eq/PartialEq on Uri

File: crates/templated_uri/src/uri.rs:50-56

Uri doesn't implement PartialEq or Eq. Tests at lines 479-481 compare via .to_string() instead. Since both BaseUri and TargetPathAndQuery (via string comparison) can be compared, adding at least string-based equality would be convenient.

[Copilot]

Pull request overview

This PR introduces a new crate family for standards-compliant URI handling with templating, safety validation, and data classification support. However, there is a significant naming discrepancy: the PR title and description reference "obscuri" while the actual crate names are "templated_uri", "templated_uri_macros", and "templated_uri_macros_impl". The implementation provides RFC 6570 Level 3 compliant URI templating with compile-time safety guarantees and integration with the data_privacy crate for redaction support.

Changes:

• Adds three new crates: templated_uri, templated_uri_macros, and templated_uri_macros_impl
• Implements RFC 6570 URI templates with derive macros for type-safe URI construction
• Provides UriSafe trait and validation to prevent URI injection vulnerabilities

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
crates/templated_uri/src/lib.rs	Main library module with core types and re-exports
crates/templated_uri/src/uri.rs	Uri type implementation with templating support
crates/templated_uri/src/uri_safe.rs	UriSafe trait and validation logic
crates/templated_uri/src/uri_fragment.rs	Fragment traits for URI template parameters
crates/templated_uri/src/base_uri.rs	BaseUri type for scheme and authority handling
crates/templated_uri_macros/src/lib.rs	Procedural macro entry points
crates/templated_uri_macros_impl/src/lib.rs	Core macro implementation logic
crates/templated_uri_macros_impl/src/template_parser.rs	RFC 6570 template parser using chumsky
crates/templated_uri_macros_impl/src/struct_template.rs	Struct template macro implementation
crates/templated_uri_macros_impl/src/enum_template.rs	Enum template macro implementation
crates/templated_uri_macros_impl/src/uri_fragment.rs	Derive macro for UriFragment traits
Cargo.toml	Workspace dependency additions
README.md	Updated with new crate reference (naming issue)
CHANGELOG.md	Updated with new crate references (naming issues)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[geeknoid]

I worry that we're having to expose all of these external types here. Are we OK coupling this crate to the http crate?

[kate-shine]

I have the same worry, but http crate is an industry standard and we need to consider it everywhere anyway. I don't think we can avoid interfacing with it.

[geeknoid]

I'd rather we introduce our own types that mirror these, and include crate features to make it easier to interop with the http crate's URI type and the stand-alone url crate. So we still play nice, but it's a separate feature.

[kate-shine]

I'd certainly like that, although the amount of work behind that to make it work well is quite non-trivial. It would be possible to start by newtype wrapping http and forwarding API to it, but I'd prefer to not do that and switch to our own types as a future breaking change that fully replaces it instead.

The reason is that there is some weirdness in http behavior which they can't get rid of anymore for backwards compatibility reasons. We will be able to drop that compatibility when we switch types, but if we wrap those types now, I'm afraid that we will conserve the behavior.

Would it be ok to introduce this as a breaking change in future major version instead of now as a part of open sourcing?

[geeknoid]

When should someone use this instead of new above? Should this an unsafe function? Maybe new_unchecked would be more idiomatic?

[kate-shine]

I can imagine using this the moment you already have an urlencoded string, which can happen. New new() would reencode % symbols and mess up the url.

I don't like unchecked explicitly checks though, the old new is now infallible due to inclusion of url encoding.

Maybe

new -> new_encode or just encode
new_raw -> new

?

Although the reason I went for new is that I'd like it to be a prioritized way to construct this.

Honestly, urlencoding is a mess. I hate that you can't safely do a second encoding pass on an already encoded string.