Configuration and Settings
Relevant source files
The following files were used as context for generating this wiki page:
The flext-ldap library utilizes a structured configuration system based on Pydantic and the FLEXT framework standards. It provides a centralized approach to managing LDAP connection parameters, search behaviors, and synchronization settings through typed models and namespaced constants. This system ensures that all LDAP operations are performed against a validated and consistent configuration state.
Configuration is primarily handled through FlextLdapSettings (and its test counterpart TestsFlextLdapSettings), which aggregates various models to define server URIs, authentication credentials, timeouts, and operational limits. The architecture follows a "Single Source of Truth" (SSOT) principle where settings are read from environment variables or YAML files and parsed into canonical types.
Sources: examples/README.md:104-123, src/flext_ldap/_models/ldap.py:19-54, AGENTS.md:15-30
Connection Configuration
The core of the settings system is the ConnectionConfig model. This model defines the necessary parameters to establish a connection with an LDAP server, including security protocols and authentication details.
Connection Parameters
The library supports standard LDAP and LDAPS (SSL/TLS) connections. A critical validation rule within the ConnectionConfig model ensures that use_ssl and use_tls are mutually exclusive to prevent conflicting security state requests.
| Parameter | Type | Default | Description |
|---|---|---|---|
host | str | localhost | The LDAP server hostname. |
port | int | 389 | The server port (e.g., 389 for LDAP, 636 for LDAPS). |
use_ssl | bool | False | Enables LDAPS (SSL). |
use_tls | bool | False | Enables StartTLS negotiation. |
bind_dn | str | None | None | The Distinguished Name for binding. |
bind_password | str | None | None | Credentials for the bind DN. |
timeout | int | (From constants) | Network timeout in seconds. |
auto_bind | bool | True | Automatically perform bind upon connection. |
Sources: src/flext_ldap/_models/ldap.py:22-54, tests/constants.py:91-110
Security Logic Flow
The following diagram illustrates the mutual exclusivity validation and connection preparation logic defined in the models and constants.
Search Configuration Models
Search operations are governed by SearchOptions and NormalizedConfig. These models define the scope, filters, and limits applied to search requests.
Search Options Structure
SearchOptions requires a non-empty base_dn and provides defaults for scopes and filters.
- Scope: Supports
BASE,ONE_LEVEL,SUBTREE, andSUBORDINATE. - Filters: Defaults to
(objectClass=*)(all entries). - Limits: Includes
size_limit(entries returned) andtime_limit(seconds).
The SearchOptions.base_scope() factory method is specifically designed for point-lookups (like upsert existence checks), automatically requesting all user attributes by setting the attribute filter to *.
Sources: src/flext_ldap/_models/ldap.py:65-121, tests/constants.py:328-348
Synchronization and Batch Settings
For bulk operations and data synchronization, the library uses specialized configuration models to track metrics and control execution flow.
Sync Phase Configuration
The SyncPhaseConfig model allows developers to customize how synchronization phases behave, including error handling strategies and progress tracking.
| Configuration | Type | Description |
|---|---|---|
server_type | str | Target server type (e.g., OpenLDAP, OUD). |
max_retries | int | Number of retries for transient failures. |
stop_on_error | bool | Whether to abort the batch if a single entry fails. |
retry_on_errors | list[str] | Specific error patterns that trigger a retry. |
Sources: src/flext_ldap/_models/ldap.py:164-175, tests/constants.py:265-275
Batch Statistics Flow
When executing batch operations, results are aggregated into LdapBatchStats and MultiPhaseSyncResult.
Runtime Protocol Contracts
Configuration is enforced at the code level through structural typing protocols. The FlextLdapProtocols class defines the expected shape of settings objects, ensuring that any configuration provider (like Pydantic or a custom dictionary) adheres to the required interface.
LdapSettingsProtocol: Mandates the presence ofhost,port,use_ssl,use_tls,bind_dn, etc.ConnectionConfigProtocol: Ensures that connection objects have the necessary attributes forldap3adapters.SearchOptionsProtocol: Standardizes the interface for search-related configuration.
Sources: src/flext_ldap/protocols.py:46-75, src/flext_ldap/protocols.py:108-117
Environment and Global Constants
The library defines a set of global constants that act as default values for the configuration system. These are organized under the c.Ldap namespace.
# Representative structure of configuration constants
RFC_DEFAULT_BASE_DN = "dc=flext,dc=local"
RFC_DEFAULT_FILTER = "(objectClass=*)"
CONFIG_LDAPS_PORT = 636
DOCKER_PORT = 3390
These constants are used to validate incoming configuration and to provide fallback values when specific settings are omitted.
Sources: tests/constants.py:80-90, tests/constants.py:130-140
Conclusion
The configuration and settings architecture of flext-ldap is designed for enterprise resilience, utilizing strict Pydantic validation and structural protocols. By separating connection details, search parameters, and synchronization strategies into distinct but related models, the system allows for granular control over LDAP interactions while maintaining type safety and preventing invalid configurations (such as simultaneous SSL/TLS requests) through internal logic.