Skip to content

v1.25.0: Hardened Community Edition (132 Issues Resolved)

Choose a tag to compare

View all tags
@Frozen811 Frozen811 released this 25 Sep 07:14
· 68 commits to main since this release
v1.25.0
2cee5a8

codex-lb (Hardened Community Edition)

Production-ready, thoroughly verified, high-reliability distribution of Soju06/codex-lb

🌐 English Overview

Executive Summary

codex-lb Hardened Community Edition is a comprehensive, production-grade release of codex-lb incorporating 100% verified solutions for all 132 tracked issues and 85 community Pull Requests.

While the upstream repository established powerful load-balancing and account-pooling concepts, production environments at scale suffered from critical failure modes:

  1. HTTP/2 Transport Cascades: A single dropped stream in Native Egress severed the underlying HTTP/2 connection, abruptly terminating all concurrent streams across all accounts.
  2. Stream Cap Freezes: Streams interrupted before terminal events leaked their concurrency leases, permanently exhausting account_stream_cap until restart.
  3. Upstream Contract Breaches: OpenAI/Codex API breaking changes (such as rejecting max_output_tokens with HTTP 400 and rejecting compaction triggers with HTTP 404) broke account health probes and automatic window warmup.
  4. SQLite Concurrency Deadlocks: Intense multi-stream burst traffic produced unrecoverable database locks ("database is locked" errors).
  5. Session wedging: Injected anchors rejected by upstream (previous_response_not_found) caused client hangs without yielding terminal error events.

In this edition, every single reported defect was verified and resolved directly at the root cause in the source code, accompanied by dedicated unit and integration regression tests and validated against OpenSpec specifications.

Key Architectural Fixes & Enhancements

