graceful

Documentation

Overview

Package graceful implements graceful reload/restart features for HTTP servers. It provides the ability to gracefully shutdown or restart HTTP servers without interrupting existing connections. This is particularly useful for zero-downtime deployments and maintenance operations.

The package wraps the standard net/http.Server and provides additional functionality for graceful server management, including: - Graceful server shutdown with timeout - Support for both HTTP and HTTPS servers - File descriptor inheritance for server reload/restart - Connection management during shutdown

Index

• type Server
  • func New(address string, fd int, loggerWriter io.Writer, config ServerConfig) *Server
  • func (s *Server) Close(ctx context.Context)
  • func (s *Server) CreateListener() error
  • func (s *Server) CreateListenerTLS(certFile, keyFile string, tlsConfig ...*tls.Config) error
  • func (s *Server) Fd() uintptr
  • func (s *Server) GetAddress() string
  • func (s *Server) GetListenedAddress() string
  • func (s *Server) GetListenedPort() int
  • func (s *Server) IsHttps() bool
  • func (s *Server) Serve(ctx context.Context) error
  • func (s *Server) SetIsHttps(isHttps bool)
  • func (s *Server) Shutdown(ctx context.Context)
  • func (s *Server) Status() ServerStatus
• type ServerConfig
• type ServerStatus

Types

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps the net/http.Server with graceful reload/restart feature.

func New

func New(
	address string,
	fd int,
	loggerWriter io.Writer,
	config ServerConfig,
) *Server

New creates and returns a graceful http server with a given address. The optional parameter `fd` specifies the file descriptor which is passed from parent server.

func (*Server) Close

func (s *Server) Close(ctx context.Context)

Close shuts down the server forcibly. for graceful shutdown, please use Server.shutdown.

func (*Server) CreateListener

func (s *Server) CreateListener() error

CreateListener creates listener on configured address.

func (*Server) CreateListenerTLS

func (s *Server) CreateListenerTLS(certFile, keyFile string, tlsConfig ...*tls.Config) error

CreateListenerTLS creates listener on configured address with HTTPS. The parameter `certFile` and `keyFile` specify the necessary certification and key files for HTTPS. The optional parameter `tlsConfig` specifies the custom TLS configuration.

func (*Server) Fd

func (s *Server) Fd() uintptr

Fd retrieves and returns the file descriptor of the current server. It is available ony in *nix like operating systems like linux, unix, darwin.

func (*Server) GetAddress

func (s *Server) GetAddress() string

GetAddress returns the server's configured address.

func (*Server) GetListenedAddress

func (s *Server) GetListenedAddress() string

GetListenedAddress retrieves and returns the address string which are listened by current server.

func (*Server) GetListenedPort

func (s *Server) GetListenedPort() int

GetListenedPort retrieves and returns one port which is listened to by current server. Note that this method is only available if the server is listening on one port.

func (*Server) IsHttps

func (s *Server) IsHttps() bool

IsHttps returns whether the server is running in HTTPS mode.

func (*Server) Serve

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

Serve starts the serving with blocking way.

func (*Server) SetIsHttps

func (s *Server) SetIsHttps(isHttps bool)

SetIsHttps sets the HTTPS mode for the server. The parameter isHttps determines whether to enable HTTPS mode.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context)

Shutdown shuts down the server gracefully.

func (*Server) Status

func (s *Server) Status() ServerStatus

Status returns the current status of the server. It returns either ServerStatusStopped or ServerStatusRunning.

type ServerConfig

type ServerConfig struct {
	// Listeners specifies the custom listeners.
	Listeners []net.Listener `json:"listeners"`

	// Handler the handler for HTTP request.
	Handler func(w http.ResponseWriter, r *http.Request) `json:"-"`

	// ReadTimeout is the maximum duration for reading the entire
	// request, including the body.
	//
	// Because ReadTimeout does not let Handlers make per-request
	// decisions on each request body's acceptable deadline or
	// upload rate, most users will prefer to use
	// ReadHeaderTimeout. It is valid to use them both.
	ReadTimeout time.Duration `json:"readTimeout"`

	// WriteTimeout is the maximum duration before timing out
	// writes of the response. It is reset whenever a new
	// request's header is read. Like ReadTimeout, it does not
	// let Handlers make decisions on a per-request basis.
	WriteTimeout time.Duration `json:"writeTimeout"`

	// IdleTimeout is the maximum amount of time to wait for the
	// next request when keep-alive are enabled. If IdleTimeout
	// is zero, the value of ReadTimeout is used. If both are
	// zero, there is no timeout.
	IdleTimeout time.Duration `json:"idleTimeout"`

	// GracefulShutdownTimeout set the maximum survival time (seconds) before stopping the server.
	GracefulShutdownTimeout int `json:"gracefulShutdownTimeout"`

	// MaxHeaderBytes controls the maximum number of bytes the
	// server will read parsing the request header's keys and
	// values, including the request line. It does not limit the
	// size of the request body.
	//
	// It can be configured in configuration file using string like: 1m, 10m, 500kb etc.
	// It's 10240 bytes in default.
	MaxHeaderBytes int `json:"maxHeaderBytes"`

	// KeepAlive enables HTTP keep-alive.
	KeepAlive bool `json:"keepAlive"`

	// Logger specifies the logger for server.
	Logger *glog.Logger `json:"logger"`
}

ServerConfig is the graceful Server configuration manager.

type ServerStatus

type ServerStatus = int

ServerStatus is the server status enum type.

const (
	// FreePortAddress marks the server listens using random free port.
	FreePortAddress = ":0"
	// ServerStatusStopped indicates the server is stopped.
	ServerStatusStopped ServerStatus = 0
	// ServerStatusRunning indicates the server is running.
	ServerStatusRunning ServerStatus = 1
)