RFC 3986 compliance

[glyn]

I came to fluent-uri-rs looking for a way to validate a RFC 3986 URI, but soon found that "" and "alice@example.com" both parse successfully in spite of the fact that neither of these has a scheme name, which is mandatory according to Section 3.1 of RFC 3986.

I wonder if something needs to be added to the README to explain what is meant by the statement there:

A full-featured URI handling library compliant with RFC 3986.

[yescallop]

It seems that the struct name Uri has been somewhat misleading. In fact, a Uri currently represents a URI reference defined in Section 4.1 of RFC 3986. You'll need to check whether a scheme is present (by calling has_scheme or is_relative_reference) to determine if a Uri is a URI defined in Section 3 of RFC 3986 (sounds weird indeed).

The choice of the name Uri was due to java.net.URI and android.net.Uri which both represent a URI reference. This practice may have resulted from the use of the term "relative URI" in Section 5 of RFC 2396, which was obsoleted by RFC 3986. There is also a note in Section 1.2.3 of RFC 3986 saying:

NOTE: Previous specifications used the terms "partial URI" and "relative URI" to denote a relative reference to a URI. As some readers misunderstood those terms to mean that relative URIs are a subset of URIs rather than a method of referencing URIs, this specification simply refers to them as relative references.

I think we can maybe change the name Uri to UriRef to prevent users from mistaking a Uri for a URI defined in RFC 3986 (as the most downloaded dependent of fluent-uri, lsp-types, seems to have already done). I'm open to making this change, but I still have some doubts on its drawbacks. Any ideas on this topic would be very welcome.

[glyn]

I submitted #20 for the doc change.

[yescallop]

Thank you for making the doc change!

I also think it's better for the type to be self-documenting. The first step towards this goal should be renaming the type to UriRef, which I've already done on branch rename. After renaming it, I would like to reintroduce a Uri struct, so that users can parse or deserialize a URI string directly into a Uri as well. Here are some considerations before doing that:

1. This should not be a slient change in behavior, as users would assume Uri::parse and <Uri as Deserialize>::deserialize behave the same before and after an update. It is possible that this change will be caught by users' testing infrastructure, but is it otherwise worth the breakage?
2. The has_scheme method should not be available on Uri. The scheme method should return &Scheme instead of Option for Uri. These differences can reduce the chance of silent changes described in (1).
3. The resolve_against method can be changed to take Uri instead of UriRef as argument. It probably should not be available on Uri.
4. It should be decided whether the Builder struct may also be used to build a Uri.
5. There should be conversion methods between Uri and UriRef.

As there is so much to consider, I guess it would also be fine to ship a 0.2 release with only the type renaming change, while postponing the reintroduction of Uri struct until a 0.3 release. This can also reduce the chance of silent changes described in (1).

[glyn]

Thanks for merging the doc change.

That plan sounds good to me. I don't think there's much you can do to completely avoid the risk of a silent change in behaviour. Moving the Uri type to another module could help, but it would be a shame to distort the module structure to solve this "point in time" issue.

What else is needed before you can ship v0.2? I'm going to develop against a tag of the current HEAD for now and will switch up to the v0.3 line as soon as it's available on main. Please advise.

In case anyone's interested, my code that uses fluent-uri is here https://github.com/glyn/webfinger-rs. After migrating to HEAD, I found that several of my tests that were policing restrictions in http::Uri could be changed to demonstrate correct behaviour with fluent-uri (and renamed - whoops!). Kudos to @yescallop.

[yescallop]

I think the current functionality is already sufficient for a 0.2 release. What is blocking the release is that I tend to go to great lengths to check the code/doc/API design to make sure that things are right. I find problems every now and then and haven't settled when to publish the release yet. You can alternatively depend on the latest pre-release version by using:

fluent-uri = "=0.2.0-alpha.8"

[glyn]

Thanks, but I'm based on a tag on my own fork. I'll subscribe to your repo to keep track.

[glyn]

@yescallop Thanks very much for the recent changes, especially the introduction of a Uri type. I upgraded my project's dependency on fluent-uri-rs to b550a1e in a development branch and it worked perfectly. I will merge my changes and release my project when your changes are tagged (so I know you have reached a point you are happy with).

[yescallop]

Thanks very much for your valueable input. I published a new release v0.3.0 with the recent changes. I'm glad to hear that the library works well and I will continue to improve it.