tracium.v1 — gRPC-контракты публичного API (target-state)
job_events.proto — контракт стриминга событий асинхронных задач. Сервер НЕ
реализован; файл фиксирует схему заранее, чтобы клиенты и будущая реализация
не разъехались.
Единая схема событий (REST / WebSocket / gRPC)
| Поле | REST-опрос (GET …?after=) | WebSocket /v1/jobs/{kind}/{id}/events | gRPC JobEvents.Watch |
|---|---|---|---|
| строка | элемент lines[], курсор cursor | {"type":"line","seq":N,"line":{…}} | JobEvent{type:"line", seq, payload_json} |
| прогресс | progress{total,done,percent} в ответе | {"type":"progress","seq":N,"job":{…}} | JobEvent{type:"progress", payload_json} |
| финал | терминальный status | {"type":"final","seq":N,"job":{…}} + Close 1000 | JobEvent{type:"final"} + конец stream’а |
| отставание | не бывает (PG-replay по курсору) | {"type":"lagged"} → переподключиться с последним seq | lagged → сервер сам делает re-replay |
Payload строки/прогресса/финала — байт-в-байт JSON REST-ответа (сериализуется один раз, PG = source of truth, in-process шина jobstream = live-хвост).
Виды задач (job_kind): offers_refresh (актуализация цен/остатков),
estimate (расчёт сметы). Идентичность владельца — субъект API-ключа;
чужая задача неотличима от несуществующей.
Подробности протоколов: docs/docs/30-services/public-api/live-refresh.md.