# TODO — публичные вложенные файлы ## Цель Довести публичную раздачу вложений до production-схемы: сервер SHiNE остаётся origin-хранилищем файлов, а Cloudflare используется перед ним для HTTPS, кэширования и CDN. Отдельный CDN-сервис на данном этапе не требуется, если Cloudflare нормально кэширует ответы серверного file endpoint. --- ## 1. Настроить Cloudflare - Подключить домен/поддомен для публичных вложений. - Проксировать file endpoint через Cloudflare. - Проверить HTTPS. - Настроить Cache Rules для публичных неизменяемых файлов. - По возможности использовать длинный TTL для файлов, адресуемых по хэшу/ID. - Проверить корректную работу Range-запросов и ответов `206 Partial Content`. - Не кэшировать служебные API-ответы и ошибки, которые кэшировать не нужно. ### Предпочтительная схема Client → Cloudflare → SHiNE server file endpoint → локальное файловое хранилище сервера То есть отдельную CDN-реализацию внутри SHiNE делать не обязательно: сервер должен корректно отдавать файлы, а Cloudflare занимается внешним кэшем/CDN. --- ## 2. Полноценная HTTP-отдача файлов Для публичного file endpoint реализовать/проверить: ### GET - Полная отдача файла. - Правильный `Content-Type`. - Правильный `Content-Length`. - `Content-Disposition`, где это необходимо. - Стабильное имя/ID файла в URL. - Корректный `404`, если файла нет. ### HEAD - Те же HTTP-заголовки, что и для `GET`, но без тела файла. - Нужен для проверки размера, типа и существования файла. - Не должен читать весь файл в память. ### Range requests Поддержать: `Range: bytes=start-end` и ответ: `206 Partial Content` с корректными: - `Accept-Ranges: bytes` - `Content-Range` - `Content-Length` Также обработать: - `bytes=N-` - при необходимости `bytes=-N` - некорректный диапазон → `416 Range Not Satisfiable` Важно: сервер не должен загружать весь большой файл в RAM ради выдачи небольшого диапазона. --- ## 3. Докачка файлов Клиент должен иметь возможность продолжить загрузку после обрыва. Сценарий: 1. Клиент уже скачал первые N байт. 2. Повторный запрос отправляется с: `Range: bytes=N-` 3. Сервер возвращает остаток через `206 Partial Content`. Желательно дополнительно использовать: - `ETag` - `Last-Modified` - `If-Range` Это позволит убедиться, что докачивается та же версия файла. --- ## 4. Кэширование Для неизменяемых публичных файлов желательно: - адресовать файл стабильным ID/хэшем; - после публикации не изменять содержимое под тем же ID; - отдавать подходящий `Cache-Control`; - использовать `ETag`. Если содержимое изменилось — лучше создавать новый объект/ID, а не менять содержимое старого URL. --- ## 5. Безопасность и корректность Проверить: - защиту от `../` и path traversal; - невозможность запросить произвольный файл сервера; - ограничения допустимых директорий; - корректность MIME-type; - лимиты размера; - отсутствие передачи внутренних filesystem-path клиенту; - логирование подозрительных и битых запросов. --- ## 6. Garbage Collector / проверка файлов — позже Добавить фоновый или периодический сборщик мусора. Он должен уметь: ### Проверять физические файлы - существует ли файл; - соответствует ли размер; - соответствует ли SHA-256/ожидаемый hash; - не повреждён ли файл; - есть ли для него запись в БД. ### Проверять БД - есть ли физический файл для каждой актуальной записи; - нет ли записей, указывающих на отсутствующие файлы. ### Находить orphan-файлы Файлы, которые лежат на диске, но больше ни на что не ссылаются. На первом этапе безопаснее: - только находить; - писать отчёт; - ничего автоматически не удалять. Позже можно добавить grace period: orphan найден → помечен → повторно проверен через несколько дней → только потом допускается удаление. ### Никогда сразу не удалять До появления уверенной reference-модели GC должен работать в режиме аудита. --- ## 7. Метрики и обслуживание — желательно позже Добавить базовые метрики: - объём файлов на диске; - количество файлов; - число GET / HEAD / Range запросов; - объём исходящего трафика; - доля `206`; - `404` / `416`; - ошибки чтения файлов; - количество orphan/corrupted файлов по результатам GC. --- ## Приоритет реализации ### Сначала 1. `GET` 2. `HEAD` 3. `Range` / `206 Partial Content` 4. нормальная докачка 5. `ETag` / `If-Range` 6. Cloudflare перед file endpoint 7. Cache Rules ### Затем 8. мониторинг 9. проверка целостности файлов 10. garbage collector в audit-only режиме 11. автоматическая очистка только после отдельного решения --- ## Основное архитектурное решение На текущем этапе отдельный собственный CDN-слой SHiNE не нужен. **SHiNE server = origin файлов** **Cloudflare = внешний CDN/cache** Сервер должен корректно поддерживать стандартный HTTP для больших файлов и частичной выдачи. Тогда браузеры, загрузчики и Cloudflare смогут нормально работать с файлами без отдельного протокола SHiNE для скачивания.