← Sandbox SDK / sandbox / api

Terminál

Připojte terminálová UI v prohlížeči k shellům sandboxu přes WebSocket. Serverová část terminal() metoda předává WebSocket připojení kontejneru a klientská SandboxAddon se integruje s xterm.js pro vykreslování terminálu.

Proxujte požadavek na WebSocket upgrade, čímž vytvoříte terminálové spojení.

const response = await sandbox.terminal(request: Request, options?: PtyOptions): Promise<Response>

Parametry:

• request - Požadavek na upgrade WebSocket z prohlížeče (musí obsahovat Upgrade: websocket hlavička)
• options (volitelné):
  • cols - Šířka terminálu ve sloupcích (výchozí: 80)
  • rows - Výška terminálu v řádcích (výchozí: 24)

Vrací: Promise<Response> : Odpověď na upgrade WebSocket

// In your Worker's fetch handler
return await sandbox.terminal(request, { cols: 120, rows: 30 });

// In your Worker's fetch handler
return await sandbox.terminal(request, { cols: 120, rows: 30 });

Funguje s oběma výchozí a explicitně vytvořené relace:

// Default session
return await sandbox.terminal(request);

// Specific session
const session = await sandbox.getSession("dev");
return await session.terminal(request);

// Default session
return await sandbox.terminal(request);

// Specific session
const session = await sandbox.getSession('dev');
return await session.terminal(request);

@cloudflare/sandbox/xterm modul poskytuje SandboxAddon pro xterm.js, který se stará o WebSocket připojení, opětovné připojení a předávání změny velikosti terminálu.

import { SandboxAddon } from '@cloudflare/sandbox/xterm';

const addon = new SandboxAddon(options: SandboxAddonOptions);

Možnosti:

• getWebSocketUrl(params) - Sestavte WebSocket URL pro každý pokus o připojení. Přijímá:
  • sandboxId - ID cílového sandboxu
  • sessionId (volitelné) - ID cílové relace
  • origin - Původ WebSocket odvozený z window.location (například wss://example.com)
• reconnect - Povolte automatické opětovné připojení s exponenciálním backoffem (výchozí: true)
• onStateChange(state, error?) - Callback pro změny stavu připojení

import { Terminal } from "@xterm/xterm";
import { SandboxAddon } from "@cloudflare/sandbox/xterm";

const terminal = new Terminal({ cursorBlink: true });
terminal.open(document.getElementById("terminal"));

const addon = new SandboxAddon({
	getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
		const params = new URLSearchParams({ id: sandboxId });
		if (sessionId) params.set("session", sessionId);
		return `${origin}/ws/terminal?${params}`;
	},
	onStateChange: (state, error) => {
		console.log(`Terminal ${state}`, error);
	},
});

terminal.loadAddon(addon);
addon.connect({ sandboxId: "my-sandbox" });

import { Terminal } from '@xterm/xterm';
import { SandboxAddon } from '@cloudflare/sandbox/xterm';

const terminal = new Terminal({ cursorBlink: true });
terminal.open(document.getElementById('terminal'));

const addon = new SandboxAddon({
  getWebSocketUrl: ({ sandboxId, sessionId, origin }) => {
    const params = new URLSearchParams({ id: sandboxId });
    if (sessionId) params.set('session', sessionId);
    return `${origin}/ws/terminal?${params}`;
  },
  onStateChange: (state, error) => {
    console.log(`Terminal ${state}`, error);
  }
});

terminal.loadAddon(addon);
addon.connect({ sandboxId: 'my-sandbox' });

Naváže spojení s terminálem sandboxu.

addon.connect(target: ConnectionTarget): void

Parametry:

• target:
  • sandboxId - Sandbox, ke kterému se má připojit
  • sessionId (volitelné) - Relace uvnitř sandboxu

Volání connect() s novým cílem se odpojí od aktuálního cíle a připojí se k novému. Zavolání se stejným cílem, pokud je spojení již navázáno, nemá žádný účinek.

Zavřete spojení a zastavte všechny pokusy o opětovné připojení.

addon.disconnect(): void

SandboxAddon obsluhuje protokol WebSocket automaticky. Tyto podrobnosti jsou určeny pro tvorbu vlastních terminálových klientů bez tohoto doplňku. Úplný příklad najdete v Připojte se bez xterm.js.

1. Klient otevře WebSocket na váš koncový bod Worker. Nastavte binaryType na arraybuffer.
2. Server přehraje veškerý bufferovaný výstup z předchozího připojení jako binární rámce. To může dorazit dříve než ready zprávy.
3. Server odešle ready stavová zpráva: terminál nyní přijímá vstup.
4. Binární rámce proudí oběma směry: od klienta přicházejí stisky kláves zakódované v UTF-8, od serveru výstup terminálu (včetně escape sekvencí ANSI).
5. Pokud se klient odpojí, PTY zůstává aktivní. Při opětovném připojení ke stejné relaci se přehraje zaznamenaný výstup, takže terminál vypadá nezměněně.

Terminál ovládejte odesíláním textových rámců JSON.

Změna velikosti : aktualizace rozměrů terminálu (obojí cols a rows musí být kladné):

{ "type": "resize", "cols": 120, "rows": 30 }

Server odesílá textové rámce JSON pro události životního cyklu.

Připraveno : PTY je inicializován. Bufferovaný výstup (pokud existuje) už byl odeslán:

{ "type": "ready" }

Ukončit : proces shellu byl ukončen:

{ "type": "exit", "code": 0, "signal": "SIGTERM" }

Chyba : došlo k chybě (například neplatná řídicí zpráva nebo nenalezená relace):

{ "type": "error", "message": "Session not found" }

interface PtyOptions {
	cols?: number;
	rows?: number;
}

type ConnectionState = "disconnected" | "connecting" | "connected";

interface ConnectionTarget {
	sandboxId: string;
	sessionId?: string;
}

interface SandboxAddonOptions {
	getWebSocketUrl: (params: {
		sandboxId: string;
		sessionId?: string;
		origin: string;
	}) => string;
	reconnect?: boolean;
	onStateChange?: (state: ConnectionState, error?: Error) => void;
}

• Terminálová připojení : Jak fungují terminálová připojení
• Terminály v prohlížeči : Návod k nastavení krok za krokem
• Sessions API : Správa relací
• Commands API : Neinteraktivní spouštění příkazů