From a9695dffd5924cc0975589c7eb941e97084511e4 Mon Sep 17 00:00:00 2001 From: Asher Date: Wed, 3 Jul 2024 12:22:42 -0800 Subject: [PATCH] Update contributing documentation --- CONTRIBUTING.md | 81 ++++++++++++++++++++++++++++++++++++++++--------- README.md | 8 ----- 2 files changed, 66 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a3d1734..5bbd7f73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,34 +2,69 @@ ## Architecture -Workspaces opened with Coder Remote have the following URI structure: +When the Coder Remote plugin handles a request to open a workspace, it invokes +Microsoft's [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) +extension using the following URI structure: ```text -vscode://ssh-remote+coder-vscode----/ +vscode://ssh-remote+ ``` -The `ssh-remote` scheme is used by the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension from Microsoft that connects to remote machines. +The `ssh-remote` scheme is registered by Microsoft's Remote - SSH extension and +indicates that it should connect to the provided host name using SSH. -Coder uses the `onResolveRemoteAuthority:ssh-remote` [extension activation event](https://code.visualstudio.com/api/references/activation-events) to activate the workspace when this scheme is used. On activation, we check if `vscode.workspace.workspaceFolders` contains the `coder-vscode--` prefix, and if so we delay activation to: +The host name takes the format +`coder-vscode.----`. This is parsed by the CLI +(which is invoked via SSH's `ProxyCommand`) to route SSH to the right workspace. -1. Match the workspace owner and name from the URI scheme and validate it's accessible. -2. Download the matching server binary to the client. -3. Add an entry to the users SSH config for VS Code Remote to resolve `coder-vscode--*`. +The Coder Remote extension also registers for the +`onResolveRemoteAuthority:ssh-remote` [extension activation +event](https://code.visualstudio.com/api/references/activation-events) to hook +into this process, running before the Remote - SSH extension actually connects. + +On activation of this event, we check if `vscode.workspace.workspaceFolders` +contains the `coder-vscode` prefix, and if so we delay activation to: + +1. Parse the host name to get the domain, username, and workspace. +2. Ensure the workspace is running. +3. Download the matching server binary to the client. +4. Configure the binary with the URL and token, asking the user for them if they + are missing. Each domain gets its own config directory. +5. Add an entry to the user's SSH config for `coder-vscode.--*`. ```text -Host coder-vscode--* - ProxyCommand "/tmp/coder" vscodessh --network-info-dir "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/net" --session-token-file "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/session_token" --url-file "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/url" %h +Host coder-vscode.dev.coder.com--* + ProxyCommand "/tmp/coder" vscodessh --network-info-dir "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/net" --session-token-file "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/dev.coder.com/session_token" --url-file "/home/kyle/.config/Code/User/globalStorage/coder.coder-remote/dev.coder.com/url" %h ConnectTimeout 0 StrictHostKeyChecking no UserKnownHostsFile /dev/null LogLevel ERROR ``` -VS Code SSH uses the `ssh -D ` flag to start a SOCKS server on the specified port. This port is printed to the `Remote - SSH` log file in the VS Code Output panel in the format `-> socksPort ->`. We use this port to find the SSH process ID that is being used by the remote session. +If any step fails, we show an error message. Once the error message is closed +we close the remote so the Remote - SSH connection does not continue to +connection. Otherwise, we yield, which lets the Remote - SSH continue. + +VS Code SSH uses the `ssh -D ` flag to start a SOCKS server on the +specified port. This port is printed to the `Remote - SSH` log file in the VS +Code Output panel in the format `-> socksPort ->`. We use this port to +find the SSH process ID that is being used by the remote session. + +The `vscodessh` subcommand on the `coder` binary periodically flushes its +network information to `network-info-dir + "/" + process.ppid`. SSH executes +`ProxyCommand`, which means the `process.ppid` will always be the matching SSH +command. -The `vscodessh` subcommand on the `coder` binary periodically flushes it's network information to `network-info-dir + "/" + process.ppid`. SSH executes `ProxyCommand`, which means the `process.ppid` will always be the matching SSH command. +Coder Remote periodically reads the `network-info-dir + "/" + matchingSSHPID` +file to display network information. -Coder Remote periodically reads the `network-info-dir + "/" + matchingSSHPID` file to display network information. +## Other features + +There is a sidebar that shows all the user's workspaces, and all users' +workspaces if the user has the required permissions. + +There are also notifications for an outdated workspace and for workspaces that +are close to shutting down. ## Testing @@ -51,12 +86,18 @@ There are some unit tests as well: yarn test ``` -However, fully testing the plugin is blocked on switching back to the standard VS Code extension testing framework. +Note that we have an unusual testing setup with `vitest`; this needs to be +changed back to how using the standard testing framework for VS Code extensions +was but for now it means some things are difficult to test as you cannot import +`vscode` in tests or write any UI tests. ## Development 1. Run `yarn watch` in the background. -2. Compile the `coder` binary and place it in the equivalent of `os.tmpdir() + "/coder"`. +2. OPTIONAL: Compile the `coder` binary and place it in the equivalent of + `os.tmpdir() + "/coder"`. If this is missing, it will download the binary + from the Coder deployment, as it normally would. Reading from `/tmp/coder` is + only done in development mode. On Linux or Mac: @@ -65,7 +106,8 @@ However, fully testing the plugin is blocked on switching back to the standard V $ go build -o /tmp/coder ./cmd/coder ``` -3. Press `F5` or navigate to the "Run and Debug" tab of VS Code and click "Run Extension". +3. Press `F5` or navigate to the "Run and Debug" tab of VS Code and click "Run + Extension". ## Dependencies @@ -75,3 +117,12 @@ Some dependencies are not directly used in the source but are required anyway. - `ua-parser-js` and `dayjs` are used by the Coder API client. - `glob`, `nyc`, `vscode-test`, and `@vscode/test-electron` are currently unused but we need to switch back to them from `vitest`. + +## Releasing + +1. Update the changelog. +2. Update the package.json version. +3. Push a tag matching the new package.json version. +4. Update the resulting draft release with the changelog contents. +5. Publish the draft release. +6. Download the `.vsix` file from the release and upload to the marketplace. diff --git a/README.md b/README.md index 6a3bfe37..5f3394d7 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,3 @@ ext install coder.coder-remote Alternatively, manually install the VSIX from the [latest release](https://github.com/coder/vscode-coder/releases/latest). - -## Publishing - -1. Update the changelog. -2. Update the package.json version. -3. Push a tag matching the new package.json version. -4. Update the release with the changelog contents. -5. Download the .vsix from the release and upload to the marketplace.