Cola de Mensajes

Publicar y consumir mensajes de colas distribuidas. Soporta multiples backends incluyendo RabbitMQ y otros brokers compatibles con AMQP.

Para configuración de colas, consulte Cola.

Carga

local queue = require("queue")

Publicar Mensajes

Enviar mensajes a una cola 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	Descripción
`queue_id`	string	Identificador de cola (formato: “namespace:name”)
`data`	any	Datos del mensaje (tablas, strings, numeros, booleanos)
`headers`	table	Cabeceras de mensaje opcionales

Devuelve: boolean, error

Cabeceras de Mensaje

Las cabeceras permiten enrutamiento, prioridad y trazabilidad:

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

Acceder al Contexto de Entrega

Dentro de un consumidor de cola, acceder al mensaje actual:

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()

Devuelve: Message, error

Solo disponible cuando se procesan mensajes de cola en contexto de consumidor.

Metodos de Message

Método	Devuelve	Descripción
`id()`	`string, error`	Identificador único de mensaje
`header(key)`	`any, error`	Valor de cabecera individual (nil si falta)
`headers()`	`table, error`	Todas las cabeceras del mensaje
`ack()`	`boolean, error`	Confirmar procesamiento (single-shot)
`nack()`	`boolean, error`	Señalar fallo para reentrega o dead-letter (single-shot)

El runtime hace auto-ack al éxito del handler y auto-nack al error del handler. Llama a ack/nack solo para confirmar anticipadamente.

Información de Cola

local stats, err = queue.info("app:tasks")
-- stats puede contener: message_count, consumer_count, ready (depende del driver)

Devuelve: table, error

Patrón de Consumidor

Los consumidores de cola se definen como puntos de entrada que reciben el payload directamente:

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  -- El mensaje sera reencolado o enviado a dead-letter
    end
end

Permisos

Las operaciones de cola estan sujetas a evaluacion de politica de seguridad.

Accion	Recurso	Descripción
`queue.publish`	-	Permiso general para publicar mensajes
`queue.publish.queue`	ID de Cola	Publicar a cola especifica

Ambos permisos se verifican: primero el permiso general, luego el específico de cola.

Errores

Condición	Tipo	Reintentable
ID de cola vacio	`errors.INVALID`	no
Datos de mensaje vacios	`errors.INVALID`	no
Sin contexto de entrega	`errors.INVALID`	no
Publicacion no permitida	`errors.INVALID`	no
Publicacion fallida	`errors.INTERNAL`	no

Consulte Manejo de Errores para trabajar con errores.

Vea También

Configuración de Cola - Drivers de cola y definiciones de entrada
Guia de Consumidores de Cola - Patrones de consumidor y pools de workers
Gestión de Procesos - Creacion y comunicación de procesos
Canales - Patrones de comunicación entre procesos
Funciones - Invocacion asincrona de funciones