Data Models
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT gRPC platform utilizes a consolidated namespace for data models, primarily housed within the FlextGrpcModels class. These models follow Clean Architecture and Domain-Driven Design (DDD) principles, providing unified, type-safe structures for gRPC entities, configurations, and message payloads. The system leverages Pydantic v2 for validation and serialization, ensuring that all domain objects maintain internal consistency and follow enterprise-grade standards.
Sources: src/flext_grpc/models.py:1-25, src/flext_grpc/README.md:100-115
Core Domain Entities
The platform defines several core entities that represent the primary components of a gRPC system. These entities inherit from a base Entity class and, where applicable, a StateMachine class to manage lifecycle transitions.
Entity Relationships
The following diagram illustrates the structural relationships between the primary gRPC entities:
This diagram shows the inheritance from the base Entity and StateMachine classes, and the composition of Channel within a Client.
Sources: src/flext_grpc/models.py:320-550
Entity Components
| Entity | Description | Key Attributes |
|---|---|---|
| Server | Manages the gRPC server lifecycle. | host, port, state, max_workers, services |
| Client | High-level client interface for RPC calls. | channel, options, grpc_stub |
| Channel | Represents the connection layer to a target. | target, state, options, grpc_channel |
| Service | Defines a group of RPC methods. | name, methods |
| GrpcStream | Represents a streaming communication pattern. | id, method_name, stream_type |
Sources: src/flext_grpc/models.py:385-585, src/flext_grpc/README.md:30-45
State Management
Entities like Server and Channel utilize a StateMachine mixin to manage valid transitions between operational states. Transitions are validated against a map of allowed source and target states.
Server State Transitions
The server lifecycle follows a strict transition path as depicted below:
Channel State Transitions
Channels transition between idle, connecting, and ready states during the connection lifecycle:
Configuration Models
The FlextGrpcModels namespace includes specialized value models for configuring different aspects of the gRPC infrastructure, including networking, performance, security, and monitoring.
Key Configuration Structures
- NetworkConfig: Handles bind addresses, port numbers, and keepalive settings.
- Default Host:
0.0.0.0 - Default Port:
50051
- Default Host:
- PerformanceConfig: Manages threading and message limits.
- Max Workers: Range 1-1000 (Default: 10)
- Message Length: Range 64KB to 16MB (Default: 4MB)
- SecurityConfig: Controls TLS encryption and authentication settings.
- Includes fields for
tls_cert_file,tls_key_file, andauth_token.
- Includes fields for
- StreamingConfig: Configures streaming behavior, including buffer sizes and durations.
Sources: src/flext_grpc/models.py:125-265, src/flext_grpc/constants.py, src/flext_grpc/README.md:65-80
Protocol and Operation Models
For internal messaging and operation execution, the platform provides immutable value models representing requests, responses, and operation specifications.
Operation Execution Flow
The following sequence shows how an OperationExecutionRequest relates to the execution of a method on an entity:
Messaging Models
| Model | Purpose | Fields |
|---|---|---|
| EchoRequest | Basic test request. | message |
| HealthRequest | Service health probe. | service |
| StreamInfo | Metadata for active streams. | stream_id, stream_type, latency_ms |
| Payload | Structured key-value data container. | values (MappingProxyType) |
Sources: src/flext_grpc/models.py:50-95, 317-340
Validation and Business Rules
Every entity implements validate_business_rules() to enforce domain-specific constraints. For example:
- Server Validation: Ensures the host is not empty, the port is within the valid IANA range (1-65535), and
max_workersis at least 1. - Service Validation: Requires a non-empty service name and at least one registered method.
- Channel Validation: Verifies that the target address is specified.
Sources: src/flext_grpc/models.py:433-440, 490-505, 515-535, examples/01_basic_usage.py:100-125
Conclusion
The data models in flext-grpc provide the structural backbone for the entire communication platform. By centralizing core entities, state machine logic, and comprehensive configurations into the FlextGrpcModels namespace, the project ensures consistency across the server and client implementations. These models not only facilitate data exchange but also enforce the architectural integrity of the system through rigorous validation and clear state transition rules.