witchcraft

Documentation

Index

• type ConfigBytesProvider
• type ConfigurableRouter
• type ECVKeyProvider
  • func ECVKeyFromFile(path string) ECVKeyProvider
  • func ECVKeyFromStatic(kwt *encryptedconfigvalue.KeyWithType) ECVKeyProvider
  • func ECVKeyNoOp() ECVKeyProvider
• type InitFunc
• type InitInfo
• type Server
  • func NewServer() *Server
  • func (s *Server) Close() error
  • func (s *Server) Running() bool
  • func (s *Server) Shutdown(ctx context.Context) error
  • func (s *Server) Start() (rErr error)
  • func (s *Server) State() ServerState
  • func (s *Server) WithClientAuth(clientAuth tls.ClientAuthType) *Server
  • func (s *Server) WithDisableGoRuntimeMetrics() *Server
  • func (s *Server) WithDisableKeepAlives() *Server
  • func (s *Server) WithDisableShutdownSignalHandler() *Server
  • func (s *Server) WithDisableSigQuitHandler() *Server
  • func (s *Server) WithECVKeyFromFile(fPath string) *Server
  • func (s *Server) WithECVKeyProvider(ecvProvider ECVKeyProvider) *Server
  • func (s *Server) WithHealth(healthSources ...status.HealthCheckSource) *Server
  • func (s *Server) WithInitFunc(initFn InitFunc) *Server
  • func (s *Server) WithInstallConfig(installConfigStruct interface{}) *Server
  • func (s *Server) WithInstallConfigFromFile(fpath string) *Server
  • func (s *Server) WithInstallConfigProvider(p ConfigBytesProvider) *Server
  • func (s *Server) WithInstallConfigType(installConfigStruct interface{}) *Server
  • func (s *Server) WithLiveness(liveness status.Source) *Server
  • func (s *Server) WithLoggerStdoutWriter(loggerStdoutWriter io.Writer) *Server
  • func (s *Server) WithMiddleware(middleware wrouter.RequestHandlerMiddleware) *Server
  • func (s *Server) WithOrigin(origin string) *Server
  • func (s *Server) WithReadiness(readiness status.Source) *Server
  • func (s *Server) WithRouterImplProvider(routerImplProvider func() wrouter.RouterImpl) *Server
  • func (s *Server) WithRuntimeConfig(in interface{}) *Server
  • func (s *Server) WithRuntimeConfigFromFile(fpath string) *Server
  • func (s *Server) WithRuntimeConfigProvider(r refreshable.Refreshable) *Server
  • func (s *Server) WithRuntimeConfigType(runtimeConfigStruct interface{}) *Server
  • func (s *Server) WithSelfSignedCertificate() *Server
  • func (s *Server) WithSigQuitHandlerWriter(w io.Writer) *Server
  • func (s *Server) WithTraceSampler(traceSampler func(id uint64) bool) *Server
• type ServerState
  • func (s ServerState) String() string

Types

type ConfigBytesProvider

type ConfigBytesProvider interface {
	LoadBytes() ([]byte, error)
}

type ConfigurableRouter

type ConfigurableRouter interface {
	wrouter.Router

	WithHealth(healthSources ...status.HealthCheckSource) *Server
	WithReadiness(readiness status.Source) *Server
	WithLiveness(liveness status.Source) *Server
}

ConfigurableRouter is a wrouter.Router that provides additional support for configuring things such as health, readiness, liveness and middleware.

type ECVKeyProvider

type ECVKeyProvider interface {
	Load() (*encryptedconfigvalue.KeyWithType, error)
}

func ECVKeyFromFile

func ECVKeyFromFile(path string) ECVKeyProvider

func ECVKeyFromStatic

func ECVKeyFromStatic(kwt *encryptedconfigvalue.KeyWithType) ECVKeyProvider

func ECVKeyNoOp

func ECVKeyNoOp() ECVKeyProvider

type InitFunc

type InitFunc func(ctx context.Context, info InitInfo) (cleanup func(), rErr error)

InitFunc is a function type used to initialize a server. ctx is a context configured with loggers and is valid for the duration of the server. Refer to the documentation of InitInfo for its fields.

If the returned cleanup function is non-nil, it is deferred and run on server shutdown. If the returned error is non-nil, the server will not start and will return the error.

type InitInfo

