Files
SHiNE-server/docs/API/21_Public_File_Storage_API.md
T

8.6 KiB
Raw Blame History

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 (включая HTTP Range)

Java servlet обслуживает GET /files/<sha256> и HEAD /files/<sha256>. Проверка SHA-256 при чтении не выполняется: хеш проверяется при исходном PUT, файл immutable, а скачивание не должно требовать предварительного прочтения всех байтов. Проверка корректности при повторном PUT уже имеющегося объекта сохранена.

Полный GET, как и прежде, возвращает 200 OK и Content-Length всего файла. HEAD всегда возвращает метаданные полного объекта без тела и без обхода всего файла по байтам (Range в HEAD игнорируется).

Для GET с одним диапазоном:

Range: bytes=0-262143

Ответ:

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 0-262143/<общий размер>
Content-Length: 262144
ETag: "<sha256>"

Поддерживаются формы bytes=START-END, bytes=START- и bytes=-SUFFIX. Для составных или неудовлетворяемых диапазонов сервер возвращает 416 + Content-Range: bytes */<общий размер>. If-Range поддерживает точный совпадающий ETag; при несовпадении возвращается полный 200.

Остальные заголовки:

Cache-Control: public, max-age=31536000, immutable
Cross-Origin-Resource-Policy: cross-origin
Access-Control-Allow-Origin: *

Тип для MP4, WebM, Ogg и AVI Java определяет по первым байтам файла. Неизвестные типы остаются application/octet-stream. Протокол S:att не меняется, имя файла/тип на сервере не сохраняются.

При прямой выдаче Caddy (file_server) Range обеспечивает Caddy, а не Java. Следует проверить Content-Type (у файлов с именем SHA-256 нет расширения), а также корректность ответа 206 через публичный домен, особенно с CDN. Если нужен корректный MIME по сигнатуре, используйте HTTP reverse_proxy к Java из инструкции deploy/PUBLIC_FILES_CADDY_CLOUDFLARE.md.

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

В UI видео со storage=server получает прямую ссылку /files/<sha256> (без полного fetch в Blob): браузер сам запрашивает диапазоны, читает длительность и загружает стартовый кадр. Размер берётся из sz вложения. Для Arweave частичная загрузка зависит от gateway.

Отдельных preview-файлов сейчас нет. preAr, preSha256, previewAr, previewSha256 не являются частью текущего протокола.

R2 direct upload (MVP, 2026-11)

New public attachments use BitTorrent v2 pr (canonical Base58 encoding of the 32-byte Pieces Root, normally 43–44 characters, variable length 32–44), mm (optional MIME) and v=1. Avatars retain the original SHA-256 /files/<sha256> API. The client signs PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs} with its Ed25519 session key, submits JSON {pr,size,mm} to POST /api/files/prepare and provides X-Shine-Session-Id, X-Shine-Time-Ms and X-Shine-Signature. The endpoint returns exists, fileUrl, and for missing objects uploadUrl and requiredHeaders. The browser uploads the original Blob directly to the S3 endpoint, not the Java server. A signature does not certify the hash of uploaded content. The public GET URL is https://files.shineup.me/<pr>; the R2 object key is exactly the same Base58 pr (no extension). Old Base64URL PR identifiers are not read or migrated. Arweave TX IDs and DM file identifiers keep their existing encodings. Client and Java server must be updated together.

Configuration: R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, r2.publicBucket=shine-files (or r2.endpoint, r2.accessKeyId, r2.secretAccessKey in trusted server config). Never publish keys. Configure browser CORS to permit signed PUT headers including If-None-Match. Max size: 500 MiB. Single PUT only, no multipart in this MVP.

Единый формат публичных идентификаторов

Аватарки и публичные вложения имеют одинаковый PR = Base58(BitTorrent v2 Pieces Root) и сохраняются в корень R2 bucket shine-files, URL https://files.shineup.me/<PR>. Папки avatars/ нет; загрузка идёт через /api/files/prepare, не через /api/avatars/prepare. После оптимизации изображения вычисляется PR от именно передаваемых байтов. <S:ava;v=2;sz=N;pr=BASE58[;ar=TXID]>; ar остаётся нативным Arweave TX ID в Base64URL. Старые <S:ava;v=1;...sha256=...> не поддерживаются.

Для потенциального будущего SHA-256 типа идентификатора публичного файла используем Base58(SHA-256(bytes)), а не hex. Это отдельный алгоритм, его нельзя смешивать с PR. На данный момент новые публичные вложения/аватарки не используют SHA-256 как идентификатор.