Protocols and Dependency Injection

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_auth/_protocols/auth_provider.py
• src/flext_auth/_protocols/auth_service.py
• src/flext_auth/protocols.py
• src/flext_auth/_protocols/__init__.py
• AGENTS.md
• pyproject.toml
• README.md

Protocols and Dependency Injection (DI) form the structural foundation of the flext-auth library, ensuring a decoupled and highly testable architecture. By adhering to the Dependency Inversion Principle (DIP), the system depends on abstractions rather than concrete implementations, allowing for flexible swapping of authentication providers, transport layers, and storage mechanisms.

The project utilizes Python's structural typing (Protocols) to define clear interfaces for core components like identity management, session handling, and token validation. This approach is integrated with the broader FLEXT ecosystem standards, which mandate the use of protocols to maintain strict library abstraction boundaries.

Sources: AGENTS.md:73-77, src/flext_auth/_protocols/init.py:11-30, README.md:33-36

Architectural Principles

The implementation follows the Universal Engineering Principles defined in the project's governance. Specifically, it focuses on the SOLID principles and DI/DIP, which require that collaborators are injected rather than hard-wired inside business logic.

Dependency Inversion and Injection

• Depend on Abstractions: Business logic interacts with FlextAuthProtocols rather than concrete classes.
• Injected Collaborators: Services receive their dependencies (e.g., a repository or a provider) during initialization.
• Structural Typing: Components are validated against protocols, ensuring they provide the necessary methods without requiring explicit inheritance.

Sources: AGENTS.md:71-77, src/flext_auth/_protocols/auth_service.py

Protocol Composition

The system organizes protocols into a hierarchical package structure, facilitating lazy loading and clear namespace management. Core authentication protocols are divided into specialized domains:

Protocol Namespace	Purpose
AuthService	High-level orchestration of authentication workflows.
AuthProvider	Specific implementations for authentication methods (JWT, Basic, etc.).
AuthIdentity	Management of user identities and attributes.
AuthSession	Lifecycle management for active authentication sessions.
AuthToken	Generation and validation of security tokens.

Sources: src/flext_auth/_protocols/init.py:11-30, src/flext_auth/_protocols/auth_service.py

Component Flow and Relationships

The interaction between the high-level service and the underlying providers is mediated through these protocols. A typical authentication flow involves the AuthService coordinating with an AuthProvider and an AuthSession manager.

Core Protocol Definitions

Auth Service Protocol

The FlextAuthProtocolsAuthService defines the public surface for the authentication system. It includes methods for user registration, credential verification, and session termination. By using a protocol, the implementation can be swapped between in-memory stores for testing and persistent databases for production.

Sources: src/flext_auth/_protocols/auth_service.py, src/flext_auth/protocols.py

Auth Provider Protocol

The FlextAuthProtocolsAuthProvider focuses on the actual verification logic. Different providers (e.g., LDAP, OAuth2, or Local Database) implement this protocol to provide a consistent interface to the AuthService.

Implementation Standards

The project uses flext-core for advanced type management and hatchling for the build system. Development dependencies include tools like pytest-mock and mypy to enforce protocol compliance during CI/CD.

• Lazy Exports: The protocols package uses install_lazy_exports to minimize startup time and manage circular dependencies.
• Type Safety: Use of TYPE_CHECKING blocks ensures that protocol definitions are available for static analysis without causing runtime overhead.

Sources: pyproject.toml:13-22, src/flext_auth/_protocols/init.py:7-50

Conclusion

The use of Protocols and Dependency Injection in flext-auth enables a modular architecture where core logic is decoupled from infrastructure. This design allows the library to support multiple authentication strategies and storage backends while maintaining a consistent and type-safe API for consumers. Following the Universal Agent Law ensures that these boundaries are never bypassed by hard-coded globals or fakes, maintaining the integrity of the system's structural contracts.

Sources: AGENTS.md:71-77, README.md:33-36