volo / volo-grpc

# CLAUDE.md - volo-grpc

## Overview

`volo-grpc` is the gRPC implementation of the Volo framework, providing async gRPC client and server based on HTTP/2 (hyper). Supports unary, client streaming, server streaming, and bidirectional streaming calls with gzip/zlib/zstd compression, gRPC-Web, and TLS.

**Documentation:** https://docs.rs/volo-grpc

## Directory Structure

```
volo-grpc/src/
├── lib.rs              # Public API exports
├── body.rs             # BoxBody type
├── codegen.rs          # Code generation helpers
├── context.rs          # ClientContext, ServerContext (RpcInfo, stats, extensions)
├── message.rs          # RecvEntryMessage, SendEntryMessage traits (prost::Message)
├── request.rs          # Request<T> wrapper (metadata + message/Streaming)
├── response.rs         # Response<T> wrapper (metadata + message/Streaming)
├── status.rs           # gRPC Status (code, message, details, metadata) and Code enum
├── tracing.rs          # Span provider
├── client/             # ClientBuilder, Client ("clone and use" pattern)
│   ├── callopt.rs      # Per-call options (CallOpt)
│   ├── dns.rs          # DNS resolution
│   ├── meta.rs         # MetaService (metadata handling)
│   └── layer/timeout.rs
├── server/             # Server, Router, ServiceBuilder, NamedService
│   ├── router.rs       # Multi-service routing
│   ├── service.rs      # ServiceBuilder::new(svc).build()
│   ├── incoming.rs     # Connection acceptance
│   ├── meta.rs         # MetaService
│   └── layer/timeout.rs
├── codec/              # Codec trait, encode/decode, compression (gzip/zlib/zstd)
├── metadata/           # MetadataMap, MetadataKey, MetadataValue (binary keys use `-bin` suffix)
├── layer/              # Shared layers: loadbalance, grpc_timeout, grpc_web, user_agent, CORS
└── transport/          # Client transport, connection, TLS config
```

## Key Components

**Client** -- `ClientBuilder` configures: `rpc_timeout`, `connect_timeout`, `discover`, `load_balance`, `layer`/`layer_front`, `compression`.

**Server** -- Built on hyper HTTP/2. Methods: `add_service`, `layer`/`layer_front`/`layer_tower`, `run`/`run_with_shutdown`, `tls_config`, plus HTTP/2 tuning options.

**Router** -- Supports multiple gRPC services via `add_service`:

```rust
Server::new()
    .add_service(ServiceBuilder::new(service_a).build())
    .add_service(ServiceBuilder::new(service_b).build())
    .run(addr).await?;
```

**NamedService** -- Services implement this trait (provides `const NAME`) for routing.

**Codec** -- Encoder/Decoder abstraction. Compression: gzip and zlib enabled by default, zstd optional.

**Metadata** -- `MetadataMap` stores key-value pairs. Binary keys use `-bin` suffix.

## Feature Flags

| Feature               | Description              |
| --------------------- | ------------------------ |
| `default`             | Enables gzip and zlib    |
| `gzip`                | gzip compression         |
| `zlib`                | zlib compression         |
| `zstd`                | zstd compression         |
| `compress`            | Compression base support |
| `rustls`              | Rustls TLS               |
| `native-tls`          | Native TLS               |
| `native-tls-vendored` | Vendored Native TLS      |
| `grpc-web`            | gRPC-Web support         |

## HTTP/2 Configuration Options

Server HTTP/2 settings:

- `http2_init_stream_window_size` / `http2_init_connection_window_size` (default 1MB)
- `http2_adaptive_window`
- `http2_max_concurrent_streams`
- `http2_keepalive_interval` / `http2_keepalive_timeout` (default 20s)
- `http2_max_frame_size`
- `http2_max_send_buf_size`
- `http2_max_header_list_size` (default 16MB)
- `accept_http1`: Accept HTTP/1 (required for gRPC-Web)

## Notes

1. **Users should not use volo-grpc directly**: Use code generated by `volo-build`
2. **gRPC-Web requires additional configuration**: Enable `grpc-web` feature and set `accept_http1(true)`
3. **Compression is optional**: gzip and zlib enabled by default, zstd requires manual enabling
4. **TLS requires backend selection**: rustls or native-tls

More agent context in cloudwego/volo

7 other files this repository gives its agents.