Introduction to bbus
Relevant source files
The following files were used as context for generating this wiki page:
bbus (also referred to as bubus in the codebase) is an advanced event bus library designed for high-performance, typed event orchestration across Python and TypeScript environments. It supports asynchronous execution, Pydantic-powered validation in Python, and Zod-powered validation in TypeScript, providing a unified runtime for browser, Node.js, and server-side Python applications.
The system is designed to handle complex event lifecycles, including serial or parallel handler execution, cross-bus forwarding with loop prevention, and hard timeout caps. It includes built-in support for middleware, allowing developers to extend the bus with logging, write-ahead logging (WAL), and OTel tracing.
Sources: pyproject.toml:2-4, bubus-ts/package.json:2-3, TODO_ts.md:1-10, TODO_python.md:1-10
Core Architecture
The bbus architecture centers on the EventBus class, which manages event dispatching, handler registration, and the internal runloop. Events are represented by BaseEvent objects, which carry a unique ID, type, version, and payload.
High-Level Component Interaction
The following diagram illustrates how a user dispatches an event and how the bus orchestrates handlers and middleware.
Citations: TODO_ts.md:40-60, TODO_python.md:42-55, tests/test_eventbus.py:100-115
Implementation Anchors
The implementation is split across Python and TypeScript with a focus on parity.
| Component | Python File/Line | TypeScript File/Line |
|---|---|---|
| Dispatch / Enqueue | bubus/event_bus.py:930 | bubus-ts/src/event_bus.ts:450 |
| Runloop Dequeue | bubus/event_bus.py:1587 | bubus-ts/src/event_bus.ts:865 |
| Event Process | bubus/event_bus.py:1887 | bubus-ts/src/event_bus.ts:687 |
| Handler Execution | bubus/event_bus.py:2194 | bubus-ts/src/event_result.ts:245 |
Sources: TODO_ts.md:68-80, TODO_python.md:58-70
Event Lifecycle and Status
Every event processed by bbus moves through a strict status lifecycle. Status transitions are monitored by middleware and reported via the bus.
| Status | Description |
|---|---|
pending | Event has been enqueued but not yet picked up by the runloop. |
started | Event has been dequeued and handlers have begun execution. |
completed | All handlers have finished execution (or the first() policy was met). |
Errors do not change the completed status of the BaseEvent; instead, they are recorded within the individual EventResult objects associated with each handler.
Sources: TODO_ts.md:16-17, TODO_python.md:15-20, bubus-ts/tests/eventbus_basics.test.ts:310-325
Validation and Schemas
bbus relies on external validation libraries to ensure payload and result integrity. In TypeScript, zod is used, while Python uses Pydantic.
TypeScript Example
const RegisterUserEvent = BaseEvent.extend('RegisterUserEvent', {
email: z.string().email(),
event_result_type: z.object({
user_id: z.string(),
}),
})
Sources: bubus-ts/examples/simple.ts:8-16
Python Example
class UserActionEvent(BaseEvent):
action: str
user_id: str
metadata: dict[str, Any] = Field(default_factory=dict)
Sources: tests/test_eventbus.py:53-58
Middleware and Extensions
The system supports a sequential middleware stack. Middlewares can hook into event lifecycle changes and handler results.
Standard Middlewares
- LoggerEventBusMiddleware: Logs event flow to stdout or a file.
- WALEventBusMiddleware: Write-Ahead Logging to a JSONL file.
- SQLiteHistoryMirrorMiddleware: Persists full event and result history to a SQLite database for monitoring.
- AutoErrorEventMiddleware: Automatically dispatches a new error event if a handler fails.
Sources: tests/test_eventbus.py:80-95, TODO_ts.md:205-215
Event Bridges
Bridges allow events to flow across process boundaries or networks. The bridges.ts module provides several implementations for IPC and network communication.
| Bridge Type | Protocol | Use Case |
|---|---|---|
HTTPEventBridge | HTTP/HTTPS | Cross-service communication via REST. |
SocketEventBridge | Unix Domain Sockets | High-performance local IPC. |
RedisEventBridge | Redis Pub/Sub | Distributed event distribution. |
NATSEventBridge | NATS | High-performance messaging. |
Sources: bubus-ts/src/bridges.ts:40-70, bubus-ts/src/bridges.ts:380-405
Monitoring and UI
bbus includes a minimal FastAPI-based monitoring dashboard. It reads from the tables created by the SQLiteHistoryMirrorMiddleware to provide a real-time view of event trees and handler results via WebSockets.
Key Dashboard Endpoints:
GET /: HTML Dashboard.GET /events: Latest events in JSON.WS /ws/events: Live stream of new events and results.
Sources: ui/main.py:45-55, ui/README.md:1-15
Summary
bbus is a robust, cross-language event bus designed for developers who need strict validation, observable lifecycles, and flexible execution policies. By combining advanced locking mechanisms with a comprehensive middleware system and real-time monitoring, it provides a stable foundation for event-driven architectures in both Python and TypeScript.