Configuration & Environment
Relevant source files
The following files were used as context for generating this wiki page:
The bubus project maintains a unified configuration and environment strategy across its Python and TypeScript implementations. The system is designed to provide high-performance event orchestration with configurable concurrency, timeouts, and persistence mirrors. Configuration is handled through project-level metadata files, environment variables for runtime behavior, and class-level options for the EventBus and BaseEvent components.
Project Environment & Dependencies
The project is structured as a dual-language repository with independent build systems for Python and TypeScript, yet it shares semantic decisions regarding event lifecycle and error taxonomy.
Python Environment
The Python environment is managed via pyproject.toml, utilizing uv as the build backend. It targets Python versions >= 3.11 and includes several optional dependency groups for external bridges like Postgres, NATS, and Redis.
| Dependency Group | Key Packages | Purpose |
|---|---|---|
| Core | pydantic, anyio, portalocker | Validation and async primitives |
| Postgres | asyncpg | Optional database bridge |
| Redis | redis | Optional cache/message bridge |
| Dev | ruff, pytest, pyright | Linting, testing, and type checking |
Sources: pyproject.toml:1-45
TypeScript Environment
The TypeScript implementation is packaged as an ESM module targeting ES2022. It utilizes pnpm for package management and esbuild for bundling.
| Configuration | Value | Description |
|---|---|---|
| Target | ES2022 | Modern JavaScript target |
| Module Resolution | Bundler | Compatibility with modern bundlers |
| Strict Mode | true | Enables all strict type-checking options |
Sources: bubus-ts/tsconfig.json:3-12, bubus-ts/package.json:1-40
Runtime Configuration Options
The runtime behavior of the event bus is governed by configuration objects passed during instantiation or defined on event classes.
Event Bus Options
The EventBus owns orchestration and centralizes middleware invocation. In the unified runtime refactor, EventBusOptions are extended to support middleware registration.
A flowchart showing the hierarchy of configuration options within the EventBus.
- Middlewares: Accepts an array of either classes (constructors) or instances. Classes are auto-instantiated by the bus.
- Concurrency: Defines default behavior for handlers (e.g.,
serialvsparallel). - Timeouts: Provides default
event_timeoutandevent_handler_timeoutvalues.
Sources: TODO_ts.md:38-42, TODO_ts.md:145-160, TODO_python.md:140-145
Event-Level Configuration
Individual events can override bus-level defaults. Configuration is defined using a Zod schema in TypeScript or Pydantic in Python.
| Field | Type | Default | Description |
|---|---|---|---|
event_timeout | number | null | null | Hard cap across all handlers for an event. |
event_handler_timeout | number | null | event_timeout | Timeout for individual handlers. |
event_concurrency | enum | null | Controls event-to-event concurrency. |
event_handler_completion | enum | 'all' | Options: 'all' (wait for everyone) or 'first' (return first winner). |
Sources: bubus-ts/src/base_event.ts:16-40, TODO_ts.md:15-18
Persistence & Monitoring Environment
The project includes a monitoring UI and persistence middlewares that require specific environment setup.
SQLite History Mirror
The SQLiteHistoryMirrorMiddleware persists event and result logs to a local database. The database path is typically resolved via the EVENT_HISTORY_DB environment variable or a default path.
A sequence diagram illustrating the flow of data from the EventBus to the Monitoring UI via SQLite.
UI Configuration
The dashboard is a FastAPI application that reads from the mirrored tables. It provides endpoints for real-time monitoring:
GET /meta: Returns the database path and table readiness flags.WS /ws/events: Streams new rows via WebSocket usingHistoryStreamState.
Sources: ui/main.py:610-630, ui/README.md:1-25
Unified Error Taxonomy
The environment enforces a strict error taxonomy to ensure consistent behavior across Python and TypeScript runtimes. This is critical for middleware and diagnostics.
| Error Class | Trigger Condition |
|---|---|
EventHandlerCancelledError | Pending handler cancelled due to parent/event completion. |
EventHandlerResultSchemaError | Handler return value fails schema validation. |
EventHandlerTimeoutError | Handler execution exceeds specified timeout. |
EventHandlerAbortedError | Started handler forcefully stopped (e.g., in first() mode). |
Sources: TODO_ts.md:20-25, TODO_python.md:21-26
Summary
The bubus Configuration & Environment system provides a robust framework for managing asynchronous event flows. By utilizing standard project descriptors (pyproject.toml, package.json) alongside specialized runtime options for timeouts and concurrency, it ensures that both Python and TypeScript implementations behave predictably. The environment is further enhanced by optional database mirrors and a real-time monitoring UI, enabling deep visibility into the event lifecycle.