Protocols & Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
The Protocols & Interfaces system in flext-grpc provides a unified, type-safe contract for gRPC operations within the FLEXT ecosystem. By leveraging Python's typing.Protocol and runtime checkability, the project ensures that various components—including servers, clients, channels, and streams—adhere to a consistent interface while maintaining loose coupling from underlying gRPC library implementations.
This system serves as the architectural backbone for the Clean Architecture approach used in the project, separating the domain logic from infrastructure concerns. It allows the core business logic to interact with abstract definitions of gRPC resources, facilitating easier testing through mocks and ensuring that any changes to external dependencies (like grpcio) do not break the high-level application flow.
Sources: src/flext_grpc/protocols.py:11-38, src/flext_grpc/README.md:105-115
Core Architecture
The protocols are organized under a unified FlextGrpcProtocols class (aliased as p), which extends the base FLEXT foundation protocols. This structure provides a Grpc namespace containing specialized protocols for different aspects of gRPC communication.
The diagram above shows the hierarchical organization of protocols where the Grpc namespace acts as a container for specialized lifecycle and communication interfaces.
Sources: src/flext_grpc/protocols.py:22-50, tests/unit/test_protocols.py:21-45
Server and Service Interfaces
The Server and Service protocols define how gRPC services are managed and registered. They emphasize a functional pattern where operations like adding a service or configuring a port return a Result object.
p.Grpc.Server Protocol
This protocol manages the lifecycle and configuration of the gRPC server instance.
| Method | Description | Return Type |
|---|---|---|
add_service | Adds a servicer to a specific server instance | p.Result[bool] |
configure_port | Configures host and port binding (secure or insecure) | p.Result[int] |
start_server | Initializes and starts the server instance | p.Result[p.Grpc.GrpcServer] |
stop_server | Shuts down the server with a grace period | p.Result[bool] |
p.Grpc.Service Protocol
This protocol handles the definition and validation of the RPC methods themselves.
| Method | Description | Return Type |
|---|---|---|
create_service | Defines a new service with a name and method handlers | p.Result[p.Grpc.GrpcServicer] |
service_methods | Retrieves a sequence of registered method names | p.Result[t.StrSequence] |
register_service | Links a servicer to a server instance | p.Result[bool] |
Sources: src/flext_grpc/protocols.py:69-105, src/flext_grpc/protocols.py:177-210
Client and Channel Communication
Communication protocols define the contract for target addressing, connection state management, and making remote procedure calls.
Connection Workflow
The system uses a state machine to track channel transitions (e.g., IDLE -> CONNECTING -> READY).
The sequence diagram illustrates the lifecycle of a client connection and a subsequent RPC call mediated by the protocol interfaces.
Sources: src/flext_grpc/protocols.py:116-150, src/flext_grpc/models.py:343-380
Communication Protocols Summary
- p.Grpc.Client: Responsible for high-level operations like
connect_client,make_call, and connection validation. - p.Grpc.Channel: Handles low-level state tracking (
channel_state) and waiting for connectivity changes. - p.Grpc.GrpcMessage: A duck-typed protocol representing serialized protobuf messages.
Sources: src/flext_grpc/protocols.py:116-148, src/flext_grpc/protocols.py:212-245
Streaming Protocols
The p.Grpc.Streaming protocol provides a unified interface for all four gRPC communication patterns: Unary, Server-side Streaming, Client-side Streaming, and Bidirectional Streaming.
The flow diagram shows how different streaming patterns are handled under a single interface.
| Operation | Purpose |
|---|---|
create_stream | Initializes a stream based on a method and channel |
handle_client_streaming | Processes a sequence of messages from the client |
handle_server_streaming | Manages sending a sequence of messages from the server |
send_data | Utility to push individual messages onto an active stream |
Sources: src/flext_grpc/protocols.py:152-175, src/flext_grpc/models.py:516-538
Infrastructure and Runtime Protocols
To facilitate Clean Architecture, flext-grpc defines protocols for the runtime environment and resource management.
GrpcRuntime Protocol
This protocol mirrors the grpc package, allowing the application to interact with grpc.insecure_channel, grpc.server, and handle standard gRPC errors like RpcError without direct dependency on the library in the domain layer.
Sources: src/flext_grpc/protocols.py:441-468
ResourceManager Protocol
Defines a contract for managing the lifecycle of ephemeral gRPC resources.
acquire: Obtains aGrpcResource.release: Safely releases a specific resource.cleanup: Triggers a global teardown of all active resources.
Sources: src/flext_grpc/protocols.py:326-343
Conclusion
The Protocols & Interfaces in flext-grpc ensure that the platform remains extensible and maintainable by abstracting the complexities of gRPC into a set of well-defined Python Protocols. This design supports the project's goals of high performance and strict type safety while adhering to Domain-Driven Design principles. By using these interfaces, developers can build robust services that are decoupled from infrastructure details, ensuring long-term architectural stability.