SHA256
Вложения файлов со своего сервера доступа пользователя
This commit is contained in:
@@ -91,5 +91,6 @@
|
||||
- Межсерверные DM-операции пока доверяют `sourceServerLogin`; отдельная межсерверная авторизация запланирована позднее.
|
||||
- `ServerHello` пока принимает заявленный `serverLogin` на доверии и не является криптографической аутентификацией.
|
||||
- HTTP endpoints зашифрованных DM-файлов (`PUT/GET/HEAD/OPTIONS /dm-files/{fileId}`) не являются WebSocket `op` и описаны отдельно в `18_DM_File_Storage_API.md`.
|
||||
- HTTP endpoints публичных content-addressed файлов (`PUT/GET/HEAD/OPTIONS /files/{sha256}`) также не являются WebSocket `op` и описаны отдельно в `21_Public_File_Storage_API.md`.
|
||||
- Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
|
||||
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
# HTTP API публичных файлов каналов
|
||||
|
||||
## 1. Назначение
|
||||
|
||||
Публичное вложение может храниться не в Arweave, а на текущем сервере доступа автора.
|
||||
Файловый слой намеренно максимально простой: он хранит только байты, адресованные их SHA-256.
|
||||
|
||||
Канонический URL:
|
||||
|
||||
```text
|
||||
/files/<sha256>
|
||||
```
|
||||
|
||||
`sha256` — lowercase hex, ровно 64 символа.
|
||||
|
||||
На диске сервер хранит один глобальный объект:
|
||||
|
||||
```text
|
||||
<public.files.storageDir>/<sha256>
|
||||
```
|
||||
|
||||
Имя пользователя, исходное имя файла, расширение, MIME и ссылка на сообщение в файловом хранилище не нужны. Одинаковые байты, загруженные разными пользователями, дедуплицируются в один объект.
|
||||
|
||||
## 2. Конфигурация Java-сервера
|
||||
|
||||
```properties
|
||||
public.files.enabled=true
|
||||
public.files.storageDir=data/public-files
|
||||
public.files.maxBytes=536870912
|
||||
```
|
||||
|
||||
Для production рекомендуется задать `public.files.storageDir` абсолютным путём, который одновременно доступен Java для записи и Caddy для чтения.
|
||||
|
||||
Например:
|
||||
|
||||
```text
|
||||
/home/player/shine-public-files
|
||||
```
|
||||
|
||||
## 3. PUT `/files/<sha256>`
|
||||
|
||||
Загружает immutable public file. PUT требует активную пользовательскую сессию.
|
||||
|
||||
Заголовки:
|
||||
|
||||
```text
|
||||
Content-Type: application/octet-stream
|
||||
X-Shine-Session-Id: <active session id>
|
||||
X-Shine-Time-Ms: <unix time ms>
|
||||
X-Shine-Content-Length: <file bytes>
|
||||
X-Shine-Signature: <Ed25519 signature, Base64>
|
||||
```
|
||||
|
||||
Подписываемая строка UTF-8:
|
||||
|
||||
```text
|
||||
PUBLIC_FILE_UPLOAD_V1:{sessionId}:{sha256}:{size}:{timeMs}
|
||||
```
|
||||
|
||||
Сервер потоково принимает байты, заново считает SHA-256 и принимает объект только если:
|
||||
|
||||
```text
|
||||
SHA256(received bytes) == sha256 из URL
|
||||
```
|
||||
|
||||
Если корректный объект уже существует и размер совпадает, PUT идемпотентно отвечает `alreadyExists=true`.
|
||||
|
||||
## 4. GET и HEAD
|
||||
|
||||
Java servlet умеет `GET` и `HEAD` как fallback. В production рекомендуется не пропускать чтение через Java: Caddy должен отдавать файл непосредственно с диска.
|
||||
|
||||
Ответ immutable:
|
||||
|
||||
```text
|
||||
Cache-Control: public, max-age=31536000, immutable
|
||||
ETag: "<sha256>"
|
||||
Content-Type: application/octet-stream
|
||||
```
|
||||
|
||||
Файловое хранилище не определяет тип контента. Официальный клиент решает, как интерпретировать байты, на основании имени `nm` из `S:att`. Если пользователь указал неверное расширение или положил неподходящие байты, клиент просто не сможет отобразить такой media-файл.
|
||||
|
||||
## 5. Связь с `S:att`
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>>
|
||||
```
|
||||
|
||||
означает public file на текущем сервере доступа автора.
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>;ar=<txId>>
|
||||
```
|
||||
|
||||
означает Arweave.
|
||||
|
||||
Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит:
|
||||
|
||||
```text
|
||||
https://<current-access-server>/files/<sha256>
|
||||
```
|
||||
|
||||
## 6. Preview
|
||||
|
||||
Отдельных preview-файлов сейчас нет. `preAr`, `preSha256`, `previewAr`, `previewSha256` не являются частью текущего протокола.
|
||||
@@ -111,16 +111,16 @@ Login/fork для edit не подписываются: edit может ссыл
|
||||
|
||||
Бинарный формат `TextBody` не меняется: вложения являются частью UTF-8 текста.
|
||||
|
||||
Один блок вложения:
|
||||
Arweave-вложение:
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123...;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
|
||||
```
|
||||
|
||||
Для файлов с отдельным превью клиент может использовать расширенный вариант:
|
||||
Вложение на сервере доступа автора:
|
||||
|
||||
```text
|
||||
<S:att;v=1;nm=video.mp4;sz=5820193;sha256=bbbb...;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;preAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;preSha256=eeee...>
|
||||
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123...>
|
||||
```
|
||||
|
||||
Несколько вложений идут подряд в самом начале текста, по одному блоку на строку. После последнего блока идёт обычный пользовательский текст.
|
||||
@@ -131,8 +131,18 @@ Login/fork для edit не подписываются: edit может ссыл
|
||||
- `nm` - имя файла, закодированное через `encodeURIComponent`
|
||||
- `sz` - размер файла в байтах
|
||||
- `sha256` - SHA-256 исходного файла в hex
|
||||
- `ar` - короткий Arweave Transaction ID, без полного URL
|
||||
- при наличии превью дополнительно могут присутствовать `preAr` и `preSha256`
|
||||
|
||||
Опциональное поле:
|
||||
|
||||
- `ar` - короткий Arweave Transaction ID, без полного URL.
|
||||
|
||||
Правило источника файла:
|
||||
|
||||
- `ar` присутствует -> файл хранится в Arweave;
|
||||
- `ar` отсутствует -> файл хранится как public file на текущем сервере доступа автора и читается по `/files/<sha256>`;
|
||||
- адрес сервера доступа в attach-блок не записывается.
|
||||
|
||||
Отдельные preview-файлы сейчас **не поддерживаются и не являются частью текущего протокола**. Поля `preAr`, `preSha256`, `previewAr`, `previewSha256` новые клиенты создавать не должны. Изображения и видео отображаются из исходного файла.
|
||||
|
||||
Правила клиента:
|
||||
|
||||
@@ -141,4 +151,4 @@ Login/fork для edit не подписываются: edit может ссыл
|
||||
- старые клиенты без поддержки вложений могут показывать технические строки как обычный текст;
|
||||
- пустой пользовательский текст допустим, если перед ним есть хотя бы один валидный attach-блок.
|
||||
|
||||
Файлы хранятся вне блокчейна, в Arweave. В блокчейне остаются только `txId`, имя, размер, SHA-256 и, при наличии отдельного preview-файла, `preAr/preSha256`.
|
||||
Сам файл всегда хранится вне блокчейна. В блокчейне остаются имя, размер, SHA-256 и, только для Arweave-вложения, `ar`.
|
||||
|
||||
@@ -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 не записываются в блокчейн отдельными полями.
|
||||
|
||||
@@ -9,6 +9,13 @@
|
||||
- Bootstrap/rebuild восстанавливает delete-state из канонической истории с учётом segmented forks по логическому `login`, поэтому root из старого fork остаётся валидным.
|
||||
- Схема PostgreSQL поднята до v31; добавлен безопасный переход v30 -> v31.
|
||||
|
||||
## 2026-10-07 — Public files на access server
|
||||
|
||||
- Отдельные preview-файлы вложений выведены из текущего протокола и UI. `preAr/preSha256` и `previewAr/previewSha256` больше не создаются и не используются.
|
||||
- Для `S:att v=1` источник определяется наличием `ar`: `ar` есть -> Arweave; `ar` отсутствует -> public file текущего сервера доступа автора по `/files/<sha256>`.
|
||||
- Добавлено публичное content-addressed хранение исходных байтов на access server: один глобальный объект на lowercase hex SHA-256, дедупликация между пользователями, signed `PUT /files/<sha256>`. Адрес сервера, MIME и owner в блок не добавляются.
|
||||
- UI каналов получил выбор `Сервер доступа` / `Arweave`; сервер доступа выбран по умолчанию. Для server-вложения клиент определяет актуальный access server автора по PDA.
|
||||
|
||||
## 2026-10-02 — Transport namespace `test5591`
|
||||
|
||||
- Текущий ANS-104 namespace переключён с `test5590` на `test5591`: `App=test5591`; channel index теперь постоянный и не зависит от namespace: `c=<slug>`.
|
||||
|
||||
Reference in New Issue
Block a user