Provide an API for extensions to know when they're running "remotely"

[DanTup]

There are some things that don't make sense when an extension is running on a remote machine/container/etc. For example in Flutter when a user tries to run an application, if there is no connected device we will show them a list of local emulators that they can start (or given them an option to create a new one):

It doesn't make sense for us to do this for a remote session because if we created/launched an emulator, the user wouldn't be able to see it.

Similarly, it doesn't make sense for us to offer to launch other interactive tools like this:

As far as I can tell, there's no current API to tell if your extension is running on the "local machine" where it's safe to spawn processes for the user to interactive with, but I think there's a good need for one.

[jrieken]

This actually already exists as proposed API: https://github.com/Microsoft/vscode/blob/b74c61286820d43e4540341d3d0700bc5e37d8b1/src/vs/vscode.proposed.d.ts#L19-L34

[DanTup]

Oh sweet, I should've checked in there 🙈

Thanks! 👍

[jrieken]

We aren't sold on the current proposal anymore and we have pushed/proposed a simple vscode.env.remoteAuthority-api:

		/**
		 * The [authority](#Uri.authority)-component. When `undefined`, extensions are
		 * executed in the same context (e.g. operating system or machine) in which the UI
		 * of the editor is executed. If defined, extensions are running on a different
		 * context, for instance a remote machine.
		 *
		 * *Note* that no assumptions about the actual value should be made as it is defined
		 * by extensions and not by the editor.
		 */
		export const remoteAuthority: string | undefined;

https://github.com/Microsoft/vscode/blob/6a1574e21ed6b449aea8f09f83d29c62a231c548/src/vs/vscode.d.ts#L6044-L6053

[DanTup]

That still works for my needs, though out of curiosity, why the change? If an extension can't make any assumption about the string, doesn't it amount to just being a boolean (since all we can really do is remoteAuthority === undefined)?

[jrieken]

If an extension can't make any assumption about the string

It's likely to have a meaning once the resolver API is out ;-)

[DanTup]

Got it :) Btw, the change above was in the main vscode definition, not proposed - is it likely that'll ship in the upcoming release? Thanks!

[jrieken]

@aeschli discussed this in the API sync and the idea is to bring more structure into this. Often URIs are like this: vscode-remote://foo+barcafebarblablub/some/path and to extensions only the part before the + is meaningful or stable. So instead of having the plain string we could have an object that exposes the prefix (foo) to begin with.

 // vscode-remote://ssh+jssjsjsj+sjsj/
		 
export const remoteAuthority: { prefix: string } | undefined;

cc @roblourens

[jrieken]

latest and greatest:

vscode/src/vs/vscode.d.ts

Lines 6044 to 6057 in a429fd1

	/**
	* Information about running remotely. When `undefined`, extensions are executed in the same
	* context (e.g. operating system or machine) in which the UI of the editor is executed.
	* If defined, extensions are running in a different context, for instance a remote machine.
	*
	* A remote [uri](#Uri) adheres to this format: `remote_scheme://auth_prefix+auth_rest/path` where
	* the `remote_scheme` is defined by the editor, `auth_prefix` and `auth_rest` are defined by extensions,
	* and `path` is defined by the user.
	*
	* Extensions contributing a remote are encouraged to use a stable `auth_prefix`-value,
	* e.g `remote_scheme://ssh+23/` and `remote_scheme://ssh+42`. Such prefix is exposed
	* in the `prefix`-property of the returned object.
	*/
	export const remoteAuthority: { prefix: string } | undefined;

Someone please review/fix the doc comment for clarity and correctness

[jrieken]

We are unsure about this, we will not finalise this for May. The current evolution of ideas/proposals:

// just a string, e.g. ssh+machineId. concern: only ssh makes sense
export const remoteAuthority: string | undefined;

// more structure, e.g prefix is ssh, the rest is left out
export const remoteAuthority: { prefix: string } | undefined;

// don't mention authority as it doesn't explain itself, use 'ssh', et al as type
export const remoteContext: { type: string } | undefined;

// don't mention remote at all, mix this with other potential contexts
export const executionContext: { kind: string | undefined };

[DanTup]

@jrieken if just knowing "if we're remote" is likely a common use case (it's what I need - I need to make sure I don't show options that will spawn local interactive processes/tools like emulators), why not also expose a simple boolean. You could ship that easily, and make it back onto this once it's finalised (keeping the API simple for those with simple requirements).

[jrieken]

The problem isn't about exposing this information but how to call it... Internally we use remoteAuthority because remote-uris look like this vscode-remote://ssh+b3fce7b3-533b/some/path. The authority portion of that uri (ssh+b3fce7b3-533b) is handed over to an extension to "resolve" that into a host, port pair.

However, that uri is completely opaque, never surfaced, and the fact that this is the authority component isn't important. That's how we got away from the "authority" name towards something more generic like "remote".

