upload-platform/upload/README.md

Upload module (v0.2.0)

Переиспользуемый модуль загрузки, состоящий из двух независимых слоёв:

1. Слой 1 (upload/frontend/) — File Picker:

   • IIFE: FilePicker.initFilePicker(config);
   • ESM: import { initFilePicker } from './file-picker.esm.js' (или из upload/frontend/index.js).
   • Получение выбранных файлов: picker.getFiles() возвращает плоский массив { path, name, size, file }.
   • Поддерживает выбор файлов, папок, клиентскую распаковку ZIP (fflate) и проверку лимитов.

2. Слой 2 (upload/frontend/upload/ + upload/backend/) — Пофайловый транзит в RAM сессии:

   • Фронтенд: uploadViaVM(files, options) или FilePicker.uploadViaVM(files, options):
     • Пофайловый стриминг: для каждого файла выполняется PUT в буфер на ВМ, немедленный POST /api/upload_refs в бэкенд, и после подтверждения приёма буфер на ВМ очищается.
     • Поддержка AbortSignal для отмены загрузки на любом этапе.
   • Бэкенд: create_upload_refs_blueprint(cfg):
     • Приём ссылок через исходящий потоковый GET в память RAM.
     • SSRF-валидация префикса буфера (vmUploadPrefix).
     • Защита от path traversal (safe_name).
     • Хранилище сессий в оперативной памяти (upload/backend/session).
     • Никакой записи на диск.

Интеграция в сторонний проект

1. Скопировать каталог upload/ в проект.
2. Во Flask подключить Blueprint:

   from upload.backend.upload_refs import create_upload_refs_blueprint
   app.register_blueprint(create_upload_refs_blueprint({"vmUploadPrefix": "..."}))
   

3. На фронтенде подключить file-picker.iife.js или импортировать ESM.
4. Вызвать initFilePicker, а при отправке вызвать uploadViaVM(picker.getFiles(), options).