Files
SHiNE-server/docs/Blockchain/15_TEXT_Attachments.md
T

7.4 KiB

Вложения в TEXT-сообщениях (S:att v=1)

Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.

Область применения

Формат применяется к UTF-8 полю text в TEXT-блоках:

  • TEXT_POST
  • TEXT_REPLY
  • TEXT_EDIT_POST
  • TEXT_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 - размер файла в байтах;
  • 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 не записываются в блокчейн отдельными полями.