# Codex Gateway

Сервис владельца · безопасные снимки интерфейса

Codex Gateway — Ruby proxy перед модельным API. Он управляет несколькими конфигурациями доступа, выборочно инспектирует только Codex-трафик, проксирует HTTP, SSE и WebSocket и считает usage по пользователям. Копия очищенных событий уходит в ограниченный outbox и NATS, не блокируя основной запрос Codex.

Версия исходников: 5a8e7e332b818df4482e4554fa724f76853741d0

Разработка и эксплуатация: 2026. Снимки подготовлены 8 сентября 2026.

## Задача

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

Владелец управляет доступом и статистикой в закрытом интерфейсе; Codex-клиенты используют отдельные proxy credentials; Synadia получает только очищенную копию событий.

## Выполнено

- Реализовал Ruby proxy и маршрутизацию CONNECT с выборочной TLS-инспекцией доменов Codex.
- Добавил HTTP, SSE и WebSocket transport, потоковый разбор usage и восстановление соединений.
- Связал конфигурации доступа, proxy-пользователей, лимиты, статистику и административный интерфейс.
- Добавил неблокирующий outbox и отправку очищенных событий в NATS для Synadia Live Monitor.

## Что отличает реализацию

Gateway объединяет управление доступом, потоковый transport и наблюдаемость в одном Ruby-процессе, но выводит мониторинг из критического пути. Выборочная TLS-инспекция ограничена Codex-доменами; event copy очищается до NATS. Поэтому Synadia получает живые данные, а сбой NATS не прерывает работу Codex.

## Состав прикладного кода

- Ruby MITM / HTTP / SSE / WebSocket: 86.1%
- Ruby event observer / outbox: 13.9%

Доли по размеру прикладных файлов Git в закреплённой версии. Каждый файл отнесён к одной подсистеме по правилам scripts/generate-stack-share.mjs; тесты, ассеты, зависимости и generated-файлы исключены. Округление — до 0,1%. Это состав кода, а не уровень владения технологиями. Для Gateway измеряются два отслеживаемых Ruby-модуля proxy и observer; библиотеки базового образа в расчёт не входят.

## Стек

| Технология | Роль |
| --- | --- |
| Ruby | MITM proxy, маршрутизация CONNECT и сервер административного интерфейса. |
| OpenSSL | Локальные сертификаты и выборочная инспекция разрешённого трафика. |
| HTTP / SSE / WebSocket | Обычные и потоковые запросы Codex, reconnect и usage. |
| NATS / outbox | Неблокирующая доставка очищенных событий в мониторинг. |

## Архитектура

- TLS-инспекция включается только для разрешённых Codex-hostnames; остальной CONNECT остаётся обычным туннелем.
- Основной ответ клиенту не ждёт NATS: при недоступности мониторинга событие попадает в ограниченный outbox, а Codex продолжает работу.
- SSE и WebSocket разбираются по мере поступления с учётом разделённых сообщений, UTF-8 и reconnect.
- Секретные заголовки и токены исключаются до формирования события мониторинга.

### Поток Codex-трафика и очищенных событий

