7.1 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 (включая 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 (base64url 43 characters), 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>.
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.