type InitInfo struct {
	// Router is a ConfigurableRouter that implements wrouter.Router for the server. It can be
	// used to register endpoints on the server and to configure things such as health, readiness and liveness sources and
	// any middleware (note that any values set using router will override any values previously set on the server).
	Router ConfigurableRouter

	// InstallConfig the install configuration. Its type is determined by the struct provided to the
	// "WithInstallConfigType" function (the default is config.Install).
	InstallConfig interface{}

	// RuntimeConfig is a refreshable that contains the initial runtime configuration. The type returned by the
	// refreshable is determined by the struct provided to the "WithRuntimeConfigType" function (the default is
	// config.Runtime).
	RuntimeConfig refreshable.Refreshable

	// ShutdownServer gracefully closes the server, waiting for any in-flight requests to finish (or the context to be cancelled).
	// When the InitFunc is executed, the server is not yet started. This will most often be useful if launching a goroutine which
	// requires access to shutdown the server in some error condition.
	ShutdownServer func(context.Context) error
}

type Server

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

func NewServer

func NewServer() *Server

NewServer returns a new uninitialized server.

func (*Server) Close

func (s *Server) Close() error

func (*Server) Running

func (s *Server) Running() bool

Running returns true if the server is in the "running" state (as opposed to "idle" or "initializing"), false otherwise.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

func (*Server) Start

func (s *Server) Start() (rErr error)

Start begins serving HTTPS traffic and blocks until s.Close() or s.Shutdown() return. Errors are logged via s.svcLogger before being returned. Panics are recovered; in the case of a recovered panic, Start will log and return a non-nil error containing the recovered object (overwriting any existing error).

func (*Server) State

func (s *Server) State() ServerState

State returns the state of the current server (idle, initializing or running).

func (*Server) WithClientAuth

func (s *Server) WithClientAuth(clientAuth tls.ClientAuthType) *Server

WithClientAuth configures the server to use the specified client authentication type for its TLS connections.

func (*Server) WithDisableGoRuntimeMetrics

func (s *Server) WithDisableGoRuntimeMetrics() *Server

WithDisableGoRuntimeMetrics disables the server's enabled-by-default collection of runtime memory statistics.

func (*Server) WithDisableKeepAlives

func (s *Server) WithDisableKeepAlives() *Server

WithDisableKeepAlives disables keep-alives on the server by calling SetKeepAlivesEnabled(false) on the http.Server used by the server. Note that this setting is only applied to the main server -- if the management server is separate from the main server, this setting is not applied to the management server. Refer to the documentation for SetKeepAlivesEnabled in http.Server for more information on when a server may want to use this setting.

func (*Server) WithDisableShutdownSignalHandler

func (s *Server) WithDisableShutdownSignalHandler() *Server

WithDisableShutdownSignalHandler disables the server's enabled-by-default shutdown on SIGTERM and SIGINT.

func (*Server) WithDisableSigQuitHandler

func (s *Server) WithDisableSigQuitHandler() *Server

WithDisableSigQuitHandler disables the server's enabled-by-default goroutine dump on SIGQUIT.

func (*Server) WithECVKeyFromFile

func (s *Server) WithECVKeyFromFile(fPath string) *Server

WithECVKeyFromFile configures the server to use the ECV key in the file at the specified path as the ECV key for decrypting ECV values in configuration.

func (*Server) WithECVKeyProvider

func (s *Server) WithECVKeyProvider(ecvProvider ECVKeyProvider) *Server

WithECVKeyProvider configures the server to use the ECV key provided by the specified provider as the ECV key for decrypting ECV values in configuration.

func (*Server) WithHealth

func (s *Server) WithHealth(healthSources ...status.HealthCheckSource) *Server

WithHealth configures the server to use the specified health check sources to report the server's health. If multiple healthSource's results have the same key, the result from the latest entry in healthSources will be used. These results are combined with the server's built-in health source, which uses the `SERVER_STATUS` key.

func (*Server) WithInitFunc

func (s *Server) WithInitFunc(initFn InitFunc) *Server

WithInitFunc configures the server to use the provided setup function to set up its initial state.

func (*Server) WithInstallConfig

func (s *Server) WithInstallConfig(installConfigStruct interface{}) *Server

WithInstallConfig configures the server to use the provided install configuration. The provided install configuration must support being marshaled as YAML.

func (*Server) WithInstallConfigFromFile

