Service Protocols (Interfaces)
Relevant source files
The following files were used as context for generating this wiki page:
Service Protocols in flext-web define the runtime registry and protocol-backed operations that govern how the web platform interacts with various service implementations. These protocols provide a structured way to handle application lifecycles, framework management, and runtime state through a decoupled interface pattern.
The system utilizes a central runtime protocol and registry behavior to ensure that operational code can interact with services via a canonical public facade, typically accessed through the web instance. This architecture supports both FastAPI and Flask framework factories while maintaining a common service base with typed runtime settings.
Sources: development.md, src/flext_web/protocols.py
Architecture and Registry
The protocol system is designed around a runtime registry that tracks active service components and their states. This allows the platform to manage multiple application instances (e.g., development vs. production apps) through a unified interface.
Component Relationship
The following diagram illustrates the relationship between the public facade, the protocols, and the underlying service implementations:
The registry acts as the intermediary between the high-level API and the low-level protocol implementations.
Sources: development.md, src/flext_web/protocols.py
Lifecycle Protocols
The Lifecycle Protocol defines the standard transitions for service components within the flext-web ecosystem. It ensures that applications can be started, stopped, and queried for status in a consistent manner regardless of the underlying web framework.
State Transitions
Applications transition through specific states managed by the lifecycle protocol, as evidenced in service tests:
Operational transitions through running and stopped states via protocol-backed runtime state.
Sources: tests/unit/test_services.py:64-77
Key Lifecycle Operations
The following table summarizes the primary lifecycle operations defined within the protocol surface:
| Operation | Description | Return Type |
|---|---|---|
start_service | Bootstraps a runtime application and associated services. | p.Result[Status] |
stop_service | Tears down the runtime application and registry. | p.Result[None] |
service_status | Retrieves structured operational status and capabilities. | p.Result[ServiceStatus] |
start_app | Moves a specific application ID to the "running" state. | p.Result[AppData] |
stop_app | Moves a specific application ID to the "stopped" state. | p.Result[AppData] |
Sources: tests/unit/test_services.py:64-77, tests/unit/test_services.py:108-124
Framework Management Protocols
Framework protocols handle the initialization and configuration of the underlying web engines (FastAPI or Flask). These protocols ensure that middleware, routes, and API capabilities are correctly projected into the runtime environment.
Initialization Sequence
The initialization of a service involves specific protocol steps to ensure a coherent runtime projection:
Coherent projection of health, dashboard, and capability data.
Sources: tests/unit/test_services.py:94-106, src/flext_web/base.py
Capability Flags
The framework protocol exposes specific capability identifiers that indicate supported features:
framework_management: Ability to manage app lifecycles.flask_support: Indicates the presence of Flask-based factory support.fastapi_support: Indicates the presence of FastAPI-based factory support.
Sources: tests/unit/test_services.py:105, tests/unit/test_services.py:124
Implementation Patterns
Protocols are implemented using a "Service Rule" where behavior belongs in services, settings, or protocols, while the api.py facade remains thin.
# Protocol usage example derived from test patterns
from flext_web import web
# Initialize routes via framework protocol
init_result = web.initialize_routes()
# Start application via lifecycle protocol
start_result = web.start_app(app_id="runtime-app")
# Query status via registry protocol
status = web.service_status()
Sources: development.md, tests/unit/test_services.py:95-108
Summary
Service Protocols in flext-web provide the necessary abstraction to manage complex web application lifecycles and framework-specific configurations. By utilizing a central registry and structured lifecycle/framework protocols, the platform ensures that service operations remain consistent, typed, and decoupled from the specific implementation details of the web factories. This architecture allows for a thin public facade (web) that delegates all complex operational logic to specialized protocol handlers.
Sources: development.md, src/flext_web/protocols.py