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

129 lines
8.6 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` - размер файла в байтах;
- `sha256` - SHA-256 исходного файла в hex, 64 символа.
Опциональное поле:
- `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL.
Источник определяется только наличием `ar`:
- `ar` присутствует -> Arweave;
- `ar` отсутствует -> public file текущего сервера доступа автора.
Адрес сервера доступа, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока, а актуальный сервер доступа определяется отдельно.
## Preview
Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**.
Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения.
Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`.
## Хранение файла
Сам файл всегда находится вне блокчейна.
### Arweave
Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`.
### Сервер доступа
Если `ar` отсутствует, клиент:
1. определяет текущий сервер доступа автора сообщения;
2. запрашивает файл по стандартному пути `/files/<sha256>`;
3. при необходимости проверяет полученные байты по `sha256` из блока.
Физическое хранилище сервера является content-addressed: один и тот же SHA-256 должен соответствовать одному набору байтов. Это позволяет дедуплицировать одинаковые файлы разных пользователей.
URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений.
## Создание вложения в UI
UI предлагает два способа хранения: `Сервер доступа` и `Arweave`. По умолчанию выбран сервер доступа. Отдельные preview-файлы не создаются.
После успешной загрузки на сервер доступа формируется тот же `S:att v=1`, но без поля `ar`. Для Arweave используется существующий механизм Arweave/Turbo и добавляется `ar`.
Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
## Отображение
Клиент при чтении сообщения:
1. читает валидные attach-блоки только из начала текста;
2. скрывает технические attach-строки;
3. определяет источник по наличию `ar`;
4. получает Arweave-файл по `txId` либо server-файл по `/files/<sha256>` текущего сервера доступа автора;
5. определяет тип вложения по расширению `nm`;
6. изображение отображает из исходного файла;
7. видео отображает из исходного файла и открывает HTML5-плеер;
8. обычный файл показывает как карточку с именем, размером и скачиванием;
9. при перелистывании останавливает воспроизводящееся видео;
10. битый attach-блок игнорирует, не ломая остальное сообщение.
## Редактирование
При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`.
## Совместимость и ограничения
- полный URL в поле `ar` не используется;
- MIME type не записывается, тип UI определяется по расширению `nm`;
- старые текстовые префиксы `<SHiNE:attach ...>` и `<S:attach ...>` могут продолжать читаться как совместимые формы;
- отдельные preview-поля не входят в текущий протокол;
- MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями.
## 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. Предпросмотр изображений и видео **публичных вложений** в MVP отключён (файловая карточка); UI личных зашифрованных файлов не изменяется.