Cross-Server Conversion
Relevant source files
The following files were used as context for generating this wiki page:
Cross-Server Conversion is a core service within the FLEXT-LDIF library designed to facilitate the migration and transformation of LDAP Data Interchange Format (LDIF) data between different LDAP server implementations. The system handles variations in schema, attribute naming conventions, boolean representations, and Access Control List (ACL) formats across servers such as Oracle Internet Directory (OID), Oracle Unified Directory (OUD), OpenLDAP, and standard RFC-compliant directories.
The conversion process is built upon a "Railway Oriented" architecture, ensuring that data integrity is maintained through multi-step validation and transformation pipelines. It utilizes server-specific "ServerServers" and "SchemaServers" to apply normalization rules, such as converting OID-specific boolean values (1/0) to RFC-compliant values (TRUE/FALSE) and renaming proprietary ACL attributes like orclaci to standard aci.
Sources: src/flext_ldif/services/conversion_metadata.py, examples/04_server_migration.py:102-125, tests/unit/test_migration_pipeline_servers.py:31-70
Architecture and Data Flow
The conversion architecture relies on a specialized mixin-based service structure that separates metadata analysis, support checking, and entry-level transformations. The FlextLdifConversionMetadataMixin and FlextLdifConversionSupportMixin provide the logic required to analyze source data and determine target compatibility.
Conversion Pipeline Flow
The following diagram illustrates the typical flow of an LDIF entry through the conversion system, from auto-detection to final RFC normalization.
The pipeline ensures that server-specific proprietary data is preserved in ServerMetadata during the transition, allowing for potential round-trip preservation.
Sources: examples/04_server_migration.py:102-120, src/flext_ldif/services/conversion_metadata.py:82-122
Metadata Analysis and Preservation
A critical component of Cross-Server Conversion is the ServerMetadata model, which acts as a universal container for tracking conversion history, RFC violations, and server-specific extensions.
Key Metadata Components
| Component | Description | Source |
|---|---|---|
conversion_history | Audit trail of steps, timestamps, and differences. | domain_metadata.py:270 |
boolean_conversions | Tracking of boolean changes (e.g., OID 1 to RFC TRUE). | domain_metadata.py:256 |
original_attribute_case | Preservation of original attribute casing for reverse conversion. | domain_metadata.py:249 |
minimal_differences | Detailed tracking of spacing, case, and punctuation changes. | domain_metadata.py:260 |
Transformation Analysis
The FlextLdifConversionMetadataMixin performs specific checks during conversion:
- Boolean Analysis: Detects attributes requiring format shifts (e.g., OID -> RFC).
- DN Format Analysis: Normalizes DN spacing for the target server.
- Attribute Case Analysis: Ensures target compatibility while preserving source conventions.
Sources: src/flext_ldif/_models/domain_metadata.py:125-276, src/flext_ldif/services/conversion_metadata.py:16-55
Server-Specific Transformations
The library implements concrete transformation rules for various LDAP servers to ensure compliance with the target environment.
Boolean and ACL Mapping
Testing and implementation reveal specific mapping rules between OID and RFC servers:
# Boolean Mapping Reference
BOOLEAN_RFC_TO_OID = {"TRUE": "1", "FALSE": "0"}
BOOLEAN_OID_TO_RFC = {"1": "TRUE", "0": "FALSE"}
# ACL Renaming
# OID Source -> RFC Target: orclaci renaming to aci
# RFC Source -> OID Target: aci renaming to orclaci
Sources: tests/unit/test_migration_pipeline_servers.py:31-70, tests/unit/test_migration_pipeline_servers.py:84-125
Schema Normalization
The SchemaTransformer handles technical nuances in attribute definitions:
- Binary Suffix Removal: Strips
;binaryfrom attribute names (e.g.,userCertificate;binary->userCertificate). - Character Replacement: Normalizes naming by replacing underscores with hyphens.
- Matching Rule Fixes: Corrects errors where substring rules (e.g.,
caseIgnoreSubstringsMatch) are incorrectly placed inEQUALITYfields.
Sources: tests/unit/servers/test_schema_transformer.py:14-60
Support and Validation
Before conversion, the FlextLdifConversionSupportMixin verifies if the target server supports the required data categories.
The support check validates four primary categories: attribute, objectclass, acl, and entry. It uses test definitions (e.g., a dummy ACL string) to probe the target server's parsing capabilities.
Sources: src/flext_ldif/services/conversion_support.py:48-75, src/flext_ldif/services/conversion_support.py:84-120
Conclusion
Cross-Server Conversion provides a robust framework for LDAP data mobility by abstracting server-specific complexities into a standardized metadata-driven pipeline. By combining deep metadata preservation with automated normalization for booleans, ACLs, and schema definitions, the system enables seamless transitions between heterogeneous LDAP environments while maintaining a complete audit trail of all transformations.
Sources: src/flext_ldif/_models/domain_metadata.py:270-276, examples/04_server_migration.py:175-200