Handler Registration

Relevant source files

The following files were used as context for generating this wiki page:

• bubus/event_handler.py
• bubus-ts/src/event_handler.ts
• bubus-ts/tests/handlers.test.ts
• bubus-ts/tests/eventbus_basics.test.ts
• TODO_python.md
• TODO_ts.md

Handler Registration is the process by which functional logic is attached to an EventBus to react to specific BaseEvent types or patterns. It involves mapping a callable (function, method, or coroutine) to an event pattern, allowing the bus to orchestrate execution when matching events are dispatched.

The system supports diverse registration methods, including string-based pattern matching, class-based matching for strong typing, and wildcard registrations. Registered handlers are wrapped in metadata objects (EventHandler) that track identity, source location, and execution constraints such as timeouts and concurrency limits.

Sources: bubus-ts/src/event_handler.ts:80-100, bubus/event_handler.py:175-195, bubus-ts/tests/handlers.test.ts:25-45

Registration Mechanisms

Users register handlers using the on() method of an EventBus. This method accepts an event pattern and a callback.

Pattern Matching Types

• String Patterns: Matching specific event_type strings.
• Class/Factory Matchers: Matching the constructor or factory of a BaseEvent subclass, providing the best type inference for payloads.
• Wildcards (*): A universal matcher that allows a handler to receive every event flowing through the bus.

Sources: bubus-ts/tests/handlers.test.ts:25-50, bubus-ts/src/event_handler.ts:46-48

Handler Types

Handlers can be implemented as:

• Synchronous or Asynchronous functions.
• Instance methods (bound or unbound).
• Static or class methods.
• Anonymous/Arrow functions (often assigned a function#id name for identification).

Sources: bubus/event_handler.py:35-80, bubus-ts/tests/handlers.test.ts:77-105

The EventHandler Entity

Every registration creates an EventHandler instance. This class acts as a serializable metadata wrapper around the raw callable.

Identity and Hashing

Handlers are assigned a globally unique ID (UUIDv5) computed from a hash of:

• EventBus ID
• Handler Name
• Source File Path
• Registration Timestamp
• Event Pattern

This ensures that even if the same function is registered on different buses or with different patterns, they are tracked as distinct logical registrations.

Sources: bubus-ts/src/event_handler.ts:125-145, bubus/event_handler.py:235-250

Metadata Fields

Field	Type	Description
id	UUID String	Unique identifier for the registration.
handler	Callable	The actual function or coroutine to execute.
handler_name	String	Extracted name of the function or "anonymous".
handler_file_path	String	Source location (file and line number) for debugging.
handler_timeout	Number	Maximum allowed execution time (seconds).
event_pattern	String	The filter used during registration (e.g., "UserEvent" or "*").

Sources: bubus-ts/src/event_handler.ts:80-95, bubus/event_handler.py:195-210

Lifecycle and Workflow

The following diagram illustrates the flow from registration to the internal preparation for execution.

The registration process captures the execution context and source information immediately to facilitate later debugging and monitoring.
Sources: bubus-ts/src/event_handler.ts:150-175, bubus-ts/tests/handlers.test.ts:25-50

Error Taxonomy

The registration and subsequent execution system uses a specific hierarchy of errors to categorize handler failures:

• EventHandlerTimeoutError: Raised when the handler exceeds its configured handler_timeout.
• EventHandlerCancelledError: Raised when a pending handler is cancelled due to a failure in a parent scope (e.g., the event itself timed out before the handler started).
• EventHandlerAbortedError: Raised when a running handler is forced to stop due to external scope failures.
• EventHandlerResultSchemaError: Raised when the handler completes but its return value fails validation against the event's event_result_type.

Sources: bubus-ts/src/event_handler.ts:230-285, TODO_python.md:15-25

Deregistration

Handlers can be removed using the off() method. The system supports removing:

1. A specific handler by passing the original function reference.
2. A specific registration by passing the handler_id.
3. All handlers for a specific event type by passing only the event pattern.

Sources: bubus-ts/tests/eventbus_basics.test.ts:490-540

Conclusion

Handler Registration provides a robust mechanism for attaching logic to the bubus event system. By wrapping callables in the EventHandler class, the system maintains strict identity tracking and enables advanced features like automatic source detection, timeout enforcement, and structured error reporting across both Python and TypeScript implementations.