Event Bus

Event Bus

Publique e inscreva-se em eventos para observabilidade — monitoramento de atividade do runtime e da aplicação e reação a ela.

Use o event bus apenas para observação: monitoramento, logging, métricas e efeitos colaterais reativos. É um canal publish/subscribe de melhor esforço, não um transporte confiável — não construa lógica de negócio sobre ele nem dependa dele para entrega garantida. Para mensagens críticas de negócio, use mensagens de processo (`process.send`), channels ou a [fila de mensagens](lua/storage/queue.md).

Carregamento

local events = require("events")

Inscrevendo-se em Eventos

Inscreva-se em eventos do event bus:

-- Inscreva-se em todos os eventos de pedidos
local sub, err = events.subscribe("orders.*")
if err then
    return nil, err
end

-- Inscreva-se em tipo de evento específico
local sub = events.subscribe("users", "user.created")

-- Inscreva-se em todos os eventos de um sistema
local sub = events.subscribe("payments")

-- Processar eventos
local ch = sub:channel()
while true do
    local evt, ok = ch:receive()
    if not ok then break end

    logger:info("Received event", {
        system = evt.system,
        kind = evt.kind,
        path = evt.path
    })
    handle_event(evt)
end

Parâmetro	Tipo	Descrição
system	string	Padrão do sistema (suporta wildcards como “test.*“)
kind	string	Filtro de tipo de evento (opcional)

Retorna: Subscription, error

Enviando Eventos

Enviar um evento para o event bus:

-- Enviar evento de pedido criado
local ok, err = events.send("orders", "order.created", "/orders/123", {
    order_id = "123",
    customer_id = "456",
    total = 99.99
})
if err then
    return nil, err
end

-- Enviar evento de usuário
events.send("users", "user.registered", "/users/" .. user.id, {
    user_id = user.id,
    email = user.email,
    created_at = time.now():format("2006-01-02T15:04:05Z07:00")
})

-- Enviar evento de pagamento
events.send("payments", "payment.completed", "/payments/" .. payment.id, {
    payment_id = payment.id,
    order_id = payment.order_id,
    amount = payment.amount,
    method = payment.method
})

-- Enviar sem dados
events.send("system", "heartbeat", "/health")

Parâmetro	Tipo	Descrição
system	string	Identificador do sistema
kind	string	Tipo do evento
path	string	Caminho do evento para roteamento
data	any	Payload do evento (opcional)

Retorna: boolean, error

Métodos de Subscription

Obtendo o Channel

Obter o channel para receber eventos:

local ch = sub:channel()

local evt, ok = ch:receive()
if ok then
    print("System:", evt.system)
    print("Kind:", evt.kind)
    print("Path:", evt.path)
    print("Data:", json.encode(evt.data))
end

Campos do evento: system, kind, path, data

Fechando Subscription

Cancelar inscrição e fechar o channel:

sub:close()

Permissões

Ação	Recurso	Descrição
events.subscribe	sistema	Inscrever-se em eventos de um sistema
events.send	sistema	Enviar eventos para um sistema

Erros

Condição	Tipo	Retentável
Sistema vazio	errors.INVALID	não
Tipo vazio	errors.INVALID	não
Caminho vazio	errors.INVALID	não
Política negou	errors.INVALID	não

Veja Error Handling para trabalhar com erros.