1. Native Egress, Rust Network Engine & HTTP/2 Multiplexing

  • Stream Cascade Isolation (#2471, #2470):
    • Implemented strict per-stream lifecycle boundaries. A network drop on one stream no longer tears down the shared HTTP/2 connection.
    • Added deterministic finally: await stream.aclose() blocks in _stream_response_error_events and egress adapters, guaranteeing that account_stream_cap leases are freed immediately upon disconnection.
    • Settle account leases and circuit states before error-health state writes.
  • Backpressure & Connection Recovery:
    • Bound Native Egress worker queues to prevent unbounded memory growth during downstream stalls.
    • Idle disconnects on pooled connections no longer mark healthy accounts as unhealthy.

2. HTTP-to-WebSocket Bridge & Replay Relocation

  • Terminal Event Delivery on Injected Anchor Rejection (#2493):
    • When upstream returns previous_response_not_found on an injected continuation anchor and no fresh replay is available, the bridge now explicitly emits a terminal response.failed event with standardized error envelopes, preventing downstream client hangs.
  • Replay Relocation Engine (PR #2428):
    • Integrated app/modules/proxy/replay_relocation.py (RelocationInputs, RelocationVerdict, decide_relocation).
    • Added pure transcript reconstruction (project_durable_transcript_for_account_neutral_fresh_replay), positive item enumeration, and tail overlap resolution in app/modules/proxy/replay_safety.py.
  • Session Quarantine & Takeover:
    • Stale and abandoned bridge sessions are retired gracefully without pinning shutdown or blocking database writers.

3. Upstream Codex / OpenAI Responses Compatibility

  • Force Probe Modernization (PR #2496, #2410):
    • Removed unsupported max_output_tokens field from Force Probe payloads in app/modules/accounts/service.py. The Codex Responses endpoint now rejects this field with HTTP 400; omitting it allows probes to succeed with HTTP 200 and wake rate limiters properly.
  • Transparent Warmup Compaction Fallback (#1895, #1976):
    • Added automatic fallback to minimal plain Responses API requests when upstream returns 404 on compaction_trigger, allowing /v1/warmup to reliably initialize 5-hour quota windows.
    • Corrected rolling quota reset deadline calculations for multi-account pools.

4. Dashboard, Web UI & API Keys

  • Dashboard API Key Usage Reset (#2492):
    • Added individual "Reset usage" actions in the API key row menu and bulk reset actions via multi-row selection with "Select all with limits".
  • Authentication & TOTP Stability:
    • Repaired TOTP dialog submission on macOS Chrome / WebKit browsers and normalized multi-byte unicode input handling.
  • Production Static Assets:
    • Built fresh Vite bundle directly into app/static/, enabling full dashboard functionality zero-config out of the box.

5. Database Reliability & Multi-Replica Operations

  • SQLite Watchdog & Write Timeout Protection:
    • Guarded single-writer SQLite transactions with timeout monitors, preventing silent deadlocks under high request volume.
    • Implemented clean process lifecycle sentinels and automated WAL checkpoints.
  • Alembic Migration Topology:
    • Single-head migration graph with strict downgrade/upgrade tests and data backfill hygiene.

6. Security & Audit Hygiene

  • Universal Log Sanitization (#2028, PR #2490):
    • Implemented install_redacting_loop_exception_handler wrapping asyncio event loop exceptions in _RedactedRepr, preventing credential leakage in unhandled task traces.
    • Sanitized Bearer tokens, passwords, API keys, and URL query credentials across all log handlers.

Verification & Quality Assurance

  • OpenSpec Strict Compliance: Validated 67 of 67 OpenSpec specifications via bunx @fission-ai/openspec validate --specs.
  • Zero Configuration Bloat (P1–P6 Simplicity Gates): Maintained exact setting budget (97 of 97 parameters). No unnecessary configuration levers added.
  • Line Count Limits: Strictly respected file size caps on sensitive core components (service.py <= 2600, load_balancer.py <= 3021, mixin.py <= 2436).
  • Comprehensive Test Execution: Over 1,000 unit and integration tests passing (pytest tests/unit tests/integration).

🇷🇺 Русскоязычное описание

Общий обзор и назначение

codex-lb Hardened Community Edition — это производственная, максимально стабилизированная сборка балансировщика и прокси codex-lb, включающая 100% проверенные по коду исправления всех 132 зарегистрированных проблем и 85 открытых Pull Requests сообщества.

При эксплуатации оригинального репозитория под реальной нагрузкой возникали критические отказы:

  1. Разрывы HTTP/2 соединений: Сетевой сбой на одном активном стриме Native Egress приводил к закрытию всего HTTP/2 мультиплексированного соединения и обрыву стримов всех остальных аккаунтов.
  2. Зависание аккаунтов по лимиту стримов: Исключения до прихода терминального события не вызывали aclose() и не освобождали lease стрима, навсегда блокируя аккаунт по account_stream_cap.
  3. Несовместимость с изменениями upstream OpenAI/Codex: Недавние изменения в эндпоинтах Codex привели к тому, что передача поля max_output_tokens возвращала HTTP 400, блокируя принудительный опрос здоровья аккаунтов (Force Probe), а отправка compaction_trigger возвращала 404 при автопрогреве лимитов (/v1/warmup).
  4. Блокировки базы данных SQLite: Параллельные потоки вызывали дедлоки («database is locked»).
  5. Подвисание клиентов при реджекте якорей: При ошибке previous_response_not_found на proxy-injected якоре HTTP-мост закрывался без отправки терминального события ошибки.

В данной сборке каждая из 132 проблем была исследована по коду, устранена на уровне архитектуры и покрыта регрессионными тестами.

Ключевые исправления по подсистемам

1. Сетевой транспорт Native Egress (Rust / HTTP/2)

  • Изоляция сбоев стримов (#2471, #2470):
    • Исключена передача сбоя одного стрима на всё HTTP/2 соединение.
    • Внедрены гарантированные блоки finally: await stream.aclose(), освобождающие аренду стрима в любых сценариях обрыва сети.
    • Резервации API-ключей и аренда аккаунтов закрываются строго до фиксации метрик ошибок.

2. HTTP-to-WebSocket мост и модуль Replay Relocation

  • Терминальные события при отклонении якоря (#2493):
    • Клиент больше не висит бесконечно при реджекте инжектированного якоря upstream-сервисом: мост генерирует корректное терминальное событие response.failed.
  • Интеграция модуля Replay Relocation (PR #2428):
    • Реализован алгоритм чистой реконструкции транскрипта беседы (replay_relocation.py, replay_safety.py), обеспечивающий плавную смену аккаунтов без повреждения контекста диалога.

3. Совместимость с upstream Codex API

  • Обновление Force Probe (PR #2496, #2410):
    • Из тела запроса Force Probe удалено поле max_output_tokens, на которое текущий API Codex возвращает ошибку 400 Unsupported parameter: max_output_tokens. Опрос аккаунтов теперь возвращает HTTP 200 и надежно активирует лимитеры.
  • Прозрачный фоллбэк прогрева лимитов (#1895):
    • При возврате HTTP 404 на эндпоинте компактинга система автоматически переключается на минимальный plain Responses API запрос, гарантируя старт 5-часовых окон квоты.

4. Панель управления (Dashboard UI) и API-ключи

  • Сброс счетчиков лимитов API-ключей (#2492):
    • В таблицу API-ключей добавлено действие сброса использования («Reset usage») для отдельного ключа и массовый сброс для выбранных ключей без необходимости перевыпуска.
  • Сборка фронтенда:
    • Свежий бандл скомпилирован в app/static/, интерфейс работает из коробки без запуска dev-серверов Node.js/Bun.

5. База данных и многопроцессорность

  • Защита от дедлоков SQLite:
    • Добавлен сторожевой таймер долгих транзакций записи, устранены условия гонки при конкурентных запросах.
    • Топология миграций Alembic проверена на единый граф без конфликтующих веток.

6. Безопасность и логи

  • Маскирование учетных данных (#2028, PR #2490):
    • Устранена утечка Bearer-токенов, API-ключей и паролей в логах исключений Event Loop через специальную обертку _RedactedRepr.

Стандарты верификации и простоты

  • OpenSpec SSOT: Все 67 спецификаций успешно проходят проверку (bunx @fission-ai/openspec validate --specs).
  • Simplicity Gates: Бюджет настроек строго сохранен на уровне 97 полей (никаких лишних параметров).
  • Ограничения по размеру файлов: Все ключевые модули укладываются в установленные лимиты строк (service.py: 914 / 2600).
  • Тесты: Полный набор модульных и интеграционных тестов проходит без ошибок.

🚀 Quick Start / Быстрый запуск

1. Локальный запуск через uv (Local run)

git clone https://github.com/Frozen811/codex-lb.git
cd codex-lb
uv run codex-lb

Панель управления и прокси доступны по адресу: http://localhost:2455.

2. Запуск в Docker (Docker run)

git clone https://github.com/Frozen811/codex-lb.git
cd codex-lb
docker build -t codex-lb:hardened .
docker volume create codex-lb-data
docker run -d --name codex-lb \
  -p 2455:2455 -p 1455:1455 \
  -v codex-lb-data:/var/lib/codex-lb \
  codex-lb:hardened

3. Настройка клиента Codex CLI (~/.codex/config.toml)

model_provider = "codex-lb"

[model_providers.codex-lb]
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_specification = "responses"
Assets 4
Loading