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` не являются частью текущего протокола.
|
||||
Reference in New Issue
Block a user