Вложения файлов со своего сервера доступа пользователя

This commit is contained in:
AidarKC
2026-10-07 11:42:12 +03:00
parent b1c42efa82
commit 7b8e178723
33 changed files with 1960 additions and 496 deletions
+56 -59
View File
@@ -15,112 +15,109 @@
## Общий вид
Канонический attach-блок:
Arweave-вложение:
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
```
Блок с превью:
Public file на сервере доступа автора:
```text
<S:att;v=1;nm=video.mp4;sz=5820193;sha256=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;preAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;preSha256=eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee>
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef>
```
Несколько вложений идут подряд в самом начале текста:
```text
<S:att;v=1;nm=photo.jpg;sz=248193;sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;ar=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB>
<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-блоков в том порядке, в котором пользователь прикрепил файлы.
Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков.
## Поля
Обязательные поля канонического формата:
Обязательные поля:
- `v=1` - версия формата attach-блока;
- `nm` - имя файла, закодированное через `encodeURIComponent`;
- `sz` - размер файла в байтах;
- `sha256` - SHA-256 исходного файла в hex, 64 символа;
- `sha256` - SHA-256 исходного файла в hex, 64 символа.
Опциональное поле:
- `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL.
Дополнительные поля для превью:
Источник определяется только наличием `ar`:
- `preAr` - короткий Arweave Transaction ID файла-превью;
- `preSha256` - SHA-256 файла-превью в hex.
- `ar` присутствует -> Arweave;
- `ar` отсутствует -> public file текущего сервера доступа автора.
Адрес сервера доступа, URL файла и login автора в attach-блок не записываются: автор уже известен из подписанного блока, а актуальный сервер доступа определяется отдельно.
## Preview
Отдельные preview-файлы в текущем протоколе **не поддерживаются и пока не нужны**.
Клиент не должен создавать или использовать поля `preAr`, `preSha256`, `previewAr`, `previewSha256`. Для изображения или видео используется исходный файл вложения.
Если такие поля встречаются в экспериментальных старых данных, текущая реализация может их игнорировать; они не являются частью канонического `S:att v=1`.
## Хранение файла
Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки:
Сам файл всегда находится вне блокчейна.
- имя файла;
- размер;
- SHA-256;
- Arweave `txId`.
### Arweave
Опционально для видео или больших изображений может храниться отдельный второй файл-превью. В таком случае основной attach-блок остаётся одним, но дополнительно указывает `preAr/preSha256`.
Если присутствует `ar`, файл читается через настроенный Arweave gateway по указанному `txId`.
### Сервер доступа
Если `ar` отсутствует, клиент:
1. определяет текущий сервер доступа автора сообщения;
2. запрашивает файл по стандартному пути `/files/<sha256>`;
3. при необходимости проверяет полученные байты по `sha256` из блока.
Физическое хранилище сервера является content-addressed: один и тот же SHA-256 должен соответствовать одному набору байтов. Это позволяет дедуплицировать одинаковые файлы разных пользователей.
URL или домен конкретного сервера в блокчейн не записывается. Поэтому смена сервера доступа не требует изменения старых сообщений.
## Создание вложения в UI
UI поддерживает три сценария:
UI предлагает два способа хранения: `Сервер доступа` и `Arweave`. По умолчанию выбран сервер доступа. Отдельные preview-файлы не создаются.
- загрузить новый файл в Arweave выбранным Arweave-кошельком;
- ввести существующий `txId`, скачать файл через Arweave gateway и локально посчитать `size/sha256`;
- выбрать файл из журнала файлов, загруженных в текущей браузерной сессии.
После успешной загрузки на сервер доступа формируется тот же `S:att v=1`, но без поля `ar`. Для Arweave используется существующий механизм Arweave/Turbo и добавляется `ar`.
Для видеофайлов UI может по желанию пользователя автоматически создать превью из первого кадра. Технически клиент загружает два файла:
- основной видеофайл;
- отдельное изображение-превью.
После успешной загрузки в журнале хранится один элемент основного файла, но с полями `preAr/preSha256`. В UI такой элемент помечается как файл `С превью`.
При ручном добавлении существующего `txId` для видео UI также позволяет вручную указать `txId` файла-превью.
Журнал хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
В настройках клиента есть отдельный экран `Загрузка файлов`: пользователь может заранее загрузить файл в Arweave без создания сообщения, увидеть компактную плитку с именем, размером, временем загрузки, `txId` и статусом доступности через gateway, а затем выбрать этот файл из истории при создании сообщения.
Если файл загружен заранее, но ещё не был отправлен ни в одном сообщении SHiNE, клиент показывает локальный флаг `Не добавлен в SHiNE`. Флаг снимается после успешной отправки сообщения с этим вложением.
Если история очищена, уже созданные сообщения не меняются: в блокчейне остаются attach-блоки с `txId`.
Журнал загрузок Arweave хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
## Отображение
Новый клиент при чтении сообщения:
Клиент при чтении сообщения:
1. читает валидные attach-блоки только из начала текста;
2. скрывает технические attach-строки;
3. отображает вложения над пользовательским текстом;
4. показывает вложения горизонтальной каруселью: одно вложение на экране, переключение свайпом или стрелками, счётчик вида `1 из 3`;
5. определяет тип вложения по расширению имени файла:
- изображение показывает как ограниченное по размеру превью;
- видео показывает как превью с кнопкой воспроизведения и открывает большой HTML5-плеер по нажатию;
- обычный файл показывает как карточку с именем, расширением, размером и скачиванием;
6. если у видео есть `preAr/preSha256`, использует отдельный preview-файл как `poster` и как большую превью-плитку в журнале загрузок;
7. при перелистывании останавливает воспроизводящееся видео;
8. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.
Если файл по ссылке Arweave gateway недоступен, клиент показывает диагностический блок:
- если сообщение создано менее 20 минут назад: файл, скорее всего, ещё не распространился в Arweave, нужно повторить через несколько минут;
- если сообщение старше 20 минут: файл считается недоступным.
Старые клиенты без поддержки формата могут показывать 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`.
При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения выполняется через edit-блок с пустым текстом, как описано в `11_TEXT_Blocks.md`.
## Совместимость и ограничения
- `ar` допускает только короткий Arweave `txId`, полный URL не используется;
- MIME type не записывается, поэтому UI определяет image/video/file по расширению имени файла;
- старые блоки `<SHiNE:attach ...>`, промежуточные `<S:attach ...>` и новые `<S:att ...>` читаются одинаково;
- старые поля `name/size/previewAr/previewSha256` и новые `nm/sz/preAr/preSha256` читаются одинаково;
- старые блоки `v=2` продолжают читаться как legacy-форма вложения с превью;
- `preAr/preSha256` используются только если присутствуют оба поля и оба валидны;
- MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями;
- проверка существующего `txId` скачивает файл локально через gateway, поэтому UI ограничивает максимальный размер такой проверки.
- полный URL в поле `ar` не используется;
- MIME type не записывается, тип UI определяется по расширению `nm`;
- старые текстовые префиксы `<SHiNE:attach ...>` и `<S:attach ...>` могут продолжать читаться как совместимые формы;
- отдельные preview-поля не входят в текущий протокол;
- MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями.