Advanced Plugin Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Advanced Plugin Configuration in the FLEXT system encompasses the structured definition, validation, and management of complex plugin settings. This includes handling multi-layered JSON mappings for infrastructure components such as databases (PostgreSQL), directory services (LDAP), and caching layers (Redis). The system leverages Pydantic-based domain models and Railway-Oriented Programming (ROP) to ensure that configurations are not only syntactically correct but also adhere to strict business rules before a plugin is activated within the platform.
The configuration lifecycle transitions from raw JSON definitions to validated Plugin.Entity objects, which are then registered within the FlextPluginPlatform. This architecture supports environment-specific overrides, resource-specific parameters (like connection pools and timeouts), and metadata tracking for monitoring plugin health and execution metrics.
Configuration Architecture and Data Flow
The configuration flow begins with the definition of a settings mapping, which is processed by the FlextPluginPlatform to create a validated execution environment.
This diagram illustrates the progression from raw configuration data to a live, executable plugin within the platform.
Sources: src/flext_plugin/_utilities/plugin_platform.py:340-410, src/flext_plugin/models.py:90-110
Structured Configuration Models
The FlextPluginModels.Plugin.Entity serves as the primary data structure for configuration. It includes fields for identity, versioning, and an extensible metadata field for operational metrics.
Key Configuration Entities
| Field | Type | Description |
|---|---|---|
name | str | Unique identifier (regex: ^[a-z0-9-]+$). |
plugin_version | str | Semantic versioning (X.Y.Z). |
plugin_type | Enum | Classification (e.g., TAP, TARGET, DATABASE). |
metadata | JsonMapping | Dynamic storage for metrics and dependencies. |
is_enabled | bool | Lifecycle toggle for activation. |
Sources: src/flext_plugin/models.py:53-90, tests/unit/test_domain_entities.py:30-45
Business Rule Validation
Validation is enforced through the validate_business_rules() method, which ensures the semantic version format is correct and that required fields are present.
def validate_business_rules(self) -> p.Result[bool]:
"""Validate plugin business rules."""
if not self.name or not self.name.strip():
return r[bool].fail("Plugin name cannot be empty")
# ... semantic version checks ...
return r[bool].ok(value=True)
Sources: src/flext_plugin/models.py:165-190, tests/unit/test_domain_entities.py:95-105
Advanced Integration Patterns
Advanced configurations often involve third-party service parameters. The following examples demonstrate how complex mappings are structured for different service types.
Database and Infrastructure Configuration
Infrastructure plugins require detailed connection parameters, including pooling logic and security settings.
# PostgreSQL Configuration Example
postgres_config = {
"host": "localhost",
"port": 5432,
"database": "flext_db",
"pool_size": 20,
"ssl_mode": "prefer",
"connection_timeout": 10
}
# LDAP Configuration Example
ldap_config = {
"server": "localhost",
"base_dn": "dc=flext,dc=dev",
"bind_dn": "cn=readonly,dc=flext,dc=dev",
"use_ssl": False,
"cache": {"enabled": True, "ttl_seconds": 300}
}
Sources: examples/02_plugin_configuration.py:20-55, examples/03_docker_integration.py:40-65
Docker and Environment Integration
In containerized environments, plugins are configured to interact with networked services. The configuration logic typically includes health checks to verify service availability before the plugin entity is finalized.
Lifecycle and Metadata Tracking
Advanced configuration is not static; it includes mutable metadata used for tracking execution performance and error rates.
- Execution Metrics: Tracks
execution_count,total_execution_time,success_count, andfailure_count. - Error Reporting: Specifically captures the
last_errorand increments anerror_countwithin the plugin's metadata.
def record_execution(self, execution_time: float, *, success: bool) -> None:
metadata = dict(self.metadata)
metadata["execution_count"] = metadata.get("execution_count", 0) + 1
metadata["total_execution_time"] = metadata.get("total_execution_time", 0.0) + execution_time
# ... update success/failure counts ...
self.metadata = t.json_mapping_adapter().validate_python(metadata)
Sources: src/flext_plugin/models.py:130-160, tests/unit/test_domain_entities.py:58-75
Conclusion
Advanced Plugin Configuration provides the robust foundation required for enterprise-grade extensibility. By combining multi-layered JSON mappings with strict domain model validation and real-time metadata tracking, the system ensures that plugins remain stable, observable, and easily integrated with complex external infrastructures like Docker-hosted databases and directory services.