Error Handling Patterns

Relevant source files

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

• src/flext_grpc/errors.py
• examples/03_error_handling_patterns.py
• tests/unit/test_errors.py
• src/README.md
• src/flext_grpc/README.md
• examples/README.md

Error handling in the flext-grpc platform is built on the principles of Clean Architecture and Domain-Driven Design, utilizing the Result (r) Pattern for railway-oriented programming. The system avoids using exceptions for flow control in business logic, instead returning explicit success or failure containers. This approach ensures that errors are treated as first-class domain concepts, providing detailed context such as affected fields or configuration keys.

The architecture separates concerns into a domain-specific exception hierarchy used at the infrastructure layer and a functional result-based propagation system used throughout the application and domain layers. This ensures that failures are handled predictably and can be composed using operations like mapping or chaining.

Sources: src/README.md:95-103, src/flext_grpc/README.md:120-128, examples/03_error_handling_patterns.py:1-12

Error Hierarchy and Context

The platform defines a structured hierarchy of exceptions that inherit from a common base, ensuring consistent metadata across different failure modes. Key specialized errors include validation, connection, timeout, and configuration issues.

The diagram shows the inheritance structure of the gRPC-specific error system, rooted in the core flext error foundation.
Sources: src/flext_grpc/errors.py, tests/unit/test_errors.py:108-119

Core Exception Classes

Exception Class	Purpose	Context Attributes
FlextGrpcError	Base exception for all gRPC-related failures.	N/A
GrpcValidationError	Raised when domain rules or input validations fail.	field: The name of the specific field that failed validation.
FlextGrpcConnectionError	Indicates network-level or channel communication failures.	N/A
FlextGrpcTimeoutError	Raised when an operation exceeds its defined deadline.	N/A
FlextGrpcConfigurationError	Indicates invalid settings or configuration parameters.	config_key: The specific setting key causing the error.

Sources: src/flext_grpc/README.md:120-136, tests/unit/test_errors.py:56-105

The Result (r) Pattern

The platform utilizes a functional approach to error handling where functions return an r (Result) object. This object encapsulates either a successful value or an error message, preventing the need for deep try-catch blocks and allowing for "Railway-Oriented Programming" where successful paths are chained together.

This diagram illustrates the flow of an operation returning a Result object instead of raising an exception.
Sources: src/README.md:95-99, examples/03_error_handling_patterns.py:112-127

Example: Validation Pipeline

In the following pattern, internal exceptions are caught immediately and converted into r.fail results to be propagated safely.

def validate_user_input(username: str, email: str) -> p.Result[t.Grpc.Headers]:
    try:
        if not username:
            raise GrpcValidationError("Username empty", field="username")
        return r[t.Grpc.Headers].ok({"username": username, "email": email})
    except GrpcValidationError as e:
        logger.exception("Validation failed", field=e.field)
        return r[t.Grpc.Headers].fail(f"Validation error: {e}")

Sources: examples/03_error_handling_patterns.py:34-52

Recovery and Resilience Patterns

The project implements several strategies for handling transient and permanent failures, including retries and fallback configurations.

Retry Logic

Operations involving connections frequently implement retry loops. The system attempts the operation multiple times before finally returning a failure result.

Fallback Configuration

When a primary operation (such as loading a production configuration) fails, the system can attempt to recover by applying a safe "fallback" or default state.

The sequence diagram shows the interaction between components during connection retries and configuration fallbacks.
Sources: examples/03_error_handling_patterns.py:130-153

Summary

The flext-grpc error handling system provides a robust framework for managing failures in high-performance gRPC services. By combining a detailed exception hierarchy with the functional Result pattern, the platform ensures that errors are explicit, context-rich, and easy to handle without disrupting execution flow. This architecture supports enterprise-grade requirements like structured logging, automatic retries, and graceful degradation via fallbacks.

Sources: src/flext_grpc/README.md:120-136, examples/03_error_handling_patterns.py:192-202 assistant