# HTTP API публичных файлов каналов ## 1. Назначение Публичное вложение может храниться не в Arweave, а на текущем сервере доступа автора. Файловый слой намеренно максимально простой: он хранит только байты, адресованные их SHA-256. Канонический URL: ```text /files/ ``` `sha256` — lowercase hex, ровно 64 символа. На диске сервер хранит один глобальный объект: ```text / ``` Имя пользователя, исходное имя файла, расширение, 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/` Загружает immutable public file. PUT требует активную пользовательскую сессию. Заголовки: ```text Content-Type: application/octet-stream X-Shine-Session-Id: X-Shine-Time-Ms: X-Shine-Content-Length: X-Shine-Signature: ``` Подписываемая строка 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 (включая HTTP Range) Java servlet обслуживает `GET /files/` и `HEAD /files/`. Проверка SHA-256 **при чтении не выполняется**: хеш проверяется при исходном PUT, файл immutable, а скачивание не должно требовать предварительного прочтения всех байтов. Проверка корректности при повторном PUT уже имеющегося объекта сохранена. Полный GET, как и прежде, возвращает `200 OK` и `Content-Length` всего файла. HEAD всегда возвращает метаданные **полного объекта** без тела и без обхода всего файла по байтам (Range в HEAD игнорируется). Для `GET` с одним диапазоном: ```http Range: bytes=0-262143 ``` Ответ: ```http HTTP/1.1 206 Partial Content Accept-Ranges: bytes Content-Range: bytes 0-262143/<общий размер> Content-Length: 262144 ETag: "" ``` Поддерживаются формы `bytes=START-END`, `bytes=START-` и `bytes=-SUFFIX`. Для составных или неудовлетворяемых диапазонов сервер возвращает `416` + `Content-Range: bytes */<общий размер>`. `If-Range` поддерживает точный совпадающий ETag; при несовпадении возвращается полный `200`. Остальные заголовки: ```http 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` ```text > ``` означает public file на текущем сервере доступа автора. ```text ;ar=> ``` означает Arweave. Адрес сервера доступа в блок не записывается. При чтении клиент определяет текущий access server автора через его PDA и строит: ```text https:///files/ ``` ## 6. Preview В UI видео со storage=server получает прямую ссылку `/files/` (без полного `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/` 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/`; 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.