Make admin and API errors visible and traceable
Return structured JSON errors with request IDs, log unexpected exceptions with tracebacks, and show HTTP and network failures in the admin UI without losing unsaved source. Preserve publication errors when release listing also fails, handle cancelled preview promises, and add regression tests, browser failure scenarios, and updated API documentation.
This commit is contained in:
@@ -45,7 +45,27 @@ HTML-операции нового редактора: `/admin/editor/pages/{id}
|
||||
|
||||
Снимок содержит kind/id/path/source/etag/model/schema/issues/revision; результат превью — URL, snapshot, expires_at и revision. ETag — `sha256:` от исходных байтов; проверка актуальной схемы и CAS выполняются под одним SiteLock вместе с history/atomic write. Изменение code/layouts/schemas через content scope запрещено, в том числе через symlink/traversal. Ошибка аудита после записи возвращает признак committed с сохранённым снимком и не выдаётся за отклонённый Save.
|
||||
|
||||
Ошибки API имеют `error: {code, message, issues, …}`; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и секретов.
|
||||
Ошибки API имеют `error: {code, message, request_id, issues, …}` с соответствующим HTTP-статусом; 409 дополнительно содержит submitted/current, 422 validation — неприменимый buffer либо диагностику. Лимит JSON-запроса — 1 MiB; source ограничен DTO и безопасным YAML-парсером. Неожиданная ошибка API возвращается без трассировки и внутренних путей.
|
||||
|
||||
Пример ответа HTTP 500 на `/admin/api/v1/publish`:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "storage_error",
|
||||
"message": "Ошибка доступа к файлам сервера. Проверьте права и свободное место. Проверьте текущую версию перед повтором операции.",
|
||||
"request_id": "c4a857fd62774d688c5135d104ce3a51"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`X-Request-ID` присутствует в ответах приложения; ID сохраняется при внутреннем вызове API. Коды: `internal_error` — неожиданное исключение; `storage_error` — ошибка файловой системы; `request_validation`/`validation` — запрос/контент; `conflict` — несовпадение версии; `preview_unavailable` — недоступный snapshot. Серверный клиент преобразует отказ транспорта в HTTP 503 `api_unavailable`, некорректный ответ — в HTTP 502 `invalid_api_response`.
|
||||
|
||||
Неожиданные исключения пишутся через `logger.exception` в `uvicorn.error`: `request_failed request_id=… method=POST path=/admin/api/v1/publish code=storage_error`, затем traceback с исходным исключением и местом ошибки. Обработанные HTTP-ошибки дают `request_error` со статусом и кодом. Тело запроса, Authorization, cookies и query string не добавляются в эти записи. В Docker смотреть `docker logs --since 10m flexly-cms`; ID из интерфейса позволяет найти соответствующий стек.
|
||||
|
||||
HTML UI показывает сообщение, код и ID запроса. На публикации ошибку видно и без JavaScript; htmx показывает постоянное уведомление, которое закрывается пользователем. Подготовленная страница ошибки может заменить boosted-страницу; исходник документа при 5xx не заменяется. Отказ сети и timeout также видимы, автоматического повтора мутаций нет. Если после ошибки публикации недоступен список релизов, исходная ошибка операции сохраняется.
|
||||
|
||||
Проверка отказов на временной копии сайта: `PYTHONPATH=src python scripts/qa_errors_001.py`. Сценарий проверяет UI 500, общий ID с traceback, мобильное уведомление, сохранность несохранённого исходника при серверном и сетевом сбое и восстановление Save/Publish после устранения сбоя. Выход — `/tmp/cms-errors-qa/`; браузер — `QA_BROWSER=firefox`, каталог — `QA_ERRORS_OUT=/tmp/cms-errors-firefox`.
|
||||
|
||||
Схема и локальная страница документации доступны после входа: `/admin/api/v1/openapi.json`, `/admin/api/v1/docs`; сокращённые `/admin/api/openapi.json`, `/admin/api/docs` также работают. Воспроизводимый экспорт без секретов и работающего сайта:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user