Web Service Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Web Service Lifecycle in flext-web manages the operational states of the web interface and its hosted applications. It provides a structured approach to bootstrapping the service, managing individual application runtimes, and performing clean shutdowns. All lifecycle operations are exposed through a canonical public facade, ensuring a consistent interface for developers and integration tools.
This lifecycle is governed by the web object, which acts as a composed facade of multiple service layers, including health monitoring, authentication, and application management.
Sources: src/flext_web/api.py, development.md:46-52, src/flext_web/README.md:27-31
Service Initialization and Bootstrap
Before the service can process requests, it must undergo initialization. This includes configuring middleware, initializing routes, and setting up the runtime environment. The service status transitions from stopped to operational during this phase.
The diagram shows the sequence of internal calls triggered when web.start_service() is invoked to reach an operational state.
Sources: tests/unit/test_services.py:84-89, tests/unit/test_services.py:102-114
Key Bootstrap Operations
| Operation | Facade Method | Description |
|---|---|---|
| Initialize Routes | web.initialize_routes() | Prepares the URL routing table for the web service. |
| Configure Middleware | web.configure_middleware() | Sets up request/response processing layers (security, logging, etc.). |
| Start Service | web.start_service(host, port) | Bootstraps the main runtime application on the specified network interface. |
Sources: tests/unit/test_services.py:84-86, tests/unit/test_services.py:103
Application Runtime Lifecycle
The lifecycle distinguishes between the "Web Service" (the platform) and "Applications" (the hosted units). Individual applications transition through three primary states: created, running, and stopped.
Application State Transitions
Applications are managed via protocol-backed runtime state, allowing independent control of multiple app instances within the service.
Sources: tests/unit/test_services.py:65-71, examples/02_api_usage.py:70-98
Lifecycle Operations
The following methods manage the transition of applications:
- Creation:
web.create_app(AppData)registers a new application with the runtime registry. - Activation:
web.start_app(app_id)transitions an application to therunningstatus. - Deactivation:
web.stop_app(app_id)gracefully halts the application and moves it to thestoppedstatus. - Discovery:
web.list_apps()andweb.fetch_app(app_id)provide visibility into current application states.
Sources: src/flext_web/api.py, tests/unit/test_services.py:53-81, examples/02_api_usage.py:34-66
Monitoring and Health Projections
During the service lifecycle, the web facade provides continuous monitoring through health and capability projections. These ensure that the service is not only running but functioning correctly with all required capabilities.
Projections are read-only views of the current service state, exposed as Railway-Oriented Result objects.
Sources: tests/unit/test_services.py:87-93, tests/unit/test_services.py:116-121, src/flext_web/services/web.py
Health and Status Metrics
| Metric | Description |
|---|---|
| Service Status | Returns the broad operational state (e.g., operational, stopped) and capability flags like flask_support. |
| Health Response | Provides detailed health checks for specific service components. |
| API Capabilities | Lists available framework management features currently active in the lifecycle. |
| Dashboard | Returns a summary of the service initialization state, including route status. |
Sources: tests/unit/test_services.py:87-93, tests/unit/test_services.py:116-121
Shutdown and Teardown
A clean lifecycle termination involves stopping all running applications before shutting down the main service. The service base ensures that resources are released and the status is updated to stopped.
# Example of a clean shutdown sequence
def teardown_service():
# 1. Stop all hosted applications
apps = web.list_apps().unwrap()
for app in apps:
if app.status == "running":
web.stop_app(app.id)
# 2. Stop the main web service
web.stop_service()
Sources: tests/unit/test_services.py:14-22, tests/unit/test_services.py:109-114
Summary
The flext-web service lifecycle provides a robust framework for managing enterprise web interfaces. By using the canonical web facade, developers can consistently initialize the platform, manage granular application runtimes, monitor health through structured projections, and ensure graceful shutdowns. The architecture relies on Railway-Oriented Programming, where every lifecycle operation returns a Result type, ensuring that failures are handled explicitly throughout the service's existence.
Sources: development.md:46-52, src/flext_web/README.md:44-47