# Техническая документация СлойРА

> Редакция 0.1 · 27 сентября 2026 года. Описание продукта и проектная спецификация технической реализации.

СлойРА — программный слой управления доступом, кешированием и размещением контента.
Клиентская поставка 2.1.74 использует отдельную конфигурацию Nginx с модулями
secure_link/auth_request и Python-агентом для проверки лицензии и чтения контента.
Lua и нативный модуль Nginx описаны в целевой архитектуре;
нативный бинарный модуль в текущий архив не включён.

Файлы, изображения, документы, видеозаписи и сегменты потокового видео
проходят через общую систему учёта популярности.
Часто востребованные данные получают место в оперативной памяти и на быстрых дисках.
Редко используемые данные остаются на более ёмких носителях.
Сервер доставки передаёт сведения о запросах и промахах кеша в контур размещения Ceph,
чтобы выбор класса хранения учитывал работу всей системы.

## Как читать эту редакцию

Документация содержит два уровня утверждений.

| Уровень | Что означает |
| --- | --- |
| Описание продукта | Функциональность, сообщённая разработчиком: Nginx, Lua, защита с ответом 403, многоуровневый кеш, учёт популярности и связь с Ceph |
| Проектная спецификация | Предложенные технические решения: форматы конфигурации, API, алгоритмы, имена метрик, управляющий агент, процедуры миграции и критерии приёмки |

Для поставки 2.1.74 есть исходные компоненты, проверенный ZIP и результаты
компонентных проверок и установки с настоящим Nginx на macOS и Linux x86_64.
Проверены подписи лицензии, ограниченные онлайн-разрешения, защита cache HIT,
локальные уровни хранения и контракт Ceph-адаптера. Работа с настоящим
Ceph-кластером, нагрузочные показатели и все перечисленные платформы этим
не подтверждаются. Проектные API и расширения в остальных разделах остаются
целевыми контрактами и не означают, что каждый из них уже реализован.

Для установки используйте инструкции внутри персонального ZIP действующей
поставки: `README.md`, `docs/INSTALL.md`, `docs/LICENSING.md`, `docs/OPERATIONS.md`
и `docs/API.md`. Они описывают фактические команды и параметры этого выпуска.
В 2.1.74 heartbeat выполняется раз в 60 секунд, онлайн-разрешение действует
не более 300 секунд; без связи новые запросы прекращаются по истечении
последнего разрешения. Подписанное продление применяется через `license-update`.

Примеры настроек и числовые значения относятся к демонстрационным профилям.
Перед применением их сопоставляют со схемой конкретного выпуска,
ресурсами узла и требованиями к доступности данных.

## Что решает СлойРА

### Контроль доступа перед выдачей контента

Каждый запрос сначала проходит проверку легитимности.
Политика может учитывать подпись ссылки, срок действия, область доступа,
разрешённые методы и ограничения клиента.
Если право доступа не подтверждено, сервер возвращает HTTP 403.

Проверка выполняется и для содержимого, уже находящегося в кеше.
Наличие быстрой локальной копии не даёт клиенту дополнительных прав.
Ограничение частоты запросов и отказ инфраструктуры имеют отдельные причины
и диагностические коды.

### Размещение в RAM и на дисках

Кеш доставки состоит из оперативной памяти и выбранных дисковых уровней.
NVMe и SATA/SAS SSD рассматриваются как разные эксплуатационные профили.
HDD используется для объектов, которым не требуется дорогой быстрый уровень.

Решение учитывает частоту обращений, размер объекта, давность последнего запроса,
стоимость повторного чтения и доступное место.
Однократная загрузка очень большого файла не должна вытеснять всю горячую выборку.
Защита от массового обхода каталога входит в политику допуска в кеш.

### Обратная связь для Ceph

Кеш меняет нагрузку на исходное хранилище.
Большое число обращений может обслуживаться в памяти и быть невидимым для Ceph.
Поэтому проект предусматривает два самостоятельных сигнала:
логический спрос клиентов и фактические чтения из исходного хранилища.

На их основе контроллер строит очередь размещения.
Объекты переводятся между подготовленными классами хранения
с учётом целостности, свободного места, квот и состояния кластера.
Изменение размещения не должно менять публичный адрес файла.

## Два контура хранения

```text
Клиент
  |
  v
Nginx + плагин СлойРА + политика Lua
  |
  +-- проверка доступа --> отказ 403
  |
  +-- RAM --> NVMe / SSD --> HDD
  |             локальный кеш доставки
  |
  +-- исходное хранилище Ceph
          |
          +-- горячий пул / класс SSD
          +-- холодный пул / класс HDD

Учёт запросов и промахов
  --> локальная очередь событий
  --> агрегатор спроса
  --> контроллер размещения
  --> проверяемый перенос объекта
```

Локальный кеш можно восстановить из исходного хранилища.
Он не заменяет механизм долговечности Ceph и не учитывается как резервная копия.
Перемещение исходного объекта между пулами имеет другие требования,
чем вытеснение его временной копии из кеша.

В этой редакции основной сценарий интеграции — выделенные пулы и каталог размещения.
Вариант с RGW описывается отдельно, поскольку S3-адресация, storage classes
и прямой доступ RADOS требуют разных адаптеров.

## Маршруты чтения

