SHiNE-server/Черновик_формата_вложений_в_сообщениях_блокчейна.md

Черновик формата вложений в сообщениях блокчейна SHiNE

Статус документа

Этот файл пока является черновиком и рабочим описанием идеи.

Важно:

• это не финальная спецификация;
• точная версия формата будет зафиксирована после начала реальной реализации;
• до момента реализации допустимы изменения полей, синтаксиса и правил отображения;
• документ специально лежит в корне проекта как временная рабочая заметка.

Цель

Нужен минимальный формат, позволяющий прикладывать файлы к текстовым сообщениям в каналах и тредах, не превращая само сообщение в отдельный файловый контейнер.

Основная идея:

• само сообщение остаётся обычным текстом;
• вложения описываются специальными техническими вставками в начале текста;
• сами файлы хранятся отдельно в архиве/Arweave;
• в сообщении хранятся только метаданные, достаточные для отображения и скачивания.

Общий принцип

Если в начале текста сообщения стоит один или несколько блоков:

<SHiNE:attach;...>

клиент трактует их как описания вложений.

После этих блоков идёт обычный пользовательский текст сообщения.

Если технических блоков нет, сообщение считается обычным текстовым сообщением без вложений.

Формат одного блока вложения

Общий вид:

<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=abcdef...;ar=tx_or_url>

Где:

• attach — тип технической вставки;
• v=1 — текущая рабочая версия чернового формата;
• name — имя файла;
• size — размер файла в байтах;
• sha256 — SHA-256 файла в hex;
• ar — идентификатор файла в архиве или адрес файла в Arweave.

Несколько вложений

Если к одному сообщению приложено несколько файлов, блоки просто идут подряд в начале текста:

<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=aaa...;ar=...>
<SHiNE:attach;v=1;name=video.mp4;size=5820193;sha256=bbb...;ar=...>
Текст сообщения

Обязательные поля

Для чернового варианта обязательными считаются:

• v
• name
• size
• sha256
• ar

Если какого-то из этих полей нет, клиент может:

• игнорировать конкретный битый блок;
• не считать его валидным вложением;
• при этом продолжать обрабатывать остальные корректные блоки.

Почему без mime и без kind

В минимальном варианте тип файла отдельно не хранится.

Причины:

• это экономит место;
• тип всё равно обычно определяется клиентом;
• для первого варианта достаточно имени файла, адреса, хэша и размера;
• превью и способ отображения клиент может решать сам по расширению имени файла или по попытке открыть файл.

То есть в сообщении не хранится:

• mime;
• kind;
• width;
• height;
• duration;
• thumbnail.

Все эти поля можно добавить позже отдельной версией, если они реально понадобятся.

Логика клиента

Клиент получает:

• имя файла;
• размер;
• хэш;
• адрес файла.

После этого клиент сам решает, как рендерить вложение:

• если расширение похоже на изображение, можно пробовать показать preview;
• если расширение похоже на видео, можно пробовать встроенный видеоплеер;
• если расширение похоже на аудио, можно пробовать аудиоплеер;
• иначе показывать обычную кнопку скачивания.

Если браузер или клиент не смог показать preview, должен быть fallback на скачивание файла.

Правила совместимости

• Сообщение без <SHiNE:attach;...> остаётся обычным текстом.
• Старые клиенты, которые не умеют распознавать этот формат, могут показывать сообщение как обычный текст целиком.
• Новые клиенты могут скрывать технические блоки и показывать вместо них UI вложений.

Ограничения чернового варианта

В текущем виде значения полей не предполагают сложного экранирования.

Значит нужно отдельно договориться, как безопасно хранить name, если там встретятся символы:

• ;
• =
• >

На этапе реальной реализации нужно выбрать один из вариантов:

• жёстко ограничить допустимые символы в name;
• хранить имя файла в безопасно закодированном виде;
• добавить отдельное правило escape/encoding.

Пока этот вопрос считается открытым.

Примеры

Одно вложение

<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
Привет, вот фото

Два вложения

<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=9ab01e...;ar=K9Lp...>
Смотри, прикрепил фото и документ

Что надо зафиксировать позже

Перед переводом этого черновика в официальную спецификацию нужно отдельно утвердить:

• точное место этого формата в общей документации блокчейна;
• где именно используются такие вложения: каналы, треды, комментарии или иные текстовые блоки;
• финальные правила кодирования name;
• допустим ли полный URL в ar или только короткий txId;
• нужно ли ограничение на количество вложений в одном сообщении;
• нужна ли отдельная серверная или клиентская проверка расширения файла;
• как именно это будет отображаться в web UI и других клиентах.