Documentation
¶
Overview ¶
Package grpcserver builds the gRPC transport every service in this repo runs on: the interceptor chain, server reflection, the standard gRPC health service, and the Serve/Shutdown lifecycle pkg/boot.Service expects. A service package supplies only what makes it *that* service — its proto registrations and its own health Check — and gets the rest for free instead of rebuilding grpc.NewServer(...) by hand.
Index ¶
Constants ¶
const ( // CheckTimeout bounds a single Check call a caller makes to whatever it // depends on; a Check that runs several dependencies concurrently is // bounded by it as a whole. Combined with the poll interval, the worst // case from a real failure to a pushed NOT_SERVING is well under a // typical Kubernetes readiness probe period. CheckTimeout = 3 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Check ¶
type Check func(ctx context.Context) (grpc_health_v1.HealthCheckResponse_ServingStatus, error)
Check reports the serving status to publish, and the error behind a failure so it can be logged. The two are separate because NOT_SERVING isn't always an error — data-access isn't serving until its JWKS has loaded, which is not itself a failure.
type Config ¶
type Config struct {
// Name is returned by Name(), for logs and the service manager.
Name string
// Component tags every log line this server emits.
Component string
Address string
ReflectionEnabled bool
// Metrics, when non-nil, records standard gRPC server metrics
// (request counts, handling time) for every RPC into it. Nil is only
// for tests building a Config directly without going through
// pkg/boot.Boot, which always supplies one.
Metrics *metrics.Metrics
Registration
}
Config is what pkg/boot.Boot builds from a Registration plus what only the platform layer decides: name, listen address, reflection, and the shared metrics registry. Metrics lives here, not on Registration, because every gRPC server records request metrics unconditionally — there's no per-service decision to express.
type Handlers ¶ added in v1.78.0
type Handlers struct {
// Register adds the service's own proto servers to the server. Required.
Register func(*grpc.Server)
PublicMethods map[string]bool
// UserAuthInterceptor runs between the service-token and validation
// interceptors. Leave nil for a service with no per-user auth layer
// (e.g. auth, which only ever talks to service-to-service callers).
UserAuthInterceptor grpc.UnaryServerInterceptor
// HealthCheck, when set, registers the standard gRPC health service and
// polls it on Transport.HealthPollInterval, draining watching clients
// for Transport.HealthDrainDelay on Shutdown before GracefulStop. Nil
// skips health wiring entirely.
HealthCheck Check
// Closers are closed, in order, once GracefulStop returns.
Closers []io.Closer
}
Handlers is what a service contributes to a server: its proto servers, which of their methods need no service token, its per-user auth layer and its own health Check.
type Registration ¶
Registration is what New hosts: one Transport and the Handlers behind it. A service running alone provides both; Merge builds one from a Transport the caller decides and the Handlers of every service it hosts.
func Merge ¶ added in v1.78.0
func Merge(t Transport, first Handlers, rest ...Handlers) Registration
Merge hosts the Handlers of several services behind one Transport. Each UserAuthInterceptor runs only on the services its Handlers register. Public methods and closers are concatenated. Merge panics when more than one Handlers sets HealthCheck.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server implements pkg/boot.Service by structural typing; this package never imports pkg/boot, so a Config's Register callback stays the only place a service's own types show up.
type Transport ¶ added in v1.78.0
type Transport struct {
ServiceAuth serviceauth.Config
// ServiceTokenHeaders are the metadata keys a caller may present the
// service token under. A service running alone has one; a merged server
// lists every hosted service's, so existing callers keep their own.
ServiceTokenHeaders []string
// ExtraServerOptions is appended after the interceptor chain, e.g.
// grpc.StatsHandler for tracing.
ExtraServerOptions []grpc.ServerOption
// HealthPollInterval (default 1s) and HealthDrainDelay (default 2s)
// apply when Handlers.HealthCheck is set; see there.
HealthPollInterval time.Duration
HealthDrainDelay time.Duration
}
Transport is what the one server decides, whoever it hosts: how callers prove they are a service, options on the grpc.Server itself, and health timing. A single service sets it from its own config; serve all sets it once for every service it hosts.
Source Files