Home
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT gRPC is a high-performance communication platform designed for enterprise-grade gRPC services. It leverages Clean Architecture and Domain-Driven Design (DDD) principles to provide a structured, type-safe, and robust framework for building distributed systems. The platform facilitates the creation and management of gRPC servers, clients, and streaming operations while ensuring strict domain validation and consistent error handling through the Result pattern.
Sources: README.md:10-12, src/README.md:14-16
Architectural Overview
The project follows a strict layered architecture to ensure separation of concerns and maintainability.
Clean Architecture Layers
| Layer | Responsibility | Key Files |
|---|---|---|
| Interface | Public API, exports, and factory functions. | api.py, __init__.py |
| Application | Business workflow orchestration and use cases. | services.py, platform.py |
| Domain | Core business logic, entities, and rules. | entities.py, models.py, types.py |
| Infrastructure | External system integration (gRPC, Pydantic). | platform.py, settings.py |
Sources: src/flext_grpc/README.md:139-146, src/README.md:37-64
Component Relationship Diagram
The following diagram illustrates the relationship between the core components of the FLEXT gRPC platform.
Core Domain Entities
Entities within FLEXT gRPC are rich domain objects that encapsulate both data and business behavior. They are designed to be immutable, using methods like copy_with() for state transitions.
Key Entities
- FlextGrpcServer: Manages the server lifecycle (Stopped -> Starting -> Running -> Stopping).
- FlextGrpcClient: Handles connection management and stub interaction.
- FlextGrpcChannel: Abstracted gRPC channel with state tracking (Idle, Connecting, Ready).
- FlextGrpcService: Defines gRPC service structures and registered RPC methods.
- FlextGrpcStream: Manages streaming communication patterns (Unary, Server-side, Client-side, Bidirectional).
Sources: src/README.md:46-52, src/flext_grpc/README.md:20-29, src/flext_grpc/models.py:382-555
Entity State Management
Entities like Server and Channel implement state machine logic to ensure valid transitions.
Sources: src/flext_grpc/models.py:417-495
Unified API Usage
The platform provides a unified facade, FlextGrpc, which serves as the primary entry point for developers. This facade simplifies complex operations into high-level factory functions.
Common Operations
| Function | Purpose | Example Parameters |
|---|---|---|
create_server | Initializes a new server entity. | host, port, max_workers |
create_client | Initializes a client for a target address. | target |
create_channel | Creates a channel entity with options. | target, options |
create_service | Defines a service with methods. | name, methods |
start_server | Transitions a server to the running state. | server (entity) |
Sources: src/flext_grpc/README.md:95-101, examples/01_basic_usage.py:25-54, tests/unit/test_api.py:33-100
Code Example: Server Lifecycle
from flext_grpc import FlextGrpc, FlextGrpcConstants
grpc = FlextGrpc()
# 1. Create Server
server_result = grpc.create_server(
host="localhost",
port=7070,
max_workers=10
)
# 2. Start Server
if server_result.success:
server = server_result.value
start_result = grpc.start_server(server)
if start_result.success:
running_server = start_result.value
# Server is now in 'running' state
Sources: examples/01_basic_usage.py:68-80, src/flext_grpc/models.py:480-495
Error Handling and Result Pattern
FLEXT gRPC follows the Result Pattern (Railway-oriented programming). Operations do not throw exceptions for business logic failures; instead, they return an r<T> object indicating success or failure.
Error Hierarchy
The platform defines a comprehensive exception hierarchy for technical failures:
- FlextGrpcError: Base exception for all platform errors.
- GrpcValidationError: Specifically for field validation failures with context.
- FlextGrpcConnectionError: For network communication issues.
- FlextGrpcTimeoutError: For deadline violations.
- FlextGrpcConfigurationError: For invalid settings.
Sources: src/README.md:85-88, src/flext_grpc/README.md:80-92, src/flext_grpc/errors.py:46-120
Conclusion
FLEXT gRPC provides a robust, enterprise-ready framework for gRPC development by enforcing Clean Architecture and rich domain modeling. By centralizing operations through the FlextGrpc facade and utilizing the Result pattern for error handling, it ensures that services are predictable, testable, and maintainable. The system currently supports entity validation, state management, and configuration, with network communication and Protocol Buffer integration serving as the foundation for its high-performance capabilities.