Request Handlers

Relevant source files

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

• src/flext_core/_handlers_parts/flexthandlers_part_04.py
• src/flext_core/_protocols/handler.py
• examples/ex_04_flext_dispatcher.py
• tests/unit/test_handlers_lifecycle.py
• tests/unit/test_handlers_validation_context.py
• src/flext_core/_root_typing.py

Request Handlers in FLEXT-Core represent the foundational units for processing commands, queries, and domain events within a Clean Architecture framework. These handlers favor structural typing and provide a robust execution pipeline that integrates validation, business logic, and metrics recording using Railway-Oriented Programming (ROP) principles.

The system is designed around the FlextHandlers base class and the p.Handler protocol, ensuring that all processing units return Result objects (r[T]) instead of raising exceptions. This approach facilitates safe chaining, predictable error handling, and seamless integration with the FlextDispatcher for message routing.

Sources: src/flext_core/_handlers_parts/flexthandlers_part_04.py:1-15, src/flext_core/_protocols/handler.py:1-12, examples/ex_04_flext_dispatcher.py:1-10

Core Architecture and Protocols

FLEXT-Core uses structural protocols to define handler behaviors, allowing the FlextDispatcher to route messages to any object that implements the required interface. The primary protocol is p.Handler, which mirrors the public API of the concrete FlextHandlers class.

Handler Protocols

Protocol	Purpose	Key Method(s)
Handler[MessageT, ResultT]	Full typed handler contract including lifecycle and context.	handle(), execute(), validate_message()
Handle	Minimal protocol for business logic execution.	handle(message)
DispatchMessage	Protocol for routing messages through a custom dispatch path.	dispatch_message(message)
Execute	Protocol for executing routed messages with transformations.	execute(message)
AutoDiscoverableHandler	Allows runtime inspection of supported message types.	can_handle(message_type)

Sources: src/flext_core/_protocols/handler.py:34-118

Architectural Flow

The following diagram illustrates how a message flows from a dispatcher to a handler implementation:

Handler Implementation

Concrete handlers are typically implemented by subclassing FlextHandlers. This class provides built-in support for context management, metrics, and a standardized validation hook.

The Execution Pipeline

The execution of a handler follows a specific sequence to ensure data integrity and observability:

1. Validation: validate_message(data) is called to verify input data. By default, it checks for non-null values but is intended to be overridden for domain-specific rules.
2. Logic Execution: handle(message) contains the core business logic. Subclasses MUST implement this method.
3. Metrics: Throughout execution, metrics like execution_time_ms and success status are recorded in the handler's runtime state.

Sources: src/flext_core/_handlers_parts/flexthandlers_part_04.py:25-63, src/flext_core/_handlers_parts/flexthandlers_part_04.py:93-111

Context Management

Handlers maintain an internal stack for execution context, allowing metadata to be propagated through complex operations.

• push_context(ctx): Adds execution context (e.g., user IDs, operation IDs) to the stack.
• pop_context(): Removes and returns the top context from the stack as a ConfigMap.
• record_metric(name, value): Stores a key-value pair in the current execution context for observability.

Sources: src/flext_core/_handlers_parts/flexthandlers_part_04.py:65-83, tests/unit/test_handlers_validation_context.py:108-135

Routing and Dispatching

Handlers are registered with the FlextDispatcher, which uses message types or custom discovery logic to route incoming requests.

Registration Types

Handlers can be registered for two primary purposes:

1. Direct Commands/Queries: Single handler per message type.
2. Events: Multiple subscribers can be registered for the same event type.

Handler Configuration

Handlers are configured using the m.Handler model, which defines properties used by the dispatcher:

• handler_name: Human-readable identifier.
• mode: The type of handler (e.g., COMMAND, QUERY, EVENT).
• metadata: Key-value attributes (e.g., priority).
• command_timeout: Execution limits.

Sources: tests/unit/test_handlers_lifecycle.py:31-50, tests/unit/test_handlers_lifecycle.py:116-135

Validation and Error Handling

FLEXT-Core enforces a zero-exception policy within handlers. All operational failures are returned as r.fail outcomes.

Common Failure Scenarios

Failure Type	Error Code / Message	Description
Validation Error	ERR_MESSAGE_CANNOT_BE_NONE	Input message was null.
Type Mismatch	UNEXPECTED_MESSAGE_TYPE	Handler received a message type it cannot process.
Execution Failure	ERR_HANDLER_FAILED	Internal error during the business logic phase.
Context Error	pop handler context	Attempted to pop context from an empty or corrupted stack.

Sources: src/flext_core/_handlers_parts/flexthandlers_part_04.py:68-72, tests/unit/test_handlers_lifecycle.py:75-80, tests/unit/test_handlers_validation_context.py:63-68

Summary

Request Handlers provide the structured execution environment necessary for maintaining Clean Architecture boundaries in FLEXT-Core. By adhering to strict protocols and the Railway-Oriented Programming model, they ensure that business logic is decoupled from routing concerns while remaining fully observable through built-in context and metrics support. Implementation via FlextHandlers ensures that validation and execution remain consistent across the entire application layer.