13 KiB
Этап 5: Publication и серверный контракт
Дата: 2026-11-17. Источники — design/publication-antirion.html, design/assets/publication.css и publication.js. Исходная композиция, таблица, инспектор, пять вкладок, карточки Workspace/Candidate/Live и диалоги перенесены в принятый shell. Mock-хранилище, выдуманные роли, симуляция сборок и ремонт демонстрационных данных исключены. Проверки — verification-publication.md.
Сценарий
- Сохранить необходимые документы в редакторе. Несохранённые правки других вкладок не участвуют в сборке.
- «Проверить» выполняет настоящие workspace/release-проверки. Исходники и Live не меняются; результат помечается устаревшим при изменении входных файлов или renderer.
- «Собрать кандидата» строго проверяет и рендерит сайт в неизменяемый каталог релиза, сохраняя текущий Live. Отдельный предварительный запуск «Проверить» не обязателен: сборка сама выполняет строгую проверку.
- Во вкладке «Кандидат» доступны настоящий снимок страницы, сравнение зафиксированных исходников с базовым Live и журнал сборок. Просмотр не пересобирает сайт.
- «Опубликовать» открывает исходный диалог с комментарием. Подтверждение переключает
currentна выбранный снимок без повторного рендера. Комментарий обязателен, до 150 символов. - «История» показывает существующие каталоги релизов. Перед откатом доступны реальные изменённые публичные файлы, маршруты/формы и подтверждение. Откат переключает Live, сохраняя workspace.
Поиск, фильтры, выбор документа и вкладки работают локально. Сетевые операции выполняются через fetch в фоне; переключение вкладок остаётся доступным, повторные изменяющие действия блокируются на время запроса. Сборка на сервере синхронная: долговечной очереди заданий и отмены задачи нет.
Один контракт FastAPI
Browser → /admin/publication/* (cookie, Origin, CSRF) → AdminApi/httpx.ASGITransport → /admin/api/v1/publication* → PublicationService. Браузер не получает внутренних credentials. Начальные данные передаются в скрытом textarea (tojson, чтение .value), который сохраняется при htmx swap с allowScriptTags:false; script-элементы для хранения этих данных не используются. Права и авторство берутся из проверенной сессии; отдельные API keys/scopes и RBAC пока не реализованы.
JSON API относительно /admin/api/v1 |
Назначение |
|---|---|
GET /publication |
Реальное состояние, изменения, проверки, кандидат, история, сборки и журнал |
POST /publication/validate |
Проверить workspace/release без записи контента |
POST /publication/build |
Собрать кандидат без активации |
GET /publication/candidate-diff |
Сравнить неизменяемый кандидат с его базовым релизом |
GET /publication/compare?path=… |
Сравнить сохранённый файл workspace с частным снимком Live |
GET /publication/document-history?path=… |
Существующие версии .engine/history, максимум 20; восстановления здесь нет |
GET /publication/release?id=… |
Сравнить публичные файлы выбранного релиза и текущего Live перед откатом |
POST /publication/preview |
{id, route} → защищённый пассивный снимок настоящего релиза |
POST /publication/activate |
{id, expected_live, comment} → переключение проверенного кандидата |
POST /publication/rollback |
{id, expected_live, comment} → переключение существующего исторического релиза |
expected_live обязателен; до первой публикации передаётся null. HTML adapter читает состояние по /admin/publication/state; остальные названия операций совпадают. POST принимает FormData csrf и JSON-строку payload; ответ — JSON. Читающие операции — GET. Экран открыт по /admin/publish; без JavaScript доступна ссылка на обычную форму /admin/publish/legacy. Старые POST /admin/publish, API /publish, /rollback и CLI сохраняют прежний сценарий сборки с публикацией.
Разделение состояния и файлов
PublicationService не редактирует файлы сайта. Изменения документов остаются ответственностью ContentService с CAS/history/audit. Проверки, сборка и переключение выполняются под общим SiteLock; в build_site добавлен параметр activate=False, обычное значение остаётся True. Внешние писатели должны соблюдать тот же lock.
Служебные данные находятся только в SITE_STATE_DIR/publication/:
candidate.json: последний кандидат, базовый Live, хеш входных файлов и renderer, hash публичного output, время/автор/маршруты/диагностика;releases/<build_id>.json: частный снимок входных файлов и происхождение релиза, комментарий/автор и факт активации;validation.json: реальный результат последней проверки и fingerprint его входных данных;builds.json: последние 40 результатов/ошибок сборки с ID запроса и кратким журналом стадий.
Список исходников охватывает pages, content, menus, assets, layouts, fragments, collections, display, data, forms, root site/theme/redirect YAML и настроенный файл темы. Для UTF-8 текста известных расширений до 512 КиБ сохраняется исходник; для остальных файлов — hash/размер. Скрытые и служебные каталоги исключены, symlink в исходниках отклоняется. Полный hash workspace консервативно инвалидирует кандидата и при изменении иных файлов, включая README; fingerprint renderer учитывает ресурсы движка.
Частные исходники, включая draft, не копируются в публичный dist или manifest. В релиз рендерятся только published. Статус published в файле не означает, что сохранённая редакция уже находится в Live.
Старые/CLI-релизы без частного снимка продолжают работать: маршруты, preview и откат доступны, сравнение исходников/автор/комментарий неизвестны и обозначены явно. Ретроспективно придумывать их нельзя. После первой публикации новым workflow сравнение станет доступно для этого релиза.
Кандидат сравнивается со своей зафиксированной базой, а не с текущими изменениями workspace. Последующие правки требуют новой сборки. Откат сравнивает реальные байты публичных файлов, включая manifest/assets. Никогда не публиковавшиеся кандидаты с известным происхождением через откат выбрать нельзя.
Конфликты, ошибки и безопасность
Перед активацией проверяются expected_live, актуальность ID кандидата, hash исходников/renderer/базового Live и неизменность собранных файлов. Нарушение актуальности — HTTP 409 release_conflict; повреждённый снимок/валидация — 422; отсутствующий релиз — 404. Отказ строгого рендера сохраняет прежние Live и кандидат.
JSON-ошибки: error: {code, message, request_id, …}. Непредвиденные ошибки и ошибки хранилища логируются со стеком и тем же ID. UI показывает сообщение, код и ID; 409 не закрывает подтверждение и не удаляет комментарий, автоматического повторного POST нет. Сеть и истёкшая сессия также видимы.
Если ошибка записи служебных данных/аудита произошла после сборки либо переключения, API отвечает 500 candidate_after_build или release_after_commit с committed_build. Сообщение различает «снимок создан, Live не переключён» и «Live уже переключён». UI перечитывает состояние перед повтором; указатель current остаётся источником истины. Переключение symlink атомарно, но несколько служебных JSON и audit не являются общей crash-atomic транзакцией.
Preview читает HTML/assets выбранного build ID, а не workspace, использует существующие TTL/epoch-токены и immutable snapshots. Скрипты удалены, script-src 'none' действует также на отдельном preview origin; iframe sandbox запрещает выполнение кода, формы и навигацию верхнего окна. Настроенный preview origin разрешён в frame-src всех страниц shell: CSP исходного документа сохраняется при htmx swap. Браузерные сценарии проверены с обеими конфигурациями origin.
Журнал показывает настоящие release-события из хвоста аудита: до 80 записей в последних 256 КиБ. Старый аудит не удаляется. Пароли, токены и тела запросов в журнал не добавляются.
Границы этапа
Новый workflow не удаляет кандидаты/релизы автоматически. Прежняя CLI-сборка сохраняет своё keep=5; если каталог уже удалён, API сообщает отсутствие, кандидат становится неактуальным. Политика retention и очистка частных снимков требуют отдельной работы.
Не добавлены durable jobs, реестр идемпотентных операций, changeset/recovery нескольких документов, согласование агентских изменений, RBAC, приём заявок или MCP. Публичные формы по-прежнему отвечают HTTP 501. Исторический релиз без provenance нельзя проверить по исходным входным файлам; UI не выдаёт это за подтверждённое сравнение.