Синхронизация пакетов Gateway

После регистрации публичного ключа Edge License Gateway получает полные поколения Edge Bundle v2 с подписью Cloud только через исходящий HTTPS (outbound HTTPS). Cloud не открывает входящее соединение к Host, а Host не подключается к Cloud RabbitMQ или базе данных Cloud.

POST /api/v1/edge-gateways/{gatewayInstanceId}/sync/pull
POST /api/v1/edge-gateways/{gatewayInstanceId}/sync/ack
POST /api/v1/edge-gateways/{gatewayInstanceId}/usage/batches

Все запросы используют Content-Type: application/json и требуют Idempotency-Key и X-Edge-Gateway-Request-Jws. JWS подписывается текущим закрытым ключом Gateway по ES256 и имеет тип MH-EDGE-GATEWAY-REQUEST-V1. Каноническая нагрузка связывает operation, POST, точный путь и Gateway id, ключ идемпотентности, SHA-256 тела в нижнем регистре и UTC timestamp. Cloud допускает не более 60 секунд рассинхронизации часов. Tenant, Customer, Site и Product не являются authority запроса.

Pull

Bootstrap отправляет {"cursor":null}. Последующие запросы повторяют только последний cursor, который был надёжно активирован и подтверждён. Успех имеет тип application/vnd.myhoreca.edge-bundle.v2+zip и заголовки:

X-Edge-Gateway-Cursor
X-Edge-Gateway-Generation
X-Edge-Gateway-Manifest-Id
Cache-Control: no-store
Pragma: no-cache

Тело содержит один полный подписанный архив Edge Bundle v2. Повтор с тем же ключом идемпотентности и тем же смысловым запросом возвращает сохранённые байты, в том числе после рестарта процесса Cloud. Использование ключа с другим телом возвращает 409. Новый pull до подтверждения возвращает то же pending-поколение.

Acknowledge

Отправляйте подтверждение только после проверки подписи, digest и binding и после надёжной атомарной локальной активации:

{
  "cursor": "1.019c4400-0000-7000-8000-000000000010",
  "generation": 1,
  "manifestId": "019c4400-0000-7000-8000-000000000010",
  "appliedAtUtc": "2026-08-08T12:00:00Z",
  "outcomeCode": "activated"
}

Cloud продвигает cursor только для точно выданного набора полей. Чужое, пропущенное, устаревшее или противоречивое подтверждение возвращает 409. Точный повтор безопасен и возвращает сохранённый результат.

Загрузка usage

Активный Gateway отправляет один ограниченный usage batch с операцией JWS usage-upload. Значение Idempotency-Key формируется строго как edge-usage-batch-{batchId:N}. JSON-тело имеет строгую схему: только batch id и 1–500 упорядоченных событий, общий размер — не более 512 KiB.

{
  "batchId": "019c5bc0-0000-7000-8000-000000000005",
  "events": [
    {
      "localEventId": "019c5bc0-0000-7000-8000-000000000006",
      "meterDefinitionId": "019c5bc0-0000-7000-8000-000000000020",
      "productId": "019c5bc0-0000-7000-8000-000000000003",
      "licenseId": "019c5bc0-0000-7000-8000-000000000004",
      "quantity": 1,
      "occurredAtUtc": "2026-08-11T12:00:00Z"
    }
  ]
}

Tenant, Gateway и Customer не принимаются из тела. Cloud получает их из аутентифицированного binding Gateway и отклоняет неизвестные поля. Product должен соответствовать указанному meter BC-USG. Надёжный успешный ответ:

{
  "batchId": "019c5bc0-0000-7000-8000-000000000005",
  "status": "accepted",
  "acceptedAtUtc": "2026-08-11T12:00:01Z",
  "eventCount": 1,
  "replayed": false
}

Подтверждение возвращается только после надёжной записи всех событий и receipt. Точный повтор возвращает исходные acceptedAtUtc, число событий и replayed: true без дубликатов. Повтор ключа batch с изменённым содержимым возвращает 409.

Ошибки и восстановление

400 означает некорректный ввод или отклонённое usage-событие; 401 — неверное доказательство владения ключом; 403 — истёкшую подпись или запрещённое состояние Gateway; 409 — конфликт cursor/idempotency/generation/content; 413 — тело больше 512 KiB; 415 — не-JSON ввод; 503 — недоступный пакет, состояние аутентификации или usage owner. Ошибки используют стандартный публичный envelope и не возвращают ключи, подписи, Tenant или Customer.

Эндпоинты синхронизации только выдают и подтверждают Cloud-поколения; endpoint usage записывает факты и не может выдавать или продлевать права. Host хранит usage-события и membership batch как append-only доказательство, повторяет точные сохранённые байты и надёжно записывает совпадающий Cloud ack. См. регистрацию публичного ключа Gateway и Local Relay.