70 lines
7.2 KiB
Markdown
70 lines
7.2 KiB
Markdown
# 2026-09-06: Реализация и верификация Слоя 2 (пофайловый транзит через RAM)
|
||
|
||
## 1. Контекст задачи
|
||
В рамках репозитория `upload-platform` выполнена реализация Слоя 2 (транзитная доставка файлов в сессию бэкенда через внешний буфер) поверх завершённого Слоя 1 (File Picker v0.1.13) с поднятием версии платформы до `0.2.0`.
|
||
|
||
---
|
||
|
||
## 2. Ключевые архитектурные решения и реализация
|
||
|
||
### 1. Пофайловый транзит (Per-File Transit)
|
||
Вместо накопления всей пачки файлов на ВМ реализован потоковый пофайловый цикл:
|
||
1. Браузер берёт файл $k$ и отправляет его методом `PUT` в буфер на ВМ (`putToVm` через XHR со стримингом прогресса и поддержкой `AbortSignal`).
|
||
2. Браузер сразу делает `POST /api/upload_refs` только для этого одного файла $k$.
|
||
3. Бэкенд забирает файл исходящим потоковым `GET` (`httpx.stream`) прямо в оперативную память сессии (`upload/backend/session`).
|
||
4. Бэкенд немедленно отправляет `DELETE` на буфер ВМ.
|
||
5. Файл на ВМ удалён, буфер чист. Браузер переходит к файлу $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):
|
||
|
||
1. **Бэкенд тесты (`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.
|
||
|
||
2. **Фронтенд тесты (`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`.
|