← Sandbox SDK / sandbox / api

Наблюдение за файлами

Отслеживайте изменения файловой системы в реальном времени с помощью встроенной в Linux системы inotify. watch() метод возвращает поток Server-Sent Events (SSE) с событиями изменения файлов, который вы обрабатываете с помощью parseSSEStream().

Отслеживает изменения в файловой системе директории. Возвращает поток событий SSE.

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

Параметры:

• path - Абсолютный путь или путь относительно /workspace (например, /app/src или src)
• options (необязательно):
  • recursive - Отслеживать подкаталоги рекурсивно (по умолчанию: true)
  • include - Glob-шаблоны для включения (например, ['*.ts', '*.js']). Нельзя использовать вместе с exclude.
  • exclude - Glob-шаблоны для исключения (по умолчанию: ['.git', 'node_modules', '.DS_Store']). Нельзя использовать вместе с include.
  • sessionId - Сессия, в которой запускается watch (если не указана, используется сессия по умолчанию, если только enableDefaultSession имеет значение false)

Возвращает: Promise<ReadableStream<Uint8Array>> : SSE-поток FileWatchSSEEvent объекты

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();

Объединённый тип всех событий SSE, которые отправляет поток 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 : генерируется один раз при установке наблюдения. Содержит watchId и path отслеживаемых.
• event : генерируется при каждом изменении в файловой системе. Содержит eventType, path которые изменились, и о том, isDirectory.
• error : генерируется, когда при наблюдении возникает ошибка.
• stopped : генерируется при остановке наблюдения, с reason.

Типы изменений файловой системы, которые можно обнаружить.

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

• create : файл или каталог создан
• modify : изменено содержимое файла
• delete : файл или каталог удалён
• move_from : файл или каталог перемещён (источник переименования или перемещения)
• move_to : файл или каталог перемещён сюда (назначение переименования или перемещения)
• attrib : изменены атрибуты файла или каталога (права доступа, временные метки)

Параметры конфигурации для отслеживания каталогов.

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;
}

Преобразует ReadableStream<Uint8Array> в типизированный AsyncGenerator событий. Принимает опциональный AbortSignal чтобы отменить поток.

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

Параметры:

• stream : SSE-поток, возвращаемый watch()
• signal (необязательно): AbortSignal чтобы отменить поток. При прерывании читатель отменяется, что распространяет очистку ресурсов на сервер.

Чтобы остановить watch извне потребляющего цикла, рекомендуется прервать сигнал:

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 и exclude опции принимают ограниченный набор glob-токенов для предсказуемого сопоставления:

Классы символов ([abc]), раскрытие фигурных скобок ({a,b}), а экранирование обратной косой чертой не поддерживается. Шаблоны, содержащие эти токены, отклоняются с ошибкой валидации.

• Руководство по отслеживанию изменений файловой системы : паттерны, лучшие практики и примеры из реальной практики
• Руководство по управлению файлами : операции с файлами