Let extensions hook into url opening

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.

[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

[mjbvz]

Thanks @JacksonKearl! I’ve adopted the same logic for our url patterns. Now you can use globs for the setting:

"workbench.externalUriOpeners": [
	{
		"uri": "localhost:*",
		"id": "simpleBrowser.open"
	}
]

or

"workbench.externalUriOpeners": [
	{
		"uri": "http://*",
		"id": "simpleBrowser.open"
	}
]

Other changes to the API:

• Added the concept of a ‘priority’ for openers

  After talking with Kai, it sounds like we do want the simple browser to be used by default in codespaces. To support this, I added ability to say that an opener is preferred and should be used by default.