A ideia#
O editor e qualquer cliente que queira acompanhar um projeto abrem um fluxo por projeto: GET /api/v1/projects/{id}/events, escopo read. O fluxo é de mão única e apenas texto. Os comandos não trafegam nele; são requisições HTTP comuns. O MCP não tem fluxo. O comando da CLI vukem-video events --project <id> o imprime, um objeto JSON por linha.
Conectar#
| Parte | Significado |
|---|---|
since (query) | Uma revisão. Igual a Last-Event-ID, para clientes que não podem definir um cabeçalho na primeira requisição. |
Last-Event-ID (cabeçalho) | Definido pelo EventSource em cada reconexão. Quando ambos estão presentes, o cabeçalho vence. |
| Valor inválido | Um valor não inteiro ou negativo é E_VALIDATION (400) antes de o fluxo começar. |
| Resposta | 200, text/event-stream, sem compressão. |
A autenticação é conferida antes de a resposta virar um fluxo, então as falhas são erros JSON normais. O EventSource não repete nenhum status além de 200; o cliente precisa repetir. Enquanto o fluxo está aberto, o servidor confere a credencial de novo a cada 60 segundos e fecha o fluxo quando ela deixa de ser válida.
Formato no fio#
id: 42
event: batch.committed
data: {"project_id":"prj_7k2m9x4q1b","revision":42, ...}O data é um objeto JSON em uma linha. Apenas o batch.committed tem um id, e ele é a revisão. Os carimbos de data e hora são RFC 3339 UTC com milissegundos. Um cliente ignora os campos que não conhece.
Ao conectar, o servidor envia retry: 1000 e um evento sem nome com dados vazios, e repete esse evento vazio a cada 15 segundos como batimento. Registre ouvintes apenas para os cinco nomes abaixo e trate 40 segundos sem nenhum evento como uma conexão morta.
Eventos#
| Evento | Quando | Campos principais |
|---|---|---|
batch.committed | Uma edição, desfazer, refazer, migração ou importação foi confirmada | revision, base_revision, kind, actor, at, description, diff |
project.updated | O projeto foi movido para a lixeira ou restaurado | state (active ou trashed), at |
asset.updated | O estado ou o progresso da ingestão de uma mídia mudou | asset_id, state, progress, error, updated_at |
job.updated | Uma tarefa mudou de estado ou de progresso | job_id, kind, state, progress, error, result, updated_at |
resync.required | O servidor não consegue atualizar este cliente por reexecução | revision, reason |
Um diff grande demais para um evento é substituído por diff_truncated: true e uma lista changed de no máximo 500 entradas. Um job.updated terminal traz result ou error, então um cliente não precisa buscar a tarefa.
Ordenação e reexecução#
- Em um fluxo, as revisões de
batch.committedsão consecutivas, cada uma no máximo uma vez. Entre reconexões, um cliente pode ver uma revisão que já tem: ignore qualquer revisão menor ou igual à que você tem. asset.updatedejob.updatednão têm garantia de ordem e não podem ser reexecutados. Guarde o evento com oupdated_atmais novo para cada mídia ou tarefa. Ao conectar, o servidor envia o estado atual do que pode ter mudado enquanto você esteve fora.- Com uma revisão, o servidor reexecuta do registro o que você perdeu quando a lacuna é de no máximo 1.000 revisões.
O resync.required tem os motivos gap_too_large, before_floor (uma migração ou importação está no meio) e client_ahead (o servidor tem um banco de dados diferente ou restaurado). Ele não tem id. Depois dele, o servidor fecha o fluxo: recarregue o projeto com GET /api/v1/projects/{id} e abra um novo fluxo com since definido como a revisão que você carregou.
Erros comuns#
- Reconectar com um
sincedesatualizado depois deresync.required. - Esperar que a resposta a uma edição e o seu evento difiram: ambos trazem os mesmos dados para a mesma revisão.