Skip to main content

Crate pbrs_grpc

Crate pbrs_grpc 

Source
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"))
    .await

Methods 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

PurposeTypes
Servers and routingServer, Router, Service, Rpc, Incoming
Clients and callsChannel, ChannelConfig, Call, CallHandle
TLS and peer identityIdentity, ServerTls, ClientTls, PeerIdentity
Request and response dataRequest, Response, Metadata, Extensions
ErrorsStatus, Code, ErrorDetails, Any
StreamingStreaming, StreamSender, Framed
InterceptorsInterceptor, ClientInterceptor, ResponseInterceptor
LimitsServerConfig, ChannelConfig, MessageLimits
Built-in serviceshealth, 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.

AttackDefenceDefault
Huge declared message lengthRefused from the 5-byte frame header without a claim-sized carry reservation; HTTP/2 may already hold DATA4 MiB (MessageLimits)
Decompression bombBounded inflate that stops one byte past the cap; opt out of inbound gzip entirely4 MiB (gzip::decode_limited); opt-out ServerConfig::accept_compressed / ChannelConfig::accept_compressed
Metadata floodHTTP/2 SETTINGS_MAX_HEADER_LIST_SIZE16 KiB (ServerConfig::max_header_list_size)
Stream floodHTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS; extras wait, they are not RESOURCE_EXHAUSTED256 (ServerConfig::max_concurrent_streams)
Transport bufferingPer-connection receive window and per-stream send-buffer threshold16 MiB / 1 MiB
Slow reader amplificationCapacity is released only after a chunk is handed on, so a slow handler throttles the peeralways on
Deeply nested protobufRecursion limit in pbrsalways on
Truncated or malformed framesRejected as a protocol error, never treated as an empty messagealways on
Reserved metadata injectiongrpc-* and hop-by-hop headers are never read from or written to user metadataalways on
Cleartext interceptionTLS 1.2/1.3, ALPN h2 required; built-in constructors configure certificate verification, caller configs retain their trusted application policyopt-in Server::serve_tls / Channel::connect_tls
ImpersonationWebPKI roots or a CA you pin; mTLS via ServerTls::mtls; verified client chain on Rpc::peer_identityopt-in
Unauthenticated Unix peerConnecting process uid/gid/pid on Rpc::peer_cred from SO_PEERCRED / LOCAL_PEERCREDUnix accept loop
Long-lived connection holdGOAWAY (server) or close (client) after age or idle; keepalive PINGs do not reset idle and do not postpone ageopt-in ServerConfig::max_connection_age / ServerConfig::max_connection_idle / ChannelConfig::max_connection_age / ChannelConfig::max_connection_idle
Slow handshakeWhole client dial, and each of the server TLS accept and HTTP/2 preface, is timed out20 s (ChannelConfig::connect_timeout / ServerConfig::handshake_timeout)
Accept stormDrop excess TCP/Unix accepts before a handshake task is spawnedopt-in ServerConfig::max_concurrent_connections
Unbounded handler concurrencyRefuse further RPCs with RESOURCE_EXHAUSTED before the handler runsopt-in ServerConfig::max_concurrent_rpcs
Unbounded client RPC concurrencyRefuse further RPCs with RESOURCE_EXHAUSTED before the stream opensopt-in ChannelConfig::max_concurrent_rpcs
Handler that never returnsCap the RPC even when the client omits grpc-timeoutopt-in ServerConfig::timeout
Silent TCP half-openTCP SO_KEEPALIVE (not HTTP/2 PING)opt-in ServerConfig::tcp_keepalive / ChannelConfig::tcp_keepalive
HTTP/2 rapid resetCap remotely-reset streams waiting in the accept queue20 (DEFAULT_MAX_PENDING_ACCEPT_RESET_STREAMS, override ServerConfig::max_pending_accept_reset_streams)
HTTP/2 protocol-error RST floodCap locally-reset streams caused by invalid frames1024 (DEFAULT_MAX_LOCAL_ERROR_RESET_STREAMS, override ServerConfig::max_local_error_reset_streams)
HTTP/2 locally-reset stream memoryRemember stream IDs after we RST; oldest purged, not GOAWAY50 (DEFAULT_MAX_CONCURRENT_RESET_STREAMS, override ServerConfig::max_concurrent_reset_streams)
HTTP/2 small-DATA floodCap framing overhead of tiny DATA frames25600 (DEFAULT_DATA_FRAME_BUDGET, override ServerConfig::data_frame_budget)
HTTP/2 CONTINUATION floodCap CONTINUATION frames on an unfinished header block; that connection dropsalways (h2, scaled from ServerConfig::max_header_list_size)
Unfinished HEADERSHeader block without END_HEADERS stalls that stream only; the accept loop still servesalways
Client RST after the request is readSignal Request::cancelled, then drop a still-pending handler; abort a stream drain waiting for the next messagealways
Client cancel after a client-streaming half-closeRST 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 statusalways
Client streaming deadlineRST the send half before headers (server-streaming and bidi) and after a half-close; after those headers RST the parked send halfalways
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 italways

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:

  • proxy sets TCP_USER_TIMEOUT with a raw setsockopt because socket2 exposes no stable safe wrapper for that option.
  • rt::per_core calls sched_setaffinity / sched_getcpu to 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:

  1. ChannelConfig::connections — one connection is one h2 driver task. A pool can distribute driver work across runtime workers.
  2. Window sizes — the 16 MiB default keeps a 4 MiB message from stalling on a WINDOW_UPDATE round trip. Lower it only under memory pressure: Server::initial_stream_window_size / ChannelConfig::initial_stream_window_size.
  3. Stream queue depth — the buffer a streaming handler passes to Streaming::channel, and Channel::stream_buffer / ChannelConfig::stream_buffer on 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.v1 service.
