Skip to main content

​
Overview

The xmtp_api_grpc crate provides a gRPC implementation of the XmtpApi trait. It supports both native (HTTP/2) and WebAssembly (gRPC-Web) environments through platform-specific service types.

​
Source Location

crates/xmtp_api_grpc/

​
GrpcClient

The main gRPC client implementation that works across native and WASM environments. 
pub struct GrpcClient {
    inner: tonic::client::Grpc<GrpcService>,
    app_version: MetadataValue<metadata::Ascii>,
    libxmtp_version: MetadataValue<metadata::Ascii>,
}

​
Platform-Specific Services

Native (HTTP/2) 
pub type GrpcService = native::NativeGrpcService;
WebAssembly (gRPC-Web) 
pub type GrpcService = wasm::GrpcWebService;

​
Construction

Basic Creation 
pub fn create(host: &str, is_secure: bool) -> Result<Self, GrpcBuilderError>
Creates a gRPC client with the specified host and TLS setting. With App Version 
pub fn create_with_version(
    host: &str,
    is_secure: bool,
    app_version: AppVersion,
) -> Result<Self, GrpcBuilderError>
Creates a gRPC client with application version metadata attached to all requests. Builder Pattern 
pub fn builder() -> ClientBuilder
Returns a ClientBuilder for more flexible configuration.

​
ClientBuilder

A fluent builder for constructing GrpcClient instances with custom configuration. 
pub struct ClientBuilder {
    pub host: Option<String>,
    pub app_version: Option<MetadataValue<metadata::Ascii>>,
    pub libxmtp_version: Option<MetadataValue<metadata::Ascii>>,
    pub tls_channel: bool,
    pub limit: Option<u64>,
    pub retry: Option<Retry>,
}

​
Configuration Methods

Network Configuration
  • set_host(host: String) - Set the gRPC server host URL
  • set_tls(tls: bool) - Enable/disable TLS
  • rate_per_minute(limit: u32) - Set rate limiting
  • port() -> Result<Option<String>, GrpcBuilderError> - Get port from configured host
Version Configuration
  • set_app_version(version: AppVersion) -> Result<(), GrpcBuilderError> - Set application version
  • set_libxmtp_version(version: String) -> Result<(), GrpcBuilderError> - Set libxmtp version
Retry Configuration
  • set_retry(retry: Retry) - Configure retry strategy
Build
  • build() -> Result<GrpcClient, GrpcBuilderError> - Construct the client

​
Example

let client = GrpcClient::builder()
    .set_host("https://grpc.example.com".to_string())
    .set_tls(true)
    .set_app_version(AppVersion::from("myapp/1.0.0"))
    .build()?;

​
Client Implementation

The GrpcClient implements the Client trait from xmtp_proto::api_client, providing:

​
Request Method

async fn request(
    &self,
    request: http::request::Builder,
    path: http::uri::PathAndQuery,
    body: Bytes,
) -> Result<http::Response<Bytes>, ApiClientError<GrpcError>>
Sends a unary gRPC request and returns the response.

​
Stream Method

async fn stream(
    &self,
    request: request::Builder,
    path: PathAndQuery,
    body: Bytes,
) -> Result<http::Response<GrpcStream>, ApiClientError<GrpcError>>
Initiates a server-streaming gRPC request and returns a stream of responses.

​
Fake Stream Method

fn fake_stream(&self) -> http::Response<GrpcStream>
Creates an empty stream for testing purposes.

​
GrpcStream

A stream of bytes from a gRPC network source. 
pub struct GrpcStream {
    inner: crate::streams::NonBlocking,
}
Implements Stream<Item = Result<Bytes, GrpcError>> for asynchronous message streaming.

​
Connection Health Check

impl IsConnectedCheck for GrpcClient {
    async fn is_connected(&self) -> bool
}
Checks if the gRPC connection is ready to accept requests.

​
Error Types

​
GrpcBuilderError

Errors that can occur during client construction: 
pub enum GrpcBuilderError {
    MissingAppVersion,
    MissingLibxmtpVersion,
    MissingHostUrl,
    MissingXmtpdGatewayUrl,
    Metadata(tonic::metadata::errors::InvalidMetadataValue),
    InvalidUri(http::uri::InvalidUri),
    Url(url::ParseError),
    Transport(tonic::transport::Error), // Native only
}

​
GrpcError

Errors that can occur during gRPC operations: 
pub enum GrpcError {
    InvalidUri(http::uri::InvalidUri),
    Metadata(tonic::metadata::errors::InvalidMetadataValue),
    Status(tonic::Status),
    NotFound(String),
    UnexpectedPayload,
    MissingPayload,
    Proto(xmtp_proto::ProtoError),
    Decode(prost::DecodeError),
    Unreachable,
    Transport(tonic::transport::Error), // Native only
}
Implements RetryableError - all gRPC errors are considered retryable by default.

​
Request Metadata

All requests automatically include these metadata headers:
  • x-app-version - Application version from builder configuration
  • x-libxmtp-version - LibXMTP version (defaults to crate version)

​
Message Size Limits

The client enforces payload size limits defined in xmtp_configuration::GRPC_PAYLOAD_LIMIT for both encoding and decoding.

​
Streaming Support

The crate includes several stream utilities in the streams module:
  • EscapableTonicStream - Stream wrapper for handling tonic responses
  • FakeEmptyStream - Empty stream for testing
  • NonBlockingWebStream - Non-blocking stream adapter for WASM
  • MultiplexedStream - Multiplexed stream handling

​
Platform Compatibility

Native (not WASM)
  • Uses HTTP/2 transport
  • Full tonic transport features
  • TCP connection pooling
WebAssembly
  • Uses gRPC-Web protocol
  • HTTP/1.1 compatibility
  • Browser fetch API integration
  • xmtp_api - Core trait definitions
  • xmtp_proto - Protocol buffer definitions
  • tonic - gRPC framework
  • xmtp_configuration - Configuration constants

Build docs developers (and LLMs) love

Get started for freeTalk to us