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 NewServer(cfg config.Containable, opt ...grpc.ServerOption) (*grpc.Server, error)
- 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 TLSServerCredentials(certFile, keyFile string) (credentials.TransportCredentials, error)
- type GRPCLoggingOption
- type Interceptor
- type InterceptorChain
- type RegisterOption
Constants ¶
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 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 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 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.
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