| Задача читателя | Разделы |
| --- | --- |
| Оценить применимость | Обзор, архитектура, ёмкость и экономика |
| Подготовить сервер | Платформы и установка, Nginx и Lua, эксплуатация |
| Настроить доступ | Защита доступа, HTTP-доставка, справочник конфигурации |
| Разобраться с кешем | Иерархия кеша, популярность, наблюдаемость |
| Подключить Ceph | Интеграция с Ceph, контракты API, эксплуатация |
| Принять реализацию | Проверки и runbooks, каталог сценариев |
| Написать интеграцию | Nginx и Lua, контракты API, справочник конфигурации |

## Языки и компоненты

| Компонент | Технология | Статус в этой редакции |
| --- | --- | --- |
| HTTP-сервер | Nginx | Основа продукта по описанию разработчика |
| Политики обработки | Lua | Реализация указана разработчиком |
| Нативный модуль | C17, динамический HTTP-модуль | Предложенная техническая реализация |
| Среда Lua | LuaJIT с языковым профилем Lua 5.1 | Целевой вариант интеграции |
| Локальный агент | Rust | Предложенный управляющий компонент |
| Контроллер размещения | Rust, адаптер Ceph | Предложенный управляющий компонент |
| Формат настроек | YAML с версионированием схемы | Проектный контракт |
| Обмен событиями | JSON; пакетная передача через HTTPS | Проектный контракт |
| Диагностика | Метрики Prometheus и структурированные журналы | Проектный контракт |

Выбор C и Rust разделяет обработку HTTP-запросов и фоновые операции.
Рабочий процесс Nginx не должен ожидать сканирования диска,
пакетной отправки телеметрии или переноса объектов Ceph.
Lua используется для контролируемой политики запроса,
а не для запуска произвольных блокирующих операций в обработчике.

## Платформы

Основной целевой профиль — Linux на x86_64.
В матрицу квалификации включены Ubuntu LTS, Debian,
а также семейства Rocky Linux и AlmaLinux.
ARM64 рассматривается как отдельный профиль сборки и испытаний.

Указание дистрибутива в проектной матрице не является сертификатом совместимости.
Для выпуска фиксируются точные версии ОС, ядра, Nginx, LuaJIT,
библиотек и адаптера Ceph.
Динамический модуль проверяется с конкретной ABI-конфигурацией Nginx.

Windows и macOS могут использоваться для работы с документацией и разработки,
но в этой редакции не являются целевыми производственными ОС сервера доставки.

## Экономия и измерения

Разработчик сообщает об экономии дискового пространства до 70%.
В этой редакции значение сохраняется как заявленный результат,
для которого ещё требуется опубликованная методика и воспроизводимый протокол.

Перенос объекта с SSD на HDD сам по себе не уменьшает число логических байтов.
Он уменьшает потребность в быстром классе хранения.
Уменьшение общего физического объёма возможно только при изменении
количества временных копий, правил кеширования или других явно измеряемых факторов.
Сравнение должно сохранять одинаковые требования к долговечности данных.

В разделе ёмкости отдельно рассчитываются логический объём,
физическое размещение с репликацией, локальный кеш,
миграционный резерв и стоимость используемых носителей.

## Границы защиты

Проверка запроса позволяет ограничить автоматизированный доступ
к контенту и снизить несанкционированную загрузку.
Она не даёт абсолютной защиты от копирования уже выданных данных.
Клиент с действительными правами может получать разрешённые ему байты.

СлойРА дополняет TLS, сетевую защиту, правила выдачи ссылок
и безопасность приложения владельца контента.
Идентификатор клиента не следует сводить только к IP-адресу:
NAT, мобильные сети и прокси делают такой признак неоднозначным.

## Установка и выпуск

Продукт поставляется отдельно от Nginx.
Целевой комплект включает модуль, политики Lua,
управляющий агент, схему настроек и документацию выпуска.

Действующая модель поставки предусматривает ZIP-архив,
ключ и инструкцию в кабинете покупателя после подтверждения оплаты.
Команды получения пакетов из публичного репозитория не предполагаются,
пока такой репозиторий не опубликован и не включён в описание выпуска.

Администратор клиента выполняет установку, настройку и обновление.
Лицензия включает обновления и исправления ошибок.
Срок начинается после подтверждения оплаты; продление выполняется вручную.
Точный регламент проверки лицензии и поведения при её недоступности
должен быть согласован отдельно от технических примеров этого справочника.

## Принципы реализации

- Авторизация предшествует выдаче любого байта защищённого объекта.
- Идентичность кеша включает арендатора, объект и версию содержимого.
- Физическое чтение из Ceph не приравнивается к числу клиентских запросов.
- Повторная доставка телеметрии не должна удваивать счётчики спроса.
- Сбой аналитики не должен останавливать уже разрешённую выдачу контента.
- Решение о размещении воспроизводимо по версии политики и входному окну.
- Перенос не удаляет исходную копию до проверки новой и переключения каталога.
- Нехватка места учитывается до начала копирования и во время переноса.
- Откат настроек восстанавливает последнюю проверенную конфигурацию.
- Секреты, подписи ссылок и содержимое файлов не попадают в телеметрию.

## Версионирование документации

Номер этой редакции относится к документу, а не к выпущенной версии программы.
Перед выпуском команда связывает редакцию справочника с артефактами сборки,
схемой конфигурации и результатами приёмки.

При несовместимом изменении контракта повышается его основная версия.
Добавление необязательного поля допускается только с определённым поведением
для старого получателя.
Изменение единиц измерения или смысла существующего поля
не считается совместимым расширением.

Исправления этой редакции должны сохранять различие между описанием продукта,
целевым поведением и результатами, подтверждёнными испытаниями.