server

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 ListenAndServe(logger logging.Logger, s Secure, e executor)
• func NewConnectionStateLogger(serverName string, logger logging.Logger) func(net.Conn, http.ConnState)
• func NewErrorLog(serverName string, logger logging.Logger) *log.Logger
• type Basic
  • func (b *Basic) Certificate() (certificateFile, keyFile string)
  • func (b *Basic) New(logger logging.Logger, handler http.Handler) *http.Server
• type Health
  • func (h *Health) Certificate() (certificateFile, keyFile string)
  • func (h *Health) New(logger logging.Logger) (handler *health.Health, server *http.Server)
• type Secure
• type WebPA
  • func Initialize(applicationName string, arguments []string, f *pflag.FlagSet, v *viper.Viper) (logger logging.Logger, webPA *WebPA, err error)
  • func (w *WebPA) Prepare(logger logging.Logger, primaryHandler http.Handler) (health.Monitor, concurrent.Runnable)

Examples

• Initialize

Constants

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"

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

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

	// 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"
)

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

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.

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 ListenAndServe

func ListenAndServe(logger logging.Logger, s Secure, e executor)

ListenAndServe invokes the appropriate server method based on the secure information. If Secure.Certificate() returns both a certificateFile and a keyFile, e.ListenAndServeTLS() is called to start the server. Otherwise, e.ListenAndServe() is used.

func NewConnectionStateLogger

func NewConnectionStateLogger(serverName string, logger logging.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 logging.Logger) *log.Logger

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

Types

type Basic

type Basic struct {
	Name               string
	Address            string
	CertificateFile    string
	KeyFile            string
	LogConnectionState bool
}

Basic describes a simple HTTP server. Typically, this struct has its values injected via Viper. See the New function in this package.

func (*Basic) Certificate

func (b *Basic) Certificate() (certificateFile, keyFile string)

func (*Basic) New

func (b *Basic) New(logger logging.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.

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.

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) Certificate

func (h *Health) Certificate() (certificateFile, keyFile string)

func (*Health) New

func (h *Health) New(logger logging.Logger) (handler *health.Health, server *http.Server)

New creates both a health.Health monitor (which is also an HTTP handler) and an HTTP server which services health requests.

This method returns nils if the configured Address is empty, which effectively disables the health server.

type Secure

type Secure interface {
	// Certificate returns the certificate information associated with this Secure instance.
	// BOTH the returned file paths must be non-empty if a TLS server is desired.
	Certificate() (certificateFile, keyFile string)
}

Secure exposes the optional certificate information to be used when starting an HTTP server.

type WebPA

type WebPA struct {
	// 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

	// Log is the logging configuration for this application.
	Log golog.LoggerFactory
}

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) (logger logging.Logger, 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, 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 logging.Logger, primaryHandler http.Handler) (health.Monitor, concurrent.Runnable)

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 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 the pprof server uses http.DefaultServeMux. The health Monitor created from configuration is returned so that other infrastructure can make use of it.