fix(import): подтвердить обязательные гарантии второго эпика
CI / Rust Checks (pull_request) Successful in 24m43s
CI / UI Checks (pull_request) Successful in 6s
CI / Community Image Smoke (pull_request) Successful in 9m5s
CI / Frontend E2E (pull_request) Successful in 12m43s
CI / Deploy (pull_request) Skipped

This commit is contained in:
bsodfather committed 2026-10-10 13:25:05 +03:00
1 parent 31f6f00d3b
commit ad23cd9a46
33 files changed
+3328 -18

No files matched your search

+5 -1
View File
@@ -784,7 +784,7 @@ Explicit зависимости Epic 8: `8.1 → 8.2`; `8.3,8.4,8.5,8.7,8.8` з
| Case ID | Проверка (Given / When / Then) | Expected evidence | PASS criterion |
|---|---|---|---|
| `AT-2.10-01` | **Given** OpenAPI 3.x `components.securitySchemes` или Swagger 2.0 `securityDefinitions`<br>**When** importer анализирует schemes<br>**Then** bearer HTTP, basic HTTP и API key в header/query/cookie преобразуются в typed security metadata<br>**And** source names, locations и применимые format hints сохраняются без credential values. | Отчёт AT-2.10-01: фактический результат указанного When и наблюдения/значения для каждого Then/And; процедура, revision/config/environment, исполнитель/дата и bounded артефакты с digest. Для мутации/отказа — состояние до/после и число side effects. | bearer HTTP, basic HTTP и API key в header/query/cookie преобразуются в typed security metadata; source names, locations и применимые format hints сохраняются без credential values. |
| `AT-2.10-01` | **Given** OpenAPI 3.x `components.securitySchemes` или Swagger 2.0 `securityDefinitions`<br>**When** importer анализирует schemes<br>**Then** OpenAPI 3.x bearer/basic и API key в header/query/cookie, а Swagger 2.0 basic и API key в header/query преобразуются в typed security metadata; Swagger 2.0 cookie явно отклоняется как unsupported<br>**And** source names, locations и применимые format hints сохраняются без credential values. | Отчёт AT-2.10-01: фактический результат указанного When и наблюдения/значения для каждого Then/And; процедура, revision/config/environment, исполнитель/дата и bounded артефакты с digest. Для мутации/отказа — состояние до/после и число side effects. | OpenAPI 3.x bearer/basic и API key в header/query/cookie, а Swagger 2.0 basic и API key в header/query преобразуются в typed security metadata; Swagger 2.0 cookie явно отклоняется как unsupported; source names, locations и применимые format hints сохраняются без credential values. |
| `AT-2.10-02` | **Given** global security requirement<br>**When** Operation не задаёт собственный override<br>**Then** candidate наследует global requirement согласно specification semantics<br>**And** operation-level requirement или explicit no-auth корректно заменяет global rule. | Отчёт AT-2.10-02: фактический результат указанного When и наблюдения/значения для каждого Then/And; процедура, revision/config/environment, исполнитель/дата и bounded артефакты с digest. Для мутации/отказа — состояние до/после и число side effects. | candidate наследует global requirement согласно specification semantics; operation-level requirement или explicit no-auth корректно заменяет global rule. |
| `AT-2.10-03` | **Given** security requirement с несколькими alternatives<br>**When** source определяет OR-семантику<br>**Then** preview сохраняет все допустимые alternatives и позволяет выбрать поддерживаемый вариант<br>**And** importer не объединяет alternatives в ложное обязательное AND. | Отчёт AT-2.10-03: фактический результат указанного When и наблюдения/значения для каждого Then/And; процедура, revision/config/environment, исполнитель/дата и bounded артефакты с digest. Для мутации/отказа — состояние до/после и число side effects. | preview сохраняет все допустимые alternatives и позволяет выбрать поддерживаемый вариант; importer не объединяет alternatives в ложное обязательное AND. |
| `AT-2.10-04` | **Given** security requirement, требующий несколько schemes одновременно<br>**When** source определяет AND-семантику<br>**Then** candidate сохраняет составное требование, если runtime contract его поддерживает<br>**And** иначе affected Operation получает blocker finding с перечислением несохраняемой semantics. | Отчёт AT-2.10-04: фактический результат указанного When и наблюдения/значения для каждого Then/And; процедура, revision/config/environment, исполнитель/дата и bounded артефакты с digest. Для мутации/отказа — состояние до/после и число side effects. | candidate сохраняет составное требование, если runtime contract его поддерживает; иначе affected Operation получает blocker finding с перечислением несохраняемой semantics. |
@@ -2996,3 +2996,7 @@ Protocol-кейсы (вне построчного AC-реестра): `AT-PROTO
---
_Конец плана._
### Уточнение AT-2.10-01 — 2026-10-10
Разделены возможности двух форматов без изменения импортёра: в [OAS 2.0 Security Scheme Object](https://spec.openapis.org/oas/v2.0.html#security-scheme-object) для `apiKey.in` допустимы только `header` и `query`. Cookie поддерживает OpenAPI 3.x; неподдерживаемая Swagger-схема должна оставаться явным blocker, без создания Draft с ослабленной безопасностью. Предыдущее обобщение header/query/cookie на оба формата было ошибкой требований.
+128
View File
@@ -0,0 +1,128 @@
# Хранение и восстановление исходных документов OpenAPI
Эта инструкция описывает текущую реализацию Community. Контракт HTTP см.
в [Admin API](admin-api.md#openapi-preview-upload), параметры — в
[runtime-config.md](runtime-config.md), обновление схемы — в [migrations.md](migrations.md).
## Корень и ограничения
`CRANK_STORAGE_ROOT` — абсолютный путь, по умолчанию `/var/lib/crank/storage`.
Admin API открывает его при запуске и закрепляет файловый дескриптор. Корень
и внутренние каталоги должны принадлежать пользователю процесса и иметь права
`0700`; опубликованные blobs — `0400`. Символьные ссылки, чужие владельцы,
небезопасные права и hard links отклоняются. В Compose именованный том
`artifact_storage` монтируется в этот путь, а `artifact-storage-init`
подготавливает права. Не заменяйте root symlink и не исправляйте проблему
прав рекурсивным `chmod 777`.
Production upload — `multipart/form-data` с единственным полем `file`, UTF-8
YAML/JSON, непустой файл до 262144 bytes включительно. Расширение и MIME
должны согласовываться; для YAML/JSON допустим `application/octet-stream`.
Это фиксированный предел текущего импортёра, не отдельная переменная окружения.
Дополнительные лимиты normalizer и external reference chain описаны в
[openapi-import.md](openapi-import.md). Увеличение HTTP proxy body limit
не увеличивает предел импортёра. Не передавайте документ через JSON `{document}`.
Физический blob адресуется только SHA-256: `sha256/<первые 2 hex>/<digest>`.
Запись использует private temp, file fsync, публикацию без перезаписи и
fsync каталога. Чтение проверяет digest до возврата bytes. PostgreSQL хранит
workspace-scoped ownership и references; один физический digest может
принадлежать нескольким workspace. Наличие файла не предоставляет права
другому workspace. Preview не создаёт Operations; Apply создаёт их одной
транзакцией и сохраняет неизменяемый результат для точного повторного запроса.
## Резервное копирование и восстановление
Сохраняйте согласованный комплект PostgreSQL, **всего** artifact storage,
Compose, runtime configuration и используемой ревизии образов. Дамп БД
без тома не восстанавливает исходники и snapshots; отдельно взятый том
не восстанавливает ownership и immutable plans. Конфигурация и исходники
могут содержать секретные данные: закрытые права, шифрование копии и ограниченный доступ.
Перед ручным снимком остановите mutating traffic и процессы `admin-api`/
`mcp-server`, включая фоновые reconciliation workers; затем получите дамп
PostgreSQL и архив тома. Не удаляйте named volume. Копируйте комплект на другой
хост и проверяйте SHA256SUMS. Возобновляйте процессы после получения снимка.
`scripts/deploy-community.sh` создаёт комплект `backups/<UTC>/` из
`postgres.dump`, `artifacts.tar.gz`, `runtime.env`, `docker-compose.yml`,
`SHA256SUMS` и проверяет миграцию копии перед обновлением. Дамп и архив
получаются последовательно; при продолжающихся записях это **не** доказательство
атомарного снимка БД+файлов. Для строгой согласованности оператор должен
организовать окно без записей. Скрипт сохраняет пять последних локальных
комплектов, поэтому внешняя копия обязательна до следующего обновления.
Проверяйте восстановление на изолированном стенде с matching image revision,
БД и томом: контрольные суммы, compatibility check, `/ready`, чтение
сохранённого source, повтор Apply с прежним ключом и отсутствие дубликатов.
Существующая команда восстановления изменяет данные назначения:
```sh
CRANK_RESTORE_CONFIRM=restore ./scripts/restore-community.sh DEPLOY_DIR BACKUP_DIR
```
Перед её выполнением сохраните текущее состояние и убедитесь, что выбрано
нужное назначение. Не откатывайте только приложение после миграции схемы:
используйте совместимый forward image либо проверенное восстановление комплекта.
## Очистка и восстановление claims
Координатор запускается в Admin API, проходит Recovery до Sweep и ограничивает
каждый тик: 4096 traversal syscalls, 32 candidates, 32 mutation attempts,
deadline 30 секунд. Период — 15 минут. Grace финальных/detached blobs — 24 часа,
lease claim — 5 минут; cleanup temp — после часа с отдельными лимитами
512 scans / 16 deletes. Это константы текущей версии, не конфигурационные ручки.
Referenced source действующего ImportPlan не является orphan. Старые upload jobs
и detached references очищаются по жизненному циклу; нельзя освобождать место
ручным удалением digest из storage, пока БД ссылается на него.
Sweep сначала помещает eligible blob в quarantine. Recovery проверяет обе
канонические локации и только после подтверждённого отсутствия переводит БД
в `unavailable`. Неопределённая мутация/fsync/commit сохраняет claim для
повторной попытки; перезапуск начинает bounded cycle заново. Старый worker
не может финализировать новый fencing token. При сбое диска/БД восстановите
ресурс, затем наблюдайте последующие тики; не сбрасывайте claim вручную в idle.
Legacy read — только из явно настроенного доверенного корня с проверками
containment и digest. Это read compatibility, не автоматическая миграция,
перезапись или удаление старых файлов. URL документа не выбирает корень.
## Диагностика и границы доказательств
Используйте canonical `X-Request-ID` и `X-Trace-ID` из ответа для сопоставления
с диагностикой. Ошибки не должны включать raw source, credentials или пути.
Reconciliation пишет фиксированные classification counters в события
`admin.artifact_reconciliation.tick` / `failed`; это безопасные категории,
а не реестр digest/workspace/token. `/ready` проверяет доступность PostgreSQL,
но не подтверждает целостность каждого blob: verified read проверяет конкретный файл.
Для проверки фоновой очистки смотрите последовательность событий
`admin.artifact_reconciliation.tick`: `cycle_completed=true` означает завершённый
проход, `recovery_completed=false` — Recovery ещё продолжается. Несколько тиков
с `retryable=true`, ростом `recovery_retryable`, `registration_retryable` или
`mutation_retryable` требуют проверки доступности БД, свободного места и ошибок
fsync/permissions. Событие `admin.artifact_reconciliation.failed` содержит
категорию `backend` или `deadline`; сопоставьте её с журналами БД и хоста.
После восстановления ресурса убедитесь, что следующие тики завершают цикл без
retryable. Предел candidates/mutation attempts может означать продолжение
ограниченного прохода, а не сбой.
В текущей версии эти значения — поля структурированных событий, а не
Prometheus gauge размера очереди. Runtime не публикует точное число оставшихся
blobs: не считайте один незавершённый тик доказательством утечки. Для Compose
отберите события из журнала Admin API командой
`docker compose logs --since 2h admin-api`; фильтруйте по фиксированным именам
событий. Не включайте raw source или digest в диагностические выгрузки.
Внешние ссылки выключены по умолчанию. Разрешение задаёт оператор allowlist;
автономный комплект требует подготовки и согласованной поддержки загрузки,
а не произвольного доступа к файловой системе. Документ не может разрешить
себе сеть. Изменённое удалённое содержимое требует нового preview.
Автоматические проверки находятся в `crank-artifacts/tests`, registry
`artifact_sources`/`artifact_reconciliation`, Admin API `reconciliation/tests`
и `openapi_import`, UI `openapi*.spec.js`. Они проверяют конкретные сбои и
состояния; успешный CI не доказывает отсутствие любых аппаратных сбоев,
потерь данных при произвольном порядке backup или утечек по времени.
Reference performance, длительная эксплуатация и человеческая приёмка
выполняются отдельно по [acceptance-test-plan.md](acceptance-test-plan.md).
+3
View File
@@ -176,6 +176,9 @@ curl -I http://127.0.0.1:3000/
## Эксплуатация
Хранение OpenAPI sources, ограничения загрузки, согласованное резервирование
и восстановление claims описаны в [операторской инструкции](artifact-storage-operations.md).
- `/health` проверяет, что процесс жив; `/ready` дополнительно проверяет доступность PostgreSQL и используется Docker Compose.
- CD перед каждым обновлением создаёт согласованный комплект в `backups/<UTC-время>`: дамп PostgreSQL, том артефактов, окружение, Compose и контрольные суммы. Хранятся последние пять локальных комплектов.
- Копируйте комплекты резервных копий на отдельный хост или в объектное хранилище.