proposal: net/url: add FromFilePath and ToFilePath

[bcmills]

In the course of investigating #27698, I learned that the conversion between URLs and file paths on Windows is rather non-trivial. (See also #6027.)

According to https://blogs.msdn.microsoft.com/ie/2006/12/06/file-uris-in-windows/, a file path beginning with a UNC prefix should use the UNC hostname as the “host” part of the URL, with only two leading slashes, whereas a file path beginning with a drive letter should omit the “host” part and prepend a slash to the remainder of the path.

Once you know those rules, the implementation in each direction is only about ten lines of code, but it's easy to get wrong (for example, by neglecting the possibility of a UNC prefix) if you haven't thought about it in depth.

I propose that we add two functions to the net/url package to make these cases more discoverable, with the following signatures:

// ToFilePath converts a URL with scheme "file" to an absolute file path.
// It returns a non-nil error if the URL does not have the scheme "file" or
// the resulting path is not well-formed.
func ToFilePath(u *URL) (string, error) {
	[…]
}

// FromFilePath converts an absolute file path to a URL.
func FromFilePath(path string) (*URL, error) {
	[…]
}

CC @alexbrainman

[bcmills]

There is at least one place where we have already gotten this wrong in the standard library:

go/src/cmd/cover/html.go

Line 85 in ac8dbe7

if !browser.Open("file://" + out.Name()) {

[mvdan]

I assume most uses will be string-based - is there a reason why you've designed the API around url.URL? It's easy to use url.Parse and url.URL.String to use the proposed API with strings, but the same could be said about using a string-based API with URLs.

[bcmills]

@mvdan, two reasons:

1. Using url adds type-safety at the call site. (It's much less likely that someone will accidentally confuse a URL for a file-path — or vice-versa — if they have different types.)
2. The subtle parts of converting Windows paths to file:// URLs involve the Host field of the URL. It's much easier to express those subtle parts in terms of the Host and Path fields, and seems easier for users to diagnose unexpected results when they can clearly see how the path was split into a Host and Path (rather than counting slashes).

[rsc]

I think there's enough subtlety in the implementation here - even though the docs sound simple - that this is worth a design doc laying out the issues that an implementation will have to address. There's no rush on this, @bcmills, but I think that's the next step.

Will mark it on-hold for design doc.

[cuishuang]

Is there any progress on adding this method? ^_^

[gopherbot]

Change https://go.dev/cl/438175 mentions this issue: client: handle file URI scheme on windows