cors

Documentation

Index

• type Cors
  • func New() *Cors
  • func (plugin *Cors) Configure(opts *Options) *Cors
  • func (plugin *Cors) Default() *Cors
  • func (plugin *Cors) Handle(c *verto.Context, next http.HandlerFunc)
• type Options

Types

type Cors

type Cors struct {
	plugins.Core
	// contains filtered or unexported fields
}

Cors is the verto plugin that handles CORS requests based on a given configuration.

Example usage:

cors := NewCors().Configure(&CorsOptions{
	AllowedOrigins: []string{"*"},
	AllowedHeadersFn:  func(h []string) bool {
		// This is functionally equivalent
		// to AllowHeaders: []string{"*"}
		return true
	},
	AllowedMethods: []string{"GET", "POST"}
})

func New

func New() *Cors

NewCors returns a new Cors plugin instance that is unconfigured. It is best practice to call either the Configure or Default functions immediately on the newly instantiated plugin instance

func (*Cors) Configure

func (plugin *Cors) Configure(opts *Options) *Cors

Configure configures the Cors plugin according to the passed in options. Each consecutive call to Configure will first create a fresh instance of a cors plugin before configuring the plugin. As such, it is generally recommended to only call the Configure function once immediately after instantiating a new Cors plugin and to not mix the call with a call to Default.

Example:

cors := NewCors().Configure(&CorsOptions{
	...
})

func (*Cors) Default

func (plugin *Cors) Default() *Cors

Default configures a Cors instance to use sensible default options. Each consective call to Default will instantiate a fresh Cors plugin instance. As such, it is generally recommended to only call Default once after instantiating a new Cors plugin instance and to not mix the call with a call to Configure.

Example:

cors := NewCors().Default()

func (*Cors) Handle

func (plugin *Cors) Handle(c *verto.Context, next http.HandlerFunc)

Handle is called per web request to handle the validation and writing of relevant CORS headers from incoming requests.

type Options

type Options struct {
	// AllowedOrigins designates a series of origins
	// as allowable for the 'Origin' header of incoming
	// requests. AllowedOrigins recognizes the wildcard
	// designation '*'. If AllowedOriginsFn is included,
	// it takes precedence over AllowedOrigins.
	AllowedOrigins []string

	// AllowedOriginsFn is a function that takes in an
	// origin and returns if it is allowable. If this
	// function is non-nil, it takes precedence over AllowedOrigins
	AllowedOriginsFn func(string) bool

	// ExposedHeaders designates a series of headers for the server
	// to expose in the 'Access-Control-Expose-Headers' header
	ExposedHeaders []string

	// AllowedHeaders designates a series of headers as allowable
	// for the 'Access-Control-Requested-Headers' header of incoming
	// requests. AllowedHeaders recognizes the wildcard designation '*'.
	// If AllowedHeadersFn is included, it takes precedence over AllowedHeaders
	AllowedHeaders []string

	// AllowedHeadersFn is a function that takes in a series of headers and
	// returns if they are allowable. If this function is non-nil, it takes
	// precedence over AllowedHeaders
	AllowedHeadersFn func([]string) bool

	// AllowedMethods designates a series of methods as allowable, either
	// per the request method for direct requests or per the 'Access-Control-Request-Method'
	// header on preflight requests. AllowedMethods recognizes the wildcard designation '*'.
	AllowedMethods []string

	// MaxAge is an optional field that designates the duration in seconds of
	// the 'Access-Control-Max-Age' header for preflight requests. If included,
	// MaxAge must be at least 1 second in duration
	MaxAge time.Duration

	// AllowCredentials is an optional field that sets the 'Access-Control-Allow-Credentials' header
	AllowCredentials bool
}

Options is a struct containing Cors plugin configuration options. MaxAge, if included, must be at least 1 second long. AllowedOrigins, AllowedHeaders, and AllowedMethods all support the wildcard designation '*'. If a wildcard is included, it should be the only string in the slice as it renders all other strings meaningless.

Note: It is good security practice to explicitly define allowed origins, methods and headers instead of relying on a wildcard.