Recoverable Web 0.6.1 · EOC 0.27.0

Интеграционный контракт для объектов, доступа и аудита

EOC v0.27.0 объединяет ingest, проверку, evidence, объектную модель, Storage Provider и контекст безопасности. Публичный gateway добавляет стабильный API v1 для проверки и интеграционных workflows; внутренние EOC-маршруты остаются закрыты.

FP — fixed representation ED — editable state R — revision data

Recoverable EOC · Public API v1Открыть техническую документацию EOC →

Integration surface · EOC v0.27.0

8 групп Integration API под одним объектным контрактом

Публичный registry содержит 17 public operations `/v1`, из которых 15 требуют аутентификацию, и 8 integration-маршрутов. Контракт учитывает 6 ролей и 9 scopes. Сервис разделяет команды и чтение состояния: ingest, jobs, objects, revisions, events, reverify, webhooks и webhook deliveries. Доступ задают scopes; API keys и user principals привязаны к tenantId и projectId.

8групп Integration APIingest · jobs · objects · revisions · events · reverify · webhooks · deliveries

6ролейadmin · integrator · auditor · readonly · policy-manager · service-account

9scopesот object:ingest до admin:manage

POST /v1/integration/ingest
GET  /v1/integration/jobs/:jobId
GET  /v1/integration/objects/:objectId
GET  /v1/integration/objects/:objectId/revisions/:revision
GET  /v1/integration/events
POST /v1/integration/reverify
GET  /v1/integration/webhooks
GET  /v1/integration/webhook-deliveries

Публичная граница — https://api.recoverable.ru/v1. Передайте ровно один credential: X-EOC-API-Key или Authorization: Bearer <OIDC JWT>. Внутренний /api/integration не является клиентским API; gateway проверяет scope, tenant/project context, лимиты и безопасную проекцию ответа.

Metadata persistence · tested

PostgreSQL

В non-production интеграции объекты, ревизии, jobs, события, idempotency и webhook records проходят через tenant/project-aware repository. Интеграционный smoke дважды подтвердил сохранение и изоляцию контекста.

Artifact persistence · tested

S3-совместимое хранилище

Adapter проверяет SHA-256, безопасность object key, повторную запись и namespace tenant/project. Live preflight с S3-совместимым сервером прошёл полный put/head/get/delete цикл; это ещё не подтверждение production rollout.

Как получить доступ

Публичная документация и OpenAPI доступны без регистрации. Для технического доступа откройте личный кабинет, войдите по одноразовому коду на email, создайте проект и выпустите API-ключ с нужными scopes.

Лимиты, состояния и события

По умолчанию действует 60 запросов в минуту на principal, до 4 одновременных операций и очередь до 64 запросов; превышение лимита возвращает 429, заполненная очередь — 503, payload свыше 64 MiB — 413. Записывающие операции требуют Idempotency-Key: повтор идентичного запроса безопасно воспроизводит результат, несовпадение даёт 409. Решения — ALLOW, WARN, REJECT, QUARANTINE; job — COMPLETED или FAILED. Event ledger фиксирует ingest, verification, evidence, storage и policy decision. Webhook delivery — at-least-once: проверяйте подпись, сохраняйте eventId и обрабатывайте повторы. Chunked upload/download не являются маршрутами этого публичного контракта.

Operation surface

Выберите задачу — получите точный набор маршрутов

Группы помогают ориентироваться, но не смешивают разные request/response contracts. HTTP status и содержательный verification result обрабатываются отдельно.

Группа 01

Проверить объект

Инспекция показывает структуру, но не заменяет решение проверки. Восстановление начинается только после положительного результата.

POST /api/check
POST /api/inspect
POST /api/extract-payload

Request · /api/check

POST /api/check
Content-Type: multipart/form-data

file=@object.eoc

Группа 02

Сформировать объект

Новая ревизия формируется как полный согласованный набор FP, ED и R, а не заменой одного компонента.

POST /api/pack-v2
POST /api/adapters/build-spec
POST /api/adapters/pack

Request · /api/pack-v2

POST /api/pack-v2
Content-Type: multipart/form-data

fixedRepresentation=@result.bin
payloads=@editable-state.bin
metadata={...}

Группа 03

Восстановить состояние

Restore возвращает допустимое редактируемое состояние; список adapter descriptors читается из фактического ответа сервиса.

POST /api/restore
GET /api/adapters

Группа 04

Получить evidence

Evidence, report, signature и provenance остаются отдельными операциями с собственными фактическими ответами.

POST /api/evidence-v1
POST /api/evidence-v1/report
POST /api/signature/verify
POST /api/provenance

Adapter rules

Адаптер следует за проверкой

Adapter связывает проверенное ED с прикладной средой, но не обходит verification gate. Если revision consistency не подтверждена, он не должен подставлять похожий файл или игнорировать mismatch. Точный набор adapter IDs и поддерживаемых payloads читается из ответа сервиса.

Restore gating

Читаемый файл ещё не означает допустимый restore

Клиент различает локальную целостность и согласованность ревизии. FP из одного объекта нельзя соединять с ED из другого по имени или дате. Отрицательный verification result сохраняет fail-closed семантику.

Error taxonomy

Transport, формат и решение проверки — разные статусы

Отсутствие соединения, HTTP 4xx/5xx, невалидный входной формат и отрицательный содержательный результат отображаются раздельно. Бинарные ответы читаются с учётом фактического Content-Type; HTTP 200 сам по себе не разрешает restore.

Contract versioning

Web и EOC имеют независимые версии

Публичный gateway отвечает как Recoverable Web 0.6.1, а поле upstream в локальной deep health подтверждает EOC 0.27.0. Клиент должен проверять нужную identity, а не смешивать версии двух сервисов.

{
  "ok": true,
  "service": "recoverable-web",
  "version": "0.6.1",
  "upstream": {
    "status": 200,
    "body": { "version": "0.27.0" }
  }
}

Публичная граница проходит по HTTP API. Внутренние process ports, deployment scripts и server topology не являются частью продуктового контракта.