Entry Adapter
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Entry Adapter is a critical component of the flext-ldap library designed to provide seamless, bidirectional conversion between ldap3 Entry objects and flext-ldif Entry models. It serves as an implementation of the Adapter pattern, ensuring that LDAP protocol operations can interact fluidly with the library's internal LDIF-based data representations while maintaining data integrity across different LDAP server types.
The adapter handles complex data transformation tasks, such as Distinguished Name (DN) normalization, binary value detection via Base64 encoding (per RFC 2849), and the preservation of attribute fidelity for auditing and schema compliance. By leveraging a stateless design, the Entry Adapter allows for consistent data transformation without side effects, supporting cross-server migrations and enterprise-grade LDAP operations.
Sources: src/flext_ldap/adapters/entry.py:1-35, src/flext_ldap/adapters/ldap3.py:27-35
Core Architecture and Components
The Entry Adapter architecture is built on the FlextLdapEntryAdapter class, which extends the base service protocol s[bool]. It utilizes internal helper classes and mixins to separate the concerns of attribute extraction, value normalization, and metadata tracking.
Component Breakdown
| Component | Responsibility |
|---|---|
FlextLdapEntryAdapter | Primary service class for bidirectional conversion between ldap3 and LDIF formats. |
_ConversionHelpers | Internal static methods for value normalization, Base64 detection, and string conversion. |
ResultConverterExtractMixin | Provides utility methods for extracting DNs, attributes, and server metadata from raw payloads. |
ConversionMetadata | A Pydantic model used to track transformations, including removed or Base64-encoded attributes. |
Sources: src/flext_ldap/adapters/entry.py:44-78, src/flext_ldap/adapters/_ldap3/result_extract.py:15-18, src/flext_ldap/_models/ldap.py:168-183
Bidirectional Conversion Flow
The following diagram illustrates the data flow when converting between LDAP protocol objects and internal library models.
The diagram shows how FlextLdapEntryAdapter acts as the bridge between raw protocol objects and structured LDIF models.
Sources: src/flext_ldap/adapters/entry.py:118-245, src/flext_ldap/adapters/_ldap3/result_extract.py:20-75
Detailed Transformation Logic
ldap3 to LDIF Conversion
When converting from a ldap3.Entry to an m.Ldif.Entry, the adapter performs several distinct steps:
- DN Extraction: Retrieves the string representation of the Distinguished Name.
- Attribute Iteration: Processes each attribute in the
entry_attributes_as_dict. - Value Normalization: Converts various types (bytes, int, datetime) into a standard
t.StrSequence. - Base64 Detection: If a value contains non-ASCII characters (threshold > 127), the attribute is flagged for Base64 encoding.
- Metadata Generation: Tracks removed attributes (None values) and encoding changes to maintain an audit trail.
Sources: src/flext_ldap/adapters/entry.py:118-175, src/flext_ldap/adapters/_ldap3/result_extract.py:100-117
LDIF to ldap3 Attribute Conversion
For operations like add or modify, the adapter converts m.Ldif.Entry models back into the mapping format expected by the ldap3 library:
- Validation: Ensures the entry contains valid attributes.
- Format Transformation: Converts the internal attribute dictionary into
t.MappingKV[str, t.StrSequence]. - Error Handling: Catches basic type errors during conversion and logs them with context-aware entry DNs.
Sources: src/flext_ldap/adapters/entry.py:205-245, src/flext_ldap/adapters/ldap3.py:84-95
Data Structures and Models
Conversion Metadata
The adapter uses a specific model to track changes during the conversion process, which is essential for data integrity and auditing.
class ConversionMetadata(m.BaseModel):
source_attributes: t.StrSequence = u.Field(default_factory=list)
source_dn: str = ""
removed_attributes: t.StrSequence = u.Field(default_factory=list)
base64_encoded_attributes: t.StrSequence = u.Field(default_factory=list)
dn_changed: bool = False
converted_dn: str = ""
attribute_changes: t.StrSequence = u.Field(default_factory=list)
Sources: src/flext_ldap/_models/ldap.py:168-183
Result Extraction Interface
The ResultConverterExtractMixin provides a structural interface for handling various input types during extraction.
| Method | Input Types | Return Type |
|---|---|---|
extract_dn | m.Ldif.Entry, p.Ldap.Ldap3Entry, t.JsonValue | m.Ldif.DN |
extract_attributes | m.Ldif.Entry, p.Ldap.Ldap3Entry, t.JsonValue | m.Ldif.Attributes |
extract_metadata | m.Ldif.Entry, p.Ldap.Ldap3Entry, t.JsonValue | m.Ldif.ServerMetadata |
Sources: src/flext_ldap/adapters/_ldap3/result_extract.py:20-98
Protocol Implementation
The Entry Adapter adheres to the Ldap3Entry protocol, which defines the structural requirements for objects being adapted from the ldap3 library.
The diagram represents the relationship between the structural protocol and the concrete adapter implementation.
Sources: src/flext_ldap/protocols.py:408-430, src/flext_ldap/adapters/entry.py:44-55
Conclusion
The Entry Adapter serves as the primary translation layer in flext-ldap, enabling the library to maintain its "Clean Architecture" boundaries. By abstracting the specificities of the ldap3 library and providing a robust mechanism for converting to and from flext-ldif models, it ensures that the core domain logic remains decoupled from external LDAP protocol implementations. Its focus on auditability via conversion metadata and strict adherence to RFC standards for encoding makes it suitable for enterprise-grade directory synchronization and management tasks.
Sources: src/flext_ldap/adapters/entry.py:1-40, src/flext_ldap/adapters/ldap3.py:1-12