Files
SHiNE-server/R2_MVP_PATCH_README.md
T
AidarKC 2f5736e67d WIP: добавить MVP загрузки вложений в Cloudflare R2
Работа ещё не готова: предпросмотр публичных R2-вложений в UI пока не завершён.
2026-11-15 00:48:41 +03:00

65 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SHiNE — патч R2 для публичных вложений (14.11.2026)
**База:** `SHiNE-bundle-2026.11.14-13.22.24.zip`. Это overlay-патч: распаковать **поверх точно этой версии** репозитория, сохраняя пути. Не раскатывать без проверки на тестовом сервере.
## Что изменено
- `S:att;v=1` поддерживает `pr` (BitTorrent v2 pieces root, base64url) и необязательное `mm` (MIME); `ar` сохраняется. Старый `sha256` остаётся читаемым.
- SHA-256 у аватаров и существующий `/files/<sha256>` не меняются.
- Новый `file-preparation-service.js` вычисляет `pr` через существующий аккумулятор порциями 1 МиБ; по окончательному файлу.
- Новый `POST /api/files/prepare` принимает `{pr,size,mm}`, проверяет Ed25519 подпись существующей сессии, возвращает `uploadUrl` / `requiredHeaders` или `exists=true`.
- Клиент напрямую делает один PUT в Cloudflare R2 (без проксирования байтов Java), максимальный размер 500 МиБ, без Multipart.
- Для публичных вложений нет встроенного медиа-превью — только файловые карточки и прямые URL; в DM просмотрщик не меняется.
- Для новых Arweave-вложений считаем `pr` и сохраняем `mm`, но аватары и транзакции прошлых версий остаются на SHA-256.
## Конфигурация Java-сервера
В защищённом окружении процесса Java задать:
```
R2_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=<secret>
R2_SECRET_ACCESS_KEY=<secret>
```
И `r2.publicBucket=shine-files` в обычной конфигурации. Убедиться, что используется endpoint юрисдикции, соответствующей bucket. Значения в Git НЕ добавлять.
Cloudflare CORS bucket `shine-files` должен позволять `PUT`, `GET`, `HEAD` с origins SHiNE и с заголовками **Content-Type, If-None-Match** (можно `AllowedHeaders: ["*"]`). Для тестового UI-домена добавить соответствующий origin в Cloudflare CORS; Java API в патче разрешает `https://test.shineup.me` наряду с основным доменом. Custom Domain: `https://files.shineup.me`.
## Запрос подписанного разрешения
```
POST /api/files/prepare
Content-Type: application/json
X-Shine-Session-Id: <sessionId>
X-Shine-Time-Ms: <epoch-ms>
X-Shine-Signature: <Ed25519 signature>
{"pr":"<43-char-base64url>","size":12345,"mm":"video/mp4"}
```
Подпись по UTF-8 строке:
```
PUBLIC_R2_PREPARE_V1:<sessionId>:<pr>:<size>:<mm>:<epoch-ms>
```
От сервера клиент получает `requiredHeaders`: передать **ровно эти заголовки** при PUT в `uploadUrl`. `If-None-Match: *` запрещает перезапись. Ключи API никогда не отправляются клиенту.
## Тесты
```
node scripts/tests/test-r2-file-preparation.mjs
python3 scripts/check_docs.py
./gradlew compileJava test
```
В среде подготовки патча проверки JavaScript и документации прошли. **Java-сборку нельзя было завершить**: Gradle Wrapper хотел скачать Gradle 8.14 с `services.gradle.org`, но сеть контейнера недоступна. Выполнить Gradle-сборку и сквозной тест реального R2 **до production deploy**. Реальный R2 не тестировался.
## Риски, которые остаются в MVP
- Клиент задаёт `pr`; сервер не пересчитывает хеш содержимого. Возможна первоначальная подмена объекта под заявленным ключом; проверка размера и `If-None-Match` не решают эту проблему полностью. Для доверенной дедупликации нужна независимая проверка или механизм карантина.
- Сервер проверяет **заявленный** размер до подписи, но простой Presigned PUT сам по себе не обеспечивает строгий лимит фактически переданных байтов. Обязательно ограничить расходы/злоупотребления в окружении R2; для публичного production это отдельный вопрос безопасности.
- Один PUT при обрыве загружается заново. Multipart пока исключён по согласованию.
- Для тестового домена нужны правильные CORS origins; кэширование Cloudflare необязательно.