# Fluxo de eventos

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

Source: https://alexgalhardo.github.io/vukem-video/pt-br/docs/reference/events/

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

```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

| 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.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

- [API HTTP](/docs/reference/http-api)
- [Lotes, revisões e idempotência](/docs/agents/batches)
