SHA256
174 lines
7.9 KiB
Markdown
174 lines
7.9 KiB
Markdown
# Черновик формата вложений в сообщениях блокчейна SHiNE
|
|
|
|
## Статус документа
|
|
|
|
Этот файл пока является черновиком и рабочим описанием идеи.
|
|
|
|
Важно:
|
|
|
|
- это не финальная спецификация;
|
|
- точная версия формата будет зафиксирована после начала реальной реализации;
|
|
- до момента реализации допустимы изменения полей, синтаксиса и правил отображения;
|
|
- документ специально лежит в корне проекта как временная рабочая заметка.
|
|
|
|
## Цель
|
|
|
|
Нужен минимальный формат, позволяющий прикладывать файлы к текстовым сообщениям в каналах и тредах, не превращая само сообщение в отдельный файловый контейнер.
|
|
|
|
Основная идея:
|
|
|
|
- само сообщение остаётся обычным текстом;
|
|
- вложения описываются специальными техническими вставками в начале текста;
|
|
- сами файлы хранятся отдельно в архиве/Arweave;
|
|
- в сообщении хранятся только метаданные, достаточные для отображения и скачивания.
|
|
|
|
## Общий принцип
|
|
|
|
Если в начале текста сообщения стоит один или несколько блоков:
|
|
|
|
```text
|
|
<SHiNE:attach;...>
|
|
```
|
|
|
|
клиент трактует их как описания вложений.
|
|
|
|
После этих блоков идёт обычный пользовательский текст сообщения.
|
|
|
|
Если технических блоков нет, сообщение считается обычным текстовым сообщением без вложений.
|
|
|
|
## Формат одного блока вложения
|
|
|
|
Общий вид:
|
|
|
|
```text
|
|
<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.
|
|
|
|
## Несколько вложений
|
|
|
|
Если к одному сообщению приложено несколько файлов, блоки просто идут подряд в начале текста:
|
|
|
|
```text
|
|
<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.
|
|
|
|
Пока этот вопрос считается открытым.
|
|
|
|
## Примеры
|
|
|
|
### Одно вложение
|
|
|
|
```text
|
|
<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
|
|
Привет, вот фото
|
|
```
|
|
|
|
### Два вложения
|
|
|
|
```text
|
|
<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 и других клиентах.
|