Skip to content

Latest commit

 

History

History
96 lines (78 loc) · 7.44 KB

0001-server-mode.md

File metadata and controls

96 lines (78 loc) · 7.44 KB

ADR-0001 — Направление на server mode через Runner-абстракцию

  • Статус: Accepted — направление принято; фазы 1–2 реализованы (Runner-слой #140, контракт результата #116). Дизайн-задачи #153/#154/#155 закрыты (оформлено в ADR-0008/0009 + server-*-design.md, PR #484); реализация полного server mode остаётся открытым v2.0-backlog (эпик #151).
  • Дата: 2026-07-08
  • Связанные issue: #152 (этот ADR), #140 (Runner), #156 (API), #157 (sandbox)
  • Связанный дизайн: server-mode.md, result-contract.md

Контекст

Сегодня грейдер — локальный инструмент: CLI и веб-оболочка --serve (127.0.0.1) исполняют доверенный код (свой или скачанный из Stepik as-is) в subprocess без OS-sandbox — это осознанное by-design ограничение (configuration.md § Ограничения и безопасность, SECURITY.md). Есть регулярный запрос на «онлайн-проверку / удалённый прогон / общий сервер», который подразумевает исполнение чужого кода. Это принципиально другая threat model: без настоящей изоляции публичный сервер, запускающий недоверенный код, — прямая RCE-поверхность.

Одновременно исполнение размазано по core/grader_core.py, core/executor.py, core/microbench_runner.py — нет единой точки, где можно сменить механизм запуска, не задев грейдинг.

Нужно зафиксировать направление, не начиная тяжёлую реализацию: снять неопределённость для будущих контрибьюторов и не дать случайно «включить сервер» без sandbox.

Решение

  1. Признать server mode отдельным продуктовым сдвигом, а не расширением --serve. Он затрагивает MAJOR-границу проекта (выход за «локальный инструмент», см. политику версионирования).
  2. Готовить архитектуру инкрементально через абстракцию Runner (issue #140): выделить интерфейс запуска в core/, обернуть текущий subprocess-путь в LocalRunner без изменения поведения. Это дешёвый, обратимый шаг, полезный и без server mode.
  3. Спроектировать (но не реализовывать) контракт API удалённого исполнения (issue #156) и обязательные требования sandbox (issue #157) — сеть off, эфемерные tmp-каталоги, жёсткие квоты, изоляция клиентов. Детали — в server-mode.md.
  4. Не включать server mode с недоверенным кодом, пока требования #157 не обеспечены реальным механизмом изоляции. Механизм (Docker/nsjail/VM/сервис) этим ADR не выбирается — только требования к нему.
  5. Сохранить ядро библиотекой. Server mode — ещё один адаптер над core/* (как CLI/Web), форма результата — result-contract.md; DAG остаётся ацикличным.

Альтернативы

  • A. Ничего не делать, остаться чисто локальными. Плюс: ноль риска и затрат. Минус: повторяющийся запрос остаётся без ответа, а стихийные попытки «пошарить --serve наружу» опасны без зафиксированного запрета. Отклонено в пользу явного, но отложенного направления.
  • B. Сразу строить сервер (напр. FastAPI + Docker). Плюс: быстрый продукт. Минус: тяжёлые зависимости и демоны против запретов CLAUDE.md; высокий риск RCE при недозревшем sandbox; переписывание исполнения без промежуточной абстракции. Отклонено как преждевременное и рискованное.
  • C. Расширить --serve до сетевого доступа без sandbox. Отклонено безоговорочно: прямая RCE-поверхность, противоречит threat model (SECURITY.md).
  • D. Абстракция Runner + отложенная реализация (выбрано). Готовит почву минимальным обратимым рефактором, фиксирует контракты и требования безопасности, не создавая продукта и рисков раньше времени.

Последствия

Положительные:

  • Направление и границы зафиксированы; контрибьюторы не «включат сервер» случайно — запрет явный и обоснованный.
  • Runner-рефактор (#140) улучшает тестируемость исполнения уже сейчас.
  • Контракты (#156) и требования sandbox (#157) готовы к реализации без повторного разбора контекста.

Отрицательные / издержки:

  • Вводится ещё одна абстракция в core/ — небольшой оверхед; митигируется тем, что LocalRunner не меняет поведение.
  • Полноценный server mode остаётся не реализованным; онлайн-проверки пока нет (это осознанно).

Нейтральные:

Миграция (фазы)

Кратко (полностью — server-mode.md § Фазовая миграция): 0 — сейчас (локально, без sandbox) → 1 — Runner/LocalRunner (#140) → 2 — SandboxRunner по требованиям #157 → 3 — API /api/v1/runs (#156) → 4 — публичный server mode. Каждая фаза обратно совместима с локальным --serve//api/grade.