Documentation
¶
Overview ¶
Package gateway makes a grpc-gateway a first-class transport for generated REST handlers. Core construction accepts an already prepared gRPC client connection and typed HTTP server settings; GTB config integration lives in adapter helpers such as SettingsFromConfig, ObserveSettingsFromConfig, NewFromContainable, and RegisterFromContainable.
Index ¶
- Constants
- func New(ctx context.Context, conn *grpc.ClientConn, register RegisterFunc, ...) (http.Handler, error)
- func NewFromConfig(ctx context.Context, cfg config.Containable, register RegisterFunc, ...) (http.Handler, error)
- func NewFromContainable(ctx context.Context, cfg config.Containable, register RegisterFunc, ...) (http.Handler, error)
- func ObserveSettingsFromConfig(cfg config.Containable, opts ...config.SectionBindingOption[Settings]) (*config.ObservedSection[Settings], error)
- func Register(ctx context.Context, id string, controller controls.Controllable, ...) (*http.Server, error)
- func RegisterFromConfig(ctx context.Context, id string, controller controls.Controllable, ...) (*http.Server, error)
- func RegisterFromContainable(ctx context.Context, id string, controller controls.Controllable, ...) (*http.Server, error)
- type Option
- type RegisterFunc
- type Settings
- type SettingsSource
Constants ¶
const ConfigPrefix = "server.gateway"
ConfigPrefix is the config block a gateway server reads (port, TLS) when run as its own service via Register. TLS falls back to the shared "server.tls".
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(ctx context.Context, conn *grpc.ClientConn, register RegisterFunc, opts ...Option) (http.Handler, error)
New builds a grpc-gateway handler from an already prepared gRPC client connection.
func NewFromConfig ¶ added in v0.30.0
func NewFromConfig(ctx context.Context, cfg config.Containable, register RegisterFunc, opts ...Option) (http.Handler, error)
NewFromConfig builds a grpc-gateway handler with GTB config resolved into typed transport settings before delegating to the config-free constructor.
func NewFromContainable ¶ added in v0.30.0
func NewFromContainable(ctx context.Context, cfg config.Containable, register RegisterFunc, opts ...Option) (http.Handler, error)
New builds a grpc-gateway handler ready to mount on an existing HTTP server. It dials the local gRPC server via grpc.DialLocal (so transport security matches the server's own config) and applies register to wire the handlers.
The returned handler is a *runtime.ServeMux (or, with WithMiddleware, that mux wrapped by the chain). The underlying gRPC connection lives for the process; it is the standard pattern for an in-process gateway.
func ObserveSettingsFromConfig ¶ added in v0.30.0
func ObserveSettingsFromConfig( cfg config.Containable, opts ...config.SectionBindingOption[Settings], ) (*config.ObservedSection[Settings], error)
ObserveSettingsFromConfig binds gateway transport settings to cfg and keeps a typed snapshot rehydrated after successful config reloads.
func Register ¶
func Register( ctx context.Context, id string, controller controls.Controllable, logger *slog.Logger, conn *grpc.ClientConn, httpSettings gtbhttp.ServerSettings, httpTLS gtbtls.Pair, register RegisterFunc, opts ...Option, ) (*http.Server, error)
Register runs the gateway as its own controller-managed HTTP server from explicit typed HTTP settings and a prepared gRPC client connection.
func RegisterFromConfig ¶ added in v0.30.0
func RegisterFromConfig(ctx context.Context, id string, controller controls.Controllable, cfg config.Containable, log logger.Logger, register RegisterFunc, opts ...Option) (*http.Server, error)
RegisterFromConfig runs the gateway with GTB config resolved into typed transport settings before delegating to the config-free constructor.
func RegisterFromContainable ¶ added in v0.30.0
func RegisterFromContainable(ctx context.Context, id string, controller controls.Controllable, cfg config.Containable, log logger.Logger, register RegisterFunc, opts ...Option) (*http.Server, error)
Register runs the gateway as its own controller-managed HTTP server on the "server.gateway" config block (TLS falling back to the shared "server.tls"), dialing the local gRPC server. It is the first-class form of New, a peer of grpc.Register and http.Register. Pass WithMiddleware to wrap the REST surface with a middleware chain (health endpoints stay outside it).
Types ¶
type Option ¶
type Option func(*options)
Option configures the gateway.
func WithDialOptions ¶
func WithDialOptions(opts ...grpc.DialOption) Option
WithDialOptions passes extra grpc.DialOption values to the connection the gateway opens to the gRPC server (transport security is set automatically).
func WithMiddleware ¶ added in v0.23.0
WithMiddleware wraps the gateway's REST surface with an HTTP middleware chain (logging, security headers, rate limiting, auth, …). The gateway handler is an ordinary http.Handler, so the standard pkg/http Chain applies to it.
On the New path the chain wraps the returned handler directly. On the Register path it is threaded to the managed server so health endpoints (/healthz, /livez, /readyz) remain outside the chain, exactly as with http.Register.
func WithMuxOptions ¶
func WithMuxOptions(opts ...runtime.ServeMuxOption) Option
WithMuxOptions passes runtime.ServeMuxOption values to the gateway mux (e.g. a custom error handler or header matcher).
type RegisterFunc ¶
RegisterFunc registers the generated gateway handlers onto the mux, using a client connection to the gRPC server. It is the only gateway-specific code a caller writes, e.g.:
func(ctx context.Context, mux *runtime.ServeMux, conn *grpc.ClientConn) error {
return widgetv1.RegisterWidgetServiceHandler(ctx, mux, conn)
}
type Settings ¶ added in v0.30.0
type Settings struct {
HTTP gtbhttp.ServerSettings `yaml:"http" json:"http"`
HTTPTLS gtbtls.Pair `yaml:"http_tls" json:"http_tls"`
GRPC gtbgrpc.ServerSettings `yaml:"grpc" json:"grpc"`
GRPCTLS gtbtls.Pair `yaml:"grpc_tls" json:"grpc_tls"`
}
Settings contains the typed transport settings needed to construct a gateway without binding the core gateway path to any particular config system.
A gateway is composed from settings that live at different GTB config prefixes (the gateway's own HTTP listener plus the upstream gRPC server), so this struct is assembled by the config adapter (SettingsFromConfig), not decoded from a single section with mapstructure. The json/yaml tags are for documentation and snapshot serialisation only.
func SettingsFromConfig ¶ added in v0.30.0
func SettingsFromConfig(cfg config.Containable) Settings
SettingsFromConfig resolves gateway transport settings from GTB config. The managed HTTP server reads server.gateway.* while the in-process gRPC dial uses server.grpc.* so it connects to the same local gRPC service as the rest of GTB.
type SettingsSource ¶ added in v0.30.0
SettingsSource exposes the latest gateway settings snapshot to packages that need reload-aware access without depending on GTB config.
Source Files