graceful

Documentation

Index

• Constants
• Variables
• func DefaultGetListener(network, address string) (net.Listener, error)
• func GetListenerTCP(network string, address *net.TCPAddr) (*net.TCPListener, error)
• func GetListenerUnix(network string, address *net.UnixAddr) (*net.UnixListener, error)
• func HTTPListenAndServe(network, address, name string, handler http.Handler, useProxyProtocol bool) error
• func HTTPListenAndServeTLSConfig(network, address, name string, tlsConfig *tls.Config, handler http.Handler, ...) error
• func InitManager(ctx context.Context)
• func KillParent()
• func RestartProcess() (int, error)
• type Manager
  • func GetManager() *Manager
  • func (g *Manager) Deadline() (deadline time.Time, ok bool)
  • func (g *Manager) DoGracefulRestart()
  • func (g *Manager) DoGracefulShutdown()
  • func (g *Manager) DoImmediateHammer()
  • func (g *Manager) Done() <-chan struct{}
  • func (g *Manager) Err() error
  • func (g *Manager) HammerContext() context.Context
  • func (g *Manager) InformCleanup()
  • func (g *Manager) IsChild() bool
  • func (g *Manager) IsHammer() <-chan struct{}
  • func (g *Manager) IsShutdown() <-chan struct{}
  • func (g *Manager) RegisterServer()
  • func (g *Manager) RunAtShutdown(ctx context.Context, shutdown func())
  • func (g *Manager) RunAtTerminate(terminate func())
  • func (g *Manager) RunWithCancel(rc RunCanceler)
  • func (g *Manager) RunWithShutdownContext(run func(context.Context))
  • func (g *Manager) ServerDone()
  • func (g *Manager) ShutdownContext() context.Context
  • func (g *Manager) TerminateContext() context.Context
  • func (g *Manager) Value(key any) any
• type RunCanceler
• type ServeFunction
• type Server
  • func NewServer(network, address, name string) *Server
  • func (srv *Server) ListenAndServe(serve ServeFunction, useProxyProtocol bool) error
  • func (srv *Server) ListenAndServeTLSConfig(tlsConfig *tls.Config, serve ServeFunction, ...) error
  • func (srv *Server) Serve(serve ServeFunction) error

Constants

const LifecyclePProfLabel = "graceful_lifecycle"

LifecyclePProfLabel is a label marking manager lifecycle phase Making it compliant with prometheus key regex https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels would enable someone interested to be able to to continuously gather profiles into pyroscope. Other labels for pprof (in "modules/process" package) should also follow this rule.

Variables

var GetListener = DefaultGetListener

GetListener returns a net listener This determines the implementation of net.Listener which the server will use, so that downstreams could provide their own Listener, such as with a hidden service or a p2p network

Functions

func DefaultGetListener

func DefaultGetListener(network, address string) (net.Listener, error)

DefaultGetListener obtains a listener for the stream-oriented local network address: "tcp", "tcp4", "tcp6", "unix" or "unixpacket".

func GetListenerTCP

func GetListenerTCP(network string, address *net.TCPAddr) (*net.TCPListener, error)

GetListenerTCP announces on the local network address. The network must be: "tcp", "tcp4" or "tcp6". It returns a provided net.Listener for the matching network and address, or creates a new one using net.ListenTCP.

func GetListenerUnix

func GetListenerUnix(network string, address *net.UnixAddr) (*net.UnixListener, error)

GetListenerUnix announces on the local network address. The network must be: "unix" or "unixpacket". It returns a provided net.Listener for the matching network and address, or creates a new one using net.ListenUnix.

func HTTPListenAndServe

func HTTPListenAndServe(network, address, name string, handler http.Handler, useProxyProtocol bool) error

HTTPListenAndServe listens on the provided network address and then calls Serve to handle requests on incoming connections.

func HTTPListenAndServeTLSConfig

func HTTPListenAndServeTLSConfig(network, address, name string, tlsConfig *tls.Config, handler http.Handler, useProxyProtocol, proxyProtocolTLSBridging bool) error

HTTPListenAndServeTLSConfig listens on the provided network address and then calls Serve to handle requests on incoming connections.

func InitManager

func InitManager(ctx context.Context)

InitManager creates the graceful manager in the provided context

func KillParent

func KillParent()

KillParent sends the kill signal to the parent process if we are a child

func RestartProcess

func RestartProcess() (int, error)

RestartProcess starts a new process passing it the active listeners. It doesn't fork, but starts a new process using the same environment and arguments as when it was originally started. This allows for a newly deployed binary to be started. It returns the pid of the newly started process when successful.

Types

type Manager

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

Manager manages the graceful shutdown process

func GetManager

func GetManager() *Manager

GetManager returns the Manager

func (*Manager) Deadline

func (g *Manager) Deadline() (deadline time.Time, ok bool)

Deadline returns nil as there is no fixed Deadline for the manager, it allows the manager to be viewed as a context.Context

func (*Manager) DoGracefulRestart

func (g *Manager) DoGracefulRestart()

DoGracefulRestart causes a graceful restart

