gRPC Link¶

The gRPC Link provides the underlying channel management and connection handling for gRPC communication.

Configuration¶

The link requires configuration for establishing the gRPC channel:

config = {
    # Required parameters
    "target": "[::]:50051",        # The gRPC server address
    "use_secure": False,           # Whether to use TLS/SSL

    # Optional parameters
    "credentials": None,           # Custom channel credentials
    "connect_timeout": 5.0,        # Connection timeout in seconds

    # Channel options
    "options": {
        # Keepalive settings
        "grpc.keepalive_time_ms": 30000,           # Time between keepalive pings
        "grpc.keepalive_timeout_ms": 10000,        # Timeout for keepalive ping responses
        "grpc.keepalive_permit_without_calls": 1,  # Allow keepalive pings when no calls
        "grpc.http2_max_pings_without_data": 0,    # Allow unlimited pings without data
    },

    # Default metadata for all calls
    "metadata": [
        ("client-id", "my-client")
    ],
}

Usage¶

Basic Setup¶

async with GrpcLink("my_link", config) as link:
    # Link is now ready for use with GrpcCodec
    channel = link.channel  # Access the underlying gRPC channel if needed

With Codec¶

Typically used in conjunction with the GrpcCodec:

async with GrpcLink("grpc", link_config) as link:
    async with GrpcCodec("codec", link, codec_config) as codec:
        # Make gRPC calls using the codec
        response = await codec.call("MyMethod", request)

Secure Connection¶

For TLS/SSL connections:

secure_config = {
    "target": "secure.example.com:443",
    "use_secure": True,
    "credentials": grpc.ssl_channel_credentials(
        root_certificates=root_cert_bytes,
        private_key=private_key_bytes,
        certificate_chain=cert_chain_bytes
    )
}

async with GrpcLink("secure_link", secure_config) as link:
    # Make secure gRPC calls

Configuration Options¶

Required Parameters¶

target (str): The address of the gRPC server (e.g., "localhost:50051")
use_secure (bool): Whether to use a secure channel (TLS/SSL)

Optional Parameters¶

credentials (grpc.ChannelCredentials): Custom channel credentials for secure connections
connect_timeout (float): Timeout in seconds for initial connection
options (dict): Channel options for tuning gRPC behavior
metadata (list): Default metadata to include with all calls

Common Channel Options¶

grpc.keepalive_time_ms: Time between keepalive pings
grpc.keepalive_timeout_ms: Timeout for keepalive ping responses
grpc.keepalive_permit_without_calls: Allow keepalive pings without active calls
grpc.http2_max_pings_without_data: Maximum pings without data
grpc.max_receive_message_length: Maximum message size in bytes
grpc.max_send_message_length: Maximum message size in bytes

Error Handling¶

The link handles various connection scenarios:

try:
    async with GrpcLink("my_link", config) as link:
        # Use link
except grpc.RpcError as e:
    # Handle gRPC-specific errors
    if e.code() == grpc.StatusCode.UNAVAILABLE:
        print("Server unavailable")
except Exception as e:
    # Handle other errors
    print(f"Unexpected error: {e}")

Properties¶

channel: The underlying gRPC channel
is_open: Boolean indicating if the link is currently open
name: The name of the link instance

Best Practices¶

Always use the link within an async context manager to ensure proper cleanup
Configure appropriate timeouts for your use case
Use keepalive settings for long-lived connections
Include relevant metadata for tracking and debugging
Consider secure connections for production environments

GrpcCodec: Higher-level interface for making gRPC calls
Proto Codec: Handles protobuf message serialization

API Reference¶

See zeloscloud.aio.links.grpc_link.GrpcLink in the API Reference.