6.3 KiB
Публичные вложения SHiNE: Cloudflare R2 и legacy API
Действующий формат (15.11.2026)
Новые публичные файлы и аватары используют BitTorrent v2 Pieces Root, закодированный Base58 (32 байта; строка обычно 43–44 символа). Идентификатор не зависит от имени и MIME. Клиент вычисляет корень по подготовленным байтам. Содержимое файла не проходит через Java.
- R2 bucket:
shine-files. - Публичный GET:
https://files.<домен access-сервера автора>/<PR>(ключ объекта =PR, без расширения). - Предпросмотр публичных изображений и видео использует прямой URL. Картинки
loading="lazy"; публичные видео получаютsrcтолько у видимой области черезIntersectionObserverи запрашивают метаданные после входа в область. В старом браузере используется обычная загрузка metadata. - Отдельных preview-файлов нет. Скачивание/просмотр медиаконтента выполняет сам браузер (в том числе HTTP Range, если доступен).
- Тип определяется по
mm, затем по расширениюnm; HTTPContent-Typeобъекта задаётся при PUT. Неизвестные файлы —application/octet-stream. - HTML, SVG и похожие активные типы отображаются как обычные файловые карточки. Перед открытием из публичного интерфейса показывается предупреждение с возможностью отмены. Это не серверная санитаризация и не гарантия безопасности прямого URL.
Формат публичного вложения (версия тега остаётся 1):
<S:att;v=1;nm=photo.jpg;sz=123456;pr=BASE58_ROOT;mm=image/jpeg>
При использовании Arweave дополнительно передаётся ;ar=TXID — существующая загрузка Arweave/Turbo не меняется. Источник выбирается по ar (если есть), иначе R2 по pr. Не добавлять storage=r2 в постоянные записи. Общее описание — docs/Blockchain/15_TEXT_Attachments.md.
Новые аватары: <S:ava;v=2;sz=N;pr=BASE58_ROOT[;ar=TXID]>. SHA-256 hex остаётся лишь в исторических файловых маршрутах, новые аватары SHA-256 не создают. Старые аватары v1 не мигрируются автоматически (v41 сбрасывает старые ссылки каналов).
Выдача разрешения на загрузку
POST /api/files/prepare (JSON):
{"pr":"BASE58_ROOT","size":123456,"mm":"image/jpeg"}
Сессионная Ed25519-подпись обязательна. Заголовки:
X-Shine-Session-IdX-Shine-Time-MsX-Shine-Signature
Подписываемая строка PUBLIC_R2_PREPARE_V1:{sessionId}:{pr}:{size}:{mm}:{timeMs}.
Сервер проверяет авторизацию, Base58 32-байтного PR, размер (≤500 МиБ), MIME, выполняет S3 HeadObject. Если объект уже существует с тем же размером — возвращает exists:true; если нет — uploadUrl, requiredHeaders, fileUrl. Браузер делает один Presigned PUT прямо в S3 Endpoint R2 с обязательными подписанными заголовками, включая If-None-Match: * для защиты от перезаписи. Действие не использует R2 credential в браузере.
Java не проверяет реальный Pieces Root содержимого и не гарантирует строгий объём через один заявленный клиентом size; нет Multipart, квот или автоматической проверки фактического PUT после выдачи URL. Неверный PR у первоначального объекта может нарушать дедупликацию — это известный компромисс MVP.
Конфигурация сервера: R2_ENDPOINT, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, r2.publicBucket=shine-files. CORS корзины должен разрешать origin PWA и PUT с подписанными заголовками. Ключи — только на сервере.
Исторический локальный API SHA-256
Старый PublicFileServlet обслуживает /files/<64 lowercase hex SHA-256> на локальном диске (public.files.storageDir). Для старых файлов может продолжать работать GET/HEAD/PUT с проверкой SHA-256 и HTTP Range. Новые pr-файлы туда не загружаются. Детали legacy передавать только при поддержке исторических данных, не использовать этот API в новых тегах.
Учёт разрешений R2 (PostgreSQL v42)
В public_file_uploads пишется событие после успешной авторизации и решения S3: логин, PR, заявленный размер, requested_at, disposition (upload_url_issued или already_exists). Это журнал выдачи разрешения/повторного использования, а не доказательство завершённого PUT. Повторные попытки фиксируются отдельными строками. Лимитов и блокировок по журналу пока нет. Параллельная таблица DM описана в docs/API/18_DM_File_Storage_API.md.