README
¶
Graceful
Package graceful provides graceful shutdown for servers.
Example
Dual HTTP Server
// DualServerConfig specifies a server split between internal and external
// clients with graceful shutdown parameters.
srv := graceful.DualServerConfig{
// ExternalServer is the server for primary clients.
ExternalServer: graceful.HTTPServer(&http.Server{
Handler: extMux,
}),
// InternalServer is the server for health checks, metrics, debugging,
// profiling, etc. It shuts down after the ExternalServer exits.
InternalServer: graceful.HTTPServer(&http.Server{
Handler: intMux,
}),
// ShutdownDelay gives time for load balancers to remove the server from
// their backend pools after a shutdown signal is received and before it
// stops listening.
ShutdownDelay: 10 * time.Second,
// ShutdownGrace gives time for pending requests to complete before the
// server forcibly shuts down.
ShutdownGrace: 30 * time.Second,
// Logger optionally adds the ability to log messages, both errors and not.
Logger: log,
}
intMux.HandleFunc("/health/alive", func(w http.ResponseWriter, _ *http.Request) {
w.WriteHeader(http.StatusOK)
})
intMux.HandleFunc("/health/ready", func(w http.ResponseWriter, _ *http.Request) {
select {
case <-srv.ShuttingDown():
w.WriteHeader(http.StatusServiceUnavailable)
default:
w.WriteHeader(http.StatusOK)
}
})
if err := srv.ListenAndServe(ctx, *intAddr, *extAddr); err != nil {
log.Error(err, "Serving failed")
}
Documentation
¶
Overview ¶
Package graceful provides graceful shutdown for servers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Contexts ¶
func Contexts(ctx context.Context, log logr.Logger, delay, grace time.Duration) (warn, soft, hard context.Context)
Contexts returns three contexts which respectively serve as warning, soft, and hard shutdown signals. They are cancelled after TERM or INT signals are received.
When a shutdown signal is received, the warning context is cancelled. This is useful to start failing health checks while other traffic is still served.
If delay is positive, the soft context will be cancelled after that duration. This is useful to allow loadbalancer updates before the server stops accepting new requests.
If grace is positive, the hard context will be cancelled that duration after the soft context is cancelled. This is useful to set a maximum time to allow pending requests to complete.
Repeated TERM or INT signals will bypass any delay or grace time.
Types ¶
type DualServerConfig ¶
type DualServerConfig struct {
// ExternalServer is the server for primary clients.
ExternalServer Server
// InternalServer is the server for health checks, metrics, debugging,
// profiling, etc. It shuts down after the ExternalServer.
InternalServer Server
// ShutdownDelay gives time for load balancers to remove the server from
// their backend pools after a shutdown signal is received and before it
// stops listening.
ShutdownDelay time.Duration
// ShutdownGrace gives time for pending requests to complete before the
// server forcibly shuts down.
ShutdownGrace time.Duration
// Logger optionally adds the ability to log messages, both errors and not.
Logger logr.Logger
// contains filtered or unexported fields
}
DualServerConfig specifies a server split between internal and external clients with graceful shutdown parameters.
func (*DualServerConfig) ListenAndServe ¶
func (cfg *DualServerConfig) ListenAndServe(ctx context.Context, intAddr, extAddr string) error
ListenAndServe listens on the given addresses and calls Serve.
func (*DualServerConfig) Serve ¶
Serve serves with the given listeners. It waits for shutdown signals with the given context and calls GracefulShutdown as configured. If the context is cancelled a hard shutdown is initiated.
func (*DualServerConfig) ShuttingDown ¶ added in v0.2.0
func (cfg *DualServerConfig) ShuttingDown() <-chan struct{}
ShuttingDown returns a channel that is closed when the server encounters an error or it receives its first signal to begin shutting down.
type Server ¶
type Server interface {
// Serve serves connections accepted from the listener. It does not return
// an error if the listener is closed by the GracefulShutown method.
Serve(net.Listener) error
// GracefulShutdown immediately closes the server's listener and signals to
// clients as necessary that it is going away. It waits for pending requests
// to finish or until the context is closed. If all pending requests finish,
// no error is returned.
GracefulShutdown(context.Context) error
}
A Server is a networked server.
func HTTPServer ¶
HTTPServer converts an http.Server into a graceful.Server.
type ServerConfig ¶
type ServerConfig struct {
// Server is the networked server.
Server Server
// ShutdownDelay gives time for load balancers to remove the server from
// their backend pools after a shutdown signal is received and before it
// stops listening.
ShutdownDelay time.Duration
// ShutdownGrace gives time for pending requests to complete before the
// server forcibly shuts down.
ShutdownGrace time.Duration
// Logger optionally adds the ability to log messages, both errors and not.
Logger logr.Logger
// contains filtered or unexported fields
}
ServerConfig specifies a server with graceful shutdown parameters.
func (*ServerConfig) ListenAndServe ¶
func (cfg *ServerConfig) ListenAndServe(ctx context.Context, addr string) error
ListenAndServe listens on the given address and calls Serve.
func (*ServerConfig) Serve ¶
Serve serves with the given listener. It waits for shutdown signals with the given context and calls GracefulShutdown as configured. If the context is cancelled a hard shutdown is initiated.
func (*ServerConfig) ShuttingDown ¶ added in v0.2.0
func (cfg *ServerConfig) ShuttingDown() <-chan struct{}
ShuttingDown returns a channel that is closed when the server encounters an error or it receives its first signal to begin shutting down.
Source Files