Ir para o conteúdo

Referência

Fluxo de eventos

Os eventos enviados pelo servidor de um projeto: nomes, conteúdos, ordenação, reexecução e quando recarregar.

Última atualização:

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#

ParteSignificado
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álidoUm valor não inteiro ou negativo é E_VALIDATION (400) antes de o fluxo começar.
Resposta200, 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#

Text
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#

EventoQuandoCampos principais
batch.committedUma edição, desfazer, refazer, migração ou importação foi confirmadarevision, base_revision, kind, actor, at, description, diff
project.updatedO projeto foi movido para a lixeira ou restauradostate (active ou trashed), at
asset.updatedO estado ou o progresso da ingestão de uma mídia mudouasset_id, state, progress, error, updated_at
job.updatedUma tarefa mudou de estado ou de progressojob_id, kind, state, progress, error, result, updated_at
resync.requiredO servidor não consegue atualizar este cliente por reexecuçãorevision, 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.committed sã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.updated e job.updated não têm garantia de ordem e não podem ser reexecutados. Guarde o evento com o updated_at mais 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 since desatualizado depois de resync.required.
  • Esperar que a resposta a uma edição e o seu evento difiram: ambos trazem os mesmos dados para a mesma revisão.

Próximos passos#