146 lines
13 KiB
Markdown
146 lines
13 KiB
Markdown
# РЕЗЮМЕ И ТЕХНИЧЕСКОЕ ЗАДАНИЕ: СЛОЙ 2 (ЗАГРУЗКА ЧЕРЕЗ ВМ-БУФЕР)
|
||
|
||
Документ составлен 2026-09-06 для старта нового рабочего контекста в репозитории [upload-platform](upload-platform).
|
||
|
||
---
|
||
|
||
## 1. ЦЕЛЬ И АРХИТЕКТУРНЫЕ ГРАНИЦЫ
|
||
|
||
В репозитории [upload-platform](upload-platform) разрабатывается и изолированно тестируется переиспользуемый встраиваемый модуль, состоящий из двух независимых слоёв:
|
||
|
||
1. **Слой 1 (Выбор файлов / File Picker)** — **ГОТОВ И ПРОТЕСТИРОВАН (v0.1.13)**:
|
||
- Фронтенд-модуль на Vanilla JS + `fflate`.
|
||
- Поддерживает выбор отдельных файлов, выбор папок (`webkitdirectory`), распаковку ZIP и вложенных архивов.
|
||
- Дедупликация, фильтрация по расширениям, древовидный UI, лимиты (`maxEntries`, `maxEntryBytes`, `maxTotalBytes`, `maxDepth`).
|
||
- Возвращает чистый плоский массив выбранных объектов `File` через метод `picker.getFiles()`. Не зависит от способа передачи данных.
|
||
|
||
2. **Слой 2 (Транзитная загрузка файлов через ВМ-буфер)** — **ТЕКУЩАЯ ЗАДАЧА**:
|
||
- Задача слоя: доставить файлы из браузера в память сессии бэкенд-приложения (Flask).
|
||
- **Почему нужен буфер**: шлюз ingress managed-кластера Kubernetes (`pythonk8s`) обрывает входящие HTTP-запросы с телом более 64 КБ. Прямой `POST /upload` больших файлов в кластер невозможен. При этом исходящий трафик (egress) из кластера не ограничен.
|
||
- **Решение**: Браузер загружает файлы во внешний буфер на ВМ, а бэкенд вытягивает их исходящими `GET`-запросами (pull) в оперативную память своей сессии.
|
||
- **Потребители модуля**: сервис анонимизации `drhider` и сервис сверки договоров (`contractor`). Оба сервиса встраивают Слой 1 + Слой 2 как подпапку `upload/` без изменения исходного кода модулей (только собственный конфиг) и поверх накладывают свою бизнес-логику (Слой 3: LLM, обфускация, парсинг, diff).
|
||
|
||
---
|
||
|
||
## 2. ФАКТИЧЕСКОЕ СОСТОЯНИЕ ИНФРАСТРУКТУРЫ (ПРОВЕРЕНО НА ВМ И В K8S)
|
||
|
||
Проверено 2026-09-06 прямыми командами на ВМ и в кластере:
|
||
|
||
1. **ВМ `5.172.178.213` (contracts.kube5s.ru)**:
|
||
- Доступ: `ssh -i ~/.ssh/naeel_vm_id_ed25519 naeel@5.172.178.213`.
|
||
- В `nginx` настроены WebDAV-буферы:
|
||
- `/drhider-upload/` $\rightarrow$ `alias /var/www/drhider-upload/;`, CORS: `https://drhider.pythonk8s.dev.nubes.ru`.
|
||
- `/contracts-upload/` $\rightarrow$ `alias /var/www/contracts-upload/;`, CORS: `https://contractor.pythonk8s.dev.nubes.ru`.
|
||
- **Проблема текущей реализации на ВМ**:
|
||
- Nginx WebDAV пишет файлы на диск (корневой раздел).
|
||
- Cron каждые 5 минут удаляет файлы старше 30 минут: `find /var/www/drhider-upload -type f -mmin +30 -delete`.
|
||
- По требованию безопасности файлы не должны оседать на диске — обработка и буферизация должны быть строго в оперативной памяти (RAM).
|
||
|
||
2. **Kubernetes-кластер (`iot-naeel`)**:
|
||
- Под `drhider`: namespace `20a75175-a58c-49cb-b8fa-e86367b1a8dc`, хост `drhider.pythonk8s.dev.nubes.ru`.
|
||
- Под `contractor`: namespace `b4523aba-b5e6-40f1-be56-bb4d2509357c`, хост `contractor.pythonk8s.dev.nubes.ru`.
|
||
- Под `uploader-dev` (полигон): namespace `0e108526-5bb2-4757-9499-3f0bac4f0e83`, хост `uploader-dev.pythonk8s.dev.nubes.ru` (на нём крутится `upload-platform` 0.1.13).
|
||
|
||
---
|
||
|
||
## 3. ПРИНЦИПИАЛЬНЫЕ АРХИТЕКТУРНЫЕ ИЗМЕНЕНИЯ СЛОЯ 2
|
||
|
||
### Изменение 1: Пофайловый транзит (Streaming / Per-File Transit) вместо батча
|
||
- **Как было раньше**: Браузер в цикле заливал все файлы пачки в буфер на ВМ, и только в самом конце отправлял во Flask один общий запрос `/api/upload_refs` со списком всех ссылок. Буфер был вынужден одновременно хранить все файлы пачки (до сотен мегабайт).
|
||
- **Как должно быть**:
|
||
1. Браузер берет **один файл** $\rightarrow$ делает `PUT` в буфер на ВМ.
|
||
2. Браузер сразу делает `POST /api/upload_refs` для **этого одного файла**.
|
||
3. Flask вытягивает его исходящим потоковым `GET` прямо в память сессии (`site/session.py`) и сразу отправляет `DELETE` на ВМ.
|
||
4. Файл на ВМ удален. Браузер переходит к следующему файлу.
|
||
- **Результат**: В буфере на ВМ в любой момент времени находится максимум один файл. Общий объем памяти буфера минимален.
|
||
|
||
### Изменение 2: Хранение строго в памяти (RAM)
|
||
- Никаких временных файлов на диске.
|
||
- На бэкенде Flask файлы хранятся в RAM-структуре сессии (`upload/backend/session/state.py`).
|
||
- На ВМ для буфера не должен использоваться сброс на диск (на стороне Nginx требуется проксирование в память или легковесный in-memory микросервис).
|
||
|
||
### Изменение 3: Полная параметризация (Zero Hardcode)
|
||
- Прямой IP из браузера поверх HTTPS невозможен (Mixed Content, отсутствие доверенного TLS-сертификата).
|
||
- В коде не должно быть зашитых хостов (`contracts.kube5s.ru` и т.д.).
|
||
- Все адреса передаются через конфигурацию:
|
||
- Фронтенд: `vmUploadUrl` (например, `https://contracts.kube5s.ru/drhider-upload/` или локальный URL).
|
||
- Бэкенд: `vmUploadPrefix` (для обязательной SSRF-валидации входящих URL перед pull).
|
||
|
||
### Изменение 4: Автономный mock-буфер для тестов в `upload-platform`
|
||
- Тесты в [upload-platform](upload-platform) не должны зависеть от внешней сети или чужих боевых ВМ.
|
||
- В тестовый стенд и dev-сервер [site/app.py](upload-platform/site/app.py) встраивается локальный легковесный in-memory mock WebDAV (обработка `PUT`, `GET`, `DELETE`), что позволяет гонять Playwright- и Python-тесты полностью оффлайн.
|
||
|
||
---
|
||
|
||
## 4. СТРУКТУРА МОДУЛЯ В `upload-platform`
|
||
|
||
```
|
||
upload-platform/
|
||
├── upload/
|
||
│ ├── frontend/
|
||
│ │ ├── index.js # Точка входа Слоя 1 (initFilePicker)
|
||
│ │ ├── table/ # Логика и UI Слоя 1
|
||
│ │ ├── zip/ # Распаковка архивов (fflate)
|
||
│ │ └── upload/ # СЛОЙ 2 (ФРОНТЕНД):
|
||
│ │ ├── put_to_vm.js # XHR PUT одного файла на буфер с прогрессом и abort
|
||
│ │ └── upload_via_vm.js # Пофайловый транзит (PUT -> upload_refs -> repeat)
|
||
│ └── backend/ # СЛОЙ 2 (БЭКЕНД):
|
||
│ ├── __init__.py
|
||
│ ├── upload_refs/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── blueprint.py # Flask Blueprint (POST /api/upload_refs)
|
||
│ │ ├── pull_file.py # Исходящий потоковый GET с ретраями (httpx)
|
||
│ │ ├── safe_name.py # Санитизация имен (защита от path traversal)
|
||
│ │ └── config.py # Дефолтные параметры (retries, delay)
|
||
│ └── session/
|
||
│ ├── __init__.py
|
||
│ ├── state.py # In-memory хранилище сессий (_sessions, lock, TTL)
|
||
│ ├── create_session.py # Создание сессии (UUID)
|
||
│ ├── add_file.py # Добавление файла с проверкой лимита памяти
|
||
│ ├── get_files.py # Получение списка файлов
|
||
│ ├── store_result.py # Сохранение ZIP-результата
|
||
│ ├── store_csv.py # Сохранение CSV-результата
|
||
│ ├── ttl.py # touch, pause_ttl, resume_ttl
|
||
│ ├── cancel.py # Мягкая отмена сессии (Event)
|
||
│ └── cleanup.py # Очистка сессии
|
||
├── site/
|
||
│ ├── app.py # Flask demo (Слой 1 + Слой 2 + local mock buffer)
|
||
│ └── templates/index.html # Demo UI со сквозным сценарием выбора и загрузки
|
||
├── tests/ # Тесты Слоя 2 (pytest + browser smoke)
|
||
├── build.mjs # Сборка бандлов (ESM / IIFE)
|
||
├── package.json # Версионирование платформы
|
||
└── requirements.txt # Зависимости Python (Flask, httpx, pytest)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. ПОШАГОВЫЙ ПЛАН РЕАЛИЗАЦИИ В НОВОМ ЧАТЕ
|
||
|
||
1. **Шаг 1. Перенос и адаптация бэкенда Слоя 2**:
|
||
- Перенести `backend/session/` и `backend/upload_refs/` из [upload/backend](upload/backend) в [upload-platform/upload/backend](upload-platform/upload/backend).
|
||
- В `upload-platform/requirements.txt` зафиксировать `httpx>=0.27.0`.
|
||
- Проверить чистоту импортов и типизацию.
|
||
|
||
2. **Шаг 2. Перенос и адаптация фронтенда Слоя 2 на пофайловый транзит**:
|
||
- Создать [upload-platform/upload/frontend/upload/put_to_vm.js](upload-platform/upload/frontend/upload/put_to_vm.js) (XHR PUT с прогрессом и возможностью `abort`).
|
||
- Создать [upload-platform/upload/frontend/upload/upload_via_vm.js](upload-platform/upload/frontend/upload/upload_via_vm.js) с реализацией **пофайловой передачи**:
|
||
- цикл по файлам;
|
||
- загрузка файла $k$ на буфер;
|
||
- немедленный вызов `/api/upload_refs` для файла $k$;
|
||
- обновление прогресса в UI;
|
||
- переход к файлу $k+1$.
|
||
|
||
3. **Шаг 3. Локальный mock-буфер и интеграция в `site/app.py`**:
|
||
- Встроить в [upload-platform/site/app.py](upload-platform/site/app.py) тестовый Blueprint mock-буфера (`PUT`, `GET`, `DELETE` в оперативной памяти).
|
||
- Подключить `create_upload_refs_blueprint` к приложению.
|
||
- Обновить [upload-platform/site/templates/index.html](upload-platform/site/templates/index.html), добавив кнопку «Загрузить» и отображение прогресса пофайловой передачи.
|
||
|
||
4. **Шаг 4. Написание автоматических тестов**:
|
||
- Python unit-тесты (`pytest`): `safe_name`, `session` (TTL, лимиты, add/get), `upload_refs` (SSRF-блокировка, pull с mock-буфера, удаление после pull).
|
||
- Playwright browser-тесты: сквозной сценарий от выбора файлов в `initFilePicker` до их успешного появления в сессии Flask.
|
||
|
||
5. **Шаг 5. Сборка, bump версии и документация**:
|
||
- Обновить `build.mjs` и `package.json` (bump версии).
|
||
- Написать подробный [upload-platform/README.md](upload-platform/README.md) с инструкцией для агентов, как встроить оба слоя в сторонний сервис за 2 минуты.
|
||
- Фиксация коммитом и пуш.
|