func (*Manager) DoGracefulShutdown

func (g *Manager) DoGracefulShutdown()

DoGracefulShutdown causes a graceful shutdown

func (*Manager) DoImmediateHammer

func (g *Manager) DoImmediateHammer()

DoImmediateHammer causes an immediate hammer

func (*Manager) Done

func (g *Manager) Done() <-chan struct{}

Done allows the manager to be viewed as a context.Context, it returns a channel that is closed when the server is finished terminating

func (*Manager) Err

func (g *Manager) Err() error

Err allows the manager to be viewed as a context.Context done at Terminate

func (*Manager) HammerContext

func (g *Manager) HammerContext() context.Context

HammerContext returns a context.Context that is Done at hammer Callers using this context should ensure that they are registered as a running server in order that they are waited for.

func (*Manager) InformCleanup

func (g *Manager) InformCleanup()

InformCleanup tells the cleanup wait group that we have either taken a listener or will not be taking a listener. At the moment the total number of servers (numberOfServersToCreate) are pre-defined as a const before global init, so this function MUST be called if a server is not used.

func (*Manager) IsChild

func (g *Manager) IsChild() bool

IsChild returns if the current process is a child of previous Gitea process

func (*Manager) IsHammer

func (g *Manager) IsHammer() <-chan struct{}

IsHammer returns a channel which will be closed at hammer. Servers running within the running server wait group should respond to IsHammer if not shutdown already

func (*Manager) IsShutdown

func (g *Manager) IsShutdown() <-chan struct{}

IsShutdown returns a channel which will be closed at shutdown. The order of closure is shutdown, hammer (potentially), terminate

func (*Manager) RegisterServer

func (g *Manager) RegisterServer()

RegisterServer registers the running of a listening server, in the case of unix this means that the parent process can now die. Any call to RegisterServer must be matched by a call to ServerDone

func (*Manager) RunAtShutdown

func (g *Manager) RunAtShutdown(ctx context.Context, shutdown func())

RunAtShutdown creates a go-routine to run the provided function at shutdown

func (*Manager) RunAtTerminate

func (g *Manager) RunAtTerminate(terminate func())

RunAtTerminate adds to the terminate wait group and creates a go-routine to run the provided function at termination

func (*Manager) RunWithCancel

func (g *Manager) RunWithCancel(rc RunCanceler)

RunWithCancel helps to run a function with a custom context, the Cancel function will be called at shutdown The Cancel function should stop the Run function in predictable time.

func (*Manager) RunWithShutdownContext

func (g *Manager) RunWithShutdownContext(run func(context.Context))

RunWithShutdownContext takes a function that has a context to watch for shutdown. After the provided context is Done(), the main function must return once shutdown is complete. (Optionally the HammerContext may be obtained and waited for however, this should be avoided if possible.)

func (*Manager) ServerDone

func (g *Manager) ServerDone()

ServerDone declares a running server done and subtracts one from the running server wait group. Users probably do not want to call this and should use one of the RunWithShutdown* functions

func (*Manager) ShutdownContext

func (g *Manager) ShutdownContext() context.Context

ShutdownContext returns a context.Context that is Done at shutdown Callers using this context should ensure that they are registered as a running server in order that they are waited for.

func (*Manager) TerminateContext

func (g *Manager) TerminateContext() context.Context

TerminateContext returns a context.Context that is Done at terminate Callers using this context should ensure that they are registered as a terminating server in order that they are waited for.

func (*Manager) Value

func (g *Manager) Value(key any) any

Value allows the manager to be viewed as a context.Context done at Terminate

type RunCanceler

type RunCanceler interface {
	Run()
	Cancel()
}

type ServeFunction

type ServeFunction = func(net.Listener) error

ServeFunction represents a listen.Accept loop

type Server

type Server struct {
	BeforeBegin          func(network, address string)
	OnShutdown           func()
	PerWriteTimeout      time.Duration
	PerWritePerKbTimeout time.Duration
	// contains filtered or unexported fields
}

Server represents our graceful server

func NewServer

func NewServer(network, address, name string) *Server

NewServer creates a server on network at provided address

func (*Server) ListenAndServe

func (srv *Server) ListenAndServe(serve ServeFunction, useProxyProtocol bool) error

ListenAndServe listens on the provided network address and then calls Serve to handle requests on incoming connections.

func (*Server) ListenAndServeTLSConfig

func (srv *Server) ListenAndServeTLSConfig(tlsConfig *tls.Config, serve ServeFunction, useProxyProtocol, proxyProtocolTLSBridging bool) error

ListenAndServeTLSConfig listens on the provided network address and then calls Serve to handle requests on incoming TLS connections.

func (*Server) Serve

func (srv *Server) Serve(serve ServeFunction) error

Serve accepts incoming HTTP connections on the wrapped listener l, creating a new service goroutine for each. The service goroutines read requests and then call handler to reply to them. Handler is typically nil, in which case the DefaultServeMux is used.

In addition to the standard Serve behaviour each connection is added to a sync.Waitgroup so that all outstanding connections can be served before shutting down the server.