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.