Файлы и Git
Файловая система песочницы — общее рабочее пространство для браузерных изменений, команд, компонентов подготовки и Git. Для непосредственного просмотра используйте вкладку Файлы, для автоматизации — REST API файлов, а после клонирования запускайте обычные Git-команды.
Выбор интерфейса
| Задача | Интерфейс |
|---|---|
| Просмотреть директорию или файл | Вкладка Файлы или REST API файлов |
| Немного изменить текст или Markdown | Вкладка Файлы |
| Передать сгенерированные или бинарные данные | REST API файлов |
Выполнить git status, pull, commit или push | Терминал или /exec |
| Начать с готовой рабочей копии | repo при создании песочницы или сохраненный секрет типа repo |
| Хранить данные независимо от одной песочницы | Хранилище |
Файлы являются частью корневой файловой системы песочницы. Остановка и гибернация сохраняют эту файловую систему, удаление — нет. Хранилище аккаунта — отдельный сервис со своими правами доступа и жизненным циклом.
Работа через веб-интерфейс
Откройте активную песочницу и выберите Файлы. Дерево начинается с / и
раскрывает рабочую директорию шаблона. С помощью панели инструментов или перетаскивания в
директорию можно:
- загрузить один или несколько файлов;
- создать директорию;
- переименовать или переместить выбранный объект;
- рекурсивно удалить выбранную директорию или удалить файл;
- скачать выбранный файл;
- просмотреть изображения и Markdown, изучить код и отредактировать текстовые файлы.
Окно просмотра проверяет изменения на диске в фоне, но сохраняет показанную копию до нажатия Перезагрузить. Сохранение правки перезаписывает целевой файл. Бинарные файлы передаются как base64 и не открываются в текстовом редакторе.
Она показывает файловую систему песочницы, а не только директорию проекта. Права
доступа Unix продолжают действовать. Не меняйте системные файлы без явной
необходимости и не выводите файлы с учетными данными, например ~/.gitconfig.
Автоматизация файловых операций
Всем эндпоинтам нужен ID песочницы и bearer-токен. Путь может быть абсолютным,
относительным к домашней директории (~/) настроенного пользователя по умолчанию или относительным к рабочей
директории по умолчанию.
| Операция | Запрос |
|---|---|
| Прочитать файл | GET /v1/sandboxes/{id}/files?path=... |
| Записать или заменить файл | POST /v1/sandboxes/{id}/files |
| Загрузить multipart-файлы в директорию | POST /v1/sandboxes/{id}/files/upload?path=... |
| Скачать сырые байты | GET /v1/sandboxes/{id}/files/download?path=... |
| Получить содержимое директории | GET /v1/sandboxes/{id}/files/list?path=...&depth=... |
| Получить свойства одного объекта | GET /v1/sandboxes/{id}/files/stat?path=... |
| Создать директории | POST /v1/sandboxes/{id}/files/mkdir |
| Переместить или переименовать | POST /v1/sandboxes/{id}/files/move |
| Удалить файл или дерево директорий | DELETE /v1/sandboxes/{id}/files?path=... |
Запишите текстовый файл и прочитайте его:
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"path": "~/workspace/config.json",
"content": "{\"mode\":\"development\"}\n",
"overwrite": true
}'
curl --fail-with-body --silent --show-error \
--get "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/files" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--data-urlencode "path=~/workspace/config.json" |
jq
Ответ чтения содержит encoding: "utf-8" для текста и
encoding: "base64" для распознанного бинарного содержимого. При записи
бинарных данных передайте base64-строку и укажите "encoding": "base64".
Новые файлы создаются с правами 0644, а недостающие родительские директории —
автоматически. Укажите overwrite: false, если замена существующего файла
должна завершаться ошибкой. Запись идет во временный соседний файл, который
переименовывается после получения всего содержимого запроса; сервис не пишет через символическую ссылку
и не заменяет ее.
Лимит тела HTTP-запроса настраивается в инсталляции и по умолчанию равен
20 МиБ. Внутренний файловый сервис может задавать дополнительный лимит загрузки.
Превышение любого из них — 413 request.payload_too_large, и это означает, что
не записано ничего: незавершенная загрузка отменяется, прежнее содержимое файла
остается нетронутым. Для больших долговечных артефактов используйте хранилище, а не
файловую систему песочницы как объектное хранилище.
Клонирование репозитория при создании
Собственный API создания принимает один высокоуровневый объект repo:
{
"template": "base",
"repo": {
"url": "https://github.com/acme/service.git",
"ref": "main",
"path": "~/service",
"depth": 1,
"required": true
},
"wait_until_ready": true
}
url должен использовать https:// или ssh://. Необязательный путь назначения
начинается с ~/, не может содержать .. и по умолчанию равен
~/<repository-name>. ref превращается в git clone --branch, а depth
включает клонирование с неполной историей.
Клонирование — шаг подготовки, а не часть загрузки VM. Песочница уже может
показывать running, пока provisioning.status остается in_progress.
wait_until_ready: true заставляет запрос создания ждать завершения подготовки;
иначе опрашивайте песочницу до ready или failed.
По умолчанию клонирование считается обязательным. Его ошибка переводит песочницу в
failed; у подготовки V1 нет действия повтора, поэтому исправьте причину и
создайте песочницу заново. При required: false шаг клонирования может завершиться
ошибкой, а песочница останется доступной.
Аутентификация приватных репозиториев
Не добавляйте токен в URL репозитория. Создайте секрет типа git_credential для
HTTPS или секрет типа ssh_key для SSH URL, затем выберите секрет при создании
песочницы. Сохраненный секрет типа repo может ссылаться по имени на соответствующий
секрет git_credential.
Учетные данные HTTPS материализуются в помощник учетных данных Git, доступный только
владельцу, внутри ~/.gitconfig пользователя по умолчанию. SSH-ключи помещаются
в ~/.ssh этого пользователя.
Клонирование запускается неинтерактивно от того же пользователя, поэтому отсутствующие
учетные данные или неверный доступ приводят к ошибке, а не к зависшему запросу ввода.
После подготовки используется Git из выбранного шаблона:
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"cmd": "git",
"args": ["-C", "/home/user/service", "status", "--short"]
}' |
jq '{exit_code, stdout, stderr}'
Отдельного REST API для команд git status, pull, commit или push нет. Используйте
Терминал, если Git нужен интерактивный ввод, и /exec для детерминированной
автоматизации. Считайте push внешним побочным эффектом и выдавайте учетным данным
репозитория только необходимые права на рабочие процессы.
Границы ошибок
- Файловым операциям нужна активная среда выполнения. Сначала возобновите или разбудите песочницу.
- Ответы чтения буферизуют целый файл. Для крупных файлов используйте скачивание сырых байтов или хранилище.
- Удаление директории рекурсивно, а публичного API для отмены нет.
- Путь клонирования принадлежит пользователю по умолчанию. Git, запущенный от другого Unix-пользователя, может не увидеть те же учетные данные в домашней директории или из-за владельца файлов.
- Остановка сохраняет рабочее дерево, но завершает процессы Git; гибернация сохраняет память, однако удаленные сетевые соединения нужно устанавливать заново.
- Не выводите значения секретов, помощников учетных данных, приватных ключей или URL удаленных репозиториев с аутентификацией в логи и пакеты данных для поддержки.