2026-09-05 · 6 min read · Rahul Chitturi
- url
- ipv6
- networking
An IPv6 address contains colons, so a URL must wrap an IPv6 host literal in square brackets to separate the host from an optional port. A raw address may work in a socket API but become ambiguous when placed after a URL scheme.
Failures often appear only behind proxies, in allowlists, or in signature verification because each component parses or serializes the authority differently.
Keep URL syntax and host data separate
Use a standards-aware URL parser and inspect scheme, hostname, port, path, and serialized authority as separate fields. Brackets belong to URL serialization around a literal host; they are not generally part of the hostname value returned by an API.
- Use forms such as https://[2001:db8::1]:8443/path
- Do not split an authority on the last colon by hand
- Handle default ports according to the protocol contract
- Reject userinfo where the application does not require it
Normalize only for a defined purpose
IPv6 text can have multiple equivalent spellings. DNS names also have case and internationalization rules that do not apply to IP literals. Preserve the original request where signatures require exact bytes, while comparing hosts through a documented canonical representation.
Zone identifiers for link-local addresses need special handling and are usually inappropriate in public application URLs. Validate allowlists against parsed host data and guard against loopback, private, and link-local destinations for server-side fetches.
A Flashman workflow
Use the URL tool with documentation-range addresses, diff to compare serialized forms, JSON formatter for sanitized proxy events, and regex only for bounded log extraction rather than authoritative URL parsing.
Test compressed and expanded literals, explicit and default ports, query strings, fragments, redirects, Host or Forwarded headers, allowlists, signed requests, DNS hosts, malformed brackets, and mixed IPv4 forms.