iri_string

Module resolve

source
Expand description

URI and IRI resolvers.

§IRI resolution can fail without WHATWG URL Standard serialization

§Pure RFC 3986 algorithm

Though this is not explicitly stated in RFC 3986, IRI resolution can fail. Below are examples:

  • base=scheme:, ref=.///bar.
    • Resulting IRI should have scheme scheme and path //bar, but does not have authority.
  • base=scheme:foo, ref=.///bar.
    • Resulting IRI should have scheme scheme and path //bar, but does not have authority.
  • base=scheme:, ref=/..//baz.
    • Resulting IRI should have scheme scheme and path //bar, but does not have authority.
  • base=scheme:foo/bar, ref=..//baz.
    • Resulting IRI should have scheme scheme and path //bar, but does not have authority.

IRI without authority (note that this is different from “with empty authority”) cannot have a path starting with //, since it is ambiguous and can be interpreted as an IRI with authority. For the above examples, scheme://bar is not valid output, as bar in scheme://bar will be interpreted as an authority, not a path.

Thus, IRI resolution by pure RFC 3986 algorithm can fail for some abnormal cases.

Note that this kind of failure can happen only when the base IRI has no authority and empty path. This would be rare in the wild, since many people would use an IRI with authority part, such as http://.

If you are handling scheme://-style URIs and IRIs, don’t worry about the failure. Currently no cases are known to fail when at least one of the base IRI or the relative IRI contains authorities.

If you want this kind of abnormal IRI resolution to succeed and to be idempotent, check the resolution result using Normalized::ensure_rfc3986_normalizable (see the section below).

§WHATWG serialization

To handle IRI resolution failure, WHATWG URL Standard defines serialization algorithm for this kind of result, and it makes IRI resolution (and even normalization) infallible and idempotent.

IRI resolution and normalization provided by this crate automatically applies this special rule if necessary, so they are infallible. If you want to detect resolution/normalization failure, use Normalized::ensure_rfc3986_normalizable method.

§Examples

use iri_string::format::ToDedicatedString;
use iri_string::types::{IriAbsoluteStr, IriReferenceStr};

let base = IriAbsoluteStr::new("scheme:")?;
{
    let reference = IriReferenceStr::new(".///not-a-host")?;
    let result = reference.resolve_against(base);
    assert!(result.ensure_rfc3986_normalizable().is_err());
    assert_eq!(result.to_dedicated_string(), "scheme:/.//not-a-host");
}

{
    let reference2 = IriReferenceStr::new("/..//not-a-host")?;
    // Resulting string will be `scheme://not-a-host`, but `not-a-host`
    // should be a path segment, not a host. So, the semantically correct
    // target IRI cannot be represented by RFC 3986 IRI resolution.
    let result2 = reference2.resolve_against(base);
    assert!(result2.ensure_rfc3986_normalizable().is_err());

    // Algorithm defined in WHATWG URL Standard addresses this case.
    assert_eq!(result2.to_dedicated_string(), "scheme:/.//not-a-host");
}

Structs§