Files
SHiNE-server/TODO/PUBLIC_ATTACHMENTS_TODO.md

214 lines
7.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 для скачивания.