API Runtime Services

Introduction

The API Runtime Services constitute the primary facade and entry point for the flext-ldap library. This system is designed as an enterprise-grade LDAP operations interface that leverages Python's Method Resolution Order (MRO) to consolidate diverse LDAP functionalities—including connection management, CRUD operations, server detection, and data synchronization—into a single, cohesive ldap API object.

The core philosophy of this module is to provide a unified, type-safe, and "zero-ceremony" interface for developers. It strictly follows the r pattern for explicit error handling, ensuring that operations return consistent Result objects rather than raising unhandled exceptions for expected business failures. This architecture allows the library to serve as a server-agnostic layer capable of interacting with OpenLDAP, Oracle Unified Directory (OUD), and other RFC-compliant LDAP servers.

Sources: examples/README.md:27-40, tests/unit/test_api.py:18-20

Architecture and Service Composition

The API Runtime is built using a mixin-based architecture. Instead of a single monolithic class, functionality is distributed across specialized service mixins which are then composed into the final FlextLdapApiRuntime facade.

Service Inheritance Model

The API Runtime inherits from several key service layers defined in the services package. This structure allows for a clean separation of concerns while exposing all methods through the ldap instance.

Key Components

Connection Lifecycle Management

The runtime services provide advanced connection management, supporting both direct calls and the Python context manager pattern. This ensures that LDAP sockets are properly closed even in the event of errors.

Execution Flow

The typical lifecycle of an API interaction involves initialization, connection (with optional auto-retry logic), execution of business logic, and graceful disconnection.

Connection Safety Features

1. MRO Method Inheritance: The facade inherits is_connected state tracking from the connection service, defaulting to False until a successful bind occurs.
2. Automatic Cleanup: When used as a context manager, the runtime calls unbind() during the __exit__ phase.
3. Failure Propagation: Operations attempted without an active connection return a failure result explicitly identifying the "Not Connected" state.

Sources: tests/unit/test_api.py:31-32, tests/unit/test_api.py:65-71

Operation Interfaces

The API Runtime exposes several high-level operation categories by proxying calls to its inherited mixins.

Search and CRUD Operations

The runtime utilizes SearchOptions and SearchRequest models to parameterize searches. It supports base, one-level, and subtree scopes.

• search(search_options): Executes a query based on the provided criteria.
• add(entry) / modify(dn, changes) / delete(dn): Standard LDAP CRUD actions.

Sources: src/flext_ldap/protocols.py:126-210, examples/README.md:65-90

Synchronization (Sync) Services

The runtime includes specialized logic for processing LDIF data and synchronizing it with the LDAP directory. This is handled via FlextLdapSync.

• Progress Callbacks: Supports both single_phase_callback and multi_phase_callback signatures for tracking long-running batch operations.
• Result Wrapping: The runtime automatically wraps multi-phase callbacks to maintain signature compatibility.

Error Handling Pattern (r)

A distinguishing feature of the API Runtime is its strict adherence to the Result (r) pattern. Instead of using try/except blocks for standard LDAP errors (like "Entry Already Exists" or "Invalid DN"), the runtime returns a Result object that contains either the value or an error message.

Pattern 1: Check before unwrap

result = api.search(search_options)
if result.is_failure:
    # Handle error
    return
entries = result.unwrap()

Sources: examples/README.md:340-355

Summary

The API Runtime Services provide the structural framework that makes flext-ldap an enterprise-ready library. By combining multiple specialized mixins into a single ldap facade, the runtime offers a comprehensive suite of tools for connection management, synchronized batch operations, and standard directory queries. Its reliance on structural protocols and Result-based error handling ensures that the library remains robust, type-safe, and highly maintainable across different LDAP server implementations.