API Runtime
Relevant source files
The following files were used as context for generating this wiki page:
The API Runtime is a critical mixin component within the FLEXT gRPC platform that provides the underlying runtime behavior for the public gRPC API facade. It acts as an orchestration layer that bridges high-level API calls to the internal utility-driven entity factories and the gRPC runtime adapter. By utilizing Method Resolution Order (MRO), it allows the public facade to compose complex behaviors such as entity creation, address parsing, and operation execution.
This module is situated within the Application Layer of the project's Clean Architecture, specifically focused on business process orchestration and use case implementation. It ensures that all gRPC-related operations—such as starting servers or connecting clients—are performed with consistent validation, timeout management, and result-oriented error handling.
Sources: src/flext_grpc/services/api_runtime.py:1-20, src/flext_grpc/README.md:120-130, src/README.md:35-45
Core Architecture and Components
The API Runtime is implemented primarily through the FlextGrpcApiRuntime class. It inherits from FlextGrpcServiceBase and serves as a runtime mixin. The architecture relies on functional composition, where high-level operations are broken down into calls to the u.Grpc (internal gRPC utilities) namespace.
Runtime Hierarchy and Composition
The following diagram illustrates how the FlextGrpcApiRuntime fits into the broader service hierarchy and its relationship with the utility layer.
The runtime utilizes a "Result Pattern" for error handling, ensuring that all operations return a p.Result object instead of raising standard exceptions for business logic failures.
Sources: src/flext_grpc/services/api_runtime.py:23-30, src/flext_grpc/_utilities/grpc.py:165-200, src/README.md:95-105
Entity Management and Creation
The primary responsibility of the API Runtime is the creation of typed gRPC entities. These entities are backed by domain models and are validated at the point of creation.
Entity Creation Methods
| Method | Parameters | Return Type | Description |
|---|---|---|---|
create_channel | target: str, options: JsonMapping | Result[m.Grpc.Channel] | Creates a typed channel entity from a validated target string. |
create_client | target: str, options: JsonMapping | Result[m.Grpc.Client] | Creates a typed client entity, automatically initializing the required channel. |
create_server | host: str, port: int, max_workers: int | Result[m.Grpc.Server] | Creates a typed server entity with configurable worker pools. |
create_service | name: str, methods: StrSequence | Result[m.Grpc.Service] | Defines a service with specific RPC methods. |
Sources: src/flext_grpc/services/api_runtime.py:32-60, tests/unit/test_api.py:30-65
Complete Setup Workflow
The create_complete_setup method demonstrates functional composition by orchestrating the creation of a server, client, and service in a single call. This is used for rapid development and testing.
Operation Execution and Validation
The runtime provides a unified interface for executing operations through the execute_operation method. This method acts as a dispatcher for various gRPC actions.
Operation Dispatching Logic
Operations are handled via pattern matching against the operation_name within an OperationExecutionRequest. Currently, this includes support for:
- connect_client: Validates the target and invokes
create_client. - Validation: Uses
validate_targetandparse_addressto ensure network strings conform to thehost:portpattern.
Sources: src/flext_grpc/services/api_runtime.py:117-140, tests/unit/test_api.py:68-80
Network Validation Rules
The runtime enforces strict validation for gRPC targets:
- Format: Must be a string in
host:portformat. - Host: Must match the
NETWORK_HOST_REregular expression (defined in constants). - Port: Must be an integer between 1 and 65535 (inclusive).
Sources: src/flext_grpc/_utilities/grpc.py:302-325, tests/unit/test_api.py:72-85
Integration with gRPC Runtime Adapter
The API Runtime indirectly interacts with the low-level grpc library through a typed adapter layer. This isolation ensures that the business logic remains independent of the specific gRPC library implementation details.
Summary
The API Runtime is the engine behind the FlextGrpc facade, providing the necessary logic to transform high-level requests into validated domain entities. By strictly adhering to Clean Architecture principles and using the Result Pattern, it provides a robust, type-safe foundation for gRPC communication within the FLEXT ecosystem. It manages the lifecycle of servers, clients, and services while abstracting away the complexities of the underlying gRPC runtime.
Sources: src/README.md:15-30, src/flext_grpc/README.md:40-60