Then, this API should answer two questions: (1) is this extension host "remote" and (2) what kind of remote is this, e.g. wsl vs ssh. The latter isn't a finite list and depends on resolver extensions. Still, we can document some well known values, like wsl, ssh, or container (that's similar to language ids or certain uri schemes). There is value in knowing those values, e.g. running in wsl allows you to launch an android emulator installed on the windows side...

Last, the question came up if this is remote specific or not. Does this compare to nodejs's process.platform property? That leads towards vscode.env.executionContent.kind but raises the question what the default is? Also, should this be designed to accommodate future JavaScript contexts, e.g. expressing that an extension host runs inside a web worker or a nodejs worker?

So, more questions than answers. We are in endgame this week so little flex for API experiments... I keep this issue updated

[DanTup]

There is value in knowing those values, e.g. running in wsl allows you to launch an android emulator installed on the windows side

Oh, I hadn't considered that. This makes more sense now, it seems like it doesn't squash to a simple boolean even for my needs after all :-)

(whether or not I could get WSL to "see" the emulator I launched in Windows, I'm not sure, but I guess that's for another day :-))

[aeschli]

Ideally you could query your environment to find out whether it makes sense to launch a certain tool.
E.g. check whether the DISPLAY variable is set. Or whether you can find a certain executable.

[DanTup]

Checking for executables isn't good enough (for ex. you might connect to a container that has the Android SDK installed, so we can list and launch emulators, but you won't see them), though I hadn't considered DISPLAY, that might work for some; I'll do some testing. Thanks! :-)

[jrieken]

So following @chrmarti's and @dbaeumer's idea of making this totally independent of remote, I think the logical consequence is to not have this inside a wrapper object but straight on the env object (which already represents the environment in which vs code and/or the extension host runs). That would result in something like vscode.env.kind: string | undefined, alternative to kind could be name or others

[jrieken]

Tho, on a second thought maybe vscode.env isn't the right place at all. Currently all its values refer to the environment in which the editor runs, e.g. vscode.env.clipboard is the clipboard to which the UI has access, not the clipboard of the remote side. Same for openExternal, machineId etc.

That means we might wanna go back to having something on ExtensionContext, similar to what we initially proposed:

vscode/src/vs/vscode.proposed.d.ts

Lines 19 to 34 in 4c5705f

	//#region Joh - ExecutionContext
	export enum ExtensionExecutionContext {
	Local = 1,
	Remote = 2
	}
	export interface ExtensionContext {
	/**
	* Describes the context in which this extension is executed, e.g.
	* a Node.js-context on the same machine or on a remote machine
	*/
	executionContext: ExtensionExecutionContext;
	}
	//#endregion

[DanTup]

@jrieken is the current proposed API (d5534b8#diff-4878e8b25d41f2ab7c2715852b1b97aa) a reasonable bet now, or is this all still up in the air? Thanks!

[jrieken]

Latest and greatest proposal

	/**
	 * In a remote window the extension kind describes if an extension
	 * runs where the UI (window) runs or if an extension runs remotely.
	 */
	export enum ExtensionKind {

		/**
		 * Extension runs where the UI runs.
		 */
		UI = 1,

		/**
		 * Extension runs where the remote extension host runs.
		 */
		Workspace = 2
	}

	export interface Extension<T> {

		/**
		 * The extension kind describes if an extension runs where the UI runs
		 * or if an extension runs where the remote extension host runs. The extension kind
		 * if defined in the `package.json` file of extensions but can also be refined
		 * via the the `remote.extensionKind`-setting. When no remote extension host exists,
		 * the value is [`ExtensionKind.UI`](#ExtensionKind.UI).
		 */
		extensionKind: ExtensionKind;
	}

	export namespace env {
		/**
		 * The name of a remote. Defined by extensions, popular samples are `wsl` for the Windows
		 * Subsystem for Linux or `ssh` for remotes using a secure shell.
		 *
		 * *Note* that the value is `undefined` when there is no remote extension host but that the
		 * value is defined in all extension hosts (local and remote) in case a remote extension host
		 * exists. Use [`ExtensionContext#extensionKind`](#ExtensionContext.extensionKind) to know if
		 * a specific extension runs remote or not.
		 */
		export const remoteName: string | undefined;
	}

[DanTup]

@jrieken great, thanks! And is there a reasonable chance this work will ship in the next release?

[jrieken]

Yes - the plan is to ship this in June as stable API

[roblourens]

Where does remoteName come from, the authority?

[roblourens]

I see the code, the example should be ssh-remote for ssh. What will it be for web?

[jrieken]

What will it be for web?

IDK, whatever we define it to be. Debugging shows 127.0.0.1:9888 but I don't know if that the final design or some pragmatic solution. The point is that you shouldn't care too much unless you know for sure what environment a remote describes, e.g wsl

[jrieken]

small update: the extensionKind is now a property of Extension<T> and not of the ExtensionContext anymore