Request Handlers

Relevant source files

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

• src/flext_web/services/handlers.py
• tests/unit/test_handlers.py
• development.md
• guides/development.md
• README.md
• api-reference/generated/overview.md

Request Handlers in flext-web represent the core coordination layer for web-specific operations, command processing, and response formatting. They follow the "one class per module" architectural requirement, serving as the single point of access for all handler functionality while extending the foundational patterns established in flext-core. Sources: src/flext_web/services/handlers.py:16-24

The system is designed around a clean architecture that utilizes Railway-Oriented Programming (ROP) for error handling and a unified facade pattern. This ensures that web-specific services, such as health monitoring and application management, remain decoupled from the underlying framework while providing a consistent operational surface. Sources: development.md:12-19, guides/development.md:95-108

Core Architecture and Inheritance

The primary implementation is contained within the FlextWebHandlers class, which inherits from the base service class s. This structure ensures that handlers comply with the project's standard lifecycle requirements, including execution and business rule validation. Sources: src/flext_web/services/handlers.py:16-26

Handler Lifecycle Flow

The following diagram illustrates how the FlextWebHandlers class coordinates between request models and business logic via the public facade.

Key Handler Functions

The handlers manage specific web domain operations, including application lifecycle and system diagnostics.

Application Management

Handlers facilitate the creation, starting, and stopping of application entities. These operations use the m.Web.Entity model and return p.Result objects to handle success or failure states gracefully. Sources: src/flext_web/services/handlers.py:30-74

Function	Purpose	Returns
handle_create_app	Initializes a new web application entity with default settings.	p.Result[m.Web.Entity]
handle_start_app	Transitions an application entity to a running state.	p.Result[m.Web.Entity]
handle_stop_app	Transitions an application entity to a stopped state.	p.Result[m.Web.Entity]

Sources: src/flext_web/services/handlers.py:30-74

System Diagnostics

Handlers provide high-level metadata about the service architecture and operational health. Sources: src/flext_web/services/handlers.py:76-108

• System Info: Returns architectural details, including patterns used (CQRS, Clean Architecture, DDD) and service capabilities. Sources: src/flext_web/services/handlers.py:76-92
• Health Check: Provides a detailed status report of components like the web service, configuration status, and handler registration. Sources: src/flext_web/services/handlers.py:94-108

Pattern Enforcement

Handlers are strictly bound to the r[T] pattern for all operations. This eliminates exception-based error handling in favor of functional flat-mapping. Sources: guides/development.md:95-108

# Implementation of application creation using Railway-Oriented Programming
@classmethod
def handle_create_app(
    cls, name: str, port: int = settings.Web.port, host: str = settings.Web.host
) -> p.Result[m.Web.Entity]:
    app_id = m.Web.Entity.format_id_from_name(name)
    app = m.Web.Entity(
        id=app_id,
        name=name,
        port=port,
        host=host,
        status=c.Web.Status.STOPPED.value,
        # ... other fields
    )
    return app.validate_business_rules().flat_map(lambda _: r[m.Web.Entity].ok(app))

Sources: src/flext_web/services/handlers.py:30-52

Integration with Public Facade

The FlextWebHandlers implementation is exposed through a public web instance. Tests verify that all handler-backed behavior—such as health checks, service status projections, and app registry integration—remains coherent through this facade. Sources: tests/unit/test_handlers.py:10-50, api-reference/generated/overview.md:12-14

Summary

Request Handlers in flext-web provide the essential coordination logic for the web platform. By centralizing operations in FlextWebHandlers and adhering to strict typing and functional error handling, the project ensures a robust, testable, and maintainable interface for application management and system monitoring. Sources: src/flext_web/services/handlers.py:16-24, guides/development.md:82-84