gRPC Server
Relevant source files
The following files were used as context for generating this wiki page:
The gRPC Server in the flext-grpc platform is a high-performance, enterprise-grade component designed for lifecycle management, service registration, and RPC orchestration. It is built using Clean Architecture and Domain-Driven Design (DDD) principles, providing a robust state machine to handle transitions between stopped, starting, running, and stopping states. Sources: src/flext_grpc/README.md:16-30, src/flext_grpc/models.py:465-475
This module provides a unified facade, FlextGrpc, which composes server management capabilities through service mixins and MRO inheritance. The server implementation leverages Pydantic v2 models for strict type validation and the Result (r) pattern for railway-oriented error handling, ensuring that business logic failures are explicitly managed without unhandled exceptions. Sources: src/flext_grpc/api.py:19-33, src/flext_grpc/README.md:104-120
Architecture and Components
The server architecture is partitioned into distinct layers to maintain separation of concerns. The Domain Layer contains the Server entity and its state logic, while the Infrastructure Layer handles integration with the underlying gRPC runtime. Sources: src/flext_grpc/README.md:123-132
Core Server Entity
The FlextGrpcModels.Grpc.Server class acts as the primary domain entity. It inherits from Entity and StateMachine to provide immutable state transitions and business rule validation. Sources: src/flext_grpc/models.py:465-470
| Field | Type | Description |
|---|---|---|
host | str | Server bind host address (Default: localhost) |
port | t.PortNumber | Server listen port number (Default: 50051) |
state | c.Grpc.ServerState | Current lifecycle state (STOPPED, STARTING, RUNNING, STOPPING) |
max_workers | t.WorkerCount | Maximum worker threads for request handling |
services | Sequence[p.Grpc.GrpcServicer] | Registered gRPC service implementations |
| Sources: src/flext_grpc/models.py:467-485, src/flext_grpc/_utilities/grpc.py:330-336 |
Server Lifecycle State Machine
The server utilizes a functional state machine to manage lifecycle transitions. Transitions are validated against allowed paths (e.g., a server must be in a starting state before it can move to running). Sources: src/flext_grpc/models.py:488-515
The diagram above illustrates the valid state transitions for the FlextGrpc Server. Sources: src/flext_grpc/models.py:488-515, src/flext_grpc/README.md:21-25
Server Configuration and Validation
Server configuration is managed through structured models that define network, performance, and monitoring parameters. These models ensure that server resources are optimized and compliant with enterprise standards. Sources: src/flext_grpc/models.py:149-210
Performance Configuration
The PerformanceConfig model defines the limits of the server's execution environment:
- max_workers: Limits the thread pool size (1 to 1000).
- max_concurrent_rpcs: Controls the number of simultaneous active calls.
- message_lengths: Sets maximum bytes for send/receive (Default: 4MB).
Sources: src/flext_grpc/models.py:176-204
Domain Rules
Before a server can be started, it must pass validate_business_rules(). This validation checks:
- Host Presence: The host string cannot be empty.
- Port Range: The port must be within the valid IANA range (1-65535).
- Worker Count: At least one worker thread must be configured.
Sources: src/flext_grpc/models.py:518-530, src/flext_grpc/_utilities/grpc.py:307-320
Service Registration and Runtime
The server interacts with the grpc runtime through a typed adapter layer. This layer isolates the application from the untyped nature of the underlying library and provides typed futures for operations like port binding. Sources: src/flext_grpc/_utilities/grpc.py:22-55
Runtime Integration Flow
When a server is initiated, the platform resolves the gRPC runtime, creates the thread pool, and binds the specified port. Sources: src/flext_grpc/_utilities/grpc.py:133-154
The sequence above shows the high-level flow from entity creation to runtime server binding. Sources: src/flext_grpc/api.py:19-28, src/flext_grpc/_utilities/grpc.py:133-170, examples/01_basic_usage.py:70-85
Service Definition
Services are registered using the FlextGrpcModels.Grpc.Service model. A service is defined by its name and a sequence of RPC methods. The server entity maintains a collection of these services, which are added functionally via add_service(). Sources: src/flext_grpc/models.py:532-565, src/flext_grpc/protocols.py:165-185
Usage Example
The following example demonstrates creating and starting a server using the FlextGrpc facade.
from flext_grpc import FlextGrpc, FlextGrpcConstants
grpc = FlextGrpc()
# Create server entity
server_result = grpc.create_server(
host="localhost",
port=7070,
max_workers=10
)
if server_result.success:
server = server_result.value
# Start the server (Transitions state STOPPED -> STARTING -> RUNNING)
start_result = grpc.start_server(server)
if start_result.success:
started_server = start_result.value
print(f"Server status: {started_server.state}")
Sources: examples/01_basic_usage.py:70-85, src/flext_grpc/api.py:19-30
Conclusion
The gRPC Server module provides a type-safe, state-managed implementation for hosting gRPC services. By strictly following DDD patterns and isolating the gRPC runtime, it offers a resilient foundation for microservices within the FLEXT ecosystem, emphasizing explicit error handling through the Result pattern and robust validation of network and performance configurations. Sources: src/flext_grpc/README.md:123-145, src/flext_grpc/models.py:465-530