Documentation
¶
Overview ¶
Package xweb provides facilities to creating composable xweb.WebHandlers and http.Server's from configuration files.
Basics ¶
xweb provides customizable and extendable components to stand up multiple http.Server's listening on one or more network interfaces.
Each xweb.Xweb is responsible for defining configuration sections to be parsed, parsing the configuration, starting servers, and shutting down relevant server. An example implementation is included in the package: xweb.XwebImpl. This implementation should cover most use cases. In addition xweb.XwebImpl makes use of xweb.Config which is reusable component for parsing xweb.XwebImpl configuration sections. Both xweb.Xweb xweb.Config assume that configuration will be acquired from some source and be presented as a map of interface{}-to-interface{} values (map[interface{}]interface{}) per the openziti/foundation config.Subconfig pattern.
xweb.Config configuration sections allow the definition of an array of xweb.WebListener. In turn each xweb.WebListener can listen on many interface/port combinations specified by an array of xweb.BindPoint and host many http.Handler's by defining an array of xweb.API's that are converted into xweb.WebHandler's. xweb.WebHandler's are http.Handler's with meta data and can be as complex or as simple as necessary - using other libraries or only the standard http Go capabilities.
To deal with a single xweb.WebListener hosting multiple APIs as web.WebListener's, incoming requests must be forwarded to the correct xweb.WebHandler. The responsibility is handled by another configurable http.Handler called an "xweb demux handler". This handler's responsibility is to inspect incoming requests and forward them to the correct xweb.WebHandler. It is specified by an xweb.DemuxFactory and a reference implementation, xweb.PathPrefixDemuxFactory has been provided.
Index ¶
- Constants
- type API
- type APIBinding
- type BindPoint
- type Config
- type ContextKey
- type DemuxFactory
- type Options
- type PathPrefixDemuxFactory
- type Server
- type TimeoutOptions
- type TlsVersionOptions
- type WebHandler
- type WebHandlerFactory
- type WebHandlerFactoryRegistry
- type WebHandlerFactoryRegistryImpl
- type WebListener
- type Xweb
- type XwebImpl
Constants ¶
const ( WebHandlerContextKey = ContextKey("XWebHandlerContextKey") BindPointContextKey = ContextKey("XWebBindPointContextKey") )
const ( DefaultIdentitySection = "identity" WebSection = "web" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
Represents some "api" or "site" by binding name. Each API configuration is used against a WebHandlerFactoryRegistry to locate the proper factory to generate a WebHandler. The options provided by this structure are parsed by the WebHandlerFactory and the behavior, valid keys, and valid values are not defined by xweb components, but by that WebHandlerFactory and it resulting WebHandler's.
func (*API) Binding ¶
Returns the string that uniquely identifies bo the WebHandlerFactory and resulting WebHandler's that will be attached to some WebListener and its resulting Server.
func (*API) Options ¶
func (api *API) Options() map[interface{}]interface{}
Returns the options associated with thsi API binding.
type APIBinding ¶
type APIBinding interface {
Binding() string
Options() map[interface{}]interface{}
}
An interface defines the minimum operations necessary to convert configuration into a WebHandler by some WebHandlerFactory The APIBinding.Binding() value is used to map configuration data to specific WebHandlerFactory instances that generate a WebHandler with the same binding value.
type BindPoint ¶
type BindPoint struct {
InterfaceAddress string // <interface>:<port>
Address string //<ip/host>:<port>
}
Represents the interface:port address of where a http.Server should listen for a WebListener and the public address that should be used to address it.
func ListenAddressFromContext ¶
Utility function to retrieve a BindPoint reference from the http.Request context that indicates what interface and port combo the incoming http.Request was handled on.
type Config ¶
type Config struct {
WebListeners []*WebListener
DefaultIdentityConfig *identity.IdentityConfig
DefaultIdentity identity.Identity
DefaultIdentitySection string
WebSection string
// contains filtered or unexported fields
}
The root configuration options necessary to start numerous http.Server instances via WebListener's.
func (*Config) Enabled ¶
Whether this configuration should be considered "enabled". Set to true after Validate passes.
func (*Config) Parse ¶
Parses a configuration map, looking for sections that define an identity.IdentityConfig and an array of WebListener's.
func (*Config) Validate ¶
func (config *Config) Validate(registry WebHandlerFactoryRegistry) error
Uses a WebHandlerFactoryRegistry to validate that all API bindings may be fulfilled. All other relevant Config values are also validated.
type ContextKey ¶
type ContextKey string
type DemuxFactory ¶
type DemuxFactory interface {
Build(handlers []WebHandler) (http.Handler, error)
}
Generates a http.Handler that interrogates a http.Request and routes them to WebHandlers. The selected WebHandler is added to the context with a key of WebHandlerContextKey. Each DemuxFactory implementation must define its own behaviors for an unmatched http.Request.
type Options ¶
type Options struct {
TimeoutOptions
TlsVersionOptions
}
The WebListener shared options configuration struct.
type PathPrefixDemuxFactory ¶
A DemuxFactory that routes http.Request requests to a specific WebHandler from a set of WebHandler's by URL path prefixes. a http.Handler for NoHandlerFound can be provided to specify behavior to perform when a WebHandler is not selected. By default an empty response with a http.StatusNotFound (404) will be sent.
func (*PathPrefixDemuxFactory) Build ¶
func (factory *PathPrefixDemuxFactory) Build(handlers []WebHandler) (http.Handler, error)
Performs WebHandler selection based on URL path prefixes
type Server ¶
type Server struct {
Handle http.Handler
OnHandlerPanic func(writer http.ResponseWriter, request *http.Request, panicVal interface{})
// contains filtered or unexported fields
}
Represents all of the http.Server's and http.Handler's necessary to run a single xweb.WebListener
func NewServer ¶
func NewServer(webListener *WebListener, demuxFactory DemuxFactory, handlerFactoryRegistry WebHandlerFactoryRegistry) (*Server, error)
Create a new xweb.Server from an xweb.WebListener. All necessary http.Handler's will be created from the supplied DemuxFactory and WebHandlerFactoryRegistry.
type TimeoutOptions ¶
type TimeoutOptions struct {
ReadTimeout time.Duration
IdleTimeout time.Duration
WriteTimeout time.Duration
}
Represents http timeout options
func (*TimeoutOptions) Default ¶
func (timeoutOptions *TimeoutOptions) Default()
Defaults all http. timeout options
func (*TimeoutOptions) Parse ¶
func (timeoutOptions *TimeoutOptions) Parse(config map[interface{}]interface{}) error
Parses a config map
func (*TimeoutOptions) Validate ¶
func (timeoutOptions *TimeoutOptions) Validate() error
Validtes all settings
type TlsVersionOptions ¶
type TlsVersionOptions struct {
MinTLSVersion int
MaxTLSVersion int
// contains filtered or unexported fields
}
Represents TLS version options
func (*TlsVersionOptions) Default ¶
func (tlsVersionOptions *TlsVersionOptions) Default()
Defaults TLS versions
func (*TlsVersionOptions) Parse ¶
func (tlsVersionOptions *TlsVersionOptions) Parse(config map[interface{}]interface{}) error
Parses a config map
func (*TlsVersionOptions) Validate ¶
func (tlsVersionOptions *TlsVersionOptions) Validate() error
Validates the configuration values
type WebHandler ¶
type WebHandler interface {
Binding() string
Options() map[interface{}]interface{}
RootPath() string
http.Handler
}
A http.Handler with options, binding, and information for a specific web API that was generated from a WebHandlerFactory.
func WebHandlerFromContext ¶
func WebHandlerFromContext(ctx context.Context) *WebHandler
Utility function to retrieve a WebHandler reference, that the demux http.Handler deferred to, during downstream http.Handler processing from the http.Request context.
type WebHandlerFactory ¶
type WebHandlerFactory interface {
Binding() string
New(webListener *WebListener, options map[interface{}]interface{}) (WebHandler, error)
}
Generates WebHandler instances. Factories can use a single instance or multiple instances based on need. This interface allows WebHandler logic to be reused across multiple xweb.Server's while delegating the instance management to the factory.
type WebHandlerFactoryRegistry ¶
type WebHandlerFactoryRegistry interface {
Add(factory WebHandlerFactory) error
Get(binding string) WebHandlerFactory
}
Describes a registry of binding to WebHandlerFactory registrations
type WebHandlerFactoryRegistryImpl ¶
type WebHandlerFactoryRegistryImpl struct {
// contains filtered or unexported fields
}
A basic WebHandlerFactoryRegistry implementation backed by a simple mapping of binding to WebHandlerFactories
func NewWebHandlerFactoryRegistryImpl ¶
func NewWebHandlerFactoryRegistryImpl() *WebHandlerFactoryRegistryImpl
Create a new WebHandlerFactoryRegistryImpl
func (WebHandlerFactoryRegistryImpl) Add ¶
func (registry WebHandlerFactoryRegistryImpl) Add(factory WebHandlerFactory) error
Adds a factory to the registry. Errors if a previous factory with the same binding is registered.
func (WebHandlerFactoryRegistryImpl) Get ¶
func (registry WebHandlerFactoryRegistryImpl) Get(binding string) WebHandlerFactory
Retrieves a factory based on a binding or nil if no factory for the binding is registered
type WebListener ¶
type WebListener struct {
Name string
APIs []*API
BindPoints []*BindPoint
Options Options
IdentityConfig *identity.IdentityConfig
Identity identity.Identity
DefaultIdentityConfig *identity.IdentityConfig
DefaultIdentity identity.Identity
}
The configuration that will eventually be used to create an xweb.Server (which in turn houses all of the components necessary to run multiple http.Server's).
func (*WebListener) Parse ¶
func (web *WebListener) Parse(webConfigMap map[interface{}]interface{}) error
Parses a configuration map to set all relavant WebListener values.
func (*WebListener) Validate ¶
func (web *WebListener) Validate(registry WebHandlerFactoryRegistry) error
Validates all WebListener values
type Xweb ¶
type Xweb interface {
Enabled() bool
LoadConfig(cfgmap map[interface{}]interface{}) error
Run()
Shutdown()
}
Implements config.Subconfig to allow Xweb implementations to be used during the normal Ziti component startup and configuration phase.
type XwebImpl ¶
type XwebImpl struct {
Config *Config
Registry WebHandlerFactoryRegistry
DemuxFactory DemuxFactory
// contains filtered or unexported fields
}
A simple implementation of xweb.XWeb used for registration and configuration from controller.Controller. Implements necessary interfaces to be a config.Subconfig.
func NewXwebImpl ¶
func NewXwebImpl(registry WebHandlerFactoryRegistry) *XwebImpl
func (*XwebImpl) LoadConfig ¶
Handle subconfig operations for xweb.Xweb components
Source Files