Documentation
¶
Overview ¶
Package grpc provides a gRPC transport for the controls lifecycle controller, enabling remote service management and health checking over gRPC.
Index ¶
- Constants
- func DialLocal(cfg config.Containable, opts ...grpc.DialOption) (*grpc.ClientConn, error)
- func NewServer(cfg config.Containable, opt ...grpc.ServerOption) (*grpc.Server, error)
- func OTelClientHandler(opts ...otelgrpc.Option) grpc.DialOption
- func OTelStatsHandler(opts ...otelgrpc.Option) grpc.ServerOption
- func Register(ctx context.Context, id string, controller controls.Controllable, ...) (*grpc.Server, error)
- func RegisterHealthService(srv *grpc.Server, controller healthSource)
- func Start(cfg config.Containable, logger logger.Logger, srv *grpc.Server) controls.StartFunc
- func Status(srv *grpc.Server) controls.StatusFunc
- func Stop(logger logger.Logger, srv *grpc.Server) controls.StopFunc
- func TLSClientCredentials(caFiles ...string) (credentials.TransportCredentials, error)
- func TLSServerCredentials(certFile, keyFile string) (credentials.TransportCredentials, error)
- type GRPCLoggingOption
- type Interceptor
- type InterceptorChain
- type RegisterOption
Constants ¶
const ( // ConfigKeyPort is the gRPC server listen port. ConfigKeyPort = "server.grpc.port" // ConfigKeyReflection toggles gRPC server reflection. ConfigKeyReflection = "server.grpc.reflection" // is unset. ConfigKeySharedPort = "server.port" // ConfigTLSPrefix is the gRPC TLS config prefix (resolved against the // shared tls.SharedPrefix). ConfigTLSPrefix = "server.grpc.tls" )
Config keys read by the gRPC server. Use these instead of bare strings when setting or reading server config programmatically.
const DefaultMaxGRPCMessageBytes = 1 << 20 // 1 MiB
DefaultMaxGRPCMessageBytes caps both send and receive message sizes on servers constructed via NewServer. Closes M-2 from docs/development/reports/security-audit-2026-04-17.md. Set to 1 MiB — tools with extraordinary message sizes can override via the explicit grpc.MaxRecvMsgSize / grpc.MaxSendMsgSize options passed to NewServer.
Variables ¶
This section is empty.
Functions ¶
func DialLocal ¶ added in v0.6.0
func DialLocal(cfg config.Containable, opts ...grpc.DialOption) (*grpc.ClientConn, error)
DialLocal dials the gRPC server described by cfg over the loopback interface, using transport security that matches the server's own TLS config (server.grpc.tls -> server.tls). Intended for in-process callers such as the grpc-gateway, so they connect to the local server without re-deriving the endpoint or credentials by hand.
func NewServer ¶
func NewServer(cfg config.Containable, opt ...grpc.ServerOption) (*grpc.Server, error)
NewServer returns a new preconfigured grpc.Server.
Default gRPC options applied (before caller-supplied opts):
- grpc.MaxRecvMsgSize(DefaultMaxGRPCMessageBytes)
- grpc.MaxSendMsgSize(DefaultMaxGRPCMessageBytes)
Caller-supplied grpc.ServerOption values in opt override the defaults (gRPC applies later options last, so a caller can raise or lower the limits explicitly).
func OTelClientHandler ¶ added in v0.7.1
func OTelClientHandler(opts ...otelgrpc.Option) grpc.DialOption
OTelClientHandler returns a grpc.DialOption that instruments a client connection with OpenTelemetry: a client span per RPC, and — using the global propagator — the trace context injected into the outgoing metadata, so a downstream gRPC server continues the same trace rather than starting a new one. It reads the globally-installed providers (see telemetry.Setup) and is a noop until those are installed. The gateway applies it by default, so a REST request and the gRPC call it proxies land in one trace.
func OTelStatsHandler ¶ added in v0.7.0
func OTelStatsHandler(opts ...otelgrpc.Option) grpc.ServerOption
OTelStatsHandler returns a grpc.ServerOption that installs OpenTelemetry instrumentation for every RPC — server spans and the standard server metrics (rpc.server.*) — reading whichever TracerProvider and MeterProvider are installed as the OTel globals (see telemetry.Setup). It is a stats handler rather than an interceptor because that is the instrumentation the OTel gRPC contrib library ships and the shape the semantic conventions are defined against.
Pass it to Register alongside any other server options:
grpc.Register(ctx, "grpc", controller, cfg, log, grpc.OTelStatsHandler())
func Register ¶
func Register(ctx context.Context, id string, controller controls.Controllable, cfg config.Containable, logger logger.Logger, opts ...any) (*grpc.Server, error)
Register creates a new gRPC server and registers it with the controller under the given id. The opts variadic accepts both grpc.ServerOption and RegisterOption values.
func RegisterHealthService ¶
RegisterHealthService registers the standard gRPC health service with the provided server, wired to the controller's status.
func Start ¶
Start returns a curried function suitable for use with the controls package. TLS configuration cascades: server.grpc.tls.* overrides server.tls.* shared defaults.
func Status ¶
func Status(srv *grpc.Server) controls.StatusFunc
Status returns a curried function suitable for use with the controls package.
func Stop ¶
Stop returns a curried function suitable for use with the controls package. GracefulStop is attempted first to allow in-flight RPCs to finish. If the shutdown context expires (or if Serve has not been called yet, which would cause GracefulStop to block indefinitely), the server is force-stopped.
func TLSClientCredentials ¶ added in v0.6.0
func TLSClientCredentials(caFiles ...string) (credentials.TransportCredentials, error)
TLSClientCredentials returns gRPC client transport credentials that trust the given CA/cert files. It is the client-side mirror of TLSServerCredentials — e.g. for the grpc-gateway dialing a gRPC server that presents a self-signed or private-CA certificate. With no files it trusts the system roots.
func TLSServerCredentials ¶
func TLSServerCredentials(certFile, keyFile string) (credentials.TransportCredentials, error)
TLSServerCredentials returns gRPC server credentials using the shared hardened TLS config. Use this when you need to pass credentials directly to grpc.NewServer via grpc.Creds() instead of using the Start function. (credentials.NewTLS advertises h2 itself, so no explicit ALPN is needed.)
Types ¶
type GRPCLoggingOption ¶
type GRPCLoggingOption func(*grpcLoggingConfig)
GRPCLoggingOption configures gRPC transport logging behaviour.
func WithGRPCLogLevel ¶
func WithGRPCLogLevel(level logger.Level) GRPCLoggingOption
WithGRPCLogLevel sets the log level for successful RPCs. Errors always log at logger.ErrorLevel.
func WithGRPCPathFilter ¶
func WithGRPCPathFilter(methods ...string) GRPCLoggingOption
WithGRPCPathFilter excludes RPCs matching the given full method names from logging.
func WithoutGRPCLatency ¶
func WithoutGRPCLatency() GRPCLoggingOption
WithoutGRPCLatency disables the "latency" field.
type Interceptor ¶
type Interceptor struct {
Unary grpc.UnaryServerInterceptor
Stream grpc.StreamServerInterceptor
}
Interceptor groups a paired unary and stream interceptor. Either field may be nil if the interceptor only applies to one RPC type.
func LoggingInterceptor ¶
func LoggingInterceptor(l logger.Logger, opts ...GRPCLoggingOption) Interceptor
LoggingInterceptor returns an Interceptor (unary + stream) that logs each completed RPC.
type InterceptorChain ¶
type InterceptorChain struct {
// contains filtered or unexported fields
}
InterceptorChain composes zero or more gRPC interceptors into ordered slices suitable for grpc.ChainUnaryInterceptor and grpc.ChainStreamInterceptor.
func NewInterceptorChain ¶
func NewInterceptorChain(interceptors ...Interceptor) InterceptorChain
NewInterceptorChain creates a new interceptor chain. Each Interceptor argument provides a unary interceptor, a stream interceptor, or both. Nil entries in either field are silently skipped.
func (InterceptorChain) Append ¶
func (c InterceptorChain) Append(interceptors ...Interceptor) InterceptorChain
Append returns a new InterceptorChain with additional interceptors appended. The original chain is not modified.
func (InterceptorChain) ServerOptions ¶
func (c InterceptorChain) ServerOptions() []grpc.ServerOption
ServerOptions returns grpc.ServerOption values that install the chain. This is the primary integration point — pass the result to grpc.NewServer or to NewServer's variadic options.
chain := NewInterceptorChain(logging, recovery) srv, _ := NewServer(cfg, chain.ServerOptions()...)
type RegisterOption ¶
type RegisterOption func(*registerConfig)
RegisterOption configures optional behaviour for gRPC server registration.
func WithInterceptors ¶
func WithInterceptors(chain InterceptorChain) RegisterOption
WithInterceptors prepends the given interceptor chain before any grpc.ServerOption interceptors passed via the variadic opts.
Source Files