Quality Gates and Validations
Relevant source files
The following files were used as context for generating this wiki page:
Quality Gates and Validations in the flext-ldap project represent a multi-tiered enforcement system designed to ensure code reliability, configuration integrity, and runtime safety. These gates encompass static analysis, automated testing, and dynamic input validation patterns that prevent common LDAP-related failures, such as injection attacks or malformed Distinguished Names (DNs).
The system is governed by a "Strict-Total" zero-tolerance policy where all failures surfaced during a task must be resolved at the root cause rather than bypassed via suppression or workarounds. This infrastructure ensures that the project remains in a "Continuous Green" state, supporting enterprise-grade LDAP operations through rigorous validation of every component from configuration to data transmission.
Sources: AGENTS.md:16-19, AGENTS.md:144-148, examples/README.md:14-18
Static Analysis and Tooling Gates
The project employs a comprehensive suite of static analysis tools that serve as the first line of defense in the quality gate pipeline. These tools are configured with strict thresholds to prevent the introduction of technical debt.
Core Tooling Suite
The following tools are mandatory for all production, test, and example code:
- Ruff: Used for high-performance linting and formatting. It enforces a standard coding style across the entire repository.
- Pyright & Mypy: Static type checkers that ensure type safety. The project enforces "Strict, Most-Restrictive Typing," prohibiting the use of
Anyor bareobjectwithout documented justification. - Pyrefly: A specialized tool used for validating project-specific patterns and cross-file relationships.
- Bandit: Scans for security vulnerabilities and common security pitfalls in Python code.
- Codespell: Checks for common misspellings in code and documentation.
Sources: AGENTS.md:18-20, AGENTS.md:179-181, pyproject.toml:68-124
Quality Thresholds
Static gates are applied with equal rigor to src/, examples/, scripts/, and tests/. The project prohibits blanket per-file-ignores or patterns that hide violations in these directories. Every violation must be fixed at its root.
Sources: AGENTS.md:18-22
Testing Architecture and Gates
Testing in flext-ldap is not merely a verification step but a validation of configuration and settings "by construction."
Test Validation Principles (P0)
A fundamental rule (P0) states that tests must remain valid even when configurations change. Tests are prohibited from hardcoding or implicitly assuming current configuration values. Instead:
- Expected values must be read from the same Single Source of Truth (SSOT) that production uses (e.g.,
config/*.yamlorFlextSettings). - A test that breaks due to a legitimate configuration change is considered a test defect.
Sources: AGENTS.md:4-13
Test Categories and Coverage
The project uses pytest as its primary testing framework, organized into various markers for targeted validation:
| Marker | Description |
|---|---|
unit | Isolated testing of individual functions and classes. |
integration | Testing interactions between modules and external LDAP servers. |
docker | Tests requiring a live LDAP server (OpenLDAP/OUD) via Docker. |
smoke | High-level checks to verify core functionality. |
performance | Benchmarks and efficiency metrics for LDAP operations. |
Sources: pyproject.toml:500-515, examples/README.md:270-285
Validation Flow Diagram
The following diagram illustrates the flow from code change to successful gate passage:
The flow shows that any failure at static, type, or test levels requires a fix at the root cause before the code can be considered "Validated."
Sources: AGENTS.md:18-22, AGENTS.md:144-150
Input and Domain Validations
Beyond developer-facing gates, the library provides a robust FlextLdapValidations module to ensure runtime data integrity.
Validation Patterns
The system categorizes validations into several critical patterns to protect the LDAP infrastructure:
- DN Validation: Ensures Distinguished Names follow valid LDAP formats before attempting server operations.
- Filter Validation: Checks LDAP search filters for syntax errors and prevents LDAP injection.
- Schema Validation: Validates entries against server-specific capabilities and object class requirements.
- Sanitization: Cleans user inputs to prevent malicious manipulation of LDAP queries.
Sources: examples/README.md:141-155, tests/unit/test_models_search.py:22-30
Connection and Operation Verification
Before operations are executed, the system performs a sequence of internal checks:
The sequence demonstrates that validation occurs on the client side before any network request is dispatched to the LDAP server.
Sources: examples/README.md:460-475, tests/unit/test_utilities.py:465-485
Result and Error Handling (The r Pattern)
A core quality gate for application logic is the mandatory use of the r pattern (Result objects) for error handling.
Explicit Failure Handling
The project forbids the use of traditional try/except blocks for routine LDAP failures. Instead, all operations return a Result object that must be explicitly checked.
- is_success / is_failure: Methods used to branch logic based on the operation outcome.
- unwrap(): Only permitted after verifying success; otherwise, the application must handle the failure gracefully.
Sources: examples/README.md:445-458, tests/unit/test_sync.py:126-135
Batch Operation Statistics
For bulk operations, quality is monitored via the LdapBatchStats and BatchUpsertResult models, which track synchronization health:
| Field | Type | Description |
|---|---|---|
total_processed | int | Total number of entries attempted. |
successful | int | Number of entries correctly synchronized. |
failed | int | Number of entries that encountered errors. |
skipped | int | Number of entries bypassed (e.g., no changes). |
success_rate | float | Percentage of successful operations. |
Sources: tests/unit/test_models_sync.py:30-45, tests/unit/test_models_sync.py:75-85
Conclusion
Quality Gates and Validations in flext-ldap serve as a comprehensive governance framework that extends from the local development environment to production runtime. By enforcing strict static analysis, configuration-aware testing (P0), and explicit Result-based error handling, the project ensures that LDAP operations are resilient, secure, and maintainable. This structured approach guarantees that every change is validated against a rigorous Single Source of Truth, maintaining high standards for enterprise authentication and directory services.