server

package
v2.4.1 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2024 License: Apache-2.0 Imports: 29 Imported by: 8

Documentation

Overview

Package server provides the standard approach to executing servers for WebPA

Deprecated: server is no longer planned to be used by future WebPA/XMiDT services.

This package is frozen and no new functionality will be added.

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"

	// DefaultPprofAddress is the bind address of the pprof server
	DefaultPprofAddress = ":6060"

	// 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.

func CreateCPUProfileFile 

func CreateCPUProfileFile(v *viper.Viper, fp *pflag.FlagSet, l *zap.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(_ *viper.Viper, fp *pflag.FlagSet, l *zap.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 *zap.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 RestartableFunc 

func RestartableFunc(logger *zap.Logger, f func() error, errs ...error) error

func Serve 

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

Serve is like ListenAndServe, but accepts a custom net.Listener

func SignalWait 

func SignalWait(logger *zap.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.

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 *zap.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 or if any config errors occur, effectively disabling this server from startup.

func (*Basic) NewListener 

func (b *Basic) NewListener(logger *zap.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 *zap.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 *zap.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 *zap.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 *[]zap.Field
}

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 *zap.Logger, registry xmetrics.Registry, webPA *WebPA, err error)

Initialize handles the bootstrapping of the server code for a WebPA node. It configures Viper, reads configuration, and unmarshals the appropriate objects. This function is typically all that's needed to fully instantiate a WebPA server. Typical usage: 

var (
  f = pflag.NewFlagSet()
  v = viper.New()

  // can customize both the FlagSet and the Viper before invoking New
  logger, registry, webPA, err = server.Initialize("petasos", os.Args, f, v)
)

if err != nil {
  // deal with the error, possibly just exiting
}

Note that the FlagSet is optional but highly encouraged. If not supplied, then no command-line binding is done for the unmarshalled configuration.

This function always returns a logger, regardless of any errors. This allows clients to use the returned logger when reporting errors. This function falls back to a logger that writes to os.Stdout if it cannot create a logger from the Viper environment.

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 *zap.Logger, health *health.Health, registry xmetrics.Registry, primaryHandler http.Handler) (health.Monitor, concurrent.Runnable, <-chan struct{})

Prepare gets a WebPA server ready for execution. This method does not return errors, but the returned Runnable may return an error. The supplied logger will usually come from the New function, but the WebPA.Log object can be used to create a different logger if desired.

The caller may pass an arbitrary Health instance. If this parameter is nil, this method will attempt to create one using Health.NewHealth. In either case, if Health.Address is not supplied, no health server will be instantiated.

The caller may also pass a gatherer type. If it is not provided, the default provided by prometheus is used.

The supplied http.Handler is used for the primary server. If the alternate server has an address, it will also be used for that server. The health server uses an internally create handler, while pprof and metrics servers use http.DefaultServeMux. The health Monitor created from configuration is returned so that other infrastructure can make use of it.

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.