SHA256
124 lines
7.4 KiB
Markdown
124 lines
7.4 KiB
Markdown
# Вложения в 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 не записываются в блокчейн отдельными полями.
|