Documentation ¶
Overview ¶
Package server provides the standard approach to executing servers for WebPA
Index ¶
- Constants
- Variables
- func Configure(applicationName string, arguments []string, f *pflag.FlagSet, v *viper.Viper) (err error)
- func ConfigureFlagSet(applicationName string, f *pflag.FlagSet)
- func ConfigureViper(applicationName string, f *pflag.FlagSet, v *viper.Viper) (err error)
- func CreateCPUProfileFile(v *viper.Viper, fp *pflag.FlagSet, l log.Logger)
- func CreateMemoryProfileFile(v *viper.Viper, fp *pflag.FlagSet, l log.Logger)
- func DefaultPeerVerifyCallback(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
- func ListenAndServe(logger log.Logger, e executor, finalizer func())
- func Metrics() []xmetrics.Metric
- func NewConnectionStateLogger(serverName string, logger log.Logger) func(net.Conn, http.ConnState)
- func NewErrorLog(serverName string, logger log.Logger) *stdlibLog.Logger
- func RestartableFunc(logger log.Logger, f func() error, errs ...error) error
- func Serve(logger log.Logger, l net.Listener, e executor, finalizer func())
- func SignalWait(logger log.Logger, signals <-chan os.Signal, waitOn ...os.Signal) os.Signal
- type Basic
- type Health
- type Metric
- type PeerVerifyCallback
- type WebPA
Examples ¶
Constants ¶
const ( APIRequestsTotal = "api_requests_total" InFlightRequests = "in_flight_requests" ActiveConnections = "active_connections" RejectedConnections = "rejected_connections" RequestDurationSeconds = "request_duration_seconds" RequestSizeBytes = "request_size_bytes" ResponseSizeBytes = "response_size_bytes" TimeWritingHeaderSeconds = "time_writing_header_seconds" MaxProcs = "maximum_processors" )
const ( // DefaultPrimaryAddress is the bind address of the primary server (e.g. talaria, petasos, etc) DefaultPrimaryAddress = ":8080" // DefaultHealthAddress is the bind address of the health check server DefaultHealthAddress = ":8081" // DefaultMetricsAddress is the bind address of the metrics server DefaultMetricsAddress = ":8082" // DefaultHealthLogInterval is the interval at which health statistics are emitted // when a non-positive log interval is specified DefaultHealthLogInterval time.Duration = time.Duration(60 * time.Second) // DefaultLogConnectionState is the default setting for logging connection state messages. This // value is primarily used when a *WebPA value is nil. DefaultLogConnectionState = false // AlternateSuffix is the suffix appended to the server name, along with a period (.), for // logging information pertinent to the alternate server. AlternateSuffix = "alternate" // DefaultProject is used as a metrics namespace when one is not defined. DefaultProject = "xmidt" // HealthSuffix is the suffix appended to the server name, along with a period (.), for // logging information pertinent to the health server. HealthSuffix = "health" // PprofSuffix is the suffix appended to the server name, along with a period (.), for // logging information pertinent to the pprof server. PprofSuffix = "pprof" // MetricsSuffix is the suffix appended to the server name, along with a period (.), for // logging information pertinent to the metrics server. MetricsSuffix = "metrics" // FileFlagName is the name of the command-line flag for specifying an alternate // configuration file for Viper to hunt for. FileFlagName = "file" // FileFlagShorthand is the command-line shortcut flag for FileFlagName FileFlagShorthand = "f" // CPUProfileFlagName is the command-line flag for creating a cpuprofile on the server CPUProfileFlagName = "cpuprofile" // CPUProfileShortHand is the command-line shortcut for creating cpushorthand on the server CPUProfileShorthand = "c" // MemProfileFlagName is the command-line flag for creating memprofile on the server MemProfileFlagName = "memprofile" // MemProfileShortHand is the command-line shortcut for creating memprofile on the server MemProfileShorthand = "m" )
const ( DefaultBuild = "development" DefaultServer = "localhost" DefaultRegion = "local" DefaultFlavor = "development" DefaultIdleTimeout time.Duration = 15 * time.Second DefaultReadHeaderTimeout time.Duration = 0 DefaultReadTimeout time.Duration = 5 * time.Second DefaultWriteTimeout time.Duration = 30 * time.Minute DefaultMaxHeaderBytes = http.DefaultMaxHeaderBytes )
Variables ¶
var ( // ErrorNoPrimaryAddress is the error returned when no primary address is specified in a WebPA instance ErrorNoPrimaryAddress = errors.New("No primary address configured") )
Functions ¶
func Configure ¶
func Configure(applicationName string, arguments []string, f *pflag.FlagSet, v *viper.Viper) (err error)
Configure is a one-stop shopping function for preparing WebPA configuration. This function does not itself read in configuration from the Viper environment. Typical usage is:
var ( f = pflag.NewFlagSet() v = viper.New() ) if err := server.Configure("petasos", os.Args, f, v); err != nil { // deal with the error, possibly just exiting } // further customizations to the Viper instance can be done here if err := v.ReadInConfig(); err != nil { // more error handling }
Usage of this function is only necessary if custom configuration is needed. Normally, using New will suffice.
func ConfigureFlagSet ¶
ConfigureFlagSet adds the standard set of WebPA flags to the supplied FlagSet. Use of this function is optional, and necessary only if the standard flags should be supported. However, this is highly desirable, as ConfigureViper can make use of the standard flags to tailor how configuration is loaded or if gathering cpuprofile or memprofile data is needed.
func ConfigureViper ¶
ConfigureViper configures a Viper instances using the opinionated WebPA settings. All WebPA servers should use this function.
The flagSet is optional. If supplied, it will be bound to the given Viper instance. Additionally, if the flagSet has a FileFlagName flag, it will be used as the configuration name to hunt for instead of the application name. * ConfigureViper function sets up paths to search for configuration files, binds environment variables to configuration settings, sets default values for configuration settings, and optionally binds command-line arguments to configuration settings. The function takes three arguments: the name of the application, a pointer to a pflag. FlagSet object containing command-line flags (which can be nil), and a pointer to a viper. Viper object to be configured. The function returns an error if there is a problem binding command-line arguments to configuration settings. *
func CreateCPUProfileFile ¶
create CPUProfileFiles creates a cpu profile of the server, its triggered by the optional flag cpuprofile
the CPU profile is created on the server's start
func CreateMemoryProfileFile ¶
Create CPUProfileFiles creates a memory profile of the server, its triggered by the optional flag memprofile
the memory profile is created on the server's exit. this function should be used within the application.
func DefaultPeerVerifyCallback ¶
func DefaultPeerVerifyCallback(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error
func ListenAndServe ¶
ListenAndServe invokes the server method
func Metrics ¶
Metrics is the module function for this package that adds the default request handling metrics. This module is exported for code that does not directly use this package to start a server. Never pass this module when using the webpa functions to start a server.
func NewConnectionStateLogger ¶
NewConnectionStateLogger produces a function appropriate for http.Server.ConnState. The returned function will log debug statements for each state change.
func NewErrorLog ¶
NewErrorLog creates a new logging.Logger appropriate for http.Server.ErrorLog
func RestartableFunc ¶
RestartableFunc returns a function that can be restarted when it returns a specific error. The returned function takes no parameters and returns an error. It accepts a logger, a function, and a list of errors. The logger is used for logging debug messages. The function is the one that needs to be restarted on a specific error. The list of errors is used to specify the error that can trigger a restart. * * logger is the logger instance used for logging debug messages f is a function that is expected to be restarted errs ...error is a variable length argument list of errors that can trigger a restart of the function
The point of a function like RestartableFunc is to provide a way to automatically restart a service if it crashes or fails in some way. This is especially useful in long-running services that need to be highly available and responsive. :emoji The RestartableFunc() function uses a technique called tail call optimization to avoid stack overflow. In Golang,
this optimization is built into the compiler and the language runtime.
############################### In a recursive function, the tail call optimization replaces the current call stack frame with the next recursive call. This means that the function does not create a new stack frame for each recursive call,
which would eventually cause a stack overflow. Instead, the function reuses the existing stack frame and overwrites it with new data. In the case of RestartableFunc(), it is using an iterative approach instead of a recursive approach, but the same tail call optimization applies. The function is repeatedly calling itself, but it is not creating a new stack frame for each call. Instead, it is reusing the same stack frame and overwriting it with new data.
Therefore, as long as the RestartableFunc() function is tail-recursive or tail-iterative, it should not cause a stack overflow, even if it runs indefinitely. but golang support tail iterative approach
##################################################################### In the case of RestartableFunc(), it is using an iterative approach instead of a recursive approach, but the same tail call optimization applies. The function is repeatedly calling itself, but it is not creating a new stack frame for each call. Instead, it is reusing the same stack frame and overwriting it with new data.
Therefore, as long as the RestartableFunc() function is tail-recursive or tail-iterative, it should not cause a stack overflow, even if it runs indefinitely. *
func Serve ¶
Serve is like ListenAndServe, but accepts a custom net.Listener *
ListenAndServe is a utility function which provides a default HTTP server configuration
and starts the server on the provided address. This function starts a new HTTP server in a separate goroutine using the provided net.Listener and executor. It also logs the start of the server using the provided logger. The finalizer parameter is a function that will be called after the server is shut down. This can be used for cleanup or other purposes. *
func SignalWait ¶
SignalWait blocks until any of a set of signals is encountered. The signal which caused this function to exit is returned. A nil return indicates that the signals channel was closed.
If no waitOn signals are supplied, this function will never return until the signals channel is closed.
In all cases, the supplied logger is used to log information about signals that are ignored. * @author jithin-kg function takes a logger of type log.Logger
channel of OS signals called signals, and an arbitrary number of os.Signal types to wait for called waitOn. it returns os.Signal type so signals channel will be passing value of type os.Signal and we have a list of signals that we are interested in waitOn slice
in first loop we create a map of signals we are interested in and we assign true to it in the second for loop;->The function then enters an infinite loop and waits for signals to be received on the 'signals'channel. whenever an os signal receive and if that signal is present in our interested signal we just return the signal else we ignore and log *
Types ¶
type Basic ¶
type Basic struct { Name string Address string CertificateFile []string KeyFile []string ClientCACertFile string LogConnectionState bool MinVersion uint16 MaxVersion uint16 PeerVerifyFunc PeerVerifyCallback // Callback func to add peer client cert CN, SAN validation MaxConnections int DisableKeepAlives bool MaxHeaderBytes int IdleTimeout time.Duration ReadHeaderTimeout time.Duration ReadTimeout time.Duration WriteTimeout time.Duration }
Basic describes a simple HTTP server. Typically, this struct has its values injected via Viper. See the New function in this package.
func (*Basic) New ¶
New creates an http.Server using this instance's configuration. The given logger is required, but the handler may be nil. If the handler is nil, http.DefaultServeMux is used, which matches the behavior of http.Server.
This method returns nil if the configured address is empty, effectively disabling this server from startup.
func (*Basic) NewListener ¶
func (b *Basic) NewListener(logger log.Logger, activeConnections metrics.Gauge, rejectedCounter xmetrics.Adder, config *tls.Config) (net.Listener, error)
NewListener creates a decorated TCPListener appropriate for this server's configuration.
func (*Basic) SetPeerVerifyCallback ¶
func (b *Basic) SetPeerVerifyCallback(vp PeerVerifyCallback)
type Health ¶
type Health struct { Name string Address string CertificateFile []string KeyFile []string LogConnectionState bool LogInterval time.Duration Options []string }
Health represents a configurable factory for a Health server. As with the Basic type, if the Address is not specified, health is considered to be disabled.
Due to a limitation of Viper, this struct does not use an embedded Basic instance. Rather, it duplicates the fields so that Viper can inject them.
func (*Health) New ¶
func (h *Health) New(logger log.Logger, chain alice.Chain, health *health.Health) (*health.Health, *http.Server)
New creates an HTTP server instance for serving health statistics. If the health parameter is nil, then h.NewHealth is used to create a Health instance. Otherwise, the health parameter is returned as is.
If the Address option is not supplied, the health module is considered to be disabled. In that case, this method simply returns the health parameter as the monitor and a nil server instance.
type Metric ¶
type Metric struct { Name string Address string CertificateFile []string KeyFile []string LogConnectionState bool HandlerOptions promhttp.HandlerOpts MetricsOptions xmetrics.Options }
Metric is the configurable factory for a metrics server.
type PeerVerifyCallback ¶
type PeerVerifyCallback func([][]byte, [][]*x509.Certificate) error
type WebPA ¶
type WebPA struct { // ApplicationName is the short identifier for the enclosing application, e.g. "talaria". // This value is defaulted to what's passed in via Initialize, but can be changed via injection. ApplicationName string // Primary is the main server for this application, e.g. petasos. Primary Basic // Alternate is an alternate server which serves the primary application logic. // Used to have the same API served on more than one port and possibly more than // one protocol, e.g. HTTP and HTTPS. Alternate Basic // Health describes the health server for this application. Note that if the Address // is empty, no health server is started. Health Health // Pprof describes the pprof server for this application. Note that if the Address // is empty, no pprof server is started. Pprof Basic // Metric describes the metrics provider server for this application Metric Metric // Build is the build string for the current codebase Build string // Server is the fully-qualified domain name of this server, typically injected as a fact Server string // Region is the region in which this server is running, typically injected as a fact Region string // Flavor is the flavor of this server, typically injected as a fact Flavor string // Log is the logging configuration for this application. Log *logging.Options }
WebPA represents a server component within the WebPA cluster. It is used for both primary servers (e.g. petasos) and supporting, embedded servers such as pprof.
func Initialize ¶
func Initialize(applicationName string, arguments []string, f *pflag.FlagSet, v *viper.Viper, modules ...xmetrics.Module) (logger log.Logger, registry xmetrics.Registry, webPA *WebPA, err error)
* Initialize function sets up the Viper environment, reads in configuration, initializes the logger and metric registry, and returns a fully initialized WebPA struct along with a logger and metric registry.
Initialize initializes the WebPA server and is the only function required to instantiate the WebPA server. The function accepts applicationName as a string, arguments as a slice of strings, f as a pointer to pflag.FlagSet, v as a pointer to viper.Viper, and modules as *
Example ¶
_, _, webPA, err := Initialize("example", nil, nil, viper.New()) if err != nil { panic(err) } fmt.Println(webPA.Primary.Name) fmt.Println(webPA.Primary.Address) fmt.Println(webPA.Primary.LogConnectionState) fmt.Println(webPA.Alternate.Name) fmt.Println(webPA.Alternate.Address) fmt.Println(webPA.Alternate.LogConnectionState) fmt.Println(webPA.Health.Name) fmt.Println(webPA.Health.Address) fmt.Println(webPA.Health.LogInterval) fmt.Println(webPA.Health.Options)
Output: example localhost:10010 true example.alternate :10011 false example.health :9001 45s [TotalRequests TotalResponses SomeOtherStat]
func (*WebPA) Prepare ¶
func (w *WebPA) Prepare(logger log.Logger, health *health.Health, registry xmetrics.Registry, primaryHandler http.Handler) (health.Monitor, concurrent.Runnable, <-chan struct{})
* *logger: a logger object used for logging throughout the function health: a health object used for monitoring the health of the server registry: a metrics registry object used for registering metrics primaryHandler: an HTTP handler object that is the primary handler for incoming requests The method returns three values:
health.Monitor: a health monitor object for monitoring the health of the server concurrent.Runnable: a concurrent runnable object used for running the server concurrently <-chan struct{}: a channel of empty structs used for signaling when the server is done *