Connection Management
Relevant source files
The following files were used as context for generating this wiki page:
Connection Management in the flext-ldap library provides an enterprise-grade abstraction over the underlying LDAP protocol, specifically leveraging the ldap3 adapter. It handles the full lifecycle of a directory connection, including server creation, TLS negotiation, authentication (binding), and graceful termination. The system is designed with a focus on resilience, supporting automatic retries for transient errors and heuristic server type detection upon successful connection.
The architecture follows a Clean Architecture approach, separating the service logic (high-level lifecycle and retries) from the adapter logic (low-level ldap3 object manipulation). This is achieved through a multi-layered structure involving mixins, adapters, and dedicated manager classes.
Architecture and Components
The system is structured into three primary layers: the Service Mixin, the Adapter Host, and the low-level Connection Manager.
Component Overview
| Component | Responsibility | Source File |
|---|---|---|
FlextLdapConnection | Manages the high-level lifecycle, retries, and server detection. | src/flext_ldap/services/connection.py |
ConnectionManager | Handles the low-level creation of ldap3.Server and ldap3.Connection objects. | src/flext_ldap/adapters/_ldap3/connection_manager.py |
ConnectionConfig | Pydantic model defining connection parameters and validation rules. | src/flext_ldap/_models/ldap.py |
LdapClient | Protocol defining the public interface for LDAP clients. | src/flext_ldap/protocols.py |
Connection Lifecycle Flow
The following diagram illustrates the sequence of operations during a connection attempt, including the interaction between the service mixin and the underlying manager.
Configuration and Validation
Connections are configured using the ConnectionConfig model, which enforces business rules and mutual exclusivity for security protocols.
Connection Configuration Model
The ConnectionConfig model utilizes Pydantic for strict validation. For example, it prevents invalid security configurations by ensuring use_ssl and use_tls are not both enabled simultaneously.
| Field | Type | Default | Description |
|---|---|---|---|
host | str | localhost | Server hostname or IP. |
port | int | 389 | Connection port. |
use_ssl | bool | False | Use LDAPS (SSL/TLS from start). |
use_tls | bool | False | Use STARTTLS (upgrade connection). |
bind_dn | str | None | None | Distinguished Name for auth. |
bind_password | str | None | None | Password for auth. |
timeout | int | 10 | Connection/receive timeout. |
auto_bind | bool | True | Automatically bind on connect. |
Sources: src/flext_ldap/_models/ldap.py:18-49, src/flext_ldap/protocols.py:73-83
Technical Implementation Details
Server Detection
After a successful bind, the FlextLdapConnection mixin automatically triggers server type detection. This process identifies the directory vendor (e.g., OpenLDAP, OID, AD) to allow the library to adapt its behavior for specific server quirks.
Sources: src/flext_ldap/services/connection.py:91-105
TLS Negotiation
TLS handling is managed within the ConnectionManager. If use_tls is enabled, the manager performs a protocol-level STARTTLS negotiation. This is explicitly skipped for use_ssl=True (LDAPS) connections, as they are secure from the first byte.
Sources: src/flext_ldap/adapters/_ldap3/connection_manager.py:82-115
Resilience and Retries
The connect method supports a u.retry pattern. When auto_retry is enabled, transient connection failures are caught and the operation is retried based on max_retries and retry_delay.
Sources: src/flext_ldap/services/connection.py:53-62
Context Management
The library supports a context manager pattern to ensure resources are cleaned up even if errors occur during operation.
from flext_ldap import ldap
with ldap(settings=my_settings) as api:
result = api.connect()
# Perform operations...
# api.unbind() is called automatically via __exit__
Sources: examples/README.md:652-671, src/flext_ldap/protocols.py:168-175
Summary
Connection Management in flext-ldap provides a robust, type-safe framework for interacting with LDAP servers. By abstracting the complexities of ldap3 object creation, TLS negotiation, and retry logic into structured services and adapters, the library ensures that directory connections are secure, resilient, and vendor-aware.