Skip to content

gRPC Codec

The gRPC codec provides protocol-level handling for gRPC communication, supporting all RPC types: unary, server streaming, client streaming, and bidirectional streaming.

Configuration

The codec requires the following configuration:

config = {
    "stub_class": my_service_pb2_grpc.MyServiceStub,  # Required: The generated gRPC stub class
    "trace_proto": True  # Optional: Enable protobuf message tracing (default: False)
}

# Link configuration example
link_config = {
    "target": "[::]:50051",  # gRPC server address
    "use_secure": False,      # Use insecure channel
    "connect_timeout": 5.0,   # Connection timeout in seconds
    "options": {
        "grpc.keepalive_time_ms": 30000,
        "grpc.keepalive_timeout_ms": 10000,
        "grpc.keepalive_permit_without_calls": 1,
        "grpc.http2_max_pings_without_data": 0,
    },
    "metadata": [("client-id", "my-client")]  # Default metadata
}

Basic setup: 

from zeloscloud.links.grpc_link import GrpcLink
from zeloscloud.codecs.grpc import GrpcCodec

async with GrpcLink("grpc", link_config) as link:
    async with GrpcCodec("codec", link, config) as codec:
        # Make RPC calls here

Usage Examples

Unary Call

Simple request-response pattern:

# Create a request message
request = HelloRequest(name="World")

# Make the call
response = await codec.call("SayHello", request)
assert response.message == "Hello, World!"

# With metadata and timeout
metadata = [("client-id", "test-123"), ("request-id", "abc-xyz")]
timeout = 2.0  # seconds
response = await codec.call(
    "SayHello",
    request,
    metadata=metadata,
    timeout=timeout
)

Server Streaming

Receive multiple responses for a single request:

# Request multiple greetings
request = HelloRequest(name="World", greeting_count=3)

# Stream responses
async for response in codec.stream("SayHellosServerStream", request):
    print(f"Got response: {response}")
    # Output:
    # Got response: Hello 1, World!
    # Got response: Hello 2, World!
    # Got response: Hello 3, World!

Client Streaming

Send multiple requests and receive a single response:

# Create multiple requests
names = ["Alice", "Bob", "Charlie"]
requests = [HelloRequest(name=name) for name in names]

# Send stream and get final response
response = await codec.client_stream("SayHellosClientStream", iter(requests))
assert response.message == "Hello, Alice and Bob and Charlie!"

Bidirectional Streaming

Send and receive multiple messages:

# Create requests with multiple greetings per person
requests = [
    HelloRequest(name="Alice", greeting_count=2),
    HelloRequest(name="Bob", greeting_count=2)
]

# Stream requests and receive responses
async for response in codec.bidirectional_stream("SayHellosBidirectional", iter(requests)):
    print(f"Got response: {response}")
    # Output:
    # Got response: Hello 1, Alice!
    # Got response: Hello 2, Alice!
    # Got response: Hello 1, Bob!
    # Got response: Hello 2, Bob!

API Reference

Methods

  • call(method_name, request, timeout=None, metadata=None) - Unary RPC call
  • stream(method_name, request, timeout=None, metadata=None) - Server streaming RPC
  • client_stream(method_name, request_iterator, timeout=None, metadata=None) - Client streaming RPC
  • bidirectional_stream(method_name, request_iterator, timeout=None, metadata=None) - Bidirectional streaming RPC

Parameters

  • method_name (str): Name of the gRPC method to call
  • request: Protobuf message or ProtoMessage instance
  • request_iterator: Iterator yielding request messages
  • timeout (float, optional): Timeout in seconds
  • metadata (list, optional): List of metadata tuples
  • message_name (str, optional): Custom name for the message
  • request_name (str, optional): Custom name for the request message
  • response_name (str, optional): Custom name for the response message

Return Values

  • Unary calls: Returns a single response message
  • Server streaming: Returns an async generator yielding response messages
  • Client streaming: Returns a single response message
  • Bidirectional streaming: Returns an async generator yielding response messages

Exceptions

All methods may raise grpc.RpcError on gRPC-related errors. 

This documentation provides a comprehensive overview of the gRPC codec's functionality, with practical examples drawn from the test cases. It covers all the major RPC patterns and includes configuration options, usage examples, and API reference information.

  • GrpcLink: Handles gRPC channel configuration and connection
  • Proto Codec: Handles protobuf message serialization

API Reference

See zeloscloud.aio.codecs.grpc.GrpcCodec in the API Reference. See zeloscloud.aio.links.grpc_link.GrpcLink in the API Reference.