Entity Management
Relevant source files
The following files were used as context for generating this wiki page:
Entity Management in the flext-web project provides a centralized framework for handling web application instances as domain entities. It follows Domain-Driven Design (DDD) principles, treating web applications as Aggregate Roots with unique identities, state lifecycles, and event-sourcing capabilities. This module is responsible for the creation, validation, and operational state management of these entities within the FLEXT platform.
The system is built upon a foundation of typed runtime settings and specialized service layers, ensuring that all entity operations maintain type safety and adhere to strict business rules. It integrates closely with the Railway-Oriented Programming pattern used throughout the project to handle operational results and errors gracefully.
Sources: src/flext_web/_models/_entity.py:16-30, development.md:14-22, development/README.md:14-20
Domain Models
The core of Entity Management resides in the FlextWebModelsEntity namespace, which defines the structural and behavioral requirements for web applications.
Web Entity (Aggregate Root)
The Web.Entity class is the primary domain object. It inherits from m.Entity and manages the complete lifecycle of a web application instance. It includes identity management via UUIDs and comprehensive validation for application names and statuses.
The diagram shows the relationship between the active Entity and its snapshot configuration EntityConfig.
Sources: src/flext_web/_models/_entity.py:20-55, src/flext_web/_models/_entity.py:228-245
Model Fields and Constraints
| Field | Type | Description | Constraints |
|---|---|---|---|
id | str | Unique application identifier | Default: UUID v4 |
name | str | Application name | 1-N chars; no reserved names or dangerous patterns |
host | str | Application host address | Max length defined in constants |
port | t.PortNumber | TCP port number | Must be within valid port range |
status | str | Current application state | Must be in: RUNNING, STOPPED, STARTING, ERROR, etc. |
environment | str | Deployment environment | e.g., development |
Sources: src/flext_web/_models/_entity.py:57-112
Operational Lifecycle
Entities transition through various states driven by service operations. The Web.Entity implementation provides properties and methods to safely manage these transitions.
State Transitions
The following state machine represents the allowed transitions for an entity:
Operational methods return p.Result objects to ensure the caller handles potential transition failures.
Sources: src/flext_web/_models/_entity.py:130-155, src/flext_web/_models/_entity.py:200-240
Lifecycle Validation Logic
Before any state change, the entity performs internal checks:
can_start: Only allows starting if status isSTOPPED.can_stop: Only allows stopping if status isRUNNING.can_restart: Allows restarting fromRUNNING,STOPPED, orERRORstates.healthy: Returns true if the status is eitherRUNNINGorMAINTENANCE.
Sources: src/flext_web/_models/_entity.py:136-160
Service Layer and Utilities
Entity management is exposed through service implementations located in src/flext_web/services/. These services interact with the facade to perform high-level operations.
Factory and Construction
Entities are typically created through factory methods that consume EntityConfig or direct parameters. The tests/utilities.py file demonstrates how the system uses namespaced MRO (Method Resolution Order) factories to instantiate these objects during runtime.
# Example of entity creation via test utilities
def create_test_app(**kwargs: t.Scalar) -> m.Web.Entity:
defaults = {
"id": "test-id",
"name": "TEST_APP",
"host": "localhost",
"port": 8080,
}
# ... logic to merge kwargs and instantiate m.Web.Entity
return m.Web.Entity(**defaults)
Sources: tests/utilities.py:157-180, tests/utilities.py:237-260
Integration Points
- Facade Access: The project standardizes on a canonical public facade:
from flext_web import web. - Service Registration: Services for entities, auth, and health are mapped in the implementation map to support protocol-backed operations.
- Metric Updates: Entities support updating metrics (e.g.,
requests,errors,uptime) which triggers internalMetricsUpdatedweb events.
Sources: development.md:14-18, development/README.md:14-22, src/flext_web/_models/_entity.py:262-282
Event Management
The entity model distinguishes between two types of events:
- Web Events: Internal strings used for application lifecycle tracking (e.g.,
ApplicationStarted,MetricsUpdated). - Domain Events: DDD-style events that represent significant state changes in the domain, buffered for eventual persistence or dispatch.
Sources: src/flext_web/_models/_entity.py:121-125, src/flext_web/_models/_entity.py:186-200
Summary
Entity Management in flext-web provides a robust, type-safe framework for managing web applications as domain-driven entities. By combining strict Pydantic validation, clear state transition rules, and a centralized facade-based service architecture, the system ensures that application instances remain consistent and healthy throughout their lifecycle.
Sources: src/flext_web/_models/_entity.py