← Artifacts / artifacts / examples

Sandbox SDK + Artifacts

В этом примере используется git-repo-per-sandbox шаблон Sandbox SDK и выделяет фрагменты, специфичные для Artifacts.

Начните с шаблона с помощью create cloudflare, как показано в Запуск Claude Code в песочнице. Затем адаптируйте процесс работы с Artifacts с помощью приведённых ниже фрагментов кода.

Создаёт песочницу или использует существующую по ID.
Создаёт репозиторий Artifacts или использует существующий с тем же ID.
Передаёт аутентифицированный удалённый репозиторий Git в песочницу как ARTIFACTS_GIT_REMOTE.

Создайте свой проект

npm create cloudflare@latest -- repo-per-sandbox --template=cloudflare/sandbox-sdk/examples/git-repo-per-sandbox

cd repo-per-sandbox

1. Создайте репозиторий или используйте существующий

Шаблон хранит один репозиторий Artifacts на каждый sandbox ID. Используйте собственный источник достоверных данных, чтобы определить, нужно ли создать новый репозиторий или загрузить уже существующий.

src/index.js

let defaultBranch;
let remote;
let token;
const sandboxWasJustCreated = true; // for example, set this when you create a new sandbox record

if (sandboxWasJustCreated) {
	const created = await env.ARTIFACTS.create(sandboxId);

	defaultBranch = created.defaultBranch;
	remote = created.remote;
	token = created.token;
} else {
	const repo = await env.ARTIFACTS.get(sandboxId);

	defaultBranch = repo.defaultBranch;
	remote = repo.remote;
	token = (await repo.createToken("write", 3600)).plaintext;
}

src/index.ts

let defaultBranch: string;
let remote: string;
let token: string;
const sandboxWasJustCreated = true; // for example, set this when you create a new sandbox record

if (sandboxWasJustCreated) {
	const created = await env.ARTIFACTS.create(sandboxId);

	defaultBranch = created.defaultBranch;
	remote = created.remote;
	token = created.token;
} else {
	const repo = await env.ARTIFACTS.get(sandboxId);

	defaultBranch = repo.defaultBranch;
	remote = repo.remote;
	token = (await repo.createToken("write", 3600)).plaintext;
}

Шаблон уже знает имя репозитория, поэтому начните с прямого поиска, а не со сканирования list() страниц. Избегайте широких catch блоков здесь. Они могут скрывать ошибки отсутствующего репозитория, аутентификации и валидации за одним и тем же сообщением о повторной попытке.

Если в вашем процессе возможна гонка с созданием репозитория, обрабатывайте повтор на уровне приложения после анализа возникшей ошибки.

2. Создайте песочницу или используйте существующую

Используйте тот же ID для sandbox:

src/index.js

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

const sandbox = getSandbox(env.Sandbox, sandboxId);

src/index.ts

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

const sandbox = getSandbox(env.Sandbox, sandboxId);

3. Передайте репозиторий в песочницу

Преобразуйте токен на запись в аутентифицированный удалённый репозиторий Git, а затем сохраните его как переменную окружения внутри песочницы.

Используйте недолговечный токен и передавайте его в sandbox только после того, как сессия sandbox авторизована для push изменений.

src/index.js

function toAuthenticatedRemote(remote, token) {
	const tokenSecret = token.split("?expires=")[0];
	return `https://x:${tokenSecret}@${remote.slice("https://".length)}`;
}

await sandbox.setEnvVars({
	ARTIFACTS_GIT_REMOTE: toAuthenticatedRemote(remote, token),
});

src/index.ts

function toAuthenticatedRemote(remote: string, token: string) {
	const tokenSecret = token.split("?expires=")[0];
	return `https://x:${tokenSecret}@${remote.slice("https://".length)}`;
}

await sandbox.setEnvVars({
	ARTIFACTS_GIT_REMOTE: toAuthenticatedRemote(remote, token),
});

Код, выполняющийся внутри песочницы, затем может использовать ARTIFACTS_GIT_REMOTE с git clone, git fetch, git pull, или git push.