grpcweb

README

gRPC-Web Bridge for Caddy

This module implements a bridge from gRPC-Web clients to gRPC servers. It is similar to Envoy's envoy.filters.http.grpc_web filter. It is EXPERIMENTAL and subject to change.

[!NOTE] This is not an official repository of the Caddy Web Server organization.

To convert gRPC-Web requests to gRPC, simply add the grpc_web handler to your HTTP route. It should go before your reverse_proxy or any other handler that would expect a gRPC request.

Installation

A new Caddy server with this module needs to be built to support GRPC-web calls. Build it with:

docker build -t <account_name>/caddy-grpc .

Example

Caddyfile:

{
	order grpc_web before reverse_proxy
}

:5452 {
	grpc_web
	reverse_proxy h2c://127.0.0.1:50051
}

JSON:

{
	"apps": {
		"http": {
			"servers": {
				"srv0": {
					"listen": [
						":5452"
					],
					"routes": [
						{
							"handle": [
								{
									"handler": "grpc_web"
								},
								{
									"handler": "reverse_proxy",
									"transport": {
										"protocol": "http",
										"versions": [
											"h2c",
											"2"
										]
									},
									"upstreams": [
										{
											"dial": "127.0.0.1:50051"
										}
									]
								}
							]
						}
					]
				}
			}
		}
	}
}

You can also specify the websocket_ping parameter to an interval value >= 1s for websocket keep-alive pings to be enabled.

Documentation

Index

• type Handler
  • func (Handler) CaddyModule() caddy.ModuleInfo
  • func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Types

type Handler

type Handler struct {
	// Enable WebSocket keep-alive pinging. Default: 0 (no pinging).
	// Minimum to enable: 1s.
	WebSocketPing caddy.Duration `json:"websocket_ping,omitempty"`
}

Handler is an HTTP handler that bridges gRPC-Web <--> gRPC requests. This module is EXPERIMENTAL and subject to change.

func (Handler) CaddyModule

func (Handler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (Handler) ServeHTTP

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*Handler) UnmarshalCaddyfile

func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up h from Caddyfile tokens. Syntax:

grpc_web {
    websocket_ping <interval>
}