Runtime Environment Lifecycle
Relevant source files
The following files were used as context for generating this wiki page:
The Runtime Environment Lifecycle in FLEXT-Core governs the foundational state, configuration, and execution context of the enterprise framework. It ensures that infrastructure components like dependency injection containers, logging levels, and metadata normalization are consistently initialized and managed across the application's lifespan.
This lifecycle is built upon a Clean Architecture foundation, utilizing a "Layer 0" approach where centralized constants and types provide a stable baseline for higher-level application logic. The runtime environment acts as the bridge between static configuration and dynamic execution, ensuring observability through context propagation and enforcing quality gates through automated checks.
Sources: README.md:9-15, src/flext_core/_runtime/_base.py:1-15
Core Runtime Foundation
The runtime foundation provides the essential helpers required for higher runtime namespaces. It handles instance creation, timezone enforcement, and log level resolution.
Instance Creation and Type Safety
The system uses object.__new__ for instance creation with explicit type validation to ensure that created instances strictly adhere to the expected class types.
@staticmethod
def create_instance[T](https://github.com/flext-sh/flext-core/blob/d3036b150f5211032434814e3fb2565304c17e98/class_type%3A%20type%5BT%5D) -> T:
"""Create an instance through object.__new__ with type validation."""
instance = object.__new__(class_type)
if not isinstance(instance, class_type):
msg = f"object.__new__ did not return instance of {class_type.__name__}"
raise TypeError(msg)
return instance
Sources: src/flext_core/_runtime/_base.py:34-41
Timezone and Scalar Management
To maintain temporal consistency, the runtime environment enforces UTC timezones on naive datetime objects. Additionally, it provides coercion utilities to convert arbitrary runtime values into standardized Scalar types (string, int, float, bool).
Sources: src/flext_core/_runtime/_base.py:43-47, src/flext_core/_runtime/_base.py:79-84
Runtime Metadata and JSON Normalization
The lifecycle includes a dedicated phase for normalizing complex runtime data structures into JSON-compliant formats. This ensures that metadata across the system remains consistent and serializable.
Normalization Logic
The FlextRuntimeMetadata component handles the translation of Pydantic models, Path objects, and complex mappings into validated JSON values.
The diagram shows the logic flow for normalizing various Python types into metadata-compatible JSON values.
Sources: src/flext_core/_runtime/_metadata.py:23-45, src/flext_core/_runtime/_metadata.py:75-111
| Method | Purpose | Input Types | Output |
|---|---|---|---|
normalize_to_json_value | Single value normalization | Scalar, Path, BaseModel, None | tb.JsonValue |
normalize_to_json_mapping | Mapping normalization | MappingKV[str, ts.JsonPayload] | tb.JsonMapping |
normalize_to_metadata | Full metadata conversion | ConfigMap, AbstractSet, datetime | tb.JsonValue |
Sources: src/flext_core/_runtime/_metadata.py:25-111
Dependency Injection Lifecycle
The FlextContainer manages the lifecycle of services, resources, and configurations. It supports singleton patterns, factory-based registration, and scoped resolution.
Container Initialization
The container lifecycle typically starts with fetching a shared global instance or creating a fresh instance for testing purposes.
This sequence illustrates the standard lifecycle of service registration and resolution within the container.
Sources: examples/ex_08_flext_container.py:100-115, tests/integration/test_system.py:218-228
Registration Methods
The container provides three primary ways to manage object lifecycles:
- Bind: Registers a static value or pre-instantiated service.
- Factory: Registers a callable that generates a new instance upon every resolution.
- Resource: Registers a component that may require specific initialization/teardown logic.
Sources: examples/ex_08_flext_container.py:38-50
Observability and Logging Lifecycle
The runtime environment dynamically resolves log levels based on the execution context (e.g., debug or trace flags).
Log Level Resolution
The system prioritizes flags in a specific hierarchy to ensure appropriate verbosity during development or production.
| Condition | Resolved Level |
|---|---|
trace=True | DEBUG |
debug=True | INFO |
| Default | Configured log_level |
Sources: src/flext_core/_runtime/_base.py:61-72
Summary
The Runtime Environment Lifecycle in FLEXT-Core provides a deterministic framework for application execution. By centralizing instance creation, metadata normalization, and dependency management, it ensures that enterprise applications remain stable and observable. The lifecycle begins with foundational base helpers, moves through container registration and configuration, and maintains integrity through consistent data normalization and log level resolution.
Sources: src/flext_core/_runtime/_base.py, src/flext_core/_runtime/_metadata.py, README.md