Skip to content

fix: keep IPv6 zone identifiers stable across parse/normalize/serialize/equal - #218

Merged
mcollina merged 5 commits into
mainfrom
fix/ipv6-zone-roundtrip
Sep 17, 2026
Merged

mcollina merged 5 commits into
mainfrom
fix/ipv6-zone-roundtrip

Conversation

@mcollina

@mcollina mcollina commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

fast-uri could disagree with itself about a zoned IPv6 host identity. When a zone identifier begins with "25", recomposition would misread the leading "25" as a %25 separator, so the same input produced different host identities from parse, normalize, serialize and equal, and equal returned a false positive for two distinct zones (e.g. "25eth0" vs "eth0").

The single-"%" component form of a zoned IPv6 host is inherently ambiguous: from host: fe80::1%25eth0 alone it is impossible to tell whether the zone is 25eth0 or eth0. parse now records the zone identifier as a plain public ipv6Zone field on the parsed component for zoned literals, and recomposeAuthority rebuilds the authority from it (always %25-separated) without re-deriving the zone. The zone is validated on use, so a host reassigned after parse or a mismatched caller-supplied zone falls back to the normal recompute path. All four entry points agree for every well-formed zone value, including zones whose leading characters are 25.

…ze/equal

A zone identifier that begins with "25" was ambiguous in the single-"%" host
form produced at parse time. During recomposition the leading "25" was
misread as a %25 separator, silently rewriting the zone ("25eth0" -> "eth0")
or, for a zone of just "25", destroying the bracketed literal entirely. As a
result parse, normalize, serialize and equal could disagree about the host
identity of the same input, and equal conflated two distinct zones.

Persist the round-trippable escapedHost computed by normalizeIPv6 on the parsed
component (non-enumerable, so it does not leak into parse output) and prefer it
when recomposing the authority. This keeps parse, normalize, serialize and
equal in agreement for every well-formed zone value, including zones whose
leading characters are 25.

@Tony133 Tony133 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two questions inline. Both cases work on main. Can we add tests for them?

Comment thread lib/utils.js Resolved
Comment thread index.js Resolved
Address review feedback on #218:
- Store the round-trippable zoned IPv6 host under a private Symbol so only
  parse can set it; a caller-supplied escapedHost string is never trusted.
- Only prefer the parse-derived escaped form while the host is unchanged, so
  reassigning host after parse (e.g. turning [::1] into example.com) takes
  effect again.
- Add regression tests for both cases.

@Tony133 Tony133 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Replace the private Symbol/defineProperty caching with a plain public
escapedHost field on parse output, validated on use by recomposeAuthority.

- Only zoned IPv6 literals carry escapedHost (plain IPv6 needs no
  disambiguation), so parse output for non-zoned IPv6 is unchanged.
- recomposeAuthority trusts escapedHost only when it normalizes back to
  the current host, so both a host reassigned after parse and a
  caller-supplied mismatched value fall back to the normal path.
- Document escapedHost on the URIComponent type, and update the uri-js
  compatibility fixture for the single zoned literal.
Comment thread lib/utils.js Resolved
Replace escapedHost with the more semantic ipv6Zone identifier, exposed as
a plain documented public field on parse output for zoned IPv6 literals.

- parse sets ipv6Zone for bracketed IPv6 literals with a zone; plain IPv6
  parse output is unchanged.
- recomposeAuthority rebuilds [address%25zone] only when ipv6Zone matches
  the current host and normalizes back to it, so a host reassigned after
  parse or a mismatched/caller-supplied zone falls back to the normal path.
- Add explicit-disambiguation coverage and update the uri-js compatibility
  fixture.
@mcollina

Copy link
Copy Markdown
Member Author

@Tony133 sorry for the massive back-and-forth, your questions have lead to a significantly better design

…back

Clarify on the public type that a hand-built single-% host whose zone
begins with 25 is ambiguous: pass ipv6Zone to disambiguate, otherwise
serialize falls back to the best-effort heuristic. Mirror the note in the
recomposer and pin the behavior with a regression test.
@Tony133

Tony133 commented Sep 17, 2026

Copy link
Copy Markdown
Member

@Tony133 sorry for the massive back-and-forth, your questions have lead to a significantly better design

No worries, happy it helped πŸ˜‰πŸ‘πŸ»

@Tony133 Tony133 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mcollina
mcollina merged commit 4fef6ce into main Sep 17, 2026
44 checks passed
@mcollina
mcollina deleted the fix/ipv6-zone-roundtrip branch September 17, 2026 21:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants