Documentation
¶
Overview ¶
Package grpcserver bootstraps a gRPC server with the SDK's cross-cutting concerns and exposes it as a worker.Runnable.
It applies the same chain of unary interceptors as the REST stack — panic recovery, trace-id injection (extracting inbound W3C trace context from gRPC metadata), structured access logging, Prometheus metrics, and errs->status mapping — then registers a health service and, optionally, server reflection. Because Server implements worker.Runnable (Name/Start/Stop), it is supervised alongside the HTTP server and background workers.
Interceptor order is recovery (outermost) -> trace -> logging -> metrics -> errormap -> application interceptors -> handler, so logging and metrics observe the already-mapped status code.
Usage ¶
srv := grpcserver.New(log, grpcserver.Config{
Addr: ":9090",
EnableReflection: true,
},
grpcserver.WithTracer(tracer),
grpcserver.WithMetrics(m.Registry),
)
widgetv1.RegisterWidgetServiceServer(srv.ServiceRegistrar(), handler)
group.Add(srv) // worker.Runnable: Start binds the listener, Stop drains
In tests, Serve runs the server on a caller-provided listener (e.g. a bufconn listener) instead of binding a TCP port.
Config ¶
- Addr: listen address, e.g. ":9090".
- ShutdownTimeout: bounds graceful drain before a hard stop (default 10s).
- EnableReflection: turns on server reflection (handy for grpcurl in dev).
- MetricsNamespace: prefixes the gRPC metric names (default "grpc").
- MaxRecvMsgSize / MaxSendMsgSize: override the 4 MiB defaults.
- NumStreamWorkers / SharedWriteBuffer: stream-serving tuning.
- Keepalive (KeepaliveConfig): server keepalive parameters and enforcement policy; zero values fall back to gRPC defaults.
Options ¶
- WithTracer(t): tracer used for trace-id injection (defaults to a no-op).
- WithMetrics(reg): registers gRPC request count/latency collectors on reg (typically the shared metrics.Metrics.Registry).
- WithUnaryInterceptors(in...): appends application interceptors, applied after the built-in ones (closest to the handler).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Addr is the listen address, e.g. ":9090".
Addr string
// ShutdownTimeout bounds graceful shutdown before a hard stop (default 10s).
ShutdownTimeout time.Duration
// EnableReflection turns on server reflection (handy for grpcurl in dev).
EnableReflection bool
// MetricsNamespace prefixes the gRPC metric names (default "grpc").
MetricsNamespace string
// MaxRecvMsgSize / MaxSendMsgSize override the 4 MiB defaults (bytes).
MaxRecvMsgSize int
MaxSendMsgSize int
// NumStreamWorkers bounds the pool of goroutines serving streams; 0 spawns
// one goroutine per stream (the gRPC default).
NumStreamWorkers uint32
// allocations under load.
SharedWriteBuffer bool
// Keepalive tunes connection liveness; zero values fall back to gRPC defaults.
Keepalive KeepaliveConfig
}
Config configures the gRPC server.
type KeepaliveConfig ¶
type KeepaliveConfig struct {
MaxConnectionIdle time.Duration
MaxConnectionAge time.Duration
Time time.Duration
Timeout time.Duration
MinTime time.Duration
PermitWithoutStream bool
}
KeepaliveConfig mirrors the gRPC keepalive server parameters and enforcement policy. Zero values are left at gRPC defaults.
type Option ¶
type Option func(*options)
Option customizes the server.
func WithMetrics ¶
func WithMetrics(reg prometheus.Registerer) Option
WithMetrics registers gRPC collectors on reg (e.g. metrics.Metrics.Registry).
func WithTracer ¶
WithTracer sets the tracer used for trace-id injection. Defaults to a no-op.
func WithUnaryInterceptors ¶
func WithUnaryInterceptors(in ...grpc.UnaryServerInterceptor) Option
WithUnaryInterceptors appends application interceptors, applied after the built-in ones (closest to the handler).
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps a *grpc.Server and implements worker.Runnable.
func (*Server) Serve ¶
Serve serves on the provided listener until Stop. It is useful for tests (e.g. a bufconn listener) and for callers that manage their own listener.
func (*Server) ServiceRegistrar ¶
func (s *Server) ServiceRegistrar() grpc.ServiceRegistrar
ServiceRegistrar returns the registrar used to register gRPC services, e.g. widgetv1.RegisterWidgetServiceServer(s.ServiceRegistrar(), handler).
Source Files