Добавить предпросмотр изображений и видео из R2 и Arweave; неподдерживаемые форматы оставить доступными как файлы.
10 KiB
Вложения в TEXT-сообщениях (S:att v=1)
Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.
Область применения
Формат применяется к UTF-8 полю text в TEXT-блоках:
TEXT_POSTTEXT_REPLYTEXT_EDIT_POSTTEXT_EDIT_REPLY
Бинарный формат TextBody не меняется. Вложения являются техническим префиксом внутри обычного текста.
Общий вид
Arweave-вложение:
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
Public file на сервере доступа автора:
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef>
Несколько вложений идут подряд в самом начале текста:
<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 отсутствуют, клиент:
- определяет текущий сервер доступа автора сообщения;
- запрашивает файл по стандартному пути
/files/<sha256>; - использует прежний формат ссылок для совместимости с существующими сообщениями.
URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений.
Создание вложения в UI
UI предлагает два способа хранения публичных вложений: Cloudflare R2 (через пункт сервера доступа) и Arweave. Отдельные preview-файлы не создаются.
После загрузки в R2 формируется S:att v=1 с pr и mm, без ar. Для Arweave используется механизм Arweave/Turbo; дополнительно записывается ar.
Журнал загрузок Arweave хранится только в sessionStorage текущего браузера и не является частью блокчейна.
Отображение
Клиент при чтении сообщения:
- читает валидные attach-блоки только из начала текста;
- скрывает технические attach-строки;
- определяет источник по наличию
ar; - получает Arweave-файл по
txId, R2-файл поprлибо старый server-файл по/files/<sha256>; - определяет тип вложения по
mm(если указан), иначе по расширениюnm; - изображение отображает из исходного файла;
- видео отображает из исходного файла и открывает HTML5-плеер;
- обычный файл показывает как карточку с именем, размером и скачиванием;
- при перелистывании останавливает воспроизводящееся видео;
- битый 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 личных зашифрованных файлов не меняется.