Let extensions hook into url opening

[mjbvz]

Overview

Let extensions hook into url opening. Motivating use case: I click on a link in the integrated terminal and it opens in my browser preview extension

Potential places to handle links:

• Links in the terminal
• Links in documents
• Links from the remote port forwarding views
• Debugger launch?
• Open external?

Additional requirements

• A url opener should be able to decline opening a link

  Some openers may only support specific types of links, such as localhost

• Clicking a link should activate relevant extensions

  We'd need a new activation event so that extensions can make sure they handle link opening

• Let users fallback to VS Code's default behavior

  This typically is to open using the default browser

• Handle multiple url openers being registered at the same time

  Users should be able to select which opener to use in this case. They should potentially be able to specify a default opener.

[connor4312]

I talked with Kai about the "debugger launch" scenario in my 1:1 last week. In my specific scenario, I think the requirements you have are sufficient. Most of the potential fancy stuff I do would be driven OOB, e.g. by the mirroring http server providing the debugging and communication pipe.

[mjbvz]

@jrieken @alexdima Here's the current version of the API based on our discussion earlier:

/**
	 * Handles opening external uris.
	 *
	 * An extension can use this to open a `http` link to a webserver inside of VS Code instead of
	 * having the link be opened by the webbrowser.
	 *
	 * Currently openers may only be registered for `http` and `https` uris.
	 */
	export interface ExternalUriOpener {

		/**
		 * Try to open a given uri.
		 *
		 * @param uri The uri being opened.
		 * @param ctx Additional metadata about how the open was triggered.
		 * @param token Cancellation token.
		 *
		 * @return Optional command that opens the uri. If no command is returned, VS Code will
		 * continue checking to see if any other openers are available.
		 *
		 * If multiple openers are available for a given uri, then the `Command.title` is shown in the UI.
		 */
		openExternalUri(uri: Uri, ctx: {}, token: CancellationToken): ProviderResult<Command>;
	}

	namespace window {
		/**
		 * Register a new `ExternalUriOpener`.
		 *
		 * When a uri is about to be opened, an `onUriOpen:SCHEME` activation event is fired.
		 *
		 * @param schemes List of uri schemes the opener is triggered for. Currently only `http`
		 * and `https` are supported.
		 * @param opener Opener to register.
		 *
		* @returns Disposable that unregisters the opener.
		 */
		export function registerExternalUriOpener(schemes: readonly string[], opener: ExternalUriOpener,): Disposable;
	}

Main changes:

• Renamed to ExternalUriOpener to make it clear the opener only applies to uris that VS Code itself does not handle

• The provider now registers for a specific set of schemes

• The openExternalUri method now returns a command. If there are multiple openers, we show the command title in a quick pick so that the user can select which opener to use

[alexr00]

This is something I'd like to take advantage of for the port auto forwarding notification. The idea would be that instead of clicking on the button in the notification to open in the browser, we could instead use that button to open a "browser preview".

Taking this even further, once we add a way to specify additional properties for ports in settings, we can make one of the additional properties an "on forward" action. This action could be one of several options: open in browser, open in "browser preview", do nothing, etc..

[mjbvz]

A few complications that I've run into while working on this API:

Trusted domains

If a user opens a url inside of VS Code itself, I believe that this uri should not go through the trusted domains flow. Right now, the trusted domains are checked before any openers (internal or external) are ever invoked, so there is no way to skip the trusted domains check for a specific opener.

Port forwarding

In port forwarding cases, an extension needs to know both the original uri that triggered the open (localhost:8000) as well as the uri that has been resolved (long-codespaces-url-pointing-to-localhost-8000).

Our simple browser extension for example only wants to open urls for specific hosts (such as only opening localhost urls). To implement this, it needs to validate against the original uri but ultimately open the resolved uri if the validation passes

---

To solve these two issues, I believe we should refactor IOpenerService.open. Here's what IOpenerService.open does today:

1. For a given uri, such as localhost:8000
2. Validate that uri (i.e. do trusted domains)
3. The find an opener for it
4. If we find an opener for an external uri, then resolve the uri (i.e. do the port forwarding)
5. Pass the external opener the resolved uri to open

Instead, I think the flow should look more like:

1. For a given uri, such as localhost:8000
2. Find the first valid opener for that uri.
3. In that opener, run a pre-open check against localhost:8000 (this is where trusted domains would be handled)
4. If that check was ok, then resolve the uri (i.e. do the port forwarding)
5. Then using both the original uri and the resolved uri, do the actual opening

/cc @JacksonKearl Since I know you've been doing some trusted domains stuff recently