Implement symmetric RFC 6570 expansion and pattern matching

[dahlia]

Implement our own RFC 6570 URI Template expansion and pattern matching to ensure symmetric behavior and eliminate dependency on third-party libraries with asymmetric implementations.

Background

Currently, Fedify relies on:

• url-template: For URI Template expansion (RFC 6570 compliant)
• uri-template-router: For pattern matching/parsing (non-standard, causes asymmetric behavior)

This leads to issues like #416 where expansion and parsing don't round-trip correctly, causing:

• Inconsistent encoding/decoding behavior
• Double-encoding problems in collections
• Unpredictable results for users

The asymmetric behavior is documented in uri-template-router issue #11.

Problem with current approach

The fundamental issue is that RFC 6570 only defines expansion behavior, not pattern matching. uri-template-router implements pattern matching as an extension, but this creates asymmetry:

Value → url-template (expand) → URL → uri-template-router (parse) → Different value

Proposed solution

Implement a custom RFC 6570 library that provides:

Core features

• Expansion: Full RFC 6570 compliance for all expression types
• Symmetric pattern matching: Custom implementation that guarantees round-trip consistency
• Type safety: Better TypeScript integration than current libraries

Expression types to support

• {var}: Simple string expansion
• {+var}: Reserved string expansion
• {/var}: Path segment expansion
• {?var}: Query parameter expansion
• {&var}: Query continuation expansion
• {#var}: Fragment expansion

Benefits

• Guaranteed symmetry: expand(parse(url)) === url and parse(expand(value)) === value
• Predictable behavior: Eliminates current inconsistencies
• Reduced dependencies: Remove url-template and uri-template-router
• Fedify-optimized: Can add ActivityPub-specific optimizations if needed

Implementation plan

Phase 1: RFC 6570 expansion

• Implement core expansion logic
• Support all expression types
• Comprehensive test suite against RFC 6570 examples
• Performance benchmarking vs url-template

Phase 2: Symmetric pattern matching

• Design pattern matching algorithm that mirrors expansion
• Implement parsing for all expression types
• Ensure round-trip consistency tests pass
• Handle edge cases and malformed inputs

Phase 3: Integration

• Replace url-template usage in Fedify
• Replace uri-template-router usage in Fedify
• Update tests and ensure no regressions
• Performance validation

Phase 4: Documentation

• Update RFC 6570 guide (Add URI Template syntax guide to documentation #417) to reference new implementation
• Document any Fedify-specific extensions or behaviors

Considerations

• Scope: This is a significant undertaking that essentially creates a new library
• Timeline: Should be treated as a long-term goal, not urgent
• Compatibility: Must maintain backward compatibility with existing Fedify APIs
• Testing: Requires extensive testing against RFC 6570 spec and real-world usage

Alternative approaches

• Contribute fixes to uri-template-router (but maintainer may not accept due to breaking changes)
• Find alternative libraries with symmetric behavior (research needed)
• Live with current limitations and document workarounds

[notJoon]

I've implemented RFC 6570 partially before. Would it be okay if I take this?

[dahlia]

@notJoon Cool! Go for it!

[notJoon]

@dahlia Thanks! If we implement this package, would it be better to manage it as a monorepo in fedify, or would it be better to create a separate repository?

The package size itself wouldn't be large, so it seems like it would be fine to manage it internally, but I'm also concerned that the codebase might become too complex.

[dahlia]

It would be better to have it in the Fedify monorepo IMHO.

[mrkvon]

FYI uri-template-router published a fix which should address #416. This could be closed then.