Expand description
An HTTP/2 gRPC client and server for pbrs and optional Prost messages.
Supports unary and streaming calls, generated service stubs, TLS, compression, and configurable connection, RPC, and message limits. Optional features add Tower and tonic integration.
Uses Tokio and an embedded h2 backend. gzip and deflate use
miniz_oxide; TLS uses rustls with
Graviola by default.
Supply application-owned TLS configs through ServerTls::from_rustls
and ClientTls::from_rustls.
§Quickstart
Given proto/hello.proto:
syntax = "proto3";
package helloworld;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }generate client and server stubs from build.rs:
// build.rs
fn main() {
pbrs::codegen::compile_protos(&["proto/hello.proto"], &["proto"])
.expect("codegen");
}then implement the generated trait and serve it:
use pbrs_grpc::hello::{Greeter, GreeterServer, HelloReply, HelloRequest};
use pbrs_grpc::{Request, Response, Status};
struct MyGreeter;
impl Greeter for MyGreeter {
async fn say_hello(
&self,
request: Request<HelloRequest>,
) -> Result<Response<HelloReply>, Status> {
let mut reply = HelloReply::new();
reply.set_message(format!("hello {}", request.get_ref().name()));
Ok(Response::new(reply))
}
}
GreeterServer::new(MyGreeter)
.serve("127.0.0.1:50051".parse().expect("addr"))
.awaitMethods you omit on the generated trait answer UNIMPLEMENTED.
The client side mirrors it:
use pbrs_grpc::hello::{GreeterClient, HelloRequest};
use pbrs_grpc::Request;
let client = GreeterClient::connect("127.0.0.1:50051").await?;
let mut req = HelloRequest::new();
req.set_name("world");
let reply = client.say_hello(Request::new(req)).await?;
println!("{}", reply.get_ref().message());examples/greeter is a complete external crate with its own proto,
build.rs, health, and reflection services.
See docs/grpc.md in the repository for the full guide, and
docs/benchmarks.md for measured numbers.
§Main APIs
| Purpose | Types |
|---|---|
| Servers and routing | Server, Router, Service, Rpc, Incoming |
| Clients and calls | Channel, ChannelConfig, Call, CallHandle |
| TLS and peer identity | Identity, ServerTls, ClientTls, PeerIdentity |
| Request and response data | Request, Response, Metadata, Extensions |
| Errors | Status, Code, ErrorDetails, Any |
| Streaming | Streaming, StreamSender, Framed |
| Interceptors | Interceptor, ClientInterceptor, ResponseInterceptor |
| Limits | ServerConfig, ChannelConfig, MessageLimits |
| Built-in services | health, reflection, channelz |
Client interceptors run before a stream opens; returning an error sends
nothing. Server interceptors run before the handler. Response interceptors
run after a successful handler result or received response. Attach hooks
with the corresponding intercept and on_response methods; repeated
attachments run in order.
Request overrides can change timeout, compression, and wait-for-ready.
The *_is_set methods tell an interceptor whether a caller supplied an
override. Configuration getters expose the channel or server defaults.
Outgoing::connected is a snapshot when the hook runs, not a readiness
guarantee. See each method for its override and clearing rules.
Rich errors preserve unknown detail types through ErrorDetails::unknown.
Reflection also serves the v1alpha path for older clients.
§Safety
The protocol-facing modules restrict unsafe: gRPC
framing, transport, TLS, compression, codec, resolver,
load-balancing, authorization, binary logging, service-config, metadata,
status, request, response, and stream code all carry
#[forbid(unsafe_code)]. Server call-record initialization, cancellation
flag recycling, HTTP name storage, static HTTP value copies, and the
private HTTP/2 backend have scoped exceptions.
Their allocation, synchronization and lifetime invariants need independent
review and targeted safety checks; the transport seam’s forbid remains intact.
Resource limits additionally bound peer-controlled work and memory.
§Threat model
The peer is assumed hostile and able to send any bytes at any rate. Each defence below targets a particular stage of work. These limits do not imply a total process-memory bound.
| Attack | Defence | Default |
|---|---|---|
| Huge declared message length | Refused from the 5-byte frame header without a claim-sized carry reservation; HTTP/2 may already hold DATA | 4 MiB (MessageLimits) |
| Decompression bomb | Bounded inflate that stops one byte past the cap; opt out of inbound gzip entirely | 4 MiB (gzip::decode_limited); opt-out ServerConfig::accept_compressed / ChannelConfig::accept_compressed |
| Metadata flood | HTTP/2 SETTINGS_MAX_HEADER_LIST_SIZE | 16 KiB (ServerConfig::max_header_list_size) |
| Stream flood | HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS; extras wait, they are not RESOURCE_EXHAUSTED | 256 (ServerConfig::max_concurrent_streams) |
| Transport buffering | Per-connection receive window and per-stream send-buffer threshold | 16 MiB / 1 MiB |
| Slow reader amplification | Capacity is released only after a chunk is handed on, so a slow handler throttles the peer | always on |
| Deeply nested protobuf | Recursion limit in pbrs | always on |
| Truncated or malformed frames | Rejected as a protocol error, never treated as an empty message | always on |
| Reserved metadata injection | grpc-* and hop-by-hop headers are never read from or written to user metadata | always on |
| Cleartext interception | TLS 1.2/1.3, ALPN h2 required; built-in constructors configure certificate verification, caller configs retain their trusted application policy | opt-in Server::serve_tls / Channel::connect_tls |
| Impersonation | WebPKI roots or a CA you pin; mTLS via ServerTls::mtls; verified client chain on Rpc::peer_identity | opt-in |
| Unauthenticated Unix peer | Connecting process uid/gid/pid on Rpc::peer_cred from SO_PEERCRED / LOCAL_PEERCRED | Unix accept loop |
| Long-lived connection hold | GOAWAY (server) or close (client) after age or idle; keepalive PINGs do not reset idle and do not postpone age | opt-in ServerConfig::max_connection_age / ServerConfig::max_connection_idle / ChannelConfig::max_connection_age / ChannelConfig::max_connection_idle |
| Slow handshake | Whole client dial, and each of the server TLS accept and HTTP/2 preface, is timed out | 20 s (ChannelConfig::connect_timeout / ServerConfig::handshake_timeout) |
| Accept storm | Drop excess TCP/Unix accepts before a handshake task is spawned | opt-in ServerConfig::max_concurrent_connections |
| Unbounded handler concurrency | Refuse further RPCs with RESOURCE_EXHAUSTED before the handler runs | opt-in ServerConfig::max_concurrent_rpcs |
| Unbounded client RPC concurrency | Refuse further RPCs with RESOURCE_EXHAUSTED before the stream opens | opt-in ChannelConfig::max_concurrent_rpcs |
| Handler that never returns | Cap the RPC even when the client omits grpc-timeout | opt-in ServerConfig::timeout |
| Silent TCP half-open | TCP SO_KEEPALIVE (not HTTP/2 PING) | opt-in ServerConfig::tcp_keepalive / ChannelConfig::tcp_keepalive |
| HTTP/2 rapid reset | Cap remotely-reset streams waiting in the accept queue | 20 (DEFAULT_MAX_PENDING_ACCEPT_RESET_STREAMS, override ServerConfig::max_pending_accept_reset_streams) |
| HTTP/2 protocol-error RST flood | Cap locally-reset streams caused by invalid frames | 1024 (DEFAULT_MAX_LOCAL_ERROR_RESET_STREAMS, override ServerConfig::max_local_error_reset_streams) |
| HTTP/2 locally-reset stream memory | Remember stream IDs after we RST; oldest purged, not GOAWAY | 50 (DEFAULT_MAX_CONCURRENT_RESET_STREAMS, override ServerConfig::max_concurrent_reset_streams) |
| HTTP/2 small-DATA flood | Cap framing overhead of tiny DATA frames | 25600 (DEFAULT_DATA_FRAME_BUDGET, override ServerConfig::data_frame_budget) |
| HTTP/2 CONTINUATION flood | Cap CONTINUATION frames on an unfinished header block; that connection drops | always (h2, scaled from ServerConfig::max_header_list_size) |
| Unfinished HEADERS | Header block without END_HEADERS stalls that stream only; the accept loop still serves | always |
| Client RST after the request is read | Signal Request::cancelled, then drop a still-pending handler; abort a stream drain waiting for the next message | always |
| Client cancel after a client-streaming half-close | RST while the unary response is pending (handle, drop, or deadline) | always |
Client request-stream abort (StreamSender::fail) | RST CANCEL; the Call resolves with that status (client-streaming, or bidi before headers — not UNAVAILABLE from the reset); after bidi headers the received Streaming sees Code::Cancelled, not that status | always |
| Client streaming deadline | RST the send half before headers (server-streaming and bidi) and after a half-close; after those headers RST the parked send half | always |
Unsupported method or content type (GET, JSON, grpc+json) | HTTP 405 / 415 with no grpc-status, before an RPC slot is taken; supported gRPC-Web types are accepted with grpc-web and rejected with 415 without it | always |
h2c (cleartext prior-knowledge HTTP/2) remains the default, because that is
what a loopback test and a mesh sidecar speak. Production that is not
behind a sidecar should call Server::serve_tls / Channel::connect_tls.
Built-in TLS constructors configure peer verification. Caller-owned rustls
configs are trusted application inputs: custom verifier security and ticket
invalidation belong to the caller. Disabling peer verification is unsupported.
Set finite connection, RPC, message, and application queue limits for the
deployment. HTTP/2 stream limits govern each connection;
ServerConfig::max_concurrent_rpcs limits active handlers across the server
and rejects excess calls with RESOURCE_EXHAUSTED.
§unsafe
The hand-written gRPC framing, transport, TLS, compression,
codec, resolver, load-balancing, authorization, binary-logging,
service-config, metadata, status, request, response, and stream modules
carry #[forbid(unsafe_code)], which cannot be overridden from inside the
module.
Two hand-written Linux-only OS helpers use scoped unsafe, each with a
local SAFETY comment:
proxysetsTCP_USER_TIMEOUTwith a rawsetsockoptbecausesocket2exposes no stable safe wrapper for that option.rt::per_corecallssched_setaffinity/sched_getcputo pin per-core runtime threads.
server::rpc::InboundRpc::from_rpc initializes a boxed call record field
by field. rpc_cancel::RpcCancel::drop moves an initialized Arc out of
ManuallyDrop exactly once. The embedded HTTP/2 backend uses a Linux
futex mutex with guarded UnsafeCell access, plus upstream’s validated
BytesStr::as_str UTF-8 view. Other platforms use the standard mutex.
Other scoped helpers store owned or static HTTP names and copy cached
static HTTP values. Request extensions publish through OnceLock without
unsafe code. These exceptions do not relax the transport seam’s forbid.
Modules that include! generated message code (hello, testing,
health, reflection, pb, channelz, orca) are also outside
those per-module forbids; pbrs gencode uses unsafe for zeroed-message
construction, and that is a pbrs property rather than a gRPC transport
one.
Invalid peer input is handled through gRPC status or HTTP/2 protocol errors. Workspace lints restrict panics, unchecked indexing, and lossy casts in shipping code. Negative tests and fuzzing exercise these paths.
§Tuning
Configure connection count, HTTP/2 windows, and stream queues for the workload:
ChannelConfig::connections— one connection is oneh2driver task. A pool can distribute driver work across runtime workers.- Window sizes — the 16 MiB default keeps a 4 MiB message from
stalling on a
WINDOW_UPDATEround trip. Lower it only under memory pressure:Server::initial_stream_window_size/ChannelConfig::initial_stream_window_size. - Stream queue depth — the buffer a streaming handler passes to
Streaming::channel, andChannel::stream_buffer/ChannelConfig::stream_bufferon the client. The wire layer writes whatever is queued as one batch, so deeper means fewer and larger writes at the cost of memory. Received streams are decoded inline and have no queue to size.
Compression trades CPU for bandwidth. Enable it with
Request::set_compress, ServerConfig::send_compressed, or
ChannelConfig::send_compressed. The default gzip effort is 1; configure it
with gzip_compression_level. Inbound compression is accepted by default
and can be disabled with accept_compressed. Response::encoding reports
the peer’s selected encoding (None for identity).
HTTP/2 windows are fixed unless adaptive flow control is explicitly enabled.
Configure reset-stream retention and flood limits through ServerConfig
and ChannelConfig. Client handshake settings take effect at connection
creation; changing a live channel cannot renegotiate HTTP/2 SETTINGS.
§Relationship to the rest of the workspace
pbrs does not depend on this crate. The native transport runs without
tonic; the optional tonic feature mounts native generated services
in tonic. Use protobuf-tonic to keep a tonic service with pbrs messages.
Re-exports§
pub use codec::CodecMessage;pub use compression::Codec;pub use compression::CompressionAlgorithm;pub use copy_counts::CopyCounts;pub use copy_counts::copy_counts;pub use copy_counts::reset_copy_counts;pub use pb::Any;pub use pb::ErrorDetails;pub use service_config::HedgingPolicy;pub use service_config::LbPolicyConfig;pub use service_config::MethodConfig;pub use service_config::MethodName;pub use service_config::RetryPolicy;pub use service_config::RetryThrottler;pub use service_config::RetryThrottling;pub use service_config::RingHashConfig;pub use service_config::ServiceConfig;pub use service_config::WeightedRoundRobinConfig;pub use service_config::pushback_delay;pub use service_config::retry_backoff;pub use telemetry::AttemptLabels;pub use telemetry::BoundedMetricObserver;pub use telemetry::CallLabels;pub use telemetry::CallRole;pub use telemetry::CancellationEvent;pub use telemetry::CancellationReason;pub use telemetry::LifecycleObserver;pub use telemetry::MAX_METRIC_LABEL_BYTES;pub use telemetry::MAX_METRIC_RPCS;pub use telemetry::MAX_METRIC_TARGETS;pub use telemetry::MetricAttemptClass;pub use telemetry::MetricCallLabels;pub use telemetry::MetricEvent;pub use telemetry::MetricLabelPolicy;pub use telemetry::MetricSink;pub use telemetry::OTHER_METRIC_LABEL;pub use telemetry::ObserverChain;pub use telemetry::OwnedCallLabels;pub use telemetry::ReconnectEvent;pub use telemetry::RejectionEvent;pub use telemetry::RejectionReason;pub use hello::Greeter;pub use hello::GreeterClient;pub use hello::GreeterServer;pub use hello::HelloReply;pub use hello::HelloRequest;pub use interop_cases::run_case;pub use testing::BoolValue;pub use testing::EchoStatus;pub use testing::Empty;pub use testing::InteropTestService;pub use testing::Payload;pub use testing::ResponseParameters;pub use testing::SimpleRequest;pub use testing::SimpleResponse;pub use testing::SizedInteropTestService;pub use testing::StreamingInputCallRequest;pub use testing::StreamingInputCallResponse;pub use testing::StreamingOutputCallRequest;pub use testing::StreamingOutputCallResponse;pub use testing::TestService;pub use testing::TestServiceClient;pub use testing::TestServiceServer;
Modules§
- authz
- gRPC authorization policies (gRFC A43).
- binlog
- gRPC binary logging (gRFC A16).
- channelz
- Channelz introspection: A14 data model +
grpc.channelz.v1service. - codec
- gRPC length-prefixed framing.
- compat
- Tonic-shaped API shims over the native
pbrs-grpctransport. - compression
- Wire message compression: the
grpc-encodingregistry (RX-06). - copy_
counts - Bench-only user-space copy counters (SB-13, Phase 0 attribution).
- gzip
gzipcoding: re-exported fromcrate::compression.- health
- The standard gRPC health service and a shared status reporter.
- hello
- Generated
helloworld.Greetermessages, client, and server. - interop_
cases - Official
--test_caseprocedures driven through the shipped kernel client. - lb
- LB policy registry and
loadBalancingConfigselection (A24, CH-03). - orca
- ORCA load reports (gRFC A51): per-call trailers and the OOB service.
- pb
google.rpc.Status,google.protobuf.Any, and the standard error-detail messages.- reflection
- The standard gRPC reflection service for descriptor lookup.
- resolver
- Client resolvers: target URIs, snapshot publication, refresh (CH-02).
- service_
config - JSON service config: method config, retry/hedging policy, throttling, LB selection.
- telemetry
- Lifecycle telemetry hooks and explicitly bounded metric labels.
- testing
- Generated
grpc.testingtypes and interoperability handlers. - timeout
- The
grpc-timeoutheader:{digits}{unit}.
Structs§
- Byte
Budget Tracker - Tracks byte charges against an optional limit.
- Byte
Permit - An RAII permit representing bytes charged to a
ByteBudgetTracker. - Call
- An RPC in flight.
- Call
Handle - A cancel signal for an in-flight
Call, detached from the call itself. - Channel
- A prior-knowledge HTTP/2 connection (or small pool) to a gRPC server.
- Channel
Config - HTTP/2 and resource settings for a
Channel. - Client
Tls - Client-side TLS: a rustls connector requiring negotiated ALPN
h2. Built-in constructors keep a session cache for up to 256 server names. Caller configs supplied toSelf::from_rustlsretain their own session policy. Clones share the underlying config and session store. - Connection
Info - Connection-level facts copied onto every RPC on this socket.
- Endpoint
- Tonic-style endpoint facade over
Channel. - Extensions
- Per-RPC typed bag: insert in an interceptor, read in the handler. A type map of protocol extensions.
- Framed
- A message plus the gRPC Compressed-Flag its frame carried.
- Identity
- A PEM certificate chain and private key.
- Intercepted
- A
Servicewith anInterceptorin front of it, and optionally aResponseInterceptorafter the handler returnsOk. - Message
Limits - Message-size, compression-work and optional decoder history limits.
- Metadata
- gRPC metadata, i.e. HTTP/2 headers or trailers minus the reserved ones.
- Outgoing
- The outbound half of an RPC, as a
crate::ClientInterceptorsees it. - Parse
Code Error - The string was not a canonical gRPC code name or a code in
0..=16. - Parts
- A
Requestenvelope without its message, includingSelf::cancelled. SeeRequest::into_message_and_parts. - Peer
Cred - Unix-domain peer credentials from
SO_PEERCRED(Linux) orLOCAL_PEERCRED(macOS / *BSD). - Peer
Identity - Client certificate chain from a TLS handshake, DER-encoded, leaf first.
- Request
- A message plus the metadata, deadline, and compression choice around it.
- Response
- A reply: message, initial headers, and trailing metadata.
- Response
Parts - A
Responseenvelope without its message, including receivedResponse::encodingand localResponse::extensions. SeeResponse::into_message_and_parts.Self::compress_is_setis occupancy on this split reply envelope, so a later interceptor can fill compress only when unset.Self::clear_compressrestores the server gzip overlay on this split reply envelope. - Retry
Stats - Retry statistics for one
Channel, A45-style. - Router
- Serves several services, routing on the service half of the path.
- Rpc
- One inbound RPC, before its call shape has been chosen.
- Server
- Serves one
Servicewithout a router lookup. - Server
Config - HTTP/2 and resource settings for a server.
- Server
Tls - Server-side TLS: a rustls acceptor requiring negotiated ALPN
h2. Built-in constructors enable TLS 1.3 session tickets with keys that rotate every 6 h; rebuilding them invalidates outstanding tickets. Caller configs supplied toSelf::from_rustlsretain their own ticket and session policy. - Status
- A gRPC status: a
Code, an optional message, optional trailing metadata, and optionalgrpc-status-details-bin. - Stream
Sender - The write half of a message stream.
- Streaming
- A sequence of decoded gRPC messages.
- Target
- Where a
Channelshould dial. - TcpConnect
Info - Connection info for standard TCP server transports.
- TcpStats
- Per-connection TCP telemetry snapshot (A80).
- TlsConnect
Info - Connection info for TLS server transports.
- TlsHandshake
Info - Per-handshake TLS telemetry snapshot (A118).
- UdsConnect
Info - Connection info for Unix-domain server transports.
Enums§
- Code
- A
grpc-statuscode. - Pushback
- Server retry pushback from a
grpc-retry-pushback-mstrailer (gRPC A6).
Constants§
- DEFAULT_
ADAPTIVE_ WINDOW_ INITIAL_ SIZE - Default adaptive-window starting point: the RFC 9113 initial window.
- DEFAULT_
ADAPTIVE_ WINDOW_ MAX_ SIZE - Default adaptive-window cap: 16 MiB.
- DEFAULT_
CONNECT_ TIMEOUT - How long a client dial or a server TLS/HTTP/2 preface may take. Default 20 s.
- DEFAULT_
DATA_ FRAME_ BUDGET - Default per-connection HTTP/2 DATA framing budget: 25,600 overhead units.
- DEFAULT_
GZIP_ COMPRESSION_ LEVEL - Default outbound gzip deflate level: 1 (
flate2fast). - DEFAULT_
HEADER_ TABLE_ SIZE - Default HTTP/2
SETTINGS_HEADER_TABLE_SIZE: 4096 octets. - DEFAULT_
KEEP_ ALIVE_ TIMEOUT - How long to wait for a keepalive PING acknowledgement. Default 20 s.
- DEFAULT_
MAX_ CONCURRENT_ RESET_ STREAMS - HTTP/2 locally-reset stream-ID memory: how many reset IDs this endpoint remembers so late frames are ignored (RFC 9113).
- DEFAULT_
MAX_ CONCURRENT_ STREAMS - Default HTTP/2
SETTINGS_MAX_CONCURRENT_STREAMS: 256 in-flight RPCs. - DEFAULT_
MAX_ CONNECTION_ AGE_ GRACE - After
ServerConfig::max_connection_ageor idle fires, how long to wait for in-flight RPCs before dropping the socket. Default 10 s. - DEFAULT_
MAX_ DECODING_ MESSAGE_ SIZE - Default inbound message cap: 4 MiB, matching gRPC’s cross-language default.
- DEFAULT_
MAX_ FRAME_ SIZE - Default HTTP/2
SETTINGS_MAX_FRAME_SIZE: 1 MiB. - DEFAULT_
MAX_ HEADER_ LIST_ SIZE - Default HTTP/2
SETTINGS_MAX_HEADER_LIST_SIZE: 16 KiB of metadata. - DEFAULT_
MAX_ LOCAL_ ERROR_ RESET_ STREAMS - HTTP/2 protocol-error RST cap: locally-reset streams after an invalid frame.
- DEFAULT_
MAX_ PENDING_ ACCEPT_ RESET_ STREAMS - HTTP/2 rapid-reset cap: remotely-reset streams waiting in the accept queue.
- DEFAULT_
MAX_ SEND_ BUFFER_ SIZE - Default HTTP/2 send buffer per stream: 1 MiB.
- DEFAULT_
RESET_ STREAM_ DURATION - HTTP/2 locally-reset stream-ID memory duration: how long reset IDs this endpoint remembers so late frames are ignored (RFC 9113).
- DEFAULT_
STREAM_ BUFFER - Default queue depth between a client-streaming caller and the wire.
- DEFAULT_
WINDOW_ SIZE - Default HTTP/2 stream and connection window: 16 MiB.
Traits§
- Client
Interceptor - Inspect or change an outbound RPC before its stream opens.
- Executor
- Schedule background HTTP/2 connection drivers.
- Fused
Future futures_core::future::FusedFuture, so a finishedCallis skipped by combinators that honour termination. A future which tracks whether or not the underlying future should no longer be polled.- Fused
Stream futures_core::stream::FusedStream, so a finishedStreamingis skipped by combinators that honour termination. A stream which tracks whether or not the underlying stream should no longer be polled.- Incoming
- A source of already-accepted byte streams.
- Interceptor
- Inspect an inbound RPC before the handler reads its body.
- Response
Interceptor - Inspect or change a successful response envelope.
- Service
- A gRPC service that can be served.
- Service
Ext - Extra methods on every
Service. - Stream
futures_core::Stream, soStreamingcan be driven withStreamExt. A stream of values produced asynchronously.
Functions§
- post_
quantum_ key_ exchange_ available - Whether the shipping TLS provider negotiates post-quantum key exchange (A120).
Type Aliases§
- Executor
Future - An owned HTTP/2 connection-driver task handed to an
Executor. - Incoming
Accept - One
Incoming::acceptresult: a connection, an error, orNoneif exhausted.