Загрузка файлов

Отдельный путь исполнения

Браузер /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-errorinvalidНеверная структура или параметры команды
woo-errorfailedОтказ обработчика загрузки: неверное имя или ID, нет начатой загрузки, файл не дописан либо порция превышает объявленный размер файла
internal-errorfailedНепредвиденный сбой обработки команды, например ошибка файловой системы
woo-errorbusyКлиент отправил команду или порцию, не дождавшись предыдущего ответа либо начального ready
woo-errorinvalidСообщение не содержит 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, принимающему путь к файлу.

Одинаковые имена получают разные каталоги. Незавершённая загрузка очищается при нормальном завершении обработчика; после аварии остатки очищаются при следующем подключении этого пользователя. Активные параллельные загрузки различаются с помощью файловых блокировок.

Источники