Fila, falhas e encerramento

Objetivo: entender como o assinante controla trabalho concorrente sem prometer entrega durável.

O callback precisa receber rápido

O cliente MQTT avisa a chegada de uma mensagem. O runtime captura receivedAt nesse callback, antes da espera na fila. Se medisse a hora só no worker, incluiria o atraso causado por mensagens anteriores.

SequentialQueue aceita itens e executa um worker de cada vez. A guarda running é marcada antes do primeiro await para impedir dois workers simultâneos.

O significado de “sequencial”

Cada item termina antes de iniciar o seguinte. Se a persistência falha, onError registra uma categoria genérica e a fila continua.

Não há retry automático desse item na fila. Ela fica em memória, não em uma tabela ou serviço de mensagens durável. Uma queda abrupta pode perder trabalho aceito que ainda não foi persistido.

Encerramento gracioso

O shutdown inicia desconexão MQTT, fecha novas admissões, espera os itens já aceitos e desconecta Prisma. A Promise de encerramento é reutilizada para que chamadas repetidas não iniciem limpezas concorrentes.

close impede novas entradas. onIdle espera worker e lista vazios. “Gracioso” é diferente de desligamento brusco do processo ou do host.

O que isso não resolve

Mecanismo	Ajuda com	Não garante
Fila sequencial	Ordem de processamento	Durabilidade após crash
Transação	Coerência de uma gravação	Entrega única MQTT
QoS 1	Entrega com possíveis repetições	Banco gravado exatamente uma vez
Timeout	Limite de espera	Saúde do inversor

Exercício

Uma mensagem falha no banco; a próxima será descartada?

Não por essa falha isolada. O worker informa o erro e continua. Isso não significa que a mensagem anterior será recuperada automaticamente.

Veja como essa etapa se relaciona à persistência.

Revisão: 06/10/2026. Base: queue.ts, mqtt-to-db/runtime.ts e subscriber.ts.