url_key_policy: Comparison-key policy

Description

Builds the immutable, versioned policy object that governs URL identity for get_url_key() and the url_join family. One policy is applied symmetrically to both sides of every comparison, because equality has to stay symmetric and transitive.

Usage

url_key_policy(
  standard = c("whatwg", "rfc3986"),
  scheme_equality = c("exact", "http_https", "http_https_missing")
)

Value

An object of class rurl_url_key_policy.

Arguments

standard: The standard whose identity semantics apply: "whatwg" (default) or "rfc3986". Unlike the parse surface, NULL is not accepted -- an unnamed standard cannot freeze key bytes.
scheme_equality: How strictly schemes compare. "exact" (default) compares the normalized scheme identity. "http_https" additionally collapses http and https into one class, so http://h/ and https://h/ compare equal; every other scheme stays exact, including the ws/wss pair. "http_https_missing" is accepted by the vocabulary but not implemented, and errors -- see Details.

Identity is not presentation

A comparison key is derived from the URL's canonical identity state -- after the selected standard has interpreted it, and before any cleaning or display transform. No cleaning option can reach it. www_handling, case_handling, trailing_slash_handling, index_page_handling, path_encoding, host_encoding, port_handling, query cleaning and every url_profile() bundle are structurally incapable of changing a key byte. That is the point: two URLs that a cleaning profile happens to render alike are not thereby the same resource.

What the key does and does not distinguish

Framed as identity: the scheme (and, separately, whether one was written at all), the authority delimiter, the host and its kind, the port, the path and its kind, and the query -- order and duplicates significant.

Excluded by contract: the fragment and any userinfo. Neither identifies a web resource, so http://u:pw@h/p#frag and http://h/p mint the same key. Their structural state is still available from safe_parse_url() and the diagnostics helpers.

Ports normalize only where the standard makes them redundant: an explicit :80 under http and :443 under https compare equal to no port at all. Every other default stays literal, so ftp://h:21/ and ftp://h/ are distinct, and an inferred scheme normalizes nothing (h.com:80/ is not http://h.com/).

Versioning

The policy carries a key version and a schema version, and both travel inside the framed key bytes. A key minted under different semantics can therefore never compare equal to one minted here, so no release can silently reinterpret a persisted key.

Details

scheme_equality = "http_https_missing" would additionally collapse "no scheme written" into the http/https class. It errors rather than guessing, because the pair it would have to equate also differs on whether an authority delimiter (//) was present, which rurl frames as independent identity. Collapsing that too is a contract change, not an implementation detail, so the mode refuses instead of silently picking a side.

Examples

Run this code

url_key_policy()

# Identity under one policy ...
get_url_key(c("http://example.com/", "https://example.com/"))

# ... and under a relaxed scheme mode.
p <- url_key_policy(scheme_equality = "http_https")
k <- get_url_key(c("http://example.com/", "https://example.com/"), p)
k[1] == k[2]

Run the code above in your browser using DataLab