Message Queue

Publique e consuma mensagens de filas distribuidas. Suporta multiplos backends incluindo RabbitMQ e outros brokers compativeis com AMQP.

Para configuração de fila, veja Queue.

Carregamento

local queue = require("queue")

Publicando Mensagens

Enviar mensagens para uma fila por ID:

local ok, err = queue.publish("app:tasks", {
    action = "send_email",
    user_id = 456,
    template = "welcome"
})
if err then
    return nil, err
end

Parâmetro	Tipo	Descrição
`queue_id`	string	Identificador da fila (formato: “namespace:name”)
`data`	any	Dados da mensagem (tabelas, strings, numeros, booleans)
`headers`	table	Headers opcionais da mensagem

Retorna: boolean, error

Headers de Mensagem

Headers habilitam roteamento, prioridade e rastreamento:

queue.publish("app:notifications", {
    type = "order_shipped",
    order_id = order.id
}, {
    priority = "high",
    correlation_id = request_id
})

Acessando Contexto de Entrega

Dentro de um consumer de fila, acessar a mensagem atual:

local msg, err = queue.message()
if err then
    return nil, err
end

local msg_id = msg:id()
local priority = msg:header("priority")
local all_headers = msg:headers()

Retorna: Message, error

Disponível apenas ao processar mensagens de fila em contexto de consumer.

Métodos de Message

Método	Retorna	Descrição
`id()`	`string, error`	Identificador único da mensagem
`header(key)`	`any, error`	Valor de header único (nil se ausente)
`headers()`	`table, error`	Todos os headers da mensagem
`ack()`	`boolean, error`	Confirmar processamento (single-shot)
`nack()`	`boolean, error`	Sinalizar falha para reentrega ou dead-letter (single-shot)

O runtime faz auto-ack no sucesso do handler e auto-nack no erro do handler. Chame ack/nack apenas para confirmar antecipadamente.

Informação da Fila

local stats, err = queue.info("app:tasks")
-- stats pode conter: message_count, consumer_count, ready (depende do driver)

Retorna: table, error

Padrão de Consumer

Consumers de fila sao definidos como entry points que recebem o payload diretamente:

entries:
  - kind: queue.consumer
    id: email_worker
    queue: app:emails
    method: handle_email

function handle_email(payload)
    local msg = queue.message()

    logger:info("Processing", {
        message_id = msg:id(),
        to = payload.to
    })

    local ok, err = email.send(payload.to, payload.template, payload.data)
    if err then
        return nil, err  -- Mensagem sera reenfileirada ou dead-lettered
    end
end

Permissões

Operações de fila estao sujeitas a avaliação de política de segurança.

Ação	Recurso	Descrição
`queue.publish`	-	Permissão geral para publicar mensagens
`queue.publish.queue`	ID da Fila	Publicar em fila específica

Ambas as permissões sao verificadas: primeiro a permissão geral, depois a específica da fila.

Erros

Condição	Tipo	Retentável
ID da fila vazio	`errors.INVALID`	não
Dados da mensagem vazios	`errors.INVALID`	não
Sem contexto de entrega	`errors.INVALID`	não
Publicação não permitida	`errors.INVALID`	não
Publicação falhou	`errors.INTERNAL`	não

Veja Error Handling para trabalhar com erros.

Veja Também

Queue Configuration - Drivers de fila e definicoes de entrada
Queue Consumers Guide - Padroes de consumer e pools de workers
Process Management - Criação de processos e comunicação
Channels - Padroes de comunicação entre processos
Functions - Invocação de funções assíncronas