Module grpc_web 

gRPC-Web framing translation and JSON-to-gRPC transcoding (DW-101).

gRPC-Web framing

gRPC-Web is the browser-friendly variant of gRPC: it replaces HTTP/2 trailers with a trailing frame that carries the gRPC status as pseudo-headers, and it frames every chunk with a 5-byte prefix (1 byte flag + 4 bytes big-endian length). The flag byte distinguishes data frames (0x00) from trailer frames (0x80). A unary response is one data frame followed by one trailer frame; a streaming response is an arbitrary number of data frames (each its own 5-byte-prefixed chunk) followed by a single trailer frame.

The gateway sits between a browser (gRPC-Web) and a native gRPC upstream (HTTP/2 + trailers). On the forward path it strips the gRPC-Web framing and reconstructs the native gRPC request body; on the response path it wraps the native gRPC frames (data + trailers) back into gRPC-Web framing so the browser can decode them.

JSON-to-gRPC transcoding

When transcoding is enabled, the gateway also accepts plain JSON requests (Content-Type: application/json) and translates them to protobuf wire bytes for the upstream, and translates the protobuf response back to JSON. The mapping is driven by .proto descriptors supplied via config (FileDescriptorSet files): at config publish the gateway loads the descriptors, builds a method map keyed by the fully-qualified gRPC method name (/{package}.{service}/{method}), and resolves each method’s request and response message types. The google.api.http annotation on each RPC maps an HTTP path + verb to the gRPC method, so a REST or JSON client can call a gRPC backend without a gRPC library.

gRPC status mapping

A gRPC status (carried in the grpc-status trailer) is mapped to an HTTP status code and a google.rpc.Status JSON body for non-gRPC clients. The mapping follows the gRPC HTTP/JSON specification (the google.rpc.Code -> HTTP status table).

Status

The module compiles into every build (no cargo feature). The config schema (GrpcWeb, GrpcWebTranscoding, GrpcWebDescriptor) parses and validates; the runtime framing/transcoding translation is scaffolded and not yet dispatched from the request path.

Modules

field_label

Field label constants (the FieldDescriptorProto.Label enum).

field_type

Field type constants (the FieldDescriptorProto.Type enum).

grpc_code

gRPC status codes (the google.rpc.Code enum values).

Structs

DescriptorProto

google.protobuf.DescriptorProto — a message type.

EnumDescriptorProto

google.protobuf.EnumDescriptorProto — an enum type.

EnumValueDescriptorProto

google.protobuf.EnumValueDescriptorProto — one enum value.

FieldDescriptorProto

google.protobuf.FieldDescriptorProto — one field in a message.

FileDescriptorProto

google.protobuf.FileDescriptorProto — one .proto file.

FileDescriptorSet

google.protobuf.FileDescriptorSet — the top-level container produced by protoc --descriptor_set_out.

GrpcTranscoder

The gRPC-Web + JSON transcoding engine. Loaded at config publish from .proto descriptor files; holds a method map keyed by the fully- qualified gRPC method path.

LoadedDescriptor

A loaded .proto descriptor entry: the raw FileDescriptorSet bytes plus the package and service names that identify the methods this descriptor covers.

MethodDescriptorProto

google.protobuf.MethodDescriptorProto — one RPC method.

MethodInfo

A resolved gRPC method: its fully-qualified path and the request/ response message type names.

ServiceDescriptorProto

google.protobuf.ServiceDescriptorProto — an RPC service.

Enums

GrpcWebError

Errors from gRPC-Web framing translation or JSON-to-gRPC transcoding.

Functions

build_trailers

Build a trailer byte payload from a map of key-value pairs, in the key: value\n format gRPC-Web expects.

grpc_status_name

The gRPC status name for a code (for logging / trailer display).

grpc_status_to_http

Map a gRPC status code to an HTTP status code and a google.rpc.Status JSON body. The JSON body follows the google.rpc.Status shape: { "code": <int>, "message": "<string>", "details": [] }.

parse_trailers

Parse the gRPC-Web trailer frame payload (key: value lines) into a map. Returns an empty map for an empty payload.

translate_grpc_to_grpc_web

Wrap native gRPC response bytes in gRPC-Web framing.

translate_grpc_to_grpc_web_data_chunk

Wrap a single gRPC data chunk in a gRPC-Web data frame (no trailer frame). Used for streaming responses where each upstream data frame becomes its own gRPC-Web data frame, and the trailer frame is sent once at stream end via translate_grpc_trailers_to_grpc_web.

translate_grpc_trailers_to_grpc_web

Wrap gRPC trailers in a gRPC-Web trailer frame. Sent as the final frame of a streaming gRPC-Web response.

translate_grpc_web_to_grpc

Strip gRPC-Web framing and reconstruct the native gRPC request body.