Передача файлов через HTTP¶
Требования применяются к upload и download файлов между browser-клиентом и
HTTP API. Хранение объекта платформой не заменяет прикладной контракт передачи.
Уровни обязательности определены в корневом README.md.
INT-FILE-001. Опубликованный контракт передачи¶
Уровень: MUST
Применяется к: каждому HTTP endpoint upload или download
Машинно-проверяемый контракт должен определять media types, максимальный общий размер, обязательные metadata, допустимость пустого файла, синхронный или асинхронный результат, статусы отказа и срок жизни незавершённой передачи. Filename, checksum и размер должны иметь точную семантику; отсутствующее значение должно отличаться от пустого или фиктивного.
Контракт должен указывать, когда объект становится доступен потребителю и какой идентификатор однозначно связывает upload, итоговый объект и повтор запроса.
Обоснование¶
Обычное HTTP-тело не определяет lifecycle крупного объекта, момент готовности и результат частичной передачи.
Проверка¶
- schema и contract-тест metadata и статусов;
- граничный тест пустого, максимального и превышающего размер файла;
- тест синхронного и асинхронного результата.
Исключения¶
Внутренний неизменяемый fixture, не принимаемый от пользователя или другого компонента, находится вне области требования.
INT-FILE-002. Недоверенный upload¶
Уровень: MUST
Применяется к: приёму файла от browser или внешнего клиента
Сервер должен ограничивать размер во время чтения и не должен использовать полученные filename, path или media type как доверенные. Внутренний storage key не должен позволять path traversal или исполнение загруженного содержимого. Контракт должен содержать закрытый перечень разрешённых типов и проверок содержимого. Эти проверки должны выполняться до отображения, разбора или исполнения файла. Если содержимое намеренно остаётся opaque, оно должно храниться и выдаваться как неисполняемый тип без доверия к client media type.
Проект должен определить необходимость malware scan или иной quarantine по классу данных и способу последующего использования. Объект, требующий проверки, не должен становиться доступным до положительного результата. Timeout, отмена, ошибка проверки и превышение лимита должны удалять либо изолировать частичные bytes с конечным сроком.
Обоснование¶
Client metadata контролируется отправителем, а частичный или исполняемый upload способен исчерпать storage либо выполнить недоверенное содержимое.
Проверка¶
- security-тест path, filename, media type и исполняемого содержимого;
- потоковый тест превышения лимита до полной загрузки;
- тест quarantine, отрицательного scan, timeout и очистки partial upload.
Исключения¶
Закрытый межсервисный producer MAY не выполнять malware scan, если contract фиксирует trusted source и получатель не публикует или исполняет содержимое; предел размера и перечисленные контрактом проверки содержимого остаются обязательными.
INT-FILE-003. Идемпотентный и возобновляемый upload¶
Уровень: MUST
Применяется к: upload, допускающему retry, chunks или resume
Upload session и итоговый объект должны иметь стабильные идентификаторы. Повтор одного chunk или finalization не должен дублировать bytes или создавать второй объект. Offset, размер и checksum chunk должны проверяться до изменения подтверждённого состояния; конфликтующие параллельные записи должны сериализоваться либо отклоняться.
Session должна иметь конечный срок и различимые состояния active, completed, aborted и expired. Возобновление после неопределённого результата должно сначала получать подтверждённый offset или состав chunks, а не предполагать успех последней отправки.
Обоснование¶
Разрыв после сохранения chunk оставляет клиенту неизвестный результат, а непроверенный offset повреждает итоговую последовательность bytes.
Проверка¶
- тест повтора chunk и finalization;
- тест разрыва до и после сохранения chunk;
- конкурентный тест offset и checksum;
- тест expiry и очистки незавершённой session.
Исключения¶
Одноразовый upload, который после отказа всегда начинается заново с новым идентификатором и удаляет partial bytes, не обязан поддерживать resume.
INT-FILE-004. Авторизованный и воспроизводимый download¶
Уровень: MUST
Применяется к: выдаче файла или временной ссылки на него
Авторизация должна проверяться для фактического объекта при создании и использовании download-возможности. Временная signed URL должна быть ограничена одним объектом и действием, иметь конечный срок и не попадать в telemetry или публичный cache. Изменение прав должно иметь определённый способ прекратить доступ: проверку на каждый запрос, отзыв либо ограниченный максимальный срок URL.
Ответ должен задавать проверенные Content-Type и размер, а также
Content-Disposition с выбранным режимом inline или attachment и filename,
закодированным без возможности создать дополнительное header field. Если
поддерживаются byte ranges, validator должен фиксировать одну версию объекта.
Диапазон внутри размера объекта, диапазон вне его размера и запрос с validator
другой версии должны давать различимые результаты без смешения bytes разных
версий.
Обоснование¶
Знание URL не подтверждает право доступа, а range от изменившегося объекта создаёт повреждённый файл.
Проверка¶
- негативный download и signed URL другого объекта или субъекта;
- тест истечения, отзыва и утечки URL в telemetry/cache;
- тест filename и response headers;
- тест полного download, диапазона внутри и вне размера, а также validator другой версии.
Исключения¶
Публичный неизменяемый объект MAY не проверять субъекта, если его публичность и срок хранения явно определены.