Обновить хранение вложений R2

This commit is contained in:
AidarKC
2026-11-16 10:47:43 +03:00
parent fed28527ae
commit 1b86bca19a
17 changed files with 321 additions and 276 deletions
+32 -135
View File
@@ -1,155 +1,52 @@
# HTTP API публичных файлов каналов
# Публичные вложения SHiNE: Cloudflare R2 и legacy API
## 1. Назначение
## Действующий формат (15.11.2026)
Публичное вложение может храниться не в Arweave, а на текущем сервере доступа автора.
Файловый слой намеренно максимально простой: он хранит только байты, адресованные их SHA-256.
Новые публичные файлы и аватары используют **BitTorrent v2 Pieces Root**, закодированный **Base58** (32 байта; строка обычно 43–44 символа). Идентификатор не зависит от имени и MIME. Клиент вычисляет корень по подготовленным байтам. Содержимое файла **не проходит через Java**.
Канонический URL:
- R2 bucket: `shine-files`.
- Публичный GET: `https://files.shineup.me/<PR>` (ключ объекта = `PR`, без расширения).
- Предпросмотр публичных изображений и видео использует прямой URL. Картинки `loading="lazy"`; публичные видео получают `src` только у видимой области через `IntersectionObserver` и запрашивают метаданные после входа в область. В старом браузере используется обычная загрузка metadata.
- Отдельных preview-файлов нет. Скачивание/просмотр медиаконтента выполняет сам браузер (в том числе HTTP Range, если доступен).
- Тип определяется по `mm`, затем по расширению `nm`; HTTP `Content-Type` объекта задаётся при PUT. Неизвестные файлы — `application/octet-stream`.
- HTML, SVG и похожие активные типы отображаются как обычные файловые карточки. Перед открытием **из публичного интерфейса** показывается предупреждение с возможностью отмены. Это не серверная санитаризация и не гарантия безопасности прямого URL.
Формат публичного вложения (версия тега остаётся 1):
```text
/files/<sha256>
<S:att;v=1;nm=photo.jpg;sz=123456;pr=BASE58_ROOT;mm=image/jpeg>
```
`sha256` — lowercase hex, ровно 64 символа.
При использовании Arweave дополнительно передаётся `;ar=TXID` — существующая загрузка Arweave/Turbo не меняется. Источник выбирается по `ar` (если есть), иначе R2 по `pr`. Не добавлять `storage=r2` в постоянные записи. Общее описание — `docs/Blockchain/15_TEXT_Attachments.md`.
На диске сервер хранит один глобальный объект:
Новые аватары: `<S:ava;v=2;sz=N;pr=BASE58_ROOT[;ar=TXID]>`. SHA-256 hex остаётся лишь в исторических файловых маршрутах, **новые аватары SHA-256 не создают**. Старые аватары v1 не мигрируются автоматически (v41 сбрасывает старые ссылки каналов).
```text
<public.files.storageDir>/<sha256>
## Выдача разрешения на загрузку
`POST /api/files/prepare` (JSON):
```json
{"pr":"BASE58_ROOT","size":123456,"mm":"image/jpeg"}
```
Имя пользователя, исходное имя файла, расширение, MIME и ссылка на сообщение в файловом хранилище не нужны. Одинаковые байты, загруженные разными пользователями, дедуплицируются в один объект.
Сессионная Ed25519-подпись обязательна. Заголовки:
## 2. Конфигурация Java-сервера
- `X-Shine-Session-Id`
- `X-Shine-Time-Ms`
- `X-Shine-Signature`
```properties
public.files.enabled=true
public.files.storageDir=data/public-files
public.files.maxBytes=536870912
```
Подписываемая строка `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}`.
Для production рекомендуется задать `public.files.storageDir` абсолютным путём, который одновременно доступен Java для записи и Caddy для чтения.
Сервер проверяет авторизацию, Base58 32-байтного PR, размер (≤500 МиБ), MIME, выполняет S3 `HeadObject`. Если объект уже существует с тем же размером — возвращает `exists:true`; если нет — `uploadUrl`, `requiredHeaders`, `fileUrl`. Браузер делает один **Presigned PUT** прямо в S3 Endpoint R2 с обязательными подписанными заголовками, включая `If-None-Match: *` для защиты от перезаписи. Действие не использует R2 credential в браузере.
Например:
Java **не проверяет реальный Pieces Root содержимого** и не гарантирует строгий объём через один заявленный клиентом `size`; нет Multipart, квот или автоматической проверки фактического PUT после выдачи URL. Неверный PR у первоначального объекта может нарушать дедупликацию — это известный компромисс MVP.
```text
/home/player/shine-public-files
```
Конфигурация сервера: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `r2.publicBucket=shine-files`. CORS корзины должен разрешать origin PWA и PUT с подписанными заголовками. Ключи — только на сервере.
## 3. PUT `/files/<sha256>`
## Исторический локальный API SHA-256
Загружает immutable public file. PUT требует активную пользовательскую сессию.
Старый `PublicFileServlet` обслуживает `/files/<64 lowercase hex SHA-256>` на локальном диске (`public.files.storageDir`). Для старых файлов может продолжать работать GET/HEAD/PUT с проверкой SHA-256 и HTTP Range. Новые `pr`-файлы туда **не загружаются**. Детали legacy передавать только при поддержке исторических данных, не использовать этот API в новых тегах.
Заголовки:
## Учёт разрешений R2 (PostgreSQL v42)
```text
Content-Type: application/octet-stream
X-Shine-Session-Id: <active session id>
X-Shine-Time-Ms: <unix time ms>
X-Shine-Content-Length: <file bytes>
X-Shine-Signature: <Ed25519 signature, Base64>
```
Подписываемая строка UTF-8:
```text
PUBLIC_FILE_UPLOAD_V1:{sessionId}:{sha256}:{size}:{timeMs}
```
Сервер потоково принимает байты, заново считает SHA-256 и принимает объект только если:
```text
SHA256(received bytes) == sha256 из URL
```
Если корректный объект уже существует и размер совпадает, PUT идемпотентно отвечает `alreadyExists=true`.
## 4. GET и HEAD (включая HTTP Range)
Java servlet обслуживает `GET /files/<sha256>` и `HEAD /files/<sha256>`.
Проверка SHA-256 **при чтении не выполняется**: хеш проверяется при исходном PUT,
файл immutable, а скачивание не должно требовать предварительного прочтения всех байтов.
Проверка корректности при повторном PUT уже имеющегося объекта сохранена.
Полный GET, как и прежде, возвращает `200 OK` и `Content-Length` всего файла.
HEAD всегда возвращает метаданные **полного объекта** без тела и без обхода
всего файла по байтам (Range в HEAD игнорируется).
Для `GET` с одним диапазоном:
```http
Range: bytes=0-262143
```
Ответ:
```http
HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-262143/<общий размер>
Content-Length: 262144
ETag: "<sha256>"
```
Поддерживаются формы `bytes=START-END`, `bytes=START-` и `bytes=-SUFFIX`.
Для составных или неудовлетворяемых диапазонов сервер возвращает `416` +
`Content-Range: bytes */<общий размер>`. `If-Range` поддерживает точный
совпадающий ETag; при несовпадении возвращается полный `200`.
Остальные заголовки:
```http
Cache-Control: public, max-age=31536000, immutable
Cross-Origin-Resource-Policy: cross-origin
Access-Control-Allow-Origin: *
```
Тип для MP4, WebM, Ogg и AVI Java определяет по первым байтам файла.
Неизвестные типы остаются `application/octet-stream`. Протокол `S:att`
не меняется, имя файла/тип на сервере не сохраняются.
При прямой выдаче Caddy (`file_server`) Range обеспечивает Caddy, а не Java.
Следует проверить `Content-Type` (у файлов с именем SHA-256 нет расширения),
а также корректность ответа `206` через публичный домен, особенно с CDN.
Если нужен корректный MIME по сигнатуре, используйте HTTP reverse_proxy к Java
из инструкции `deploy/PUBLIC_FILES_CADDY_CLOUDFLARE.md`.
## 5. Связь с `S:att`
```text
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>>
```
означает public file на текущем сервере доступа автора.
```text
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>;ar=<txId>>
```
означает Arweave.
Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит:
```text
https://<current-access-server>/files/<sha256>
```
## 6. Preview
В UI видео со storage=server получает прямую ссылку `/files/<sha256>` (без полного `fetch` в Blob): браузер сам запрашивает диапазоны, читает длительность и загружает стартовый кадр. Размер берётся из `sz` вложения. Для Arweave частичная загрузка зависит от gateway.
Отдельных preview-файлов сейчас нет. `preAr`, `preSha256`, `previewAr`, `previewSha256` не являются частью текущего протокола.
## R2 direct upload (MVP, 2026-11)
New public attachments use BitTorrent v2 `pr` (canonical Base58 encoding of the 32-byte Pieces Root, normally 43–44 characters, variable length 32–44), `mm` (optional MIME) and `v=1`. Avatars retain the original SHA-256 `/files/<sha256>` API. The client signs `PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}` with its Ed25519 session key, submits JSON `{pr,size,mm}` to `POST /api/files/prepare` and provides `X-Shine-Session-Id`, `X-Shine-Time-Ms` and `X-Shine-Signature`. The endpoint returns `exists`, `fileUrl`, and for missing objects `uploadUrl` and `requiredHeaders`. The browser uploads the original Blob directly to the S3 endpoint, not the Java server. A signature does not certify the hash of uploaded content. The public GET URL is `https://files.shineup.me/<pr>`; the R2 object key is exactly the same Base58 `pr` (no extension). Old Base64URL PR identifiers are not read or migrated. Arweave TX IDs and DM file identifiers keep their existing encodings. Client and Java server must be updated together.
Configuration: `R2_ENDPOINT`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `r2.publicBucket=shine-files` (or `r2.endpoint`, `r2.accessKeyId`, `r2.secretAccessKey` in trusted server config). Never publish keys. Configure browser CORS to permit signed PUT headers including `If-None-Match`. Max size: 500 MiB. Single PUT only, no multipart in this MVP.
## Единый формат публичных идентификаторов
Аватарки и публичные вложения имеют одинаковый `PR = Base58(BitTorrent v2 Pieces Root)` и сохраняются в **корень** R2 bucket `shine-files`, URL `https://files.shineup.me/<PR>`. Папки `avatars/` нет; загрузка идёт через `/api/files/prepare`, не через `/api/avatars/prepare`. После оптимизации изображения вычисляется PR от именно передаваемых байтов. `<S:ava;v=2;sz=N;pr=BASE58[;ar=TXID]>`; `ar` остаётся нативным Arweave TX ID в Base64URL. Старые `<S:ava;v=1;...sha256=...>` не поддерживаются.
Для потенциального **будущего** SHA-256 типа идентификатора публичного файла используем `Base58(SHA-256(bytes))`, а не hex. Это отдельный алгоритм, его нельзя смешивать с PR. На данный момент новые публичные вложения/аватарки не используют SHA-256 как идентификатор.
В `public_file_uploads` пишется событие после успешной авторизации и решения S3: логин, PR, заявленный размер, `requested_at`, `disposition` (`upload_url_issued` или `already_exists`). **Это журнал выдачи разрешения/повторного использования, а не доказательство завершённого PUT.** Повторные попытки фиксируются отдельными строками. Лимитов и блокировок по журналу пока нет. Параллельная таблица DM описана в `docs/API/18_DM_File_Storage_API.md`.