![Поток Codex-трафика и очищенных событий](https://komaroff-dev.ru/evidence/codex/diagrams/flow.svg)

[Mermaid](https://komaroff-dev.ru/evidence/codex/diagrams/flow.mmd)

### Размещение owner-интерфейса и хранилищ

![Размещение owner-интерфейса и хранилищ](https://komaroff-dev.ru/evidence/codex/diagrams/deployment.svg)

[Mermaid](https://komaroff-dev.ru/evidence/codex/diagrams/deployment.mmd)

## Code-map

| Функция | Экран / API | Модуль | Данные / проверка |
| --- | --- | --- | --- |
| CONNECT / TLS | Proxy CONNECT endpoint | proxy.rb: handle_connect; codex_interception_required? | OpenSSL; permitted hostnames and relay checks |
| HTTP / SSE / WebSocket | Forwarded model requests | proxy.rb: forward_request; forward_websocket_request | Response streams, usage and observer tests |
| Configurations / usage | Owner dashboard / control API | proxy.rb: handle_control_request; AssetStore | JSON files; active configuration and usage aggregates |
| Monitoring events | Bounded outbox → NATS | docker/monitor/observer.rb | Sanitized events; fragmented secrets and overflow tests |

Перед изменением пройти связи экран → API → состояние → хранилище. Проверить входы, ошибки и повторные действия. Обновить карту и схемы вместе с кодом, выполнить связанные проверки и привязать материалы к версии.

## Сценарии

- Открыть закрытую панель и проверить активную конфигурацию, сроки и состояние обновления.
- Сопоставить usage proxy-пользователя с агрегатами за 24 часа и 7 дней.
- Проверить прохождение HTTP, SSE и WebSocket и состояние Ruby proxy.
- Открыть документацию proxy и границы TLS-инспекции.

## Проверки

- Проверка health, HTTP и потоковых transport с сохранением ответа клиенту.
- Проверка очистки секретных заголовков и переполнения ограниченного outbox.
- Browser QA dashboard, sessions, stats and mobile layout after DOM-only masking.

## Результаты

- Рабочий Gateway обслуживает Codex-клиентов и показывает агрегированный usage по отдельным proxy-пользователям.
- Восемь снимков получены с действующего экземпляра; серверные данные не изменялись, ошибок страницы не обнаружено.

## Ограничения

- Административный интерфейс закрыт Basic Auth; публичная страница содержит только обезличенные снимки.
- Снимки показывают реальные агрегаты, но аккаунты и конфигурационные значения заменены в DOM перед кадром.
- Tracing в самом Gateway не является источником публичного эфира: живые события передаются в отдельный Synadia-контур.

## Запуск и эксплуатация

Gateway запускается как отдельный контейнер на loopback, а Nginx публикует только закрытый административный интерфейс.

Недоступность NATS не останавливает основной proxy-поток. Отключение сбора через MONITOR_ENABLED=false требует пересоздания proxy и краткого переподключения активных соединений.

## Скриншоты

[Панель Gateway показывает активную конфигурацию, сроки токенов и агрегированный расход по пользователям. Видимые аккаунты заменены только в DOM перед снимком.](https://komaroff-dev.ru/evidence/codex/full/01-dashboard.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Раздел сессий отделяет трассировку proxy-запросов от общей статистики и явно показывает отсутствие сохранённых trace-записей.](https://komaroff-dev.ru/evidence/codex/full/02-sessions.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Служебная статистика показывает состояние Ruby proxy, transport counters и ошибки без доступа к содержимому секретных заголовков.](https://komaroff-dev.ru/evidence/codex/full/03-service-stats.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Встроенная документация описывает границу выборочной TLS-инспекции и прохождение HTTP, SSE и WebSocket.](https://komaroff-dev.ru/evidence/codex/full/04-proxy-docs.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Карточка конфигурации показывает жизненный цикл доступа и диагностические состояния; значения аккаунта и конфигурации подменены на снимке.](https://komaroff-dev.ru/evidence/codex/full/05-config.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Карточка proxy-пользователя связывает запросы, расход токенов и состояние доступа без раскрытия ключа пользователя.](https://komaroff-dev.ru/evidence/codex/full/06-user-usage.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Мобильная панель сохраняет графики, статусы конфигураций и переключатели состава токенов в одной вертикальной колонке.](https://komaroff-dev.ru/evidence/codex/full/07-dashboard-mobile.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Мобильный раздел сессий сохраняет навигацию и явное пустое состояние трассировки.](https://komaroff-dev.ru/evidence/codex/full/08-sessions-mobile.png) — 2026-09-08T06:40:00Z, 5a8e7e332b818df4482e4554fa724f76853741d0.

[Материалы](https://komaroff-dev.ru/downloads/codex-materials.zip)