Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

improvment: add xterm addons and terminal resize (#6395)

Myles Scolnickea27274f1a0a
diff --git a/frontend/package.json b/frontend/package.json
index 7f028efc23..2f05ce09c3 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -100,7 +100,11 @@
"@uwdata/flechette": "^1.1.2",
"@valtown/codemirror-codeium": "^1.1.1",
"@xterm/addon-attach": "^0.11.0",
+ "@xterm/addon-canvas": "^0.7.0",
"@xterm/addon-fit": "^0.10.0",
+ "@xterm/addon-search": "^0.15.0",
+ "@xterm/addon-unicode11": "^0.8.0",
+ "@xterm/addon-web-links": "^0.11.0",
"@xterm/xterm": "^5.5.0",
"@zed-industries/agent-client-protocol": "^0.3.1",
"ai": "^5.0.30",
diff --git a/frontend/src/components/terminal/terminal.tsx b/frontend/src/components/terminal/terminal.tsx
index 4649145279..b2b845ff28 100644
--- a/frontend/src/components/terminal/terminal.tsx
+++ b/frontend/src/components/terminal/terminal.tsx
@@ -1,35 +1,244 @@
/* Copyright 2024 Marimo. All rights reserved. */
import { AttachAddon } from "@xterm/addon-attach";
+import { CanvasAddon } from "@xterm/addon-canvas";
import { FitAddon } from "@xterm/addon-fit";
+import { SearchAddon } from "@xterm/addon-search";
+import { Unicode11Addon } from "@xterm/addon-unicode11";
+import { WebLinksAddon } from "@xterm/addon-web-links";
import { Terminal } from "@xterm/xterm";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useMemo, useRef, useState } from "react";
import "@xterm/xterm/css/xterm.css";
import "./xterm.css";
+import {
+ ClipboardPasteIcon,
+ CopyIcon,
+ TextSelectionIcon,
+ Trash2Icon,
+} from "lucide-react";
+import useEvent from "react-use-event-hook";
import { waitForConnectionOpen } from "@/core/network/connection";
import { useRuntimeManager } from "@/core/runtime/config";
+import { useDebouncedCallback } from "@/hooks/useDebounce";
+import { cn } from "@/utils/cn";
+import { copyToClipboard } from "@/utils/copy";
import { Logger } from "@/utils/Logger";
+import { MinimalHotkeys } from "../shortcuts/renderShortcut";
+import { createTerminalTheme } from "./theme";
-const TerminalComponent: React.FC<{
+interface TerminalButtonProps {
+ onClick: () => void;
+ disabled?: boolean;
+ icon: React.ComponentType<{ className?: string }>;
+ children: React.ReactNode;
+ keyboardShortcut?: string;
+}
+
+const TerminalButton: React.FC<TerminalButtonProps> = ({
+ onClick,
+ disabled = false,
+ icon: Icon,
+ children,
+ keyboardShortcut,
+}) => (
+ <button
+ className={cn(
+ "w-full text-left px-3 py-2 text-sm flex items-center gap-3 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-muted",
+ )}
+ type="button"
+ onClick={onClick}
+ disabled={disabled}
+ >
+ <Icon className="w-4 h-4" />
+ {children}
+ {keyboardShortcut && (
+ <MinimalHotkeys className="ml-auto" shortcut={keyboardShortcut} />
+ )}
+ </button>
+);
+
+interface TerminalComponentProps {
visible: boolean;
onClose: () => void;
-}> = ({ visible, onClose }) => {
+}
+
+interface Position {
+ x: number;
+ y: number;
+ placement: "bottom" | "top"; // Whether to place the menu above or below the cursor
+}
+
+// Keyboard shortcut handlers
+function createKeyboardHandler(terminal: Terminal, _searchAddon: SearchAddon) {
+ return (event: KeyboardEvent) => {
+ const { ctrlKey, metaKey, key } = event;
+ const modifier = ctrlKey || metaKey;
+
+ if (modifier) {
+ switch (key) {
+ case "c":
+ if (terminal.hasSelection()) {
+ event.preventDefault();
+ void copyToClipboard(terminal.getSelection());
+ }
+ break;
+ case "v":
+ event.preventDefault();
+ void navigator.clipboard.readText().then((text) => {
+ terminal.paste(text);
+ });
+ break;
+ case "a":
+ event.preventDefault();
+ terminal.selectAll();
+ break;
+ case "l":
+ event.preventDefault();
+ terminal.clear();
+ break;
+ }
+ }
+ };
+}
+
+// Context menu actions
+function createContextMenuActions(
+ terminal: Terminal,
+ setContextMenu: (menu: Position | null) => void,
+) {
+ const closeMenu = () => setContextMenu(null);
+
+ return {
+ handleCopy: () => {
+ if (terminal.hasSelection()) {
+ navigator.clipboard.writeText(terminal.getSelection());
+ }
+ closeMenu();
+ },
+ handlePaste: () => {
+ navigator.clipboard.readText().then((text) => {
+ terminal.paste(text);
+ });
+ closeMenu();
+ },
+ handleSelectAll: () => {
+ terminal.selectAll();
+ closeMenu();
+ },
+ handleClear: () => {
+ terminal.clear();
+ closeMenu();
+ },
+ closeMenu,
+ };
+}
+
+const RESIZE_DEBOUNCE_TIME = 100;
+
+const TerminalComponent: React.FC<TerminalComponentProps> = ({
+ visible,
+ onClose,
+}) => {
const terminalRef = useRef<HTMLDivElement>(null);
+ const wsRef = useRef<WebSocket | null>(null);
+
// eslint-disable-next-line react/hook-use-state
- const [{ terminal, fitAddon }] = useState(() => {
+ const [{ terminal, fitAddon, searchAddon }] = useState(() => {
// Create a new terminal instance
const term = new Terminal({
fontFamily:
"Menlo, DejaVu Sans Mono, Consolas, Lucida Console, monospace",
fontSize: 14,
+ scrollback: 10_000,
+ cursorBlink: true,
+ cursorStyle: "block",
+ allowTransparency: false,
+ theme: createTerminalTheme("dark"),
+ rightClickSelectsWord: true,
+ wordSeparator: " \t\r\n\"'`(){}[]<>|&;",
+ allowProposedApi: true,
});
+
+ // Load essential addons
const fitAddon = new FitAddon();
+ const searchAddon = new SearchAddon();
+ const canvasAddon = new CanvasAddon();
+ const unicode11Addon = new Unicode11Addon();
+ const webLinksAddon = new WebLinksAddon();
+
term.loadAddon(fitAddon);
- return { terminal: term, fitAddon };
+ term.loadAddon(searchAddon);
+ term.loadAddon(canvasAddon);
+ term.loadAddon(unicode11Addon);
+ term.loadAddon(webLinksAddon);
+
+ // Set Unicode version
+ term.unicode.activeVersion = "11";
+
+ return { terminal: term, fitAddon, searchAddon };
});
+
const [initialized, setInitialized] = React.useState(false);
+ const [contextMenu, setContextMenu] = useState<Position | null>(null);
const runtimeManager = useRuntimeManager();
+ // Keyboard shortcuts handler
+ const handleKeyDown = useEvent(createKeyboardHandler(terminal, searchAddon));
+
+ // Context menu handler
+ const handleContextMenu = useEvent((event: MouseEvent) => {
+ event.preventDefault();
+
+ const menuHeight = 200; // Approximate height of the context menu
+ const viewportHeight = window.innerHeight;
+ const cursorY = event.clientY;
+
+ // Check if there's enough space below the cursor
+ const spaceBelow = viewportHeight - cursorY;
+ const shouldPlaceAbove = spaceBelow < menuHeight;
+
+ setContextMenu({
+ x: event.clientX,
+ y: event.clientY,
+ placement: shouldPlaceAbove ? "top" : "bottom",
+ });
+ });
+
+ // Close context menu on click outside
+ const handleClickOutside = useEvent((event: MouseEvent) => {
+ const target = event.target;
+ const isInsideContextMenu =
+ target &&
+ target instanceof HTMLElement &&
+ target.closest(".xterm-context-menu");
+ if (contextMenu && !isInsideContextMenu) {
+ setContextMenu(null);
+ }
+ });
+
+ const handleBackendResizeDebounced = useDebouncedCallback(
+ ({ cols, rows }: { cols: number; rows: number }) => {
+ if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
+ Logger.debug("Sending resize to backend terminal", { cols, rows });
+ wsRef.current.send(JSON.stringify({ type: "resize", cols, rows }));
+ }
+ },
+ RESIZE_DEBOUNCE_TIME,
+ );
+
+ const handleResize = useEvent(() => {
+ if (!terminal || !fitAddon) {
+ return;
+ }
+ fitAddon.fit();
+ });
+
+ // Context menu actions
+ const { handleCopy, handlePaste, handleSelectAll, handleClear } = useMemo(
+ () => createContextMenuActions(terminal, setContextMenu),
+ [terminal],
+ );
+
// Websocket Connection
useEffect(() => {
if (initialized) {
@@ -43,11 +252,13 @@ const TerminalComponent: React.FC<{
const socket = new WebSocket(runtimeManager.getTerminalWsURL());
const attachAddon = new AttachAddon(socket);
terminal.loadAddon(attachAddon);
+ wsRef.current = socket;
const handleDisconnect = () => {
onClose();
// Reset
attachAddon.dispose();
+ wsRef.current = null;
terminal.clear();
setInitialized(false);
};
@@ -86,23 +297,85 @@ const TerminalComponent: React.FC<{
}
terminal.open(terminalRef.current);
- fitAddon.fit();
- terminal.focus();
- // Handle resize
- const handleResize = () => {
+
+ // Initial fit with delay to ensure DOM is ready
+ setTimeout(() => {
fitAddon.fit();
- };
- window.addEventListener("resize", handleResize);
+ }, RESIZE_DEBOUNCE_TIME);
+
+ terminal.focus();
+
+ const abortController = new AbortController();
+
+ // Add event listeners
+ window.addEventListener("resize", handleResize, {
+ signal: abortController.signal,
+ });
+ terminalRef.current.addEventListener("keydown", handleKeyDown, {
+ signal: abortController.signal,
+ });
+ terminalRef.current.addEventListener("contextmenu", handleContextMenu, {
+ signal: abortController.signal,
+ });
+ terminal.onResize(handleBackendResizeDebounced);
+ document.addEventListener("click", handleClickOutside, {
+ signal: abortController.signal,
+ });
return () => {
- window.removeEventListener("resize", handleResize);
+ abortController.abort();
};
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
return (
- <div className="relative w-full h-[calc(100%-4px)] dark bg-(--slate-1)">
+ <div className={"relative w-full h-[calc(100%-4px)] bg-popover"}>
<div className="w-full h-full" ref={terminalRef} />
+ {contextMenu && (
+ <div
+ className={
+ "xterm-context-menu fixed z-50 rounded-md shadow-lg py-1 min-w-[160px] border bg-popover"
+ }
+ style={{
+ left: contextMenu.x,
+ [contextMenu.placement === "top" ? "bottom" : "top"]:
+ contextMenu.placement === "top"
+ ? window.innerHeight - contextMenu.y
+ : contextMenu.y,
+ }}
+ >
+ <TerminalButton
+ onClick={handleCopy}
+ disabled={!terminal.hasSelection()}
+ icon={CopyIcon}
+ keyboardShortcut="mod-c"
+ >
+ Copy
+ </TerminalButton>
+ <TerminalButton
+ onClick={handlePaste}
+ icon={ClipboardPasteIcon}
+ keyboardShortcut="mod-v"
+ >
+ Paste
+ </TerminalButton>
+ <hr className={cn("my-1 border-border")} />
+ <TerminalButton
+ onClick={handleSelectAll}
+ icon={TextSelectionIcon}
+ keyboardShortcut="mod-a"
+ >
+ Select all
+ </TerminalButton>
+ <TerminalButton
+ onClick={handleClear}
+ icon={Trash2Icon}
+ keyboardShortcut="mod-l"
+ >
+ Clear terminal
+ </TerminalButton>
+ </div>
+ )}
</div>
);
};
diff --git a/frontend/src/components/terminal/theme.tsx b/frontend/src/components/terminal/theme.tsx
new file mode 100644
index 0000000000..1cdeab002b
--- /dev/null
+++ b/frontend/src/components/terminal/theme.tsx
@@ -0,0 +1,56 @@
+import type { ResolvedTheme } from "@/theme/useTheme";
+
+// Terminal theme configuration
+export function createTerminalTheme(theme: ResolvedTheme) {
+ const baseTheme = {
+ cursor: "#ffffff",
+ cursorAccent: "#000000",
+ };
+
+ return theme === "dark"
+ ? {
+ ...baseTheme,
+ background: "#0f172a", // slate-900
+ foreground: "#f8fafc", // slate-50
+ black: "#0f172a",
+ red: "#ef4444",
+ green: "#22c55e",
+ yellow: "#eab308",
+ blue: "#3b82f6",
+ magenta: "#a855f7",
+ cyan: "#06b6d4",
+ white: "#f1f5f9",
+ brightBlack: "#475569",
+ brightRed: "#f87171",
+ brightGreen: "#4ade80",
+ brightYellow: "#facc15",
+ brightBlue: "#60a5fa",
+ brightMagenta: "#c084fc",
+ brightCyan: "#22d3ee",
+ brightWhite: "#ffffff",
+ selection: "rgba(148, 163, 184, 0.3)", // slate-400 with opacity
+ }
+ : {
+ ...baseTheme,
+ background: "#ffffff", // white
+ foreground: "#0f172a", // slate-900
+ cursor: "#0f172a",
+ black: "#0f172a",
+ red: "#dc2626",
+ green: "#16a34a",
+ yellow: "#ca8a04",
+ blue: "#2563eb",
+ magenta: "#9333ea",
+ cyan: "#0891b2",
+ white: "#e2e8f0",
+ brightBlack: "#64748b",
+ brightRed: "#ef4444",
+ brightGreen: "#22c55e",
+ brightYellow: "#eab308",
+ brightBlue: "#3b82f6",
+ brightMagenta: "#a855f7",
+ brightCyan: "#06b6d4",
+ brightWhite: "#ffffff",
+ selection: "rgba(71, 85, 105, 0.2)", // slate-600 with opacity
+ };
+}
diff --git a/marimo/_server/api/endpoints/terminal.py b/marimo/_server/api/endpoints/terminal.py
index b20b74df90..1b3823deee 100644
--- a/marimo/_server/api/endpoints/terminal.py
+++ b/marimo/_server/api/endpoints/terminal.py
@@ -2,10 +2,14 @@
from __future__ import annotations
import asyncio
+import json
import os
import select
import signal
-import subprocess
+import struct
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Literal, TypedDict
from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketState
@@ -14,30 +18,200 @@ from marimo._server.api.deps import AppState
from marimo._server.model import SessionMode
from marimo._server.router import APIRouter
+if TYPE_CHECKING:
+ from collections.abc import Iterable
+
LOGGER = _loggers.marimo_logger()
router = APIRouter()
+# Configuration constants
+MAX_CHUNK_SIZE = 8192
+MAX_BUFFER_SIZE = 65536
+MAX_COMMAND_BUFFER_SIZE = 1024
+KEEP_COMMAND_CHARS = 512
+HEALTH_CHECK_INTERVAL = 5.0
+READ_TIMEOUT = 0.05
+IDLE_SLEEP = 0.01
+
+
+def _resize_pty(fd: int, rows: int, cols: int) -> None:
+ """Resize the PTY to the specified dimensions."""
+ try:
+ # Use TIOCSWINSZ ioctl to set window size
+ import fcntl
+ import termios
+
+ # Format: struct winsize { unsigned short ws_row, ws_col, ws_xpixel, ws_ypixel }
+ winsize = struct.pack("HHHH", rows, cols, 0, 0)
+ fcntl.ioctl(fd, termios.TIOCSWINSZ, winsize)
+ LOGGER.debug(f"PTY resized to {cols}x{rows}")
+ except Exception as e:
+ LOGGER.warning(f"Failed to resize PTY: {e}")
+
+
+def _send_sigwinch(pid: int) -> None:
+ """Send SIGWINCH signal to the child process to notify of terminal resize."""
+ try:
+ os.kill(pid, signal.SIGWINCH)
+ LOGGER.debug(f"Sent SIGWINCH to process {pid}")
+ except (OSError, ProcessLookupError) as e:
+ LOGGER.debug(f"Failed to send SIGWINCH to {pid}: {e}")
+
+
+def _create_shell_environment(
+ cwd: str | None = None,
+) -> tuple[str, dict[str, str]]:
+ """Create a proper shell environment with working directory and env vars."""
+ # Set working directory to a reasonable default
+ if cwd is None:
+ try:
+ cwd = os.getcwd()
+ except (OSError, PermissionError):
+ try:
+ cwd = str(Path.home())
+ except Exception:
+ cwd = "/tmp"
+
+ # Set up environment variables
+ env = os.environ.copy()
+ env["TERM"] = "xterm-256color"
+ env["LANG"] = env.get("LANG", "en_US.UTF-8")
+ env["LC_ALL"] = env.get("LC_ALL", "en_US.UTF-8")
+
+ # Determine shell
+ default_shell = os.environ.get("SHELL")
+ if not default_shell or not os.path.exists(default_shell):
+ # Try common shells
+ for shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]:
+ if os.path.exists(shell):
+ default_shell = shell
+ break
+ else:
+ default_shell = "/bin/sh" # Fallback
+
+ return default_shell, env
+
+
+def _setup_child_process(shell: str, env: dict[str, str], cwd: str) -> None:
+ """Set up the child process environment and start the shell."""
+ try:
+ os.chdir(cwd)
+ os.execve(shell, [shell], env)
+ except Exception as e:
+ LOGGER.error(f"Failed to start shell: {e}")
+ sys.exit(1)
+
+
+def _create_process_cleanup_handler(
+ child_pid: int, fd: int
+) -> Callable[[], None]:
+ """Create a cleanup handler for the child process and file descriptor."""
+
+ def cleanup() -> None:
+ try:
+ # Try graceful termination first
+ os.kill(child_pid, signal.SIGTERM)
+ # Give the process a moment to terminate gracefully
+ try:
+ os.waitpid(child_pid, os.WNOHANG)
+ except (OSError, ChildProcessError):
+ pass
+ # Force kill if still running
+ try:
+ os.kill(child_pid, signal.SIGKILL)
+ os.waitpid(child_pid, 0)
+ except (OSError, ProcessLookupError, ChildProcessError):
+ pass
+ except Exception as e:
+ LOGGER.debug(f"Error during cleanup: {e}")
+
+ # Close the pty file descriptor
+ try:
+ os.close(fd)
+ except OSError:
+ pass
+
+ return cleanup
+
+
+def _decode_pty_data(
+ buffer: bytes, max_buffer_size: int = MAX_BUFFER_SIZE
+) -> tuple[str, bytes]:
+ """Decode PTY data handling partial UTF-8 sequences."""
+ try:
+ # Decode and send data, handling partial UTF-8 sequences
+ text = buffer.decode("utf-8", errors="ignore")
+ return text, b""
+ except UnicodeDecodeError:
+ # Keep buffer if we have incomplete UTF-8 sequence
+ if len(buffer) > max_buffer_size:
+ # Force send to prevent memory issues
+ text = buffer.decode("utf-8", errors="replace")
+ return text, b""
+ return "", buffer
+
+
+def _should_close_on_command(command_buffer: str, data: str) -> bool:
+ """Check if the terminal should close based on the command."""
+ if data in ["\r", "\n"]:
+ return command_buffer.strip().lower() == "exit"
+ return False
+
+
+def _manage_command_buffer(
+ buffer: str, data: str, max_size: int = MAX_COMMAND_BUFFER_SIZE
+) -> str:
+ """Manage the command buffer size to prevent memory issues."""
+ buffer += data
+ if len(buffer) > max_size:
+ return buffer[-KEEP_COMMAND_CHARS:] # Keep last chars
+ return buffer
+
+
async def _read_from_pty(master: int, websocket: WebSocket) -> None:
+ """Read data from PTY and send to websocket with proper buffering."""
loop = asyncio.get_running_loop()
+ buffer = b""
+
try:
- # TODO: loop.add_reader would likely be better in this case
- # but when the program is closed from the terminal, it hangs
- # for an additional second before the process is killed.
with os.fdopen(master, "rb", buffering=0) as master_file:
while True:
try:
+ # Check for available data with a timeout
r, _, _ = await loop.run_in_executor(
- None, select.select, [master_file], [], [], 0.1
+ None,
+ select.select,
+ [master_file],
+ [],
+ [],
+ READ_TIMEOUT,
)
- if not r:
- await asyncio.sleep(0.1) # Prevent busy-waiting
- continue
- data = os.read(master, 1024)
- if not data:
- break
- await websocket.send_text(data.decode())
+
+ if r:
+ # Read available data
+ try:
+ chunk = os.read(master, MAX_CHUNK_SIZE)
+ if not chunk:
+ break
+ buffer += chunk
+ except OSError as e:
+ if (
+ e.errno == 5
+ ): # Input/output error (process died)
+ break
+ raise
+
+ # Send buffered data if we have any
+ if buffer:
+ text, buffer = _decode_pty_data(buffer)
+ if text:
+ await websocket.send_text(text)
+ else:
+ # Small delay to prevent busy-waiting when no data
+ await asyncio.sleep(IDLE_SLEEP)
+
except (asyncio.CancelledError, WebSocketDisconnect):
break
except OSError as e:
@@ -47,27 +221,89 @@ async def _read_from_pty(master: int, websocket: WebSocket) -> None:
raise # Re-raise other OSErrors
-async def _write_to_pty(master: int, websocket: WebSocket) -> None:
+class ResizeMessage(TypedDict):
+ type: Literal["resize"]
+ cols: int
+ rows: int
+
+
+async def _maybe_handle_resize(
+ *, master: int, child_pid: int, message: str
+) -> bool:
+ """Handle resize messages from websocket."""
+
try:
- buffer = ""
+ parsed_message: ResizeMessage = json.loads(message)
+ if (
+ isinstance(parsed_message, dict)
+ and parsed_message.get("type") == "resize"
+ ):
+ cols = parsed_message.get("cols")
+ rows = parsed_message.get("rows")
+ if (
+ isinstance(cols, int)
+ and isinstance(rows, int)
+ and cols > 0
+ and rows > 0
+ ):
+ _resize_pty(master, rows, cols)
+ _send_sigwinch(child_pid)
+ return True
+ else:
+ LOGGER.warning("Invalid resize message")
+ return False
+ except (json.JSONDecodeError, TypeError):
+ # Not a JSON message, treat as regular terminal input
+ pass
+
+ return False
+
+
+async def _write_to_pty(
+ master: int, websocket: WebSocket, child_pid: int
+) -> None:
+ """Write data from websocket to PTY with command monitoring and resize handling."""
+ try:
+ command_buffer = ""
with os.fdopen(master, "wb", buffering=0) as master_file:
while True:
try:
data = await websocket.receive_text()
- LOGGER.debug("Received: %s", data)
-
- buffer += data
- if data in ["\r", "\n"]: # Check for line ending
- if buffer.strip().lower() == "exit":
- LOGGER.debug(
- "Exit command received, closing connection"
- )
- # End the connection
- return
- buffer = "" # Reset buffer after processing a command
-
- master_file.write(data.encode())
- master_file.flush()
+ LOGGER.debug("Received: %s", repr(data))
+
+ # Check if this is a resize message
+ if await _maybe_handle_resize(
+ master=master, child_pid=child_pid, message=data
+ ):
+ continue
+
+ # Handle special key combinations and commands
+ command_buffer = _manage_command_buffer(
+ command_buffer, data
+ )
+
+ # Check for exit command
+ if _should_close_on_command(command_buffer, data):
+ LOGGER.debug(
+ "Exit command received, closing connection"
+ )
+ return
+
+ # Reset buffer on line endings
+ if data in ["\r", "\n"]:
+ command_buffer = ""
+
+ # Write data to PTY
+ try:
+ encoded_data = data.encode("utf-8")
+ master_file.write(encoded_data)
+ master_file.flush()
+ except OSError as e:
+ if e.errno == 5: # Input/output error (process died)
+ LOGGER.debug("Process died, stopping write loop")
+ break
+ raise
+
except (asyncio.CancelledError, WebSocketDisconnect):
break
except OSError as e:
@@ -77,46 +313,72 @@ async def _write_to_pty(master: int, websocket: WebSocket) -> None:
raise
+async def _cancel_tasks(tasks: Iterable[asyncio.Task[Any]]) -> None:
+ for task in tasks:
+ if not task.done():
+ task.cancel()
+ try:
+ await task
+ except asyncio.CancelledError:
+ pass
+
+
@router.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket) -> None:
app_state = AppState(websocket)
if app_state.mode != SessionMode.EDIT:
- await websocket.close()
+ await websocket.close(
+ code=1008, reason="Terminal only available in edit mode"
+ )
+ return
+
+ try:
+ await websocket.accept()
+ LOGGER.debug("Terminal websocket accepted")
+ except Exception as e:
+ LOGGER.error(f"Failed to accept websocket connection: {e}")
return
- await websocket.accept()
- LOGGER.debug("Terminal websocket accepted")
import pty
child_pid, fd = pty.fork()
if child_pid == 0:
- default_shell = os.environ.get("SHELL", "/bin/bash")
- subprocess.run([default_shell], shell=True) # noqa: ASYNC221
- return
+ # Child process - set up the shell environment
+ shell, env = _create_shell_environment()
+ cwd = env.get("PWD", os.getcwd())
+ _setup_child_process(shell, env, cwd)
+
+ # Set up cleanup handler
+ cleanup_child = _create_process_cleanup_handler(child_pid, fd)
reader_task = asyncio.create_task(_read_from_pty(fd, websocket))
- writer_task = asyncio.create_task(_write_to_pty(fd, websocket))
+ writer_task = asyncio.create_task(_write_to_pty(fd, websocket, child_pid))
try:
_done, pending = await asyncio.wait(
[reader_task, writer_task], return_when=asyncio.FIRST_COMPLETED
)
- for task in pending:
- task.cancel()
+
+ # Cancel all pending tasks
+ await _cancel_tasks(pending)
+
except WebSocketDisconnect:
- pass
+ LOGGER.debug("Client disconnected from terminal")
except Exception as e:
- LOGGER.exception(e)
+ LOGGER.exception(f"Terminal websocket error: {e}")
finally:
+ # Ensure all tasks are cleaned up
+ await _cancel_tasks([reader_task, writer_task])
+
+ # Close websocket if still connected
try:
if websocket.application_state != WebSocketState.DISCONNECTED:
- await websocket.close()
- except RuntimeError:
- pass
- if reader_task and not reader_task.done():
- reader_task.cancel()
- if writer_task and not writer_task.done():
- writer_task.cancel()
- os.kill(child_pid, signal.SIGKILL)
- os.waitpid(child_pid, 0) # noqa: ASYNC222
+ await websocket.close(
+ code=1000, reason="Terminal session ended"
+ )
+ except Exception as e:
+ LOGGER.debug(f"Error closing websocket: {e}")
+
+ # Clean up process and file descriptor
+ cleanup_child()
LOGGER.debug("Terminal websocket closed")
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4ef5fe8678..4a3dde1014 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -280,9 +280,21 @@ importers:
'@xterm/addon-attach':
specifier: ^0.11.0
version: 0.11.0(@xterm/[email protected])
+ '@xterm/addon-canvas':
+ specifier: ^0.7.0
+ version: 0.7.0(@xterm/[email protected])
'@xterm/addon-fit':
specifier: ^0.10.0
version: 0.10.0(@xterm/[email protected])
+ '@xterm/addon-search':
+ specifier: ^0.15.0
+ version: 0.15.0(@xterm/[email protected])
+ '@xterm/addon-unicode11':
+ specifier: ^0.8.0
+ version: 0.8.0(@xterm/[email protected])
+ '@xterm/addon-web-links':
+ specifier: ^0.11.0
+ version: 0.11.0(@xterm/[email protected])
'@xterm/xterm':
specifier: ^5.5.0
version: 5.5.0
@@ -4220,11 +4232,31 @@ packages:
peerDependencies:
'@xterm/xterm': ^5.0.0
+ '@xterm/[email protected]':
+ resolution: {integrity: sha512-LF5LYcfvefJuJ7QotNRdRSPc9YASAVDeoT5uyXS/nZshZXjYplGXRECBGiznwvhNL2I8bq1Lf5MzRwstsYQ2Iw==}
+ peerDependencies:
+ '@xterm/xterm': ^5.0.0
+
resolution: {integrity: sha512-UFYkDm4HUahf2lnEyHvio51TNGiLK66mqP2JoATy7hRZeXaGMRDr00JiSF7m63vR5WKATF605yEggJKsw0JpMQ==}
peerDependencies:
'@xterm/xterm': ^5.0.0
+ '@xterm/[email protected]':
+ resolution: {integrity: sha512-ZBZKLQ+EuKE83CqCmSSz5y1tx+aNOCUaA7dm6emgOX+8J9H1FWXZyrKfzjwzV+V14TV3xToz1goIeRhXBS5qjg==}
+ peerDependencies:
+ '@xterm/xterm': ^5.0.0
+
+ '@xterm/[email protected]':
+ resolution: {integrity: sha512-LxinXu8SC4OmVa6FhgwsVCBZbr8WoSGzBl2+vqe8WcQ6hb1r6Gj9P99qTNdPiFPh4Ceiu2pC8xukZ6+2nnh49Q==}
+ peerDependencies:
+ '@xterm/xterm': ^5.0.0
+
+ '@xterm/[email protected]':
+ resolution: {integrity: sha512-nIHQ38pQI+a5kXnRaTgwqSHnX7KE6+4SVoceompgHL26unAxdfP6IPqUTSYPQgSwM56hsElfoNrrW5V7BUED/Q==}
+ peerDependencies:
+ '@xterm/xterm': ^5.0.0
+
resolution: {integrity: sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==}
@@ -14445,10 +14477,26 @@ snapshots:
dependencies:
'@xterm/xterm': 5.5.0
+ dependencies:
+ '@xterm/xterm': 5.5.0
+
dependencies:
'@xterm/xterm': 5.5.0
+ dependencies:
+ '@xterm/xterm': 5.5.0
+
+ dependencies:
+ '@xterm/xterm': 5.5.0
+
+ dependencies:
+ '@xterm/xterm': 5.5.0
+
'@xterm/[email protected]': {}
'@xtuc/[email protected]': {}
diff --git a/tests/_server/api/endpoints/test_terminal.py b/tests/_server/api/endpoints/test_terminal.py
index fa103a4551..dd14934d2e 100644
--- a/tests/_server/api/endpoints/test_terminal.py
+++ b/tests/_server/api/endpoints/test_terminal.py
@@ -1,12 +1,25 @@
# Copyright 2024 Marimo. All rights reserved.
from __future__ import annotations
+import os
+import signal
import sys
+import tempfile
+from pathlib import Path
from typing import TYPE_CHECKING
+from unittest.mock import Mock, patch
import pytest
from starlette.websockets import WebSocketDisconnect
+from marimo._server.api.endpoints.terminal import (
+ _create_process_cleanup_handler,
+ _create_shell_environment,
+ _decode_pty_data,
+ _manage_command_buffer,
+ _setup_child_process,
+ _should_close_on_command,
+)
from marimo._server.model import SessionMode
from marimo._server.sessions import SessionManager
from tests._server.conftest import get_session_manager
@@ -18,7 +31,7 @@ is_windows = sys.platform == "win32"
is_mac = sys.platform == "darwin"
[email protected](is_windows or is_mac, reason="Skip on Windows or Mac")
[email protected](is_windows, reason="Skip on Windows")
def test_terminal_ws(client: TestClient) -> None:
with client.websocket_connect("/terminal/ws") as websocket:
# Send echo message
@@ -34,3 +47,385 @@ def test_terminal_ws_not_allowed_in_run(client: TestClient) -> None:
with client.websocket_connect("/terminal/ws") as websocket:
websocket.send_text("echo hello")
session_manager.mode = SessionMode.EDIT
+
+
+# Unit tests for terminal utility functions
+
+
+class TestCreateShellEnvironment:
+ def test_create_shell_environment_default_cwd(self) -> None:
+ """Test shell environment creation with default working directory."""
+ shell, env = _create_shell_environment()
+
+ assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
+ assert env["TERM"] == "xterm-256color"
+ assert "LANG" in env
+ assert "LC_ALL" in env
+
+ def test_create_shell_environment_custom_cwd(self) -> None:
+ """Test shell environment creation with custom working directory."""
+ with tempfile.TemporaryDirectory() as temp_dir:
+ shell, env = _create_shell_environment(cwd=temp_dir)
+
+ assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
+ assert env["TERM"] == "xterm-256color"
+
+ @patch("os.getcwd")
+ @patch("pathlib.Path.home")
+ def test_create_shell_environment_fallback_cwd(
+ self, mock_home: Mock, mock_getcwd: Mock
+ ) -> None:
+ """Test shell environment creation when getcwd fails."""
+ mock_getcwd.side_effect = OSError("No such directory")
+ mock_home.return_value = Path("/home/user")
+
+ shell, env = _create_shell_environment()
+
+ assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
+ assert env["TERM"] == "xterm-256color"
+
+ @patch("os.getcwd")
+ @patch("pathlib.Path.home")
+ def test_create_shell_environment_ultimate_fallback(
+ self, mock_home: Mock, mock_getcwd: Mock
+ ) -> None:
+ """Test shell environment creation when both getcwd and home fail."""
+ mock_getcwd.side_effect = OSError("No such directory")
+ mock_home.side_effect = Exception("No home directory")
+
+ shell, env = _create_shell_environment()
+
+ assert shell in ["/bin/bash", "/bin/zsh", "/bin/sh"]
+ assert env["TERM"] == "xterm-256color"
+
+ @patch("os.path.exists")
+ @patch.dict(os.environ, {"SHELL": "/nonexistent/shell"})
+ def test_create_shell_environment_shell_fallback(
+ self, mock_exists: Mock
+ ) -> None:
+ """Test shell selection fallback when default shell doesn't exist."""
+
+ # Mock that the default shell doesn't exist, but /bin/bash does
+ def exists_side_effect(path: str) -> bool:
+ return path == "/bin/bash"
+
+ mock_exists.side_effect = exists_side_effect
+
+ shell, env = _create_shell_environment()
+
+ assert shell == "/bin/bash"
+ assert env["TERM"] == "xterm-256color"
+
+
+class TestDecodeProxyData:
+ def test_decode_pty_data_valid_utf8(self) -> None:
+ """Test decoding valid UTF-8 data."""
+ buffer = b"hello world"
+ text, remaining = _decode_pty_data(buffer)
+
+ assert text == "hello world"
+ assert remaining == b""
+
+ def test_decode_pty_data_with_unicode(self) -> None:
+ """Test decoding UTF-8 data with unicode characters."""
+ buffer = "hello 🌍".encode()
+ text, remaining = _decode_pty_data(buffer)
+
+ assert text == "hello 🌍"
+ assert remaining == b""
+
+ def test_decode_pty_data_invalid_utf8_ignored(self) -> None:
+ """Test decoding invalid UTF-8 data with ignore errors."""
+ buffer = b"hello\xff\xfeinvalid"
+ text, remaining = _decode_pty_data(buffer)
+
+ assert text == "helloinvalid" # Invalid bytes are ignored
+ assert remaining == b""
+
+ def test_decode_pty_data_buffer_too_large(self) -> None:
+ """Test decoding when buffer exceeds max size."""
+ large_buffer = b"x" * 100000 # Larger than MAX_BUFFER_SIZE
+ text, remaining = _decode_pty_data(large_buffer, max_buffer_size=1024)
+
+ assert text == "x" * 100000 # Should decode with replacement
+ assert remaining == b""
+
+ def test_decode_pty_data_empty_buffer(self) -> None:
+ """Test decoding empty buffer."""
+ buffer = b""
+ text, remaining = _decode_pty_data(buffer)
+
+ assert text == ""
+ assert remaining == b""
+
+
+class TestShouldCloseOnCommand:
+ def test_should_close_on_command_exit_with_return(self) -> None:
+ """Test exit command detection with return key."""
+ assert _should_close_on_command("exit", "\r") is True
+ assert _should_close_on_command("EXIT", "\r") is True
+ assert _should_close_on_command(" exit ", "\r") is True
+
+ def test_should_close_on_command_exit_with_newline(self) -> None:
+ """Test exit command detection with newline."""
+ assert _should_close_on_command("exit", "\n") is True
+ assert _should_close_on_command("EXIT", "\n") is True
+ assert _should_close_on_command(" exit ", "\n") is True
+
+ def test_should_close_on_command_not_exit(self) -> None:
+ """Test non-exit commands don't trigger close."""
+ assert _should_close_on_command("ls", "\r") is False
+ assert _should_close_on_command("echo hello", "\n") is False
+ assert _should_close_on_command("exit_status", "\r") is False
+
+ def test_should_close_on_command_no_enter(self) -> None:
+ """Test exit command without enter key doesn't trigger close."""
+ assert _should_close_on_command("exit", "x") is False
+ assert _should_close_on_command("exit", "") is False
+
+ def test_should_close_on_command_empty_buffer(self) -> None:
+ """Test empty command buffer."""
+ assert _should_close_on_command("", "\r") is False
+ assert _should_close_on_command(" ", "\n") is False
+
+
+class TestManageCommandBuffer:
+ def test_manage_command_buffer_normal_size(self) -> None:
+ """Test command buffer management under normal size."""
+ buffer = "ls -la"
+ new_buffer = _manage_command_buffer(buffer, " /home")
+
+ assert new_buffer == "ls -la /home"
+
+ def test_manage_command_buffer_exceeds_max_size(self) -> None:
+ """Test command buffer management when exceeding max size."""
+ # Create a buffer that will exceed max size
+ long_command = "x" * 1000
+ buffer = long_command
+ new_buffer = _manage_command_buffer(buffer, "y", max_size=500)
+
+ # Should keep only the last 512 chars (KEEP_COMMAND_CHARS)
+ assert len(new_buffer) == 512 # Exactly KEEP_COMMAND_CHARS
+ assert new_buffer.endswith("y")
+ assert new_buffer.startswith("x")
+
+ def test_manage_command_buffer_empty_buffer(self) -> None:
+ """Test command buffer management with empty buffer."""
+ buffer = ""
+ new_buffer = _manage_command_buffer(buffer, "hello")
+
+ assert new_buffer == "hello"
+
+ def test_manage_command_buffer_exactly_max_size(self) -> None:
+ """Test command buffer management at exactly max size."""
+ buffer = "x" * 100
+ new_buffer = _manage_command_buffer(buffer, "y", max_size=100)
+
+ assert len(new_buffer) == 101
+ assert new_buffer == buffer + "y"
+
+
[email protected](is_windows, reason="Skip on Windows")
+class TestCreateProcessCleanupHandler:
+ def test_create_process_cleanup_handler_normal_cleanup(self) -> None:
+ """Test process cleanup handler creation and execution."""
+ mock_child_pid = 12345
+ mock_fd = 10
+
+ cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
+
+ with (
+ patch("os.kill") as mock_kill,
+ patch("os.waitpid") as mock_waitpid,
+ patch("os.close") as mock_close,
+ ):
+ cleanup()
+
+ # Should try graceful termination first
+ mock_kill.assert_any_call(mock_child_pid, signal.SIGTERM)
+ # Should try force kill
+ mock_kill.assert_any_call(mock_child_pid, signal.SIGKILL)
+ mock_waitpid.assert_called()
+ mock_close.assert_called_with(mock_fd)
+
+ def test_create_process_cleanup_handler_process_not_found(self) -> None:
+ """Test cleanup handler when process doesn't exist."""
+ mock_child_pid = 12345
+ mock_fd = 10
+
+ cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
+
+ with (
+ patch("os.kill") as mock_kill,
+ patch("os.waitpid") as mock_waitpid,
+ patch("os.close") as mock_close,
+ ):
+ mock_kill.side_effect = [
+ None,
+ ProcessLookupError("No such process"),
+ ]
+
+ cleanup()
+
+ # Should still try to close the file descriptor
+ mock_close.assert_called_with(mock_fd)
+
+ def test_create_process_cleanup_handler_fd_error(self) -> None:
+ """Test cleanup handler when file descriptor close fails."""
+ mock_child_pid = 12345
+ mock_fd = 10
+
+ cleanup = _create_process_cleanup_handler(mock_child_pid, mock_fd)
+
+ with (
+ patch("os.kill") as mock_kill,
+ patch("os.waitpid") as mock_waitpid,
+ patch("os.close") as mock_close,
+ ):
+ mock_close.side_effect = OSError("Bad file descriptor")
+
+ # Should not raise an exception
+ cleanup()
+
+ mock_close.assert_called_with(mock_fd)
+
+
+class TestSetupChildProcess:
+ @patch("os.chdir")
+ @patch("os.execve")
+ def test_setup_child_process_success(
+ self, mock_execve: Mock, mock_chdir: Mock
+ ) -> None:
+ """Test successful child process setup."""
+ shell = "/bin/bash"
+ env = {"TERM": "xterm-256color", "PATH": "/usr/bin"}
+ cwd = "/home/user"
+
+ _setup_child_process(shell, env, cwd)
+
+ mock_chdir.assert_called_once_with(cwd)
+ mock_execve.assert_called_once_with(shell, [shell], env)
+
+ @patch("os.chdir")
+ @patch("os.execve")
+ @patch("sys.exit")
+ def test_setup_child_process_chdir_fails(
+ self, mock_exit: Mock, mock_execve: Mock, mock_chdir: Mock
+ ) -> None:
+ """Test child process setup when chdir fails."""
+ shell = "/bin/bash"
+ env = {"TERM": "xterm-256color"}
+ cwd = "/nonexistent"
+
+ mock_chdir.side_effect = OSError("No such directory")
+
+ _setup_child_process(shell, env, cwd)
+
+ mock_chdir.assert_called_once_with(cwd)
+ mock_execve.assert_not_called()
+ mock_exit.assert_called_once_with(1)
+
+ @patch("os.chdir")
+ @patch("os.execve")
+ @patch("sys.exit")
+ def test_setup_child_process_execve_fails(
+ self, mock_exit: Mock, mock_execve: Mock, mock_chdir: Mock
+ ) -> None:
+ """Test child process setup when execve fails."""
+ shell = "/bin/bash"
+ env = {"TERM": "xterm-256color"}
+ cwd = "/home/user"
+
+ mock_execve.side_effect = OSError("Exec format error")
+
+ _setup_child_process(shell, env, cwd)
+
+ mock_chdir.assert_called_once_with(cwd)
+ mock_execve.assert_called_once_with(shell, [shell], env)
+ mock_exit.assert_called_once_with(1)
+
+
+# Additional edge case tests
+
+
+class TestDecodeProxyDataEdgeCases:
+ def test_decode_pty_data_partial_utf8_sequence(self) -> None:
+ """Test handling of partial UTF-8 sequences."""
+ # Create a partial UTF-8 sequence (emoji split across buffers)
+ full_emoji = "🌍".encode() # 4 bytes
+ partial_buffer = full_emoji[:2] # First 2 bytes only
+
+ text, remaining = _decode_pty_data(partial_buffer)
+
+ # Should handle gracefully with ignore errors
+ assert isinstance(text, str)
+ assert remaining == b""
+
+ def test_decode_pty_data_mixed_valid_invalid(self) -> None:
+ """Test decoding buffer with mix of valid and invalid UTF-8."""
+ buffer = b"hello\xff\xfe world \xe2\x9c\x93" # hello[invalid] world ✓
+ text, remaining = _decode_pty_data(buffer)
+
+ assert "hello" in text
+ assert "world" in text
+ assert remaining == b""
+
+
+class TestCommandBufferEdgeCases:
+ def test_manage_command_buffer_unicode_characters(self) -> None:
+ """Test command buffer with unicode characters."""
+ buffer = "echo 🌍"
+ new_buffer = _manage_command_buffer(buffer, " 🚀")
+
+ assert new_buffer == "echo 🌍 🚀"
+
+ def test_manage_command_buffer_control_characters(self) -> None:
+ """Test command buffer with control characters."""
+ buffer = "ls\x1b[1m" # ANSI escape sequence
+ new_buffer = _manage_command_buffer(buffer, "\x1b[0m")
+
+ assert new_buffer == "ls\x1b[1m\x1b[0m"
+
+ def test_should_close_on_command_case_variations(self) -> None:
+ """Test exit command detection with various case combinations."""
+ test_cases = [
+ ("exit", "\r", True),
+ ("Exit", "\r", True),
+ ("EXIT", "\r", True),
+ ("eXiT", "\r", True),
+ ("quit", "\r", False), # Only 'exit' should work
+ ("logout", "\r", False),
+ ]
+
+ for command, key, expected in test_cases:
+ assert _should_close_on_command(command, key) == expected
+
+
[email protected](is_windows, reason="Skip on Windows")
+def test_terminal_ws_unicode_input(client: TestClient) -> None:
+ """Test terminal websocket with unicode input."""
+ with client.websocket_connect("/terminal/ws") as websocket:
+ # Send unicode command
+ websocket.send_text("echo 'Hello 🌍'")
+ websocket.send_text("\r")
+ data = websocket.receive_text()
+
+ # Should handle unicode properly
+ assert isinstance(data, str)
+
+
+def test_terminal_ws_invalid_session_mode(client: TestClient) -> None:
+ """Test terminal websocket rejects non-edit mode sessions."""
+ session_manager: SessionManager = get_session_manager(client)
+ original_mode = session_manager.mode
+
+ try:
+ # Test with RUN mode
+ session_manager.mode = SessionMode.RUN
+ with pytest.raises(WebSocketDisconnect):
+ with client.websocket_connect("/terminal/ws"):
+ pass # Should fail immediately
+
+ finally:
+ # Restore original mode
+ session_manager.mode = original_mode