Crate trillium_grpc 

A gRPC server and client for trillium, built as a thin layer on trillium-http’s HTTP/2, h2c (HTTP/2 over cleartext), and HTTP/3 support. If you have a .proto service definition and want to serve it — or call it — from a trillium application, this generates the glue and handles the wire format. It is a from-scratch, spec-conformant implementation of the gRPC over HTTP/2 protocol.

All four call shapes are supported — unary, server-streaming, client-streaming, and bidirectional-streaming — along with protobuf messages via prost (and optional JSON behind the json feature) and per-message compression (gzip by default, deflate and zstd behind features).

A worked example

You write a .proto:

syntax = "proto3";
package greeter.v1;

service Greeter {
  rpc SayHello(HelloRequest) returns (HelloReply);
}

message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

Codegen turns it into a Rust module: the prost message types, a Greeter trait you implement, a GreeterServer<T> handler that mounts into a trillium handler chain, and a GreeterClient for calling the service. Every service method receives a GrpcServerConn — the per-call control surface for request metadata, the deadline, and response metadata — and returns its result as a Result<_, Status>; the framework writes the terminating grpc-status from that result.

use trillium_grpc::{GrpcServerConn, Status};
use greeter::v1::{Greeter, GreeterServer, HelloReply, HelloRequest};

struct MyGreeter;

impl Greeter for MyGreeter {
    async fn say_hello(
        &self,
        _conn: &mut GrpcServerConn,
        request: HelloRequest,
    ) -> Result<HelloReply, Status> {
        Ok(HelloReply { message: format!("Hello, {}", request.name) })
    }
}

// GreeterServer<T> is an ordinary trillium Handler — mount it like any other.
trillium_tokio::run(GreeterServer::new(MyGreeter));

The generated GreeterClient wraps a trillium_client::Client. Its From constructor appends the service path to the client’s base URL; each method returns a typed call handle you drive like a trillium_client::Conn — configure it, then .await it:

use greeter::v1::{GreeterClient, HelloRequest};

let client = GreeterClient::from(
    trillium_client::Client::new(trillium_tokio::ClientConfig::default())
        .with_base("http://127.0.0.1:8080"),
);

let reply = client
    .say_hello(HelloRequest { name: "world".into() })
    .await?
    .into_message()?;
assert_eq!(reply.message, "Hello, world");

A complete, runnable version covering all four shapes is in examples/greeter.rs (cargo run --example greeter --features macros).

Guide

Module	Topic
generating	Turning a .proto into Rust — the CLI, the generate! macro, and build scripts
serving	Implementing a service: the four server-side shapes and GrpcServerConn
calling	Calling a service: the typed client handles and per-client configuration
advanced	Driving the library types directly for shape-dynamic and unusual work

Re-exports

pub use client::BidiConn;

pub use client::CancelHandle;

pub use client::GrpcClientConn;

pub use client::ServiceClient;

pub use client::ServiceClientExt;

pub use client::StreamingConn;

pub use client::UnaryConn;

pub use client::with_service_prefix;

pub use codec::Codec;

pub use codec::Prost;

pub use encoding::Encoding;

pub use metadata::Metadata;

pub use metadata::MetadataError;

pub use metadata::MetadataValue;

pub use server::BidiResponder;

pub use server::Channel;

pub use server::GrpcServerConn;

pub use server::RequestStream;

pub use server::Server;

pub use server::dispatch::prepare_grpc_conn;

pub use server::drive_bidi_upgrade;

pub use server::has_bidi_upgrade;

pub use status::Code;

pub use status::Status;

pub use trillium_grpc_codegen as codegen;codegen

pub use prost;

pub use trillium_client;

Modules

advanced

Driving the library types directly.

calling

Calling a service.

client

The client half of trillium-grpc.

codec

Message codecs: the Codec trait and the default Prost implementation.

encoding

Per-message compression negotiation and codecs.

frame

gRPC message framing.

generating

Turning a .proto into Rust.

metadata

Custom request, response, and trailing metadata.

server

The server half of trillium-grpc.

serving

Implementing a service.

status

RPC outcomes: the Status type and its Code, plus the grpc-status trailer (de)serialization that moves them on and off the wire.

timeout

grpc-timeout header codec.

Macros

generatemacros

Generate trillium-grpc service modules from one or more .proto files.

Traits

Stream

A stream of values produced asynchronously.