← Sandbox SDK / sandbox / api

Sledování souborů

Sledujte změny v souborovém systému v reálném čase pomocí nativního systému inotify v Linuxu. Metoda watch() metoda vrací stream Server-Sent Events (SSE) s událostmi změn souborů, který zpracujete pomocí parseSSEStream().

Sledujte adresář a zaznamenávejte změny v souborovém systému. Vrací stream událostí SSE.

const stream = await sandbox.watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>

Parametry:

• path - Absolutní cesta nebo cesta relativní k /workspace (například /app/src nebo src)
• options (volitelné):
  • recursive - Rekurzivní sledování podadresářů (výchozí: true)
  • include - Vzory glob k zahrnutí (například ['*.ts', '*.js']). Nelze použít společně s exclude.
  • exclude - Vzory glob k vyloučení (výchozí: ['.git', 'node_modules', '.DS_Store']). Nelze použít společně s include.
  • sessionId - Relace, ve které se má spustit watch (pokud není uvedena, použije se výchozí relace, pokud enableDefaultSession je nastaven na false)

Vrací: Promise<ReadableStream<Uint8Array>> : stream SSE FileWatchSSEEvent objekty

import { parseSSEStream } from "@cloudflare/sandbox";

const stream = await sandbox.watch("/workspace/src", {
	recursive: true,
	include: ["*.ts", "*.js"],
});

const controller = new AbortController();

for await (const event of parseSSEStream(stream, controller.signal)) {
	switch (event.type) {
		case "watching":
			console.log(`Watch established on ${event.path} (id: ${event.watchId})`);
			break;
		case "event":
			console.log(`${event.eventType}: ${event.path}`);
			break;
		case "error":
			console.error(`Watch error: ${event.error}`);
			break;
		case "stopped":
			console.log(`Watch stopped: ${event.reason}`);
			break;
	}
}

// Cancel the watch by aborting — cleans up the watcher server-side
controller.abort();

import { parseSSEStream } from "@cloudflare/sandbox";
import type { FileWatchSSEEvent } from "@cloudflare/sandbox";

const stream = await sandbox.watch("/workspace/src", {
	recursive: true,
	include: ["*.ts", "*.js"],
});

const controller = new AbortController();

for await (const event of parseSSEStream<FileWatchSSEEvent>(
	stream,
	controller.signal,
)) {
	switch (event.type) {
		case "watching":
			console.log(`Watch established on ${event.path} (id: ${event.watchId})`);
			break;
		case "event":
			console.log(`${event.eventType}: ${event.path}`);
			break;
		case "error":
			console.error(`Watch error: ${event.error}`);
			break;
		case "stopped":
			console.log(`Watch stopped: ${event.reason}`);
			break;
	}
}

// Cancel the watch by aborting — cleans up the watcher server-side
controller.abort();

Union type reprezentující všechny události SSE vysílané streamem watch.

type FileWatchSSEEvent =
	| { type: "watching"; path: string; watchId: string }
	| {
			type: "event";
			eventType: FileWatchEventType;
			path: string;
			isDirectory: boolean;
			timestamp: string;
	  }
	| { type: "error"; error: string }
	| { type: "stopped"; reason: string };

• watching : Vyvoláno jednou při navázání sledování. Obsahuje watchId a path sledováno.
• event : Vyvoláno při každé změně v souborovém systému. Obsahuje eventType, path které se změnily, a zda isDirectory.
• error : Vyvoláno, když sledování narazí na chybu.
• stopped : Vyvoláno při zastavení sledování, s reason.

Typy změn v souborovém systému, které lze detekovat.

type FileWatchEventType =
	| "create"
	| "modify"
	| "delete"
	| "move_from"
	| "move_to"
	| "attrib";

• create : Byl vytvořen soubor nebo adresář
• modify : Změněn obsah souboru
• delete : Byl smazán soubor nebo adresář
• move_from : Soubor nebo adresář byl přesunut jinam (zdroj přejmenování nebo přesunu)
• move_to : Soubor nebo adresář byl přesunut sem (cíl přejmenování nebo přesunu)
• attrib : Změněny atributy souboru nebo adresáře (oprávnění, časová razítka)

Možnosti konfigurace pro sledování adresářů.

interface WatchOptions {
	/** Watch subdirectories recursively (default: true) */
	recursive?: boolean;
	/** Glob patterns to include. Cannot be used together with `exclude`. */
	include?: string[];
	/** Glob patterns to exclude. Cannot be used together with `include`. Default: ['.git', 'node_modules', '.DS_Store'] */
	exclude?: string[];
	/** Session to run the watch in. If omitted, the sandbox's implicit execution mode is used. */
	sessionId?: string;
}

Převede ReadableStream<Uint8Array> do typované AsyncGenerator událostí. Přijímá volitelný AbortSignal pro zrušení streamu.

function parseSSEStream<T>(
	stream: ReadableStream<Uint8Array>,
	signal?: AbortSignal,
): AsyncGenerator<T>;

Parametry:

• stream : Stream SSE vrácený watch()
• signal (volitelné): AbortSignal pro zrušení streamu. Po přerušení se zruší i reader, což vyvolá úklid na serveru.

Nejlepší způsob, jak sledování (watch) zastavit zvenčí zpracovávající smyčky, je přerušit signál:

const controller = new AbortController();

// Cancel after 60 seconds
setTimeout(() => controller.abort(), 60_000);

for await (const event of parseSSEStream<FileWatchSSEEvent>(
	stream,
	controller.signal,
)) {
	// process events
}

include a exclude volby přijímají omezenou sadu glob tokenů pro předvídatelné porovnávání:

Třídy znaků ([abc]), expanze složených závorek ({a,b}), a escapování zpětným lomítkem není podporováno. Vzory obsahující tyto tokeny jsou odmítnuty s validační chybou.

• Průvodce sledováním změn v souborovém systému : Vzory, osvědčené postupy a příklady z praxe
• Průvodce správou souborů : Operace se soubory