[ST4] Opening URIs

[rwols]

Problem description

Development is moving more and more towards web-based tooling. Sublime is lacking in this area.

• Views only have the notion of a file name, but should have the notion of an URI: Implement view.uri() #3742
• Opening and loading a resource is an asynchronous operation, but the API only provides blocking functions. We have to write a manual state machine to handle views that are still loading: Make Window.open_file asynchronous #3172 (depends on asyncio: Provide a global event loop for python 3.8 plugins #3129)

Preferred solution

A new async method for the sublime.Window class:

async def open_uri(
    uri: str,
    flags: int = 0,
    group: int = -1
) -> Optional[View]
    ...

It should have the following behavior:

• If the URI scheme is file or res, delegates to Make Window.open_file asynchronous #3172.
• If the URI scheme is http or https, downloads the file asynchronously, puts the content into a scratch buffer. The view.uri() should return the uri passed in open_uri.
• If The URI scheme is buffer, find an existing view with that buffer ID.
• Otherwise, look for a provider (see below)
• If no provider is found, raise an exception.

The return type should be an Optional[View] if the URI can be represented as a single file. It may be None because it might have been closed/cancelled by the user while opening it.

Alternatives

N/A

Additional Information (optional)

sublimelsp/LSP#1605

The Deno language server has the "goto definition" capability. When the user wants to jump to the definition of a module that is not in the workspace, it will report back a resource on the web. The editor is expected to open that web resource.

EDIT: Contrary to what you might expect, Deno doesn't use http:// schemes but rather deno:// schemes (see below).

[rwols]

Preferred solution continued

If the scheme of the URI is not file, res, http, https or buffer, then ST should look for a "view provider", much like how it searches for a "key binding handler" with on_query_context. There should be a new async callback that can signal to ST that it can "handle" a certain scheme. So maybe a new callback for sublime_plugin.EventListener:

async def on_query_uri(
    self,
    window: sublime.Window,
    uri: str
) -> Optional[Tuple[str, str, Optional[str]]]:
    ...

If you define this method in a plugin, then you must return a tuple of three elements:

1. The first element is the content of the new view
2. The second element is the syntax to apply to the new view
3. The third optional element is a file-system backed file, in case the user wants to save it, and for interoperability with view.file_name(), although I guess this should be None.

If you don't know how to handle the provided URI then you must return None.

This would allow plugins to extend the behavior of opening URIs for custom schemes.

For instance, the Deno language server uses a deno scheme. This scheme requires custom handling to fetch the remote content (and again, it must all be asynchronous).

[rwols]

Of course I didn't think of this myself. VSCode already has this mechanism.

[rwols]

I'm learning this idea has consequences for various other features:

• The immediate previews of "goto definition" would be more complex, as you can't rely on views being files anymore.
• The "goto symbol in project" cannot work with such "virtual views".

Nevertheless I still think this would be a nice feature to have as a basis for, for instance, remote SSH file viewing, or translating paths for inspecting files in a docker container.

[rwols]

Another use case is resolving URIs with a jdt scheme for Debugger + Eclipse language server integration: daveleroy/SublimeDebugger#106 (comment)