gRPC Client
Relevant source files
The following files were used as context for generating this wiki page:
The gRPC Client in the FLEXT ecosystem is a high-performance communication component designed following Clean Architecture and Domain-Driven Design (DDD) principles. It manages the lifecycle of gRPC connections, including channel creation, state management, and RPC execution. The client is exposed through a unified facade, providing a simplified API for enterprise-grade microservice communication.
The implementation relies on immutable domain entities, such as FlextGrpcModels.Grpc.Client and FlextGrpcModels.Grpc.Channel, and utilizes the Result pattern (r) for consistent, railway-oriented error handling. This ensures that network operations, timeouts, and validation failures are handled explicitly without unmanaged exceptions.
Sources: src/flext_grpc/README.md:1-25, src/flext_grpc/api.py:15-30
Architecture and Components
The gRPC client architecture is layered to separate concerns between domain logic, application orchestration, and infrastructure integration.
Core Client Entities
The client system is built around several key Pydantic-based models that define its state and behavior:
- Client Entity: The primary domain object representing a gRPC client, which delegates connection logic to an associated channel.
- Channel Entity: Manages the underlying connection target and state machine (e.g., IDLE, CONNECTING, READY).
- Complete Setup: A composite model used for rapid development that bundles a server, client, and service definition.
Sources: src/flext_grpc/models.py:530-580, src/flext_grpc/README.md:32-40
Component Relationship Diagram
The following diagram illustrates the relationship between the unified facade, the client entity, and the underlying gRPC channel.
Client Operations and Lifecycle
Client operations are orchestrated through the FlextGrpc facade, which composes functionality from various service mixins. The lifecycle follows a standard path: creation, connection (channel readiness), execution (calls), and disconnection.
Connection Flow
The connection process involves creating a typed channel entity and waiting for the gRPC runtime to report a "READY" state.
Key API Methods
| Method | Description | Return Type |
|---|---|---|
create_client(target, options) | Creates a new client entity with a corresponding channel. | p.Result[m.Grpc.Client] |
connect_client(target, timeout) | Establishes a connection and waits for the channel to be ready. | p.Result[m.Grpc.Client] |
make_call(client, method, request) | Executes a synchronous gRPC call using the client stub. | p.Result[p.Grpc.GrpcMessage] |
disconnect_client(client) | Closes the underlying channel and transitions state to IDLE. | p.Result[bool] |
Sources: src/flext_grpc/protocols.py:98-135, src/flext_grpc/_utilities/grpc.py:200-225
Configuration and Validation
The client uses FlextGrpcSettings for infrastructure-level configuration and domain-level validation within the entities themselves.
Configuration Parameters
The ClientConfig and NetworkConfig models define the operational parameters for client connections.
| Field | Type | Default | Description |
|---|---|---|---|
target | str | localhost:50051 | The host:port address of the gRPC server. |
timeout | float | 30.0 | Global request timeout in seconds. |
max_connections | int | 100 | Maximum concurrent connections allowed. |
keepalive_time | int | 7200 | Interval between keepalive pings in seconds. |
Sources: src/flext_grpc/models.py:115-165, src/flext_grpc/README.md:75-85
Validation Rules
The client entity implements validate_business_rules() to ensure integrity before network operations:
- Target Format: Must follow the
host:portpattern. - Port Range: Must be within the valid IANA range (1-65535).
- Channel Integrity: If a channel exists, its internal target must not be empty.
Sources: src/flext_grpc/_utilities/grpc.py:270-300, src/flext_grpc/models.py:575-585
Integration and Usage
The gRPC client is designed to work seamlessly with the FLEXT ecosystem, including automated metrics collection and dependency injection.
Basic Usage Example
from flext_grpc import FlextGrpc, FlextGrpcConstants
grpc = FlextGrpc()
# 1. Create client
client_result = grpc.create_client(target="localhost:7070")
# 2. Connect client
if client_result.success:
connect_result = grpc.connect_client("localhost:7070")
# 3. Make RPC call
if connect_result.success:
connected_client = connect_result.value
call_result = grpc.make_call(
connected_client,
"GetInfo",
{"id": "123"}
)
Sources: examples/01_basic_usage.py:65-90
Conclusion
The gRPC Client module provides a robust, type-safe implementation for microservice communication. By combining Pydantic models with the gRPC runtime adapter, it offers developers a predictable interface that enforces domain rules and provides detailed error context through the FLEXT Result pattern. Its integration into the unified FlextGrpc facade allows for minimal boilerplate code while maintaining strict adherence to SOLID principles.
Sources: src/flext_grpc/api.py:15-35, src/flext_grpc/README.md:140-160