Better guide WSL users opening UNC \\wsl$\ paths

[radeksimko]

Current Version

0.22.0

Use-cases

Currently the language server doesn't support UNC paths as per #74

However even when it does, users will continue to be unable to use WSL paths.

Generally speaking WSL users can (and should) use the Linux path (such as /mnt/c/...) directly, and most do.

However, the following attempt

code "\\wsl$\Ubuntu-20.04\home\example"

(assuming the Linux instance for WSL is still running somewhere on the background)

leads to an error message such as

URI "file://wsl%24/Ubuntu-20.04/home/example" is not valid

Proposal

The hostname in a WSL URI uses the dollar sign ($), which is passed escaped as %24 by the language client. This trips up the Go URL parser, which is otherwise capable of unescaping the path, but clearly not the hostname.

See https://play.golang.org/p/ROjLYnDbDjR

We can attempt to unescape the whole URL somehow and just make WSL UNC paths work and/or return a more helpful error message to nudge users to use the native Linux path. Additionally on VS Code we could recommend installation of the WSL extension https://code.visualstudio.com/docs/remote/wsl

[radeksimko]

The Go parser actually behaves correctly, as documented here:

https://cs.opensource.google/go/go/+/refs/tags/go1.17.7:src/net/url/url.go;l=214-222;drc=refs%2Ftags%2Fgo1.17.7;bpv=0;bpt=1

// Per https://tools.ietf.org/html/rfc3986#page-21
// in the host component %-encoding can only be used
// for non-ASCII bytes.

https://tools.ietf.org/html/rfc3986#page-21

In other words \\wsl$\Ubuntu-20.04\home\example is a valid file path in Windows, but the corresponding URI is supposed to be file://wsl$/Ubuntu-20.04/home/example, i.e. with $ not escaped.

It is likely just the vscode-uri over-escaping the URI, so we may just need to account for that edge case, assuming vscode won't fix this.

[jpogran]

So, I didn't 'get' this until today when I looked at this from the perspective of running code "\\wsl$\Ubuntu-20.04\home\example" from a Windows shell. This is telling the VSCode Windows install to open a Windows file path inside the Windows VS Code install, which does not load any WSL distro or VSCode WSL features.

The correct way is to open the shell of the WSL distro you're using then run code /home/example. This starts the VSCode editor in Windows as a 'client' with the WSL VSCode Server 'inside' the WSL distro. As explained in the WSL tutorial:

VS Code is installing a small server on the Linux side that the desktop VS Code will then talk to. That server will then install and host extensions in WSL, so that they run in the context of the tools and frameworks installed in WSL. In other words, your language extensions will run against the tools and frameworks installed in WSL, not against what is installed on the Windows side, as it should for the proper development experience.

Another article describing how to open WSL projects: https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode#open-a-wsl-project-in-visual-studio-code

Overview of Remote Development: https://code.visualstudio.com/docs/remote/remote-overview

In summary, the action item here is to add links to the above to our readme explaining how to open a folder in WSL. There is no code work here to perform.

[radeksimko]

@jpogran I don't disagree about how WSL is supposed to be used or that we should document it but I worry that "docs" may be not be good enough - people do make mistakes and many just do not read docs.

Currently the error they get in such a scenario does not make it clear what kind of mistake they made and how to "fix it".

I'm not saying we necessarily need to support \\wsl$\ paths but I do think we should be able to detect this and warn the user somehow - through a human-readable error message somewhere.

[jpogran]

Human readable is a plus. Was trying to underline the root 'problem' isn't fixable.

As a comparison for messaging, the Go extension really doesn't like it:

[radeksimko]

Yeah - I think gopls further masks the problem by adding the third / into the URI for some reason, which IMO must also be affecting UNC paths.

https://github.com/golang/tools/blob/32c652e336b3839959abdd99f32809f8f4ad4889/internal/span/uri.go#L61-L64

golang/tools@88f3c62

I don't know Windows well enough to confirm but I believe that file://something are valid UNC paths and that AFAIK has nothing to do with VSCode's escaping.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.