Documentation
¶
Overview ¶
Package grpcserver is the lifecycle shell every aether gRPC server runs in: TCP or Unix-socket listen, PreListen callbacks, a bind gate, liveness and readiness, and graceful shutdown. It deliberately depends on nothing Envoy: the xDS server (common/xds) builds on it, and so do servers that are not xDS at all (the registrar, the agent's CNI server), which therefore do not link go-control-plane through it.
Index ¶
- type Server
- func (s *Server) AddCallback(callback ServerCallback)
- func (s *Server) Config() *ServerConfig
- func (s *Server) GRPCServer() *grpc.Server
- func (s *Server) HealthzCheck(req *http.Request) error
- func (s *Server) NeedLeaderElection() bool
- func (s *Server) ReadyzCheck(req *http.Request) error
- func (s *Server) SetBindGate(gate func(ctx context.Context) error)
- func (s *Server) Start(ctx context.Context) error
- type ServerCallback
- type ServerConfig
- type ServerConfigOpt
- type ServerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Server ¶
Server is a gRPC server that manages lifecycle and provides health checks. It supports both TCP and Unix domain socket transports and implements graceful shutdown.
Server is safe for concurrent use.
func NewServer ¶
func NewServer(cfg *ServerConfig, log *slog.Logger, opts ...ServerOption) Server
NewServer creates a new Server with the given configuration and logger. The server is not started until Start is called.
func (*Server) AddCallback ¶
func (s *Server) AddCallback(callback ServerCallback)
AddCallback registers a ServerCallback to be invoked before the server starts listening.
func (*Server) Config ¶
func (s *Server) Config() *ServerConfig
Config returns the configuration this Server was built with.
func (*Server) GRPCServer ¶
GRPCServer returns the gRPC server this Server serves (the one passed via WithGRPCServer), so a wrapper that built it can inspect its registered services.
func (*Server) HealthzCheck ¶
HealthzCheck is a liveness probe handler for health check endpoints. It returns an error when the server is not live, indicating the process should be restarted by the container runtime.
func (*Server) NeedLeaderElection ¶
NeedLeaderElection returns false so the server runs on all replicas, not just the leader. This is required for HA deployments where every replica must serve gRPC traffic independently.
func (*Server) ReadyzCheck ¶
ReadyzCheck is a readiness probe handler for health check endpoints. It returns an error when the server is not ready to accept client requests, causing the pod to be removed from service endpoints until it becomes ready.
func (*Server) SetBindGate ¶
SetBindGate makes Start wait on gate after PreListen and before it binds its listener. A gate returning an error while ctx is live fails Start; one returning because ctx ended makes Start return nil (a shutdown, not a fault).
The node agent uses it for the surge handoff (proposal 041): a standby agent builds everything a first serve needs, but must not bind the node's sockets until the agent that owns them has exited.
func (*Server) Start ¶
Start starts the gRPC server and blocks until the context is cancelled or the server errors. It invokes the PreListen callback before starting to listen if a callback is registered. For Unix domain sockets, it sets appropriate permissions on the socket file. The server will attempt graceful shutdown when the context is cancelled.
type ServerCallback ¶
type ServerCallback interface {
// PreListen is called before the server starts listening on the configured address.
// It is called after the context is created but before net.Listen is invoked.
// Implementations should return an error if setup fails; the server will not start.
PreListen(ctx context.Context) error
}
ServerCallback provides lifecycle hooks for the Server. Implementations can perform setup tasks before the server starts accepting connections.
type ServerConfig ¶
type ServerConfig struct {
// Network is the network type: "tcp" or "unix"
Network string
// Address is the address to bind to (e.g., ":50051" for TCP or "/tmp/server.sock" for Unix domain socket)
Address string
// ShutdownTimeout is the maximum time to wait for graceful shutdown
ShutdownTimeout time.Duration
// contains filtered or unexported fields
}
ServerConfig holds configuration for a Server.
Network and Address specify the network type and address for the server to bind to. For Unix domain sockets, use WithUDS. For TCP, the Address should be ":port" format. ShutdownTimeout specifies how long to wait for graceful shutdown before forcefully stopping the server.
func NewServerConfig ¶
func NewServerConfig(opts ...ServerConfigOpt) *ServerConfig
NewServerConfig creates a new ServerConfig with default values. The default network is TCP on port 50051 with a 30-second shutdown timeout. Options can be provided to override defaults.
type ServerConfigOpt ¶
type ServerConfigOpt func(*ServerConfig)
ServerConfigOpt is a functional option for configuring ServerConfig.
func WithUDS ¶
func WithUDS(address string) ServerConfigOpt
WithUDS configures the server to use a Unix domain socket at the given address.
type ServerOption ¶
type ServerOption func(*Server)
ServerOption is a functional option for configuring a Server.
func WithGRPCServer ¶
func WithGRPCServer(srv *grpc.Server) ServerOption
WithGRPCServer sets a pre-configured gRPC server to be used by the Server. If not provided, a new gRPC server will be created with default settings.
Source Files