server

package
v1.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2023 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package server provides the standard approach to executing servers for WebPA

Index

Examples

Constants

View Source 
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"
)
View Source 
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"
)
View Source 
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

View Source 
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 

func ConfigureFlagSet(applicationName string, f *pflag.FlagSet)

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 

func ConfigureViper(applicationName string, f *pflag.FlagSet, v *viper.Viper) (err error)

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 

func CreateCPUProfileFile(v *viper.Viper, fp *pflag.FlagSet, l log.Logger)

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 

func CreateMemoryProfileFile(v *viper.Viper, fp *pflag.FlagSet, l log.Logger)

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 

func ListenAndServe(logger log.Logger, e executor, finalizer func())

ListenAndServe invokes the server method

func Metrics 

func Metrics() []xmetrics.Metric

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 

func NewConnectionStateLogger(serverName string, logger log.Logger) func(net.Conn, http.ConnState)

NewConnectionStateLogger produces a function appropriate for http.Server.ConnState. The returned function will log debug statements for each state change.

func NewErrorLog 

func NewErrorLog(serverName string, logger log.Logger) *stdlibLog.Logger

NewErrorLog creates a new logging.Logger appropriate for http.Server.ErrorLog

func RestartableFunc 

func RestartableFunc(logger log.Logger, f func() error, errs ...error) error

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 

func Serve(logger log.Logger, l net.Listener, e executor, finalizer func())

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 

func SignalWait(logger log.Logger, signals <-chan os.Signal, waitOn ...os.Signal) os.Signal

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 

func (b *Basic) New(logger log.Logger, handler http.Handler) *http.Server

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.

func (*Health) NewHealth 

func (h *Health) NewHealth(logger log.Logger, options ...health.Option) *health.Health

NewHealth creates a Health instance from this instance's configuration. If the Address field is not supplied, this method returns nil.

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.

func (*Metric) New 

func (m *Metric) New(logger log.Logger, chain alice.Chain, gatherer stdprometheus.Gatherer) *http.Server

func (*Metric) NewRegistry 

func (m *Metric) NewRegistry(modules ...xmetrics.Module) (xmetrics.Registry, error)

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 *

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.