Universal Links are routable but untested, and one URLPathRouter serves only one scheme

[nashysolutions-bot]

Surfaced while gating async-digital-site#546, which proposes a public repo description naming Universal Links as a supported input. The capability is real but thinner than that claim implies, and nothing here is tested.

Measured on main @ depth-1 clone, 2026-08-30

• URLPathRouter carries exactly one scheme: public let scheme: String, set once in init(scheme:routes:) (Sources/Iris/URLRoute.swift:142-148).
• parse(_:) hard-rejects anything else: guard url.scheme == scheme else { return nil } (URLRoute.swift:153).
• URLPattern takes its host from the first path segment of the pattern string: self.host = segments.first ?? "" (URLRoute.swift:73).
• grep -rn https Sources/ returns zero hits.
• The only router test constructs scheme: "demo" (Tests/IrisTests/URLPathRouterTests.swift:18).

What that means in practice

Universal Links are routable — URLPathRouter(scheme: "https", routes: [URLPattern("myapp.com/profile/:id")]) works. Three consequences follow that a reader of a one-line description would not expect:

1. One router serves one scheme. An app accepting both myapp://profile/1 and https://myapp.com/profile/1 needs two URLPathRouter instances and its own dispatch between them. Nothing in the package composes them.
2. Every Universal Link pattern must repeat the domain as its first segment, because pattern host is segment zero. A custom-scheme pattern reads profile/:id; the Universal Link equivalent reads myapp.com/profile/:id, and the two cannot share a route table.
3. It is untested and undocumented for https. AGENTS.md names .onOpenURL as "the standard SwiftUI universal-link / custom-scheme entry point", which is true of the modifier but says nothing about the router behind it.

What breaks if this is never fixed

An adopter who picks the package up because its description promises Universal Links writes one router, gets nil from every https URL, and has to read the source to find the scheme guard. That is the friction the case-study series exists to argue we design out.

Options, not a prescription

• Document the two-router pattern in AGENTS.md and add an https test. Cheapest, makes the existing behaviour honest.
• Let URLPathRouter hold a set of accepted schemes, keeping host matching as-is.
• Separate scheme from host in URLPattern so one table serves both.

Pick before the public description claims Universal Links as a headline capability.

[nashysolutions-bot]

Correcting my own framing on this ticket, filed an hour ago.

I wrote it after measuring URLPathRouter and treating that as evidence that the package's parsing seam is scheme-limited. It is not, and I was measuring the wrong type.

URLParsing is func parse(_ url: URL) -> Intent (Sources/Iris/URLParsing.swift:10-15). It takes a URL and returns an Intent, with no scheme involved anywhere in the contract. A conforming codec is free to accept https and a custom scheme in the same implementation. URLPathRouter does not conform to it, and returns Intent? rather than Intent, so it is a provided helper beside the protocol rather than the seam itself.

So the public case-study claim on /case-studies/deep-linking/internals/url-codec/ ("the protocol does not care whether the link arrived as a custom-scheme deep link or as a Universal Link over https") is accurate, and I was wrong to treat it as overreach. No change is needed there.

What survives, and it is still worth fixing:

URLPathRouter is the batteries-included, table-driven router, and it is the thing an adopter reaches for before writing a codec by hand. That type is single-scheme by construction: public let scheme: String set once in init, and guard url.scheme == scheme else { return nil } in parse (URLRoute.swift:142-153). grep -rn https Sources/ returns zero hits and the only router test uses scheme: "demo", so the https path through that helper is untested.

The corrected finding is therefore narrower than the title suggests: not that Iris cannot route Universal Links, but that its convenience router handles one scheme per instance and has no https coverage, while the protocol it sits beside has no such limit. The three options in the body still apply, and the documentation option is now the strongest of them, since the gap is a reader mistaking the helper's limit for the protocol's.

Retitling would be reasonable. Leaving that to whoever picks this up rather than editing the title under a comment thread.