Files
SHiNE-server/docs/Blockchain/15_TEXT_Attachments.md
T
AidarKC 3ecec25fce Исправить отображение публичных медиа-вложений
Добавить предпросмотр изображений и видео из R2 и Arweave; неподдерживаемые форматы оставить доступными как файлы.
2026-11-15 02:24:15 +03:00

133 lines
10 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.
# Вложения в TEXT-сообщениях (`S:att v=1`)
Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.
## Область применения
Формат применяется к UTF-8 полю `text` в TEXT-блоках:
- `TEXT_POST`
- `TEXT_REPLY`
- `TEXT_EDIT_POST`
- `TEXT_EDIT_REPLY`
Бинарный формат `TextBody` не меняется. Вложения являются техническим префиксом внутри обычного текста.
## Общий вид
Arweave-вложение:
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
```
Public file на сервере доступа автора:
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef>
```
Несколько вложений идут подряд в самом начале текста:
```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-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение.
Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок 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 личных зашифрованных файлов не меняется.