Plugin Lifecycle Management
Relevant source files
The following files were used as context for generating this wiki page:
Plugin Lifecycle Management in the FLEXT ecosystem refers to the end-to-end process of discovering, validating, registering, activating, executing, and cleaning up plugin entities. This system is built upon a Railway-Oriented Programming (ROP) pattern, utilizing a Result[T] type to handle errors and state transitions gracefully. The management logic is primarily orchestrated by the FlextPluginPlatform and the FlextPlugin base class, ensuring that resources are allocated and released correctly while maintaining detailed execution metrics.
The lifecycle ensures that plugins transition through specific states—such as INACTIVE, ACTIVE, and ERROR—while strictly validating configurations and input data at each stage. This robust framework allows the FLEXT platform to support diverse plugin types including Taps, Targets, and Processors while maintaining system stability and observability.
Plugin State and Transitions
The status of a plugin is determined by its is_enabled boolean attribute and its interaction with the FlextPluginPlatform. A plugin entity tracks its own lifecycle state, which is reflected in the PluginStatus enumeration.
Status Transitions
- INACTIVE: The initial state upon registration or after being disabled.
- ACTIVE: The state after successful initialization and activation.
- ERROR: A state reached if execution or initialization fails.
The state transition flow for a FLEXT plugin from discovery to disposal.
Sources: examples/basic-plugin.md:39-166, src/flext_plugin/_utilities/plugin_platform.py:165-171, tests/unit/test_domain_entities.py:46-60
Core Lifecycle Methods
The FlextPlugin class provides three primary hooks that developers must implement to manage a plugin's lifecycle: initialize(), execute(), and cleanup().
| Method | Purpose | Typical Actions | Return Type |
|---|---|---|---|
initialize() | Resource Allocation | Validating config, establishing DB connections, setting up logging. | r[bool] |
execute() | Logic Processing | Transforming data, performing IO, updating internal statistics. | r[dict] |
cleanup() | Resource Deallocation | Closing connections, deleting temp files, saving final stats. | r[bool] |
Sources: examples/basic-plugin.md:47-152, examples/README.md:158-195
Initialization Phase
During initialization, the plugin validates its internal settings against business rules and prepares necessary resources. If any step fails, the r.fail() result prevents the plugin from moving to an active state.
Sources: src/flext_plugin/_utilities/plugin_platform.py:483-500, examples/basic-plugin.md:68-93
Execution Phase
Execution is protected by state checks. The platform verifies the plugin is both initialized and active before invoking the core logic.
Sources: src/flext_plugin/_utilities/plugin_platform.py:307-333, examples/basic-plugin.md:95-135
Cleanup Phase
Cleanup is invoked to ensure zero-debt resource management. It involves resetting internal flags and ensuring persistent data (like processing statistics) is saved.
Sources: examples/basic-plugin.md:137-157, examples/README.md:316-330
Platform Orchestration
The FlextPluginPlatform acts as the central registry and executor. It utilizes a PluginRegistry to track active entities and a PluginExecution entity to manage the lifecycle of individual execution runs.
The sequence of interactions between the platform and a plugin during registration and execution.
Sources: src/flext_plugin/_utilities/plugin_platform.py:207-268, examples/basic-plugin.md:280-315
Metrics and Monitoring
Plugin entities automatically track execution metrics within their metadata attribute. The FlextPluginModels.Plugin.Entity class provides methods to record successes, failures, and execution times.
| Metric Field | Description | Source |
|---|---|---|
execution_count | Total number of times the plugin was executed. | record_execution |
success_count | Number of successful executions. | record_execution |
failure_count | Number of failed executions. | record_execution |
total_execution_time | Cumulative time spent in execution (seconds). | record_execution |
error_count | Total count of errors encountered. | record_error |
last_error | The most recent error message string. | record_error |
Sources: src/flext_plugin/models.py:127-185, tests/unit/test_domain_entities.py:62-95
Discovery and Validation
Before a plugin enters the lifecycle, it must be discovered and validated. The FlextPluginUtilities and PluginDiscovery protocol search for files matching patterns like .py, .yaml, or .json and inspect them for manifests.
Validation Rules
- Naming: Must match
^[a-zA-Z][a-zA-Z0-9_-]*$. - Version: Must follow semantic versioning
X.Y.Z. - Safety: Files are scanned for dangerous patterns such as
exec(),eval(), oros.system. - Size: Individual plugin files are typically capped (e.g., 100MB).
Sources: src/flext_plugin/utilities.py:46-56, src/flext_plugin/models.py:75-80, src/flext_plugin/utilities.py:146-180
Conclusion
Plugin Lifecycle Management in FLEXT provides a structured, fail-safe environment for extending platform functionality. By enforcing strict transitions between registration, initialization, execution, and cleanup, the system ensures that plugins remain observable and resource-efficient. The use of Railway-Oriented Programming throughout the lifecycle guarantees that errors are caught early and handled without destabilizing the core platform.