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 (rest/mid, 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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.
type HandlerRegistrar ¶
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)
Source Files