grpcgateway

Documentation

Overview

Package grpcgateway builds a grpc-gateway as a plain http.Handler, so the JSON/HTTP transport runs as just another brick of the server kit — wrapped by httpserver and supervised in the same worker.Group as the gRPC and REST servers.

The gateway translates RESTful JSON requests into gRPC calls against a backing gRPC server, using the handlers generated by protoc-gen-grpc-gateway from your google.api.http annotations. New dials that gRPC server (or reuses a connection you supply), creates a runtime.ServeMux, applies the generated registrars, and returns a *Gateway that embeds http.Handler.

Usage

gw, err := grpcgateway.New(ctx, grpcgateway.Config{
	Endpoint: opts.GRPC.Addr, // the gRPC server this proxies to
}, widgetv1.RegisterWidgetServiceHandler)
if err != nil {
	return err
}
closer.Add(gw.Close) // release the dialed conn on shutdown

group.Add(httpserver.New(httpserver.Config{
	Name: "gateway-server", Addr: opts.Gateway.Addr, Logger: log.Slog(),
}, gw))

Because gw is an http.Handler, cross-cutting behavior (tracing, request metrics, auth) is added the stdlib way — by wrapping it with middleware (the middleware package, otelhttp, ...) before handing it to httpserver.

Connection ownership

When Config.ClientConn is nil, New dials Config.Endpoint and the Gateway owns that connection — call Close to release it. When you pass Config.ClientConn, New uses it as-is and Close is a no-op: the connection's lifecycle stays with you (e.g. managed by your DI container / closer).

Config

• Endpoint: gRPC target to proxy to; required unless ClientConn is set.
• ClientConn: reuse an existing *grpc.ClientConn instead of dialing.
• DialOptions: override the default insecure dial options.
• MuxOptions: forwarded to runtime.NewServeMux (marshaler, error handler, header matchers, ...).

Index

• type Config
• type Gateway
  • func New(ctx context.Context, cfg Config, register ...HandlerRegistrar) (*Gateway, error)
  • func (g *Gateway) Close() error
• type HandlerRegistrar

Types

type Config

type Config struct {
	// Endpoint is the gRPC server target to proxy to (e.g. "localhost:9090" or
	// "dns:///grpc:9090"). Required unless ClientConn is supplied.
	Endpoint string
	// ClientConn, when set, is used as-is and Endpoint/DialOptions are ignored;
	// the caller owns its lifecycle (close it via your closer/DI). When nil, New
	// dials Endpoint and the returned Gateway owns and closes that connection.
	ClientConn *grpc.ClientConn
	// DialOptions override the options used to dial Endpoint. The default is a
	// single insecure transport credential — the gateway and the gRPC server are
	// expected to be co-located behind the same trust boundary.
	DialOptions []grpc.DialOption
	// MuxOptions are forwarded to runtime.NewServeMux (custom marshaler, error
	// handler, header matchers, ...).
	MuxOptions []runtime.ServeMuxOption
}

Config configures the gateway.

type Gateway

type Gateway struct {
	http.Handler
	// contains filtered or unexported fields
}

Gateway is the assembled gRPC-gateway: an http.Handler (the runtime.ServeMux) plus the gRPC client connection it proxies through. Because it embeds http.Handler, run it via httpserver.New(cfg, gw) like any other handler; call Close on shutdown to release a dialed connection.

func New

func New(ctx context.Context, cfg Config, register ...HandlerRegistrar) (*Gateway, error)

New dials the gRPC endpoint (or uses cfg.ClientConn), builds a runtime ServeMux, applies every registrar in order, and returns the resulting Gateway. If a registrar fails, a connection dialed by New is closed before returning the error.

func (*Gateway) Close

func (g *Gateway) Close() error

Close releases the gRPC client connection when New dialed it; it is a no-op when the caller supplied cfg.ClientConn (that connection's lifecycle stays with the caller).

type HandlerRegistrar

type HandlerRegistrar func(ctx context.Context, mux *runtime.ServeMux, conn *grpc.ClientConn) error

HandlerRegistrar registers a generated gRPC-gateway handler onto mux, backed by conn. It matches the signature protoc-gen-grpc-gateway emits, e.g.

widgetv1.RegisterWidgetServiceHandler(ctx, mux, conn)

so the application passes the generated functions directly:

gw, err := grpcgateway.New(ctx, cfg, widgetv1.RegisterWidgetServiceHandler)