feat: support configurable web terminal rendering

- Added a deployment option for configuring web terminal rendering. Valid values are 'webgl', 'canvas', and 'dom'.
coder · sreya · Oct 10, 2023 · Oct 6, 2023 · Oct 6, 2023 · Oct 6, 2023
commit efabdec427ac3efb9849c70b13ae02b28c3129f0
diff --git a/cli/testdata/coder_server_--help.golden b/cli/testdata/coder_server_--help.golden
@@ -66,6 +66,10 @@ Clients include the coder cli, vs code extension, and the web UI.
       --ssh-hostname-prefix string, $CODER_SSH_HOSTNAME_PREFIX (default: coder.)
           The SSH deployment prefix is used in the Host of the ssh config.
 
+      --web-terminal-renderer string, $CODER_WEB_TERMINAL_RENDERER (default: webgl)
+          The framework to use when rendering the terminal. Valid values are
+          'canvas', 'webgl', or 'dom'.
+
 CONFIG OPTIONS: 
 Use a YAML configuration file when your server launch become unwieldy.
 

diff --git a/cli/testdata/server-config.yaml.golden b/cli/testdata/server-config.yaml.golden
@@ -411,6 +411,10 @@ client:
   # incorrectly can break SSH to your deployment, use cautiously.
   # (default: <unset>, type: string-array)
   sshConfigOptions: []
+  # The framework to use when rendering the terminal. Valid values are 'canvas',
+  # 'webgl', or 'dom'.
+  # (default: webgl, type: string)
+  webTerminalRenderer: webgl
 # Support links to display in the top right drop down menu.
 # (default: <unset>, type: struct[[]codersdk.LinkConfig])
 supportLinks: []

diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/codersdk/deployment.go b/codersdk/deployment.go
@@ -180,6 +180,7 @@ type DeploymentValues struct {
 	ProxyHealthStatusInterval       clibase.Duration                     `json:"proxy_health_status_interval,omitempty" typescript:",notnull"`
 	EnableTerraformDebugMode        clibase.Bool                         `json:"enable_terraform_debug_mode,omitempty" typescript:",notnull"`
 	UserQuietHoursSchedule          UserQuietHoursScheduleConfig         `json:"user_quiet_hours_schedule,omitempty" typescript:",notnull"`
+	WebTerminalRenderer             clibase.String                       `json:"web_terminal_renderer,omitempty" typescript:",notnull"`
 
 	Config      clibase.YAMLConfigPath `json:"config,omitempty" typescript:",notnull"`
 	WriteConfig clibase.Bool           `json:"write_config,omitempty" typescript:",notnull"`
@@ -1762,7 +1763,18 @@ Write out the current server config as YAML to stdout.`,
 			Group:       &deploymentGroupUserQuietHoursSchedule,
 			YAML:        "defaultQuietHoursSchedule",
 		},
+		{
+			Name:        "Web Terminal Renderer",
+			Description: "The framework to use when rendering the terminal. Valid values are 'canvas', 'webgl', or 'dom'.",
+			Flag:        "web-terminal-renderer",
+			Env:         "CODER_WEB_TERMINAL_RENDERER",
+			Default:     "webgl",
+			Value:       &c.WebTerminalRenderer,
+			Group:       &deploymentGroupClient,
+			YAML:        "webTerminalRenderer",
+		},
 	}
+
 	return opts
 }
 

diff --git a/docs/api/general.md b/docs/api/general.md
diff --git a/docs/api/schemas.md b/docs/api/schemas.md
diff --git a/docs/cli/server.md b/docs/cli/server.md
diff --git a/enterprise/cli/testdata/coder_server_--help.golden b/enterprise/cli/testdata/coder_server_--help.golden
@@ -67,6 +67,10 @@ Clients include the coder cli, vs code extension, and the web UI.
       --ssh-hostname-prefix string, $CODER_SSH_HOSTNAME_PREFIX (default: coder.)
           The SSH deployment prefix is used in the Host of the ssh config.
 
+      --web-terminal-renderer string, $CODER_WEB_TERMINAL_RENDERER (default: webgl)
+          The framework to use when rendering the terminal. Valid values are
+          'canvas', 'webgl', or 'dom'.
+
 CONFIG OPTIONS: 
 Use a YAML configuration file when your server launch become unwieldy.
 

diff --git a/site/src/AppRouter.tsx b/site/src/AppRouter.tsx
@@ -339,7 +339,7 @@ export const AppRouter: FC = () => {
             {/* Terminal and CLI auth pages don't have the dashboard layout */}
             <Route
               path="/:username/:workspace/terminal"
-              element={<TerminalPage renderer="webgl" />}
+              element={<TerminalPage />}
             />
             <Route path="/cli-auth" element={<CliAuthenticationPage />} />
             <Route path="/icons" element={<IconsPage />} />

diff --git a/site/src/api/typesGenerated.ts b/site/src/api/typesGenerated.ts
diff --git a/site/src/pages/TerminalPage/TerminalPage.test.tsx b/site/src/pages/TerminalPage/TerminalPage.test.tsx
@@ -37,7 +37,7 @@ Object.defineProperty(window, "TextEncoder", {
 const renderTerminal = async (
   route = `/${MockUser.username}/${MockWorkspace.name}/terminal`,
 ) => {
-  const utils = renderWithAuth(<TerminalPage renderer="dom" />, {
+  const utils = renderWithAuth(<TerminalPage />, {
     route,
     path: "/:username/:workspace/terminal",
   });

diff --git a/site/src/pages/TerminalPage/TerminalPage.tsx b/site/src/pages/TerminalPage/TerminalPage.tsx
@@ -7,6 +7,7 @@ import { colors } from "theme/colors";
 import { v4 as uuidv4 } from "uuid";
 import * as XTerm from "xterm";
 import { WebglAddon } from "xterm-addon-webgl";
+import { CanvasAddon } from "xterm-addon-canvas";
 import { FitAddon } from "xterm-addon-fit";
 import { WebLinksAddon } from "xterm-addon-web-links";
 import { Unicode11Addon } from "xterm-addon-unicode11";
@@ -28,18 +29,16 @@ import {
   LoadedScriptsAlert,
   LoadingScriptsAlert,
 } from "./TerminalAlerts";
+import { useQuery } from "@tanstack/react-query";
+import { deploymentConfig } from "api/queries/deployment";
 
 export const Language = {
   workspaceErrorMessagePrefix: "Unable to fetch workspace: ",
   workspaceAgentErrorMessagePrefix: "Unable to fetch workspace agent: ",
   websocketErrorMessagePrefix: "WebSocket failed: ",
 };
 
-type TerminalPageProps = React.PropsWithChildren<{
-  renderer: "webgl" | "dom";
-}>;
-
-const TerminalPage: FC<TerminalPageProps> = ({ renderer }) => {
+const TerminalPage: FC = () => {
   const navigate = useNavigate();
   const styles = useStyles();
   const { proxy } = useProxy();
@@ -101,6 +100,8 @@ const TerminalPage: FC<TerminalPageProps> = ({ renderer }) => {
     prevLifecycleState.current = lifecycleState;
   }, [lifecycleState]);
 
+  const config = useQuery(deploymentConfig());
+
   // handleWebLink handles opening of URLs in the terminal!
   const handleWebLink = useCallback(
     (uri: string) => {
@@ -166,9 +167,13 @@ const TerminalPage: FC<TerminalPageProps> = ({ renderer }) => {
         background: colors.gray[16],
       },
     });
-    // DOM is the default renderer.
-    if (renderer === "webgl") {
+    if (config.data && config.data.config.web_terminal_renderer === "webgl") {
       terminal.loadAddon(new WebglAddon());
+    } else if (
+      config.data &&
+      config.data.config.web_terminal_renderer === "canvas"
+    ) {
+      terminal.loadAddon(new CanvasAddon());
     }
     const fitAddon = new FitAddon();
     setFitAddon(fitAddon);
@@ -208,7 +213,7 @@ const TerminalPage: FC<TerminalPageProps> = ({ renderer }) => {
       window.removeEventListener("resize", listener);
       terminal.dispose();
     };
-  }, [renderer, sendEvent, xtermRef, handleWebLink]);
+  }, [config.data, sendEvent, xtermRef, handleWebLink]);
 
   // Triggers the initial terminal connection using
   // the reconnection token and workspace name found