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 and ports.
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 and xweb.Config assume that configuration will be acquired from some source and be presented as a map of interface{}-to-interface{} values.
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's 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.
Another way to say it: each Xweb defines a configuration section (default `web`) to define WebListener's and their hosted APIs. Each WebListener maps to one http.Server per BindPoint. No two WebListeners can have colliding BindPoint's due to port conflicts.
Index ¶
- Constants
- Variables
- type API
- type APIBinding
- type BindPoint
- type Config
- type ContextKey
- type DemuxFactory
- type IsHandledDemuxFactory
- type Options
- type PathPrefixDemuxFactory
- type Server
- type TimeoutOptions
- type TlsVersionOptions
- type WebHandler
- type WebHandlerFactory
- type WebHandlerFactoryRegistry
- type WebHandlerFactoryRegistryImpl
- type WebListener
- type XWebContext
- type Xweb
- type XwebImpl
Constants ¶
const ( MinTLSVersion = tls.VersionTLS12 MaxTLSVersion = tls.VersionTLS13 DefaultHttpWriteTimeout = time.Second * 10 DefaultHttpReadTimeout = time.Second * 5 DefaultHttpIdleTimeout = time.Second * 5 )
const ( WebHandlerContextKey = ContextKey("XWebHandlerContextKey") WebContextKey = ContextKey("XWebContext") ZitiCtrlAddressHeader = "ziti-ctrl-address" )
const ( DefaultIdentitySection = "identity" WebSection = "web" )
Variables ¶
var ReverseTlsVersionMap = map[int]string{ tls.VersionTLS10: "TLS1.0", tls.VersionTLS11: "TLS1.1", tls.VersionTLS12: "TLS1.2", tls.VersionTLS13: "TLS1.3", }
ReverseTlsVersionMap is a map of TLS version identifiers to configuration strings
var TlsVersionMap = map[string]int{ "TLS1.0": tls.VersionTLS10, "TLS1.1": tls.VersionTLS11, "TLS1.2": tls.VersionTLS12, "TLS1.3": tls.VersionTLS13, }
TlsVersionMap is a map of configuration strings to TLS version identifiers
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
API 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 its resulting WebHandler's.
func (*API) Binding ¶
Binding returns the string that uniquely identifies bo the WebHandlerFactory and resulting WebHandler instances that will be attached to some WebListener and its resulting Server.
func (*API) Options ¶
func (api *API) Options() map[interface{}]interface{}
Options returns the options associated with this API binding.
type APIBinding ¶
type APIBinding interface {
Binding() string
Options() map[interface{}]interface{}
}
APIBinding is 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>
NewAddress string //<ip/host>:<port> sent out as a header for clients to alternatively swap to (ip -> hostname moves)
}
BindPoint 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.
type Config ¶
type Config struct {
SourceConfig map[interface{}]interface{}
WebListeners []*WebListener
WebSection string
DefaultIdentity identity.Identity
DefaultIdentitySection string
// contains filtered or unexported fields
}
Config is the root configuration options necessary to start numerous http.Server instances via WebListener's.
func (*Config) Enabled ¶
Enabled returns true/false on whether this configuration should be considered "enabled". Set to true after Validate passes.
func (*Config) Parse ¶
Parse parses a configuration map, looking for sections that define an identity.Config and an array of WebListener's.
func (*Config) Validate ¶
func (config *Config) Validate(registry WebHandlerFactoryRegistry) error
Validate 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)
}
DemuxFactory 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 IsHandledDemuxFactory ¶
IsHandledDemuxFactory is a DemuxFactory that routes http.Request requests to a specific WebHandler by delegating to the WebHandler's IsHandled function.
func (*IsHandledDemuxFactory) Build ¶
func (factory *IsHandledDemuxFactory) Build(handlers []WebHandler) (http.Handler, error)
Build performs WebHandler selection based on IsHandled()
type Options ¶
type Options struct {
TimeoutOptions
TlsVersionOptions
}
Options is the shared options for a WebListener.
type PathPrefixDemuxFactory ¶
PathPrefixDemuxFactory is 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)
Build 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{})
ParentWebListener *WebListener
// contains filtered or unexported fields
}
Server 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, config *Config) (*Server, error)
NewServer creates 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
}
TimeoutOptions represents http timeout options
func (*TimeoutOptions) Default ¶
func (timeoutOptions *TimeoutOptions) Default()
Default defaults all HTTP timeout options
func (*TimeoutOptions) Parse ¶
func (timeoutOptions *TimeoutOptions) Parse(config map[interface{}]interface{}) error
Parse parses a config map
func (*TimeoutOptions) Validate ¶
func (timeoutOptions *TimeoutOptions) Validate() error
Validate validates all settings and return nil or an error
type TlsVersionOptions ¶
type TlsVersionOptions struct {
MinTLSVersion int
MaxTLSVersion int
// contains filtered or unexported fields
}
TlsVersionOptions represents TLS version options
func (*TlsVersionOptions) Default ¶
func (tlsVersionOptions *TlsVersionOptions) Default()
Default defaults TLS versions
func (*TlsVersionOptions) Parse ¶
func (tlsVersionOptions *TlsVersionOptions) Parse(config map[interface{}]interface{}) error
Parse parses a config map
func (*TlsVersionOptions) Validate ¶
func (tlsVersionOptions *TlsVersionOptions) Validate() error
Validate validates the configuration values and returns nil or error
type WebHandler ¶
type WebHandler interface {
Binding() string
Options() map[interface{}]interface{}
RootPath() string
IsHandler(r *http.Request) bool
http.Handler
}
WebHandler is an interface that is a http.Handler with options, binding, and information for a specific web API that was generated from a WebHandlerFactory.
func WebHandlerFromRequestContext ¶
func WebHandlerFromRequestContext(ctx context.Context) *WebHandler
WebHandlerFromRequestContext us a 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 returns the string binding value used in configurations
Binding() string
// New creates a new instances of this factories API
New(webListener *WebListener, options map[interface{}]interface{}) (WebHandler, error)
// Validate is used for factory level configuration checks. It is not meant for individual instance validation.
// It is meant for validating configuration that all instances generated by a factory share (i.e. sanity across
// instances or configuration from another section).
Validate(config *Config) error
}
The WebHandlerFactory interface 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
}
WebHandlerFactoryRegistry describes a registry of binding to WebHandlerFactory registrations
type WebHandlerFactoryRegistryImpl ¶
type WebHandlerFactoryRegistryImpl struct {
// contains filtered or unexported fields
}
WebHandlerFactoryRegistryImpl is a basic WebHandlerFactoryRegistry implementation backed by a simple mapping of binding (string) to WebHandlerFactories
func NewWebHandlerFactoryRegistryImpl ¶
func NewWebHandlerFactoryRegistryImpl() *WebHandlerFactoryRegistryImpl
NewWebHandlerFactoryRegistryImpl creates a new WebHandlerFactoryRegistryImpl
func (WebHandlerFactoryRegistryImpl) Add ¶
func (registry WebHandlerFactoryRegistryImpl) Add(factory WebHandlerFactory) error
Add 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
Get 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
DefaultIdentity identity.Identity
Identity identity.Identity
}
WebListener is the configuration that will eventually be used to create an xweb.Server (which in turn houses all the components necessary to run multiple http.Server's).
func (*WebListener) Parse ¶
func (web *WebListener) Parse(webConfigMap map[interface{}]interface{}, pathContext string) error
Parse parses a configuration map to set all relevant WebListener values.
func (*WebListener) Validate ¶
func (web *WebListener) Validate(registry WebHandlerFactoryRegistry) error
Validate all WebListener values
type XWebContext ¶
type XWebContext struct {
BindPoint *BindPoint
WebListener *WebListener
XWebConfig *Config
}
func WebContextFromRequestContext ¶
func WebContextFromRequestContext(ctx context.Context) *XWebContext
WebContextFromRequestContext is a utility function to retrieve a *XWebContext reference from the http.Request that provides access to XWeb configuration like BindPoint, WebListener, and Config values.
type Xweb ¶
type Xweb interface {
Enabled() bool
LoadConfig(cfgmap map[interface{}]interface{}) error
Run()
Shutdown()
}
Xweb 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
}
XwebImpl is 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, defaultIdentity identity.Identity) *XwebImpl
func (*XwebImpl) Enabled ¶
Enabled returns true/false on whether this subconfig should be considered enabled
func (*XwebImpl) LoadConfig ¶
LoadConfig handles subconfig operations for xweb.Xweb components
Source Files
Directories