tonic-client-reference

Reference the LOCAL tonic/ directory for understanding gRPC client implementation patterns in Rust.

CRITICAL: Use Local Files Only

NEVER fetch from GitHub. Do not use:

•WebFetch with github.com/hyperium/tonic
•WebFetch with raw.githubusercontent.com/.../tonic
•WebSearch for "tonic" implementation details

ALWAYS use local files:

•Read tool with tonic/**/*.rs paths
•Grep tool with path="tonic/"
•Glob tool with path="tonic/"

The tonic/ directory at the repository root is the authoritative reference.

Instructions

The tonic/ directory at the repository root contains the official Rust gRPC implementation.

Setup (one-time only)

If the directory doesn't exist, clone it once:

bash

git clone https://github.com/hyperium/tonic.git tonic

After cloning, ALWAYS use the local files via Read/Grep/Glob tools.

Key Files Reference

File	Purpose
`tonic/tonic/src/client/grpc.rs`	Main gRPC client implementation
`tonic/tonic/src/client/service.rs`	Client service wrapper
`tonic/tonic/src/request.rs`	Request wrapper with metadata
`tonic/tonic/src/response.rs`	Response wrapper with metadata
`tonic/tonic/src/metadata/`	gRPC metadata (headers) handling
`tonic/tonic/src/codec/`	Encoding/decoding traits and implementations
`tonic/tonic/src/transport/channel/`	HTTP/2 channel and connection management
`tonic/tonic/src/transport/channel/service/`	Tower service implementations
`tonic/tonic/src/status.rs`	gRPC status codes and error handling
`tonic/tonic/src/extensions.rs`	Request/response extensions
`tonic/tonic/src/body.rs`	HTTP body handling

Client-Specific Files

File	Purpose
`tonic/tonic/src/transport/channel/endpoint.rs`	Endpoint builder and configuration
`tonic/tonic/src/transport/channel/mod.rs`	Channel implementation
`tonic/tonic/src/transport/channel/service/reconnect.rs`	Reconnection logic
`tonic/tonic/src/transport/channel/service/tls.rs`	TLS configuration
`tonic/tonic/src/transport/service/grpc_timeout.rs`	Timeout handling

Codec/Streaming Files

File	Purpose
`tonic/tonic/src/codec/decode.rs`	Streaming decoder implementation
`tonic/tonic/src/codec/encode.rs`	Streaming encoder implementation
`tonic/tonic/src/codec/compression.rs`	Compression handling
`tonic/tonic/src/codec/buffer.rs`	Buffer management for streaming

Retry/Backoff Files

File	Purpose
`tonic/grpc/src/client/name_resolution/backoff.rs`	Exponential backoff implementation
`tonic/tonic-types/src/richer_error/std_messages/retry_info.rs`	RetryInfo error detail type

Usage Patterns

Channel configuration:

code

Read tonic/tonic/src/transport/channel/endpoint.rs for Endpoint and Channel setup

Streaming implementation:

code

Read tonic/tonic/src/codec/decode.rs and encode.rs for streaming frame handling

Metadata handling:

code

Read tonic/tonic/src/metadata/map.rs for MetadataMap implementation

Error/Status handling:

code

Read tonic/tonic/src/status.rs for Status type and code mappings

Interceptors:

code

Read tonic/tonic/src/service/interceptor.rs for interceptor patterns

Retry/Backoff:

code

Read tonic/grpc/src/client/name_resolution/backoff.rs for exponential backoff with jitter

When to Use

•Implementing client-side gRPC features
•Understanding streaming patterns
•Debugging connection or channel issues
•Verifying correct metadata handling
•Checking status code mappings
•Understanding Tower service integration

How to Use (Examples)

bash

# Search for channel configuration
Grep pattern="Endpoint" path="tonic/tonic/src/transport/"

# Read client implementation
Read file_path="tonic/tonic/src/client/grpc.rs"

# Find streaming-related code
Grep pattern="Streaming" path="tonic/tonic/src/codec/"

# Search for interceptor patterns
Grep pattern="Interceptor" path="tonic/tonic/src/"

# Search for backoff/retry patterns
Grep pattern="backoff" path="tonic/grpc/src/client/"

FORBIDDEN:

•WebFetch("https://github.com/hyperium/tonic/...") - NO
•WebFetch("https://raw.githubusercontent.com/hyperium/tonic/...") - NO
•WebSearch("tonic ...") for implementation details - NO
•Guessing behavior without reading local tonic/**/*.rs files - NO