Configuration & Settings

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_plugin/models.py
• pyproject.toml
• tests/unit/test_config.py
• examples/02_plugin_configuration.py
• examples/basic-plugin.md
• src/flext_plugin/init.py

The FLEXT Plugin system utilizes a structured configuration architecture designed for isolation, type safety, and environment-driven management. At its core, the system distinguishes between global platform settings and specific plugin-level configurations. Platform-level settings are managed via FlextPluginSettings, which maintains a strict environment prefix to prevent collision with core system settings.

Individual plugins leverage a JSON-mapping based configuration model, often validated through Pydantic or domain-specific entities. This allows for complex setups including database connections, LDAP integrations, and operational parameters like batch sizes and timeouts. The system follows Railway-Oriented Programming patterns, ensuring that configuration validation returns explicit success or failure results.

Platform Settings Architecture

The platform settings are governed by the FlextPluginSettings class, which follows a singleton pattern for global access while allowing isolated snapshots for testing or specific contexts.

Environment Isolation

To ensure zero debt and clean boundaries, the plugin system uses a dedicated environment prefix. This prevents "leakage" from the root FLEXT_ namespace into plugin-specific operations.
Sources: tests/unit/test_config.py:28-30

The diagram above shows how environment variables are filtered by prefix to populate specific settings containers. Sources: tests/unit/test_config.py:11-30

Key Management Functions

Function	Description
fetch_global()	Retrieves the shared singleton instance of FlextPluginSettings.
clone()	Returns an independent, deep-copied snapshot of the current settings.
update_global(**kwargs)	Updates the singleton; raises ValueError if undeclared fields are provided.
reset_for_testing()	Resets the singleton state between test executions.
Sources: tests/unit/test_config.py:18-40

Plugin Configuration Models

Plugins define their own configuration schemas using the FlextPluginModels namespace. Configurations are typically passed as t.JsonMapping during initialization and stored within the plugin entity's metadata or a dedicated config attribute.

Entity Configuration Structure

The FlextPluginModels.Plugin.Entity represents the core domain object, which includes several configuration-related fields:

• name: Unique identifier validated against specific length and pattern constraints.
• plugin_version: Must follow semantic versioning (X.Y.Z).
• plugin_type: Categorizes the plugin (e.g., TAP, TARGET, DATABASE, SERVICE).
• metadata: A JsonMapping used for extensible configuration data and execution metrics.

Sources: src/flext_plugin/models.py:46-88

Configuration Data Flow

Implementation Examples

Advanced Service Configurations

Plugins often require complex nested configurations for external services. Standard patterns include database and directory service settings.

# Database Plugin Configuration Pattern
db_config = {
    "database": {
        "host": "localhost",
        "port": 5432,
        "pool_size": 5,
    },
    "retry_config": {
        "max_retries": 3,
        "exponential_backoff": True,
    }
}

Sources: examples/02_plugin_configuration.py:24-42

Validation and Business Rules

The system enforces strict validation of configuration parameters through the validate_business_rules method, which checks for empty names and non-numeric version parts.

Rule	Requirement	Source
Plugin Name	Non-empty, specific pattern/length	models.py:199
Version	X.Y.Z format (Numeric parts)	models.py:203-210
Type	Must exist in c.Plugin.Type StrEnum	models.py:213

Project Dependencies

The configuration system relies on several core libraries defined in the project metadata to handle validation and environment parsing:

• pydantic & pydantic-settings: Core validation and settings management.
• jsonschema: Schema validation for plugin definitions.
• flext-core & flext-cli: Base classes for entities and CLI integration.

Sources: pyproject.toml:28-36

Summary

The "Configuration & Settings" module provides a robust foundation for plugin development within the FLEXT ecosystem. By enforcing environment isolation via the FLEXT_PLUGIN_ prefix and utilizing type-safe models for plugin entities, the system ensures that plugin configurations are both flexible and resilient to operational errors. Sources: tests/unit/test_config.py:29, src/flext_plugin/models.py:34-40