codec
gRPC length-prefixed framing.
compat
Tonic-shaped API shims over the native pbrs-grpc transport.
compression
Wire message compression: the grpc-encoding registry (RX-06).
copy_counts
Bench-only user-space copy counters (SB-13, Phase 0 attribution).
gzip
gzip coding: re-exported from crate::compression.
health
The standard gRPC health service and a shared status reporter.
hello
Generated helloworld.Greeter messages, client, and server.
interop_cases
Official --test_case procedures driven through the shipped kernel client.
lb
LB policy registry and loadBalancingConfig selection (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.testing types and interoperability handlers.
timeout
The grpc-timeout header: {digits}{unit}.

Structs§

ByteBudgetTracker
Tracks byte charges against an optional limit.
BytePermit
An RAII permit representing bytes charged to a ByteBudgetTracker.
Call
An RPC in flight.
CallHandle
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.
ChannelConfig
HTTP/2 and resource settings for a Channel.
ClientTls
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 to Self::from_rustls retain their own session policy. Clones share the underlying config and session store.
ConnectionInfo
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 Service with an Interceptor in front of it, and optionally a ResponseInterceptor after the handler returns Ok.
MessageLimits
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::ClientInterceptor sees it.
ParseCodeError
The string was not a canonical gRPC code name or a code in 0..=16.
Parts
A Request envelope without its message, including Self::cancelled. See Request::into_message_and_parts.
PeerCred
Unix-domain peer credentials from SO_PEERCRED (Linux) or LOCAL_PEERCRED (macOS / *BSD).
PeerIdentity
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.
ResponseParts
A Response envelope without its message, including received Response::encoding and local Response::extensions. See Response::into_message_and_parts. Self::compress_is_set is occupancy on this split reply envelope, so a later interceptor can fill compress only when unset. Self::clear_compress restores the server gzip overlay on this split reply envelope.
RetryStats
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 Service without a router lookup.
ServerConfig
HTTP/2 and resource settings for a server.
ServerTls
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 to Self::from_rustls retain their own ticket and session policy.
Status
A gRPC status: a Code, an optional message, optional trailing metadata, and optional grpc-status-details-bin.
StreamSender
The write half of a message stream.
Streaming
A sequence of decoded gRPC messages.
Target
Where a Channel should dial.
TcpConnectInfo
Connection info for standard TCP server transports.
TcpStats
Per-connection TCP telemetry snapshot (A80).
TlsConnectInfo
Connection info for TLS server transports.
TlsHandshakeInfo
Per-handshake TLS telemetry snapshot (A118).
UdsConnectInfo
Connection info for Unix-domain server transports.

Enums§

Code
A grpc-status code.
Pushback
Server retry pushback from a grpc-retry-pushback-ms trailer (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 (flate2 fast).
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_age or 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§

ClientInterceptor
Inspect or change an outbound RPC before its stream opens.
Executor
Schedule background HTTP/2 connection drivers.
FusedFuture
futures_core::future::FusedFuture, so a finished Call is skipped by combinators that honour termination. A future which tracks whether or not the underlying future should no longer be polled.
FusedStream
futures_core::stream::FusedStream, so a finished Streaming is 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.
ResponseInterceptor
Inspect or change a successful response envelope.
Service
A gRPC service that can be served.
ServiceExt
Extra methods on every Service.
Stream
futures_core::Stream, so Streaming can be driven with StreamExt. 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§

ExecutorFuture
An owned HTTP/2 connection-driver task handed to an Executor.
IncomingAccept
One Incoming::accept result: a connection, an error, or None if exhausted.