2026-09-06: Реализация и верификация Слоя 2 (пофайловый транзит через RAM)

1. Контекст задачи

В рамках репозитория upload-platform выполнена реализация Слоя 2 (транзитная доставка файлов в сессию бэкенда через внешний буфер) поверх завершённого Слоя 1 (File Picker v0.1.13) с поднятием версии платформы до 0.2.0.

2. Ключевые архитектурные решения и реализация

1. Пофайловый транзит (Per-File Transit)

Вместо накопления всей пачки файлов на ВМ реализован потоковый пофайловый цикл:

Браузер берёт файл k и отправляет его методом PUT в буфер на ВМ (putToVm через XHR со стримингом прогресса и поддержкой AbortSignal).
Браузер сразу делает POST /api/upload_refs только для этого одного файла k.
Бэкенд забирает файл исходящим потоковым GET (httpx.stream) прямо в оперативную память сессии (upload/backend/session).
Бэкенд немедленно отправляет DELETE на буфер ВМ.
Файл на ВМ удалён, буфер чист. Браузер переходит к файлу k+1.

Результат: в буфере на ВМ в любой момент времени находится максимум один файл; объем потребляемой буфером памяти минимален.

2. Хранение строго в оперативной памяти (RAM-only)

На бэкенде: файлы сессии хранятся в RAM-структуре _sessions (upload/backend/session/state.py). Никаких временных файлов на диске.
Защита памяти: настраиваемые лимиты MAX_FILE_BYTES (по умолчанию 50 МБ) и MAX_SESSION_BYTES (по умолчанию 500 МБ).
Автоматическая очистка: TTL-таймер (по умолчанию 30 мин), функции touch, pause_ttl, resume_ttl, cleanup.

3. Защита и параметры (Zero Hardcode & Security)

SSRF-защита: create_upload_refs_blueprint валидирует входящие URL по префиксу vmUploadPrefix (поддерживаются абсолютные URL для прода и относительные для локального мока). Запросы к сторонним хостам отсекаются.
Path Traversal защита: модуль safe_name нормализует пути, запрещает .. и сохраняет безопасные относительные подпапки.
Мягкая отмена: поддержка AbortSignal на фронтенде и threading.Event на бэкенде (request_cancel, get_cancel_event).
Слой 3 (эмуляция/интеграция): в create_upload_refs_blueprint добавлен колбэк onFileReceived(sid, name, content), вызываемый при успешной доставке файла в RAM.

4. Автономный mock-буфер и тестовый стенд

В site/app.py встроен in-memory mock WebDAV (PUT, GET, DELETE по пути /mock-buffer/<key>), хранящий данные в RAM.
Позволяет запускать тесты и локальный demo-стенд на 100% автономно без доступа к внешней сети или боевой ВМ.
В шаблоне site/templates/index.html добавлена панель запуска Слоя 2, отображение прогресса пофайловой передачи и просмотр файлов, сохранённых в RAM сессии.

3. Автоматическое тестирование

Создан полный набор автоматических тестов (19 тестов, 100% PASS):

Бэкенд тесты (pytest tests/ -v, 10 тестов, 0.99s):
- test_safe_name_simple — проверка корректных путей и слэшей.
- test_safe_name_traversal — отсечение атак .., абсолютных путей, пустых строк.
- test_session_lifecycle — полный жизненный цикл сессии (создание, добавление, чтение, TTL, отмена, cleanup).
- test_session_limits — проверка ограничения суммарного размера сессии в RAM.
- test_upload_refs_pull_and_delete — проверка pull по исходящему GET, удаления из буфера, вызова колбэка Слоя 3.
- test_upload_refs_ssrf_protection — блокировка попыток pull с недоверенных хостов (SSRF).
- test_health — liveness-проверка платформы.
- test_index_page — проверка отдачи UI стенда.
- test_mock_buffer_crud — операции PUT, GET, DELETE и статус mock-буфера.
- test_full_transit_flow_mock — сквозной тест пофайлового транзита от mock-буфера до сессии Flask.
Фронтенд тесты (npm test, node:test, 9 тестов, 329ms):
- putToVm: успешная отправка — проверка корректности HTTP PUT с сырым бинарным телом.
- putToVm: ошибка HTTP статуса — обработка ответов 4xx/5xx.
- putToVm: сетевая ошибка — обработка XHR onerror.
- putToVm: таймаут — обработка XHR ontimeout.
- putToVm: прерывание через AbortSignal — мгновенный abort текущего XHR.
- uploadViaVM: пофайловый транзит — проверка, что N файлов вызывают N парных запросов PUT + upload_refs последовательно, передавая session_id.
- uploadViaVM: поддержка формата FilePicker.getFiles() — совместимость со Слой 1.
- uploadViaVM: обработка ошибки PUT — остановка конвейера и возврат ошибки.
- uploadViaVM: прерывание через signal — отмена всего пофайлового цикла.

4. Версионирование и сборка

Версия поднята с 0.1.13 до 0.2.0 в package.json и site/app.py.
Собраны актуальные дистрибутивные бандлы dist/file-picker.esm.js (40.1 KB) и dist/file-picker.iife.js (43.4 KB).
Документация в README.md и upload/README.md полностью обновлена с пошаговой инструкцией интеграции в drhider и contractor.

7.2 KiB Raw Blame History Unescape Escape