Загрузка файлов
Отдельный путь исполнения
Браузер /upload
↕ WebSocket
Web-мост Altera
↕ Unix-сокет sessions
altera-sessions
↕ stdin/stdout
altera-cli /upload под UID/GID пользователя
↕
Каталог загрузок пользователя
Здесь altera-cli не подключается к Unix-входу основной службы Altera и не запускает модуль бекенда. Для загрузки требуется действующая Bearer-сессия после PAM-аутентификации; файл создаётся под UID/GID пользователя. Проверка Polkit появится позже, когда клиент обратится к backend с этим файлом как параметром.
Протокол
После подключения нужно дождаться:
{"type":"ready","directory":"/home/user/Загрузки/altera","max_chunk_size":1048576}
Начало:
{"action":"begin","name":"archive.tar","size":12345}
Сервер отвечает type:"started" и объектом file. После этого клиент передаёт содержимое бинарными WebSocket-сообщениями до 1 МиБ, получая type:"progress" после каждого.
Завершение:
{"action":"finish"}
Только type:"uploaded" подтверждает успешное завершение и совпадение полученного размера с заявленным.
Для управления файлами:
{"action":"list"}
{"action":"delete","id":"/home/user/Загрузки/altera/TOKEN/archive.tar"}
Ответы: files и deleted.
Один сокет обрабатывает один текущий файл. Следующий запрос или chunk отправляется только после ответа на предыдущий. Файл делится на отдельные WebSocket-сообщения; протокол не поддерживает фрагментированные upload-сообщения. JSON-команду chunk из браузера посылать не нужно: её создаёт веб-мост для приватного канала к CLI.
Ошибки и разрыв соединения
Ошибка команды приходит отдельным JSON-сообщением без обёртки пути:
{"type":"woo-error","code":"failed","message":"file is incomplete"}
Клиент должен различать ошибки по паре type + code; message предназначено для человека.
| Тип | Код | Причина |
|---|---|---|
type-error | invalid | Неверная структура или параметры команды |
woo-error | failed | Отказ обработчика загрузки: неверное имя или ID, нет начатой загрузки, файл не дописан либо порция превышает объявленный размер файла |
internal-error | failed | Непредвиденный сбой обработки команды, например ошибка файловой системы |
woo-error | busy | Клиент отправил команду или порцию, не дождавшись предыдущего ответа либо начального ready |
woo-error | invalid | Сообщение не содержит JSON-объект либо клиент отправил JSON-команду chunk вместо бинарной порции |
Ошибки команд передаются как обычные ответы и сами по себе не закрывают канал. Получив ошибку, клиент должен исправить запрос, а не считать операцию успешной. Загрузку подтверждает только ответ type:"uploaded" на finish.
Сбой соединения или обработчика может закрыть WebSocket без JSON-ответа. Превышение входного лимита сообщения 1 МиБ приводит к Close 1009, сбой службы — к 1011, отзыв или истечение сессии — к 1008. Общие правила аутентификации и закрытия описаны в клиентском протоколе.
После обрыва незавершённая загрузка удаляется при очистке обработчика. Если ответ на finish потерян, файл мог уже сохраниться: после нового подключения проверьте его через list, прежде чем загружать повторно. Эти ошибки относятся к маршруту /upload, который не обращается к модулям основной службы Altera.
Хранение
Файлы размещаются в пользовательских «Загрузках»:
<Downloads>/altera/<случайный каталог>/<имя файла>
Для определения каталога вызывается xdg-user-dir DOWNLOAD от имени пользователя. Есть fallback к существующему ~/Downloads либо ~/Загрузки. Метаданные .altera.json и признак .complete сохраняются рядом с файлом; индивидуальный файл создаётся с правами 0600.
file.id является абсолютным путём. Его можно передать backend, принимающему путь к файлу.
Одинаковые имена получают разные каталоги. Незавершённая загрузка очищается при нормальном завершении обработчика; после аварии остатки очищаются при следующем подключении этого пользователя. Активные параллельные загрузки различаются с помощью файловых блокировок.