Обновить хранение вложений 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
+21 -118
View File
@@ -1,132 +1,35 @@
# Вложения в TEXT-сообщениях (`S:att v=1`)
# Вложения в TEXT-сообщениях (`S:att;v=1`)
Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.
Технический префикс в UTF-8 `text` для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST`, `TEXT_EDIT_REPLY`. Бинарный формат TEXT не меняется. До 10 вложений в начале сообщения, затем обычный текст; порядок сохраняется.
## Область применения
Формат применяется к UTF-8 полю `text` в TEXT-блоках:
- `TEXT_POST`
- `TEXT_REPLY`
- `TEXT_EDIT_POST`
- `TEXT_EDIT_REPLY`
Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста.
## Общий вид
Arweave-вложение:
## Канонический формат (2026-11)
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
<S:att;v=1;nm=photo.jpg;sz=248193;pr=BASE58_ROOT;mm=image/jpeg>
<S:att;v=1;nm=video.mp4;sz=15000000;pr=BASE58_ROOT;mm=video/mp4;ar=TXID>
Текст публикации
```
Public file на сервере доступа автора:
- `v` — версия (1).
- `nm` — имя файла в `encodeURIComponent`.
- `sz` — размер подготовленных байтов в десятичном виде.
- `pr` — **BitTorrent v2 Pieces Root (32 байта), Base58**, не SHA-256 целого файла; текущий стандарт новых вложений.
- `mm` — необязательный MIME, в формате `type/subtype`; неизвестный — `application/octet-stream`.
- `ar` — необязательный Arweave Transaction ID, нативный формат Arweave.
- `sha256` — исторический lowercase hex SHA-256 для старых тегов/объектов; новые записи его не создают.
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef>
```
`ar` присутствует → получить файл через Arweave gateway. Нет `ar`, есть `pr` → `https://files.shineup.me/<pr>`. Исторический `sha256` без `pr`/`ar` → прежний `/files/<sha256>` access-сервера автора. `storage=r2` и абсолютные URL в тег не записываются.
Несколько вложений идут подряд в самом начале текста:
Идентификаторы новых аватаров — тоже **Base58(PR)**, но формат аватара отдельный: `<S:ava;v=2;sz=N;pr=ROOT[;ar=TXID]>`. Формат v1/SHA-256 аватаров больше не создаётся; миграция v41 не конвертирует старые значения.
```text
<S:att;v=1;nm=photo.jpg;sz=248193;sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa>
<S:att;v=1;nm=report.pdf;sz=845221;sha256=cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc;ar=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD>
Текст сообщения
```
## Отображение и безопасность
После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение.
Клиент берёт тип по `mm` (при его наличии), иначе пытается использовать расширение `nm`. Для HTTP-открытия URL без расширения R2 также хранит `Content-Type` в метаданных объекта. Изображения загружаются `loading="lazy"`; публичные видео не получают `src`, пока не приблизились к экрану (`IntersectionObserver` с fallback). Встроенное отображение использует исходный файл, дополнительных preview-объектов нет.
Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков.
HTML, SVG, XHTML, JavaScript, XML по расширению или MIME выводятся карточками с подтверждением перед переходом из UI. Пользователь может отменить открытие; прямые ссылки R2/Arweave обходят это предупреждение. Это не изменение доступа, криптографии или правила хранения и **не даёт защиты от вредоносного содержимого на уровне HTTP**.
## Поля
Публичные вложения сохраняются на R2 либо в Arweave без автоматического удаления; DM-вложения используют отдельный протокол, см. `docs/Personal_Messages/Файлы_DM_v3_R2.md`. Редактирование текста сохраняет технические attach-блоки и не переносит объекты между хранилищами.
Обязательные поля:
## Совместимость
- `v=1` - версия формата attach-блока;
- `nm` - имя файла, закодированное через `encodeURIComponent`;
- `sz` - размер файла в байтах;
- один из идентификаторов файла: `pr` — pieces root BitTorrent v2 (base64url, 43 символа) для новых вложений; `sha256` — hex SHA-256 (64 символа) для совместимости со старыми.
Опциональные поля:
- `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL;
- `mm` - MIME типа `image/jpeg` или `video/mp4`; если отсутствует, UI использует расширение `nm`.
Источник определяется следующим образом:
- `ar` присутствует -> Arweave;
- `ar` отсутствует, но есть `pr` -> публичный Cloudflare R2 (`https://files.shineup.me/<pr>`);
- `ar` и `pr` отсутствуют, есть `sha256` -> старое файловое хранилище сервера доступа автора.
Адрес сервера автора, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока. Старые файлы разрешаются через сервер доступа, новые R2 — по `pr`.
## Preview
Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**.
Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения.
Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`.
## Хранение файла
Сам файл всегда находится вне блокчейна.
### Arweave
Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`.
### Cloudflare R2 (новые публичные файлы)
Если `ar` отсутствует и указан `pr`, клиент использует прямой адрес `https://files.shineup.me/<pr>`. Браузер запрашивает исходное медиа напрямую; сервер Java в отдаче файла не участвует. При видео браузер может запрашивать только метаданные и нужные фрагменты через HTTP Range.
### Сервер доступа (старые вложения с SHA-256)
Если `ar` и `pr` отсутствуют, клиент:
1. определяет текущий сервер доступа автора сообщения;
2. запрашивает файл по стандартному пути `/files/<sha256>`;
3. использует прежний формат ссылок для совместимости с существующими сообщениями.
URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений.
## Создание вложения в UI
UI предлагает два способа хранения публичных вложений: `Cloudflare R2` (через пункт сервера доступа) и `Arweave`. Отдельные preview-файлы не создаются.
После загрузки в R2 формируется `S:att v=1` с `pr` и `mm`, без `ar`. Для Arweave используется механизм Arweave/Turbo; дополнительно записывается `ar`.
Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
## Отображение
Клиент при чтении сообщения:
1. читает валидные attach-блоки только из начала текста;
2. скрывает технические attach-строки;
3. определяет источник по наличию `ar`;
4. получает Arweave-файл по `txId`, R2-файл по `pr` либо старый server-файл по `/files/<sha256>`;
5. определяет тип вложения по `mm` (если указан), иначе по расширению `nm`;
6. изображение отображает из исходного файла;
7. видео отображает из исходного файла и открывает HTML5-плеер;
8. обычный файл показывает как карточку с именем, размером и скачиванием;
9. при перелистывании останавливает воспроизводящееся видео;
10. битый attach-блок игнорирует, не ломая остальное сообщение.
## Редактирование
При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`.
## Совместимость и ограничения
- полный URL в поле `ar` не используется;
- для старых `sha256`-вложений MIME не записывался, тип UI определяется по расширению `nm`;
- старые текстовые префиксы `<SHiNE:attach ...>` и `<S:attach ...>` могут продолжать читаться как совместимые формы;
- отдельные preview-поля не входят в текущий протокол;
- `width`, `height`, `duration` и `thumbnail` не записываются отдельными полями; новые вложения могут содержать `mm` (MIME).
## MVP R2 (2026-11): новые публичные вложения
Для **новых** публичных вложений использовать `<S:att;v=1;nm=video.mp4;sz=12345;pr=BASE64URL;mm=video/mp4>`; при загрузке в Arweave добавляется `;ar=TXID`. `pr` — 32-байтный BitTorrent v2 pieces root в base64url без padding (43 символа), а не SHA-256 файла. `mm` необязателен; отсутствие означает `application/octet-stream`. Новое публичное вложение без `ar` скачивается с `https://files.shineup.me/<pr>`. `storage=r2` отсутствует. Новые аватары **не изменяются**: SHA-256 и старый API `/files/<sha256>` остаются. Существующий формат чтения `sha256` оставлен для ранее созданных данных и уже загруженных транзакций Arweave. Публичные изображения и видео показываются внутри сообщения из исходного файла (`<img>` / `<video preload="metadata">`) и открываются в общем просмотрщике; PDF, архивы и другие файлы остаются карточками. Тип определяется по `mm`, если он указан и не равен `application/octet-stream`, иначе — по расширению `nm`. Если браузер не может декодировать файл, сохраняется карточка для скачивания (если HEAD-запрос недоступен, показывается ошибка файла). Клиент не скачивает медиа целиком через JavaScript для предпросмотра. UI личных зашифрованных файлов не меняется.
Парсер терпимо читает старое поле `sha256` и префиксы `<SHiNE:attach>`/`<S:attach>`, если данные сохранились. Массовая миграция не выполняется. Экспериментальные `preAr`, `preSha256`, `previewAr`, `previewSha256`, `width`, `duration`, `thumbnail` не входят в протокол.