Add support for config flags to settings UI (+ technical explanation flag system)

[SchoofsKelvin]

If you're here just to see how to enable flags, check the How to add flags as a user section in the explanation below

Feature request

Add two new sections to the webview:

• A button on the startpage leading to a page where global flags (sshfs.flags) can be viewed/added/changed/removed.
  We might also want to give the user the choice whether to edit the "global" flags in User Settings, Workspace settings, ...
• A similar section (in a collapsible div?) to the ConfigEditor, allowing the user to do the same for config-specific flags

Some notes regarding this:

• The actual FlagEditor component that'll probably be created can be used in both sections
• We need to (manually) add a list of flags that exist along with their descriptions
• For boolean flags, allow the user to set the flag to true/false or just remove it (thus using the default)
• For string flags, it can just be a simple text input field
• While the extension/webview supports editing configs from the settings UI, it doesn't allow changing global User Settings
• It might be good to allow the user to add any flag (with any value), although currently flags are hardcoded.
  Only allowing the user to pick existing flags (and limit what type of value they can enter) is more than fine though.

Technical explanation about the flag system

The flag system got added in 83d6cd0 and expanded upon in 218188a and 9de1d03. It allows the user to quickly toggle certain features/fixes in the extension, both globally or per-config. We can also make the extension automatically enable/disable flags (yet allow it to be overridden by the user), as shown here for DF-GE that fixes #239:

Extension auto-enabling DF-GE

vscode-sshfs/src/config.ts

Lines 389 to 405 in 87d2cf8

	function calculateFlags(): Record<string, FlagCombo> {
	const flags: Record<string, FlagCombo> = {};
	const config = vscode.workspace.getConfiguration('sshfs').inspect<string[]>('flags');
	if (!config) throw new Error(`Could not inspect "sshfs.flags" config field`);
	const applyList = (list: string[] | undefined, origin: string) => Object.assign(flags, parseFlagList(list, origin));
	applyList(DEFAULT_FLAGS, 'Built-in Default');
	applyList(config.defaultValue, 'Default Settings');
	// Electron v11 crashes for DiffieHellman GroupExchange, although it's fixed in 11.3.0
	if ((process.versions as { electron?: string }).electron?.match(/^11\.(0|1|2)\./)) {
	applyList(['+DF-GE'], 'Fix for issue #239')
	}
	applyList(config.globalValue, 'Global Settings');
	applyList(config.workspaceValue, 'Workspace Settings');
	applyList(config.workspaceFolderValue, 'WorkspaceFolder Settings');
	Logging.info(`Calculated config flags: ${JSON.stringify(flags)}`);
	return cachedFlags = flags;
	}

And a simple example of the extension checking a boolean flag:

Extension checking DF-GE

vscode-sshfs/src/connect.ts

Lines 266 to 273 in 87d2cf8

	const [flagV, flagR] = getFlagBoolean('DF-GE', false, config.flags);
	if (flagV) {
	logging.info(`Flag "DF-GE" enabled due to '${flagR}', disabling DiffieHellman kex groupex algorithms`);
	let kex: string[] = require('ssh2-streams/lib/constants').ALGORITHMS.KEX;
	kex = kex.filter(algo => !algo.includes('diffie-hellman-group-exchange'));
	logging.debug(`\tResulting algorithms.kex: ${kex}`);
	finalConfig.algorithms = { ...finalConfig.algorithms, kex };
	}

Here's more information regarding flags:

How to add flags as a user

For managing flags globally, the user can edit the sshfs.flags setting in VS Code's User Settings. For example:

"sshfs.flags": [
    "DEBUG_SSH2"
],

For a per-config basis, the user requires to edit the JSON-representation of the config. This is usually under sshfs.configs in the User Settings, but could be in other places if you configured it that way, e.g. the workspace settings:

"sshfs.configs": [
    {
        "name": "config-name",
        "host": "localhost",
        "flags": ["DEBUG_SSH2"]
    }
],

Parsing of flags

Flags are case-insensitive, and are basically represented as strings, where the resulting flag value depends on the format:

"+KEY" => true
"-KEY" => false
"KEY" => null
"KEY=something" => "something"

Boolean flags (e.g. DEBUG_SSH2 in 06bce85) will on top of that convert non-boolean values (e.g. null and "something") to booleans on very simple rules:

• If the value is null, we return true (thus the presence of a (non-false) flag counts as true)
• If it's a string that lowercase equals true, t, yes or y, we return true
• If it's a string that lowercase equals false, f, no or n, we return false
• In other cases, we assume the user did something wrong, so we throw an error

This allows the user to simply add e.g. DEBUG_SSH2 (or +DEBUG_SSH2 or DEBUG_SSH=true etc) to enable debugging of the ssh2 library, while also supporting -CHECK_HOME (or CHECK_HOME=no etc) to disable that enabled-by-default flag.

List of currently available flags

vscode-sshfs/src/config.ts

Lines 370 to 384 in 87d2cf8

	/* List of flags
	DF-GE (boolean) (default=false)
	- Disables the 'diffie-hellman-group-exchange' kex algorithm as a default option
	- Originally for issue #239
	- Automatically enabled for Electron v11.0, v11.1 and v11.2
	DEBUG_SSH2 (boolean) (default=false)
	- Enables debug logging in the ssh2 library (set at the start of each connection)
	WINDOWS_COMMAND_SEPARATOR (boolean) (default=false)
	- Makes it that commands are joined together using ` && ` instead of `; `
	CHECK_HOME (boolean) (default=true)
	- Determines whether we check if the home directory exists during `createFileSystem` in the Manager
	REMOTE_COMMANDS (boolean) (default=false)
	- Enables automatically launching a background command terminal during connection setup
	- Enables attempting to inject a file to be sourced by the remote shells (which adds the `code` alias)
	*/

check up-to-date list at https://github.com/SchoofsKelvin/vscode-sshfs/blob/master/src/config.ts