Modifying URIs/IRIs

[silverpill]

It would be great to have the ability to modify URIs. Owned string types, like RiString already provide some in-place modification methods, such as set_fragment and replace_host, but I didn't find methods for changing scheme, path, or query.

[lo48576]

Hmm... I've once thought about it, but set_fragment and replace_host-family are special case, and for other components I'll recommend using Builder or converting into String.

Why special case?

• set_fragment always receives already-validated fragment string, and modifying the suffix of String is lightweight, so no reason not to provide this.
• replace_host- (especially {,try_}replace_host_reg_name) is primarily for IDNA (punycode) support.
  • IDNA conversion will change the host part only when the host is reg-name and non-ASCII. It is very likely that the host (thus the entire URI) doesn't change, so it would be very beneficial to provide inline conversions.
    • See

      iri-string/src/types/generic.rs

      Lines 104 to 144 in 291f00b

      	//! ## Allocated IRI types
      	//!
      	//! For allocated types such as `IriString`, you can use
      	//! `{,try_}replace_host{,_reg_name}` methods.
      	//!
      	//! 1. Get host by `authority_components()?.host()`.
      	//! 2. Process the name.
      	//! 3. Replace the host by the new result.
      	//!
      	//! ```
      	//! # #[cfg(feature = "alloc")] {
      	//! # extern crate alloc;
      	//! # use alloc::string::String;
      	//! use iri_string::types::IriString;
      	//!
      	//! fn apply_idna(s: &str) -> String {
      	//! /* ... */
      	//! # match s {
      	//! # "alpha.\u{03B1}.example.com" => "alpha.xn--mxa.example.com".to_owned(),
      	//! # _ => unimplemented!(),
      	//! # }
      	//! }
      	//!
      	//! let mut iri =
      	//! IriString::try_from("https://alpha.\u{03B1}.example.com")
      	//! .unwrap();
      	//!
      	//! // 1. Get the host.
      	//! let orig_host = iri.authority_components()
      	//! .expect("orig_iri has a host")
      	//! .host();
      	//! debug_assert_eq!(orig_host, "alpha.\u{03B1}.example.com");
      	//!
      	//! // 2. Process the name.
      	//! let new_domain = apply_idna(orig_host);
      	//!
      	//! // 3. Replace the host.
      	//! iri.replace_host(&new_domain);
      	//! debug_assert_eq!(iri, "https://alpha.xn--mxa.example.com");
      	//! # }
      	//! ```

      . (until now I hadn't noticed this doc is in the private module... 😭 )
• encode_to_uri_inline is also very likely to do nothing because so many IRIs (and literally all URIs) are ASCII-only, so this would be beneficial for omitting unnecessary syntax checking.
• remove_password_inline and remove_nonempty_password_inline will be important for secure logging, and it always strips the whole component (or does nothing at all), so the syntax checking after modification can be omitted safely.

Handling invalid parameter?

Honestly I'm not a fan of replace_host-like APIs, because it doesn't handle syntax errors well.
For example, replace_host will return None if self has no authority component OR the parameter is invalid.
Ideally such invalid parameters should be rejected before calling the function, by restricting input by types.
(See set_fragment: you cannot pass an invalid fragment!)

So, I would implement types for each components (such as RiSchemeStr, RiAuthorityStr, RiHostStr, RiPathStr, etc.) before implementing in-place modification APIs, but... to me it seems like overkill.

(It is simply my laziness that RiQueryStr is already there but RiString has no replace_query().)

Workaround

use iri_string::types::IriString;
use iri_string::build::Builder;

#[test]
fn replace_scheme_by_builder() {
    let orig = IriString::try_from("http://example.com/").unwrap();
    let expected = IriString::try_from("https://example.com/").unwrap();

    let mut builder = Builder::from(orig.as_slice());
    builder.scheme("https");
    let new: IriString = builder.build().unwrap().into();

    assert_eq!(new, expected);
}

#[test]
fn replace_scheme_raw_inline() {
    let orig = IriString::try_from("http://example.com/").unwrap();

    let mut buf: String = orig.into();
    buf.insert("http".len(), 's');
    assert!(buf.starts_with("https://"));

    // No internal `clone`!
    let new = IriString::try_from(buf).unwrap();

    assert_eq!(new, "https://example.com/");
}

[lo48576]

So, I would implement types for each components (such as RiSchemeStr, RiAuthorityStr, RiHostStr, RiPathStr, etc.) before implementing in-place modification APIs, but... to me it seems like overkill.

That said, I still have conflicting feelings that I should provide syntactically-checked types for every component, especially when I see methods of components::AuthorityComponents returning &str and build::Builder always accepts potentially invalid inputs...

Feel free to comment if you have strong needs or preference on this.
I'll revisit this in future anyway and/or slowly add such types, but I would change the priority if this looks super efficient and super useful in some situation.

[silverpill]

Thank you for the detailed response!

There is no urgency, but I can think of several situations where infallible setters could be useful. In particular, set_path and set_query. If syntactically-checked types make these infallible setters possible, they would be a valuable addition to the library.

The Builder workaround is a good alternative to set_<component> methods but it's fallible.