Crate grpc_webnext_client 

grpc-webnext-client

A gRPC client for Rust WASM frontends, speaking real gRPC to a grpc-webnext endpoint over an h2ts WebSocket tunnel.

No hyper, no tokio — and no tonic unless you ask for it. The wire is real HTTP/2 — trailers, multiplexing, flow control — so there is nothing to translate: framing plus a status read off the trailers is the whole client. Everything is single-threaded (Rc, !Send), which is what a browser actually is; nothing here asserts Send to satisfy a runtime that does not exist on this target.

The optional tonic feature runs tonic’s generated stubs over the same tunnel — see Generated stubs. It is off by default because it is not free (≈26 KB gzipped); with it off, this crate has no tonic in its tree at all.

use grpc_webnext_client::CallOptions;

let reply = client
    .unary("/helloworld.Greeter/SayHello", encoded_request(), CallOptions::new())
    .await?;
let _ = reply.message; // your codec decodes these bytes

Codec

The client deals in message bytes, so it is codec-agnostic: encode with prost, or anything else. The prost feature adds typed helpers over prost::Message, and a service is then a handful of thin wrappers over Client::unary and friends.

Generated stubs

For greeter.say_hello(request) instead of hand-written wrappers, the tonic feature lets tonic’s own generated stubs run over the tunnel — GreeterClient::new(client.into_tonic()), all four cardinalities, nothing grpc-webnext-specific in the codegen. See tonic_service, which also covers the one build-script setting a browser target needs.

Streaming

All four cardinalities. Backpressure on the response is real and costs nothing here: h2ts-client replenishes the HTTP/2 receive window only as the body is polled, so a consumer that stops reading stops the server rather than filling memory — the same property the TypeScript client gets, for the same reason.

Dropping a Streaming cancels the RPC: the HTTP/2 stream is reset, so the server stops work it has no reader for. That is also how a deadline stops a stream, and why CallOptions::timeout covers a stream’s whole lifetime rather than only its opening.

The streaming cardinalities need h2ts-client 0.1.2: at 0.1.1 Response::into_body took self while trailers() needed &self, so a caller could stream the body or read the trailers, never both — and gRPC’s terminal status lives in the trailers. A streaming client built on 0.1.1 could not tell a failed stream from a successfully empty one. Response::into_parts fixes that.

Reconnect

Client is a gRPC channel, not a handle to a socket: the tunnel opens on the first call and reopens if it drops, the way tonic::transport::Channel does. The call that discovers a dead tunnel reports the failure and the next one reconnects — the transport never silently replays a request the server may already have seen, because that is a retry policy decision and not its to make.

Client::state and Client::state_changes surface where the channel is (gRPC’s connectivity states, WaitForStateChange as a stream), so an app can say something useful instead of guessing from a failed call.

There is no reconnect backoff: like tonic, a redial happens when a call asks for one, so the call rate bounds the dial rate. A client built with Client::over_transport cannot redial at all — the transport is consumed — and says so rather than pretending to be live.

Re-exports

pub use tonic_service::ResponseBody;

pub use tonic_service::TonicService;

Modules

tonic_service

tonic interop: drive generated client stubs over the tunnel.

Structs

CallOptions

Per-call options.

Client

A grpc-webnext client: a gRPC channel, not a handle to a socket.

ConnectOptions

Settings we advertise + push handling (port of ConnectOptions).

Deframer

Reassembles messages from a byte stream that arrives in arbitrary chunks.

H2Connection

The HTTP/2 connection handle. Cheap to clone (shares one Rc state).

Metadata

Metadata for one call. Keys are lowercase, as HTTP/2 requires.

Status

A terminal gRPC status. Trailing metadata rides along, because a server that fails is often the one with the most to say about why.

Streaming

An in-flight response stream.

Transport

A bidirectional byte transport: a reader (inbound) and a writer (outbound).

TransportError

An error from the underlying transport (socket closed, send failed, …).

TypedResponse

A decoded response plus both metadata blocks.

UnaryResponse

A completed single-response call.

Enums

Code

The canonical gRPC status codes (https://grpc.io/docs/guides/status-codes/).

ConnectivityState

Where the tunnel is, using gRPC’s connectivity-state vocabulary.

MetadataValue

Constants

H2TS_SUBPROTOCOL

The WebSocket subprotocol an h2ts client offers.

Traits

TypedClient

Typed calls over a Client.

Functions

connect

Connect to a grpc-webnext endpoint.

encode_message

Frame one message for sending.

open_tunnel

Open an h2ts tunnel over a byte transport: the connection, plus the driver future the caller must poll for anything to happen.

Type Aliases

Connector

Opens a tunnel on demand. The client holds one so it can redial, which is what makes it a gRPC channel rather than a handle to a socket.