Event Bus

The event bus publishes runtime and application activity for monitoring, logging, metrics, and reactive side effects. This page is an API reference; the snippets assume an executable Lua entry with the listed module and permissions.

Loading

local events = require("events")

Subscribing to Events

Subscribe to one system or a system pattern, with an optional event-kind filter:

-- Subscribe to all order events
local sub, err = events.subscribe("orders.*")
if err then
    return nil, err
end

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

    print(evt.system, evt.kind, evt.path)
    -- Process evt.data when the publisher supplied a payload.
end

Pass a second argument to restrict delivery to one kind, for example events.subscribe("users", "user.created"). An omitted kind accepts every kind from the matching system.

Returns: Subscription, error

Publishing Events

Publish an event to the event bus:

-- Send order created event
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

-- Send without data
local heartbeat_sent, heartbeat_err = events.send("system", "heartbeat", "/health")
if heartbeat_err then
    return nil, heartbeat_err
end

Returns: boolean, error

A successful return confirms that the runtime accepted the send. It does not confirm that any subscriber received or processed the event.

Subscription Methods

Receive Channel

Use the subscription channel to receive events:

local json = require("json")
local ch = sub:channel()

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

Each event contains system, kind, and path. The data field is present only when the publisher supplied a non-nil payload.

Close a Subscription

Close the subscription to unsubscribe and close its channel:

local closed = sub:close() -- true

Closing is idempotent. After the channel is closed, receive() returns nil, false once buffered events are drained.

Permissions

Errors

See Error Handling for working with errors.