grpcserver

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 NewServer(cfg *ServerConfig, log *slog.Logger, opts ...ServerOption) 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
  • func NewServerConfig(opts ...ServerConfigOpt) *ServerConfig
• type ServerConfigOpt
  • func WithUDS(address string) ServerConfigOpt
• type ServerOption
  • func WithGRPCServer(srv *grpc.Server) ServerOption

Types

type Server

type Server struct {
	Log *slog.Logger
	// contains filtered or unexported fields
}

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

func (s *Server) GRPCServer() *grpc.Server

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

func (s *Server) HealthzCheck(req *http.Request) error

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

func (s *Server) NeedLeaderElection() bool

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

func (s *Server) ReadyzCheck(req *http.Request) error

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

func (s *Server) SetBindGate(gate func(ctx context.Context) error)

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

func (s *Server) Start(ctx context.Context) error

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.