func (s *Server) WithInstallConfigFromFile(fpath string) *Server

WithInstallConfigFromFile configures the server to read the install configuration from the file at the specified path.

func (*Server) WithInstallConfigProvider

func (s *Server) WithInstallConfigProvider(p ConfigBytesProvider) *Server

WithInstallConfigProvider configures the server to use the install configuration obtained by reading the bytes from the specified ConfigBytesProvider.

func (*Server) WithInstallConfigType

func (s *Server) WithInstallConfigType(installConfigStruct interface{}) *Server

WithInstallConfigType configures the server to use the type of the provided struct as the type for the install configuration. The YAML representation of the install configuration is unmarshaled into a newly created struct that has the same type as the provided struct, so the provided struct should either embed or be compatible with config.Install.

func (*Server) WithLiveness

func (s *Server) WithLiveness(liveness status.Source) *Server

WithLiveness configures the server to use the specified source to report liveness.

func (*Server) WithLoggerStdoutWriter

func (s *Server) WithLoggerStdoutWriter(loggerStdoutWriter io.Writer) *Server

WithLoggerStdoutWriter configures the writer that loggers will write to IF they are configured to write to STDOUT. This configuration is typically only used in specialized scenarios (for example, to write logger output to an in-memory buffer rather than Stdout for tests).

func (*Server) WithMiddleware

func (s *Server) WithMiddleware(middleware wrouter.RequestHandlerMiddleware) *Server

WithMiddleware configures the server to use the specified middleware. The provided middleware is added to any other specified middleware.

func (*Server) WithOrigin

func (s *Server) WithOrigin(origin string) *Server

WithOrigin configures the server to use the specified origin.

func (*Server) WithReadiness

func (s *Server) WithReadiness(readiness status.Source) *Server

WithReadiness configures the server to use the specified source to report readiness.

func (*Server) WithRouterImplProvider

func (s *Server) WithRouterImplProvider(routerImplProvider func() wrouter.RouterImpl) *Server

WithRouterImplProvider configures the server to use the specified routerImplProvider to provide router implementations.

func (*Server) WithRuntimeConfig

func (s *Server) WithRuntimeConfig(in interface{}) *Server

WithRuntimeConfig configures the server to use the provided runtime configuration. The provided runtime configuration must support being marshaled as YAML.

func (*Server) WithRuntimeConfigFromFile

func (s *Server) WithRuntimeConfigFromFile(fpath string) *Server

WithRuntimeConfigFromFile configures the server to use the file at the provided path as its runtime configuration. The server will create a refreshable.Refreshable using the file at the provided path (and will thus live-reload the configuration based on updates to the file).

func (*Server) WithRuntimeConfigProvider

func (s *Server) WithRuntimeConfigProvider(r refreshable.Refreshable) *Server

WithRuntimeConfigProvider configures the server to use the provided Refreshable as its runtime configuration. The value provided by the refreshable must be the byte slice for the runtime configuration.

func (*Server) WithRuntimeConfigType

func (s *Server) WithRuntimeConfigType(runtimeConfigStruct interface{}) *Server

WithRuntimeConfigType configures the server to use the type of the provided struct as the type for the runtime configuration. The YAML representation of the runtime configuration is unmarshaled into a newly created struct that has the same type as the provided struct, so the provided struct should either embed or be compatible with config.Runtime.

func (*Server) WithSelfSignedCertificate

func (s *Server) WithSelfSignedCertificate() *Server

WithSelfSignedCertificate configures the server to use a dynamically generated self-signed certificate for its TLS authentication. Because there is no way to verify the certificate used by the server, this option is typically only used in tests or very specialized circumstances where the connection to the server can be verified/authenticated using separate external mechanisms.

func (*Server) WithSigQuitHandlerWriter

func (s *Server) WithSigQuitHandlerWriter(w io.Writer) *Server

WithSigQuitHandlerWriter sets the output for the goroutine dump on SIGQUIT.

func (*Server) WithTraceSampler

func (s *Server) WithTraceSampler(traceSampler func(id uint64) bool) *Server

WithTraceSampler configures the server's trace log tracer to use the specified traceSampler function to make a determination on whether or not a trace should be sampled (if such a decision needs to be made).

type ServerState

type ServerState int32

const (
	ServerIdle ServerState = iota
	ServerInitializing
	ServerRunning
)

func (ServerState) String

func (s ServerState) String() string