3.9 KiB
HTTP API публичных файлов каналов
1. Назначение
Публичное вложение может храниться не в Arweave, а на текущем сервере доступа автора. Файловый слой намеренно максимально простой: он хранит только байты, адресованные их SHA-256.
Канонический URL:
/files/<sha256>
sha256 — lowercase hex, ровно 64 символа.
На диске сервер хранит один глобальный объект:
<public.files.storageDir>/<sha256>
Имя пользователя, исходное имя файла, расширение, MIME и ссылка на сообщение в файловом хранилище не нужны. Одинаковые байты, загруженные разными пользователями, дедуплицируются в один объект.
2. Конфигурация Java-сервера
public.files.enabled=true
public.files.storageDir=data/public-files
public.files.maxBytes=536870912
Для production рекомендуется задать public.files.storageDir абсолютным путём, который одновременно доступен Java для записи и Caddy для чтения.
Например:
/home/player/shine-public-files
3. PUT /files/<sha256>
Загружает immutable public file. PUT требует активную пользовательскую сессию.
Заголовки:
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:
PUBLIC_FILE_UPLOAD_V1:{sessionId}:{sha256}:{size}:{timeMs}
Сервер потоково принимает байты, заново считает SHA-256 и принимает объект только если:
SHA256(received bytes) == sha256 из URL
Если корректный объект уже существует и размер совпадает, PUT идемпотентно отвечает alreadyExists=true.
4. GET и HEAD
Java servlet умеет GET и HEAD как fallback. В production рекомендуется не пропускать чтение через Java: Caddy должен отдавать файл непосредственно с диска.
Ответ immutable:
Cache-Control: public, max-age=31536000, immutable
ETag: "<sha256>"
Content-Type: application/octet-stream
Файловое хранилище не определяет тип контента. Официальный клиент решает, как интерпретировать байты, на основании имени nm из S:att. Если пользователь указал неверное расширение или положил неподходящие байты, клиент просто не сможет отобразить такой media-файл.
5. Связь с S:att
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>>
означает public file на текущем сервере доступа автора.
<S:att;v=1;nm=photo.jpg;sz=12345;sha256=<64 hex>;ar=<txId>>
означает Arweave.
Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит:
https://<current-access-server>/files/<sha256>
6. Preview
Отдельных preview-файлов сейчас нет. preAr, preSha256, previewAr, previewSha256 не являются частью текущего протокола.