cors

Documentation

Index

• Variables
• type AllowOriginFunc
• type CORS
  • func New() *CORS
  • func (c *CORS) AllowHeaders(headers ...string) *CORS
  • func (c *CORS) AllowOrigin(originLine string) *CORS
  • func (c *CORS) AllowOriginFunc(fn AllowOriginFunc) *CORS
  • func (c *CORS) AllowOriginMatcherFunc(fn func(origin string) bool) *CORS
  • func (c *CORS) AllowOriginRegex(regexpLines ...string) *CORS
  • func (c *CORS) AllowOrigins(origins ...string) *CORS
  • func (c *CORS) DisallowCredentials() *CORS
  • func (c *CORS) ExposeHeaders(headers ...string) *CORS
  • func (c *CORS) ExtractOriginFunc(fn ExtractOriginFunc) *CORS
  • func (c *CORS) HandleErrorFunc(fn HandleErrorFunc) *CORS
  • func (c *CORS) Handler() context.Handler
  • func (c *CORS) MaxAge(d time.Duration) *CORS
  • func (c *CORS) ReferrerPolicy(referrerPolicy ReferrerPolicy) *CORS
• type ExtractOriginFunc
• type HandleErrorFunc
• type ReferrerPolicy
  • func (r ReferrerPolicy) String() string

Variables

var (
	// ErrOriginNotAllowed is given to the error handler
	// when the error is caused because an origin was not allowed to pass through.
	ErrOriginNotAllowed = errors.New("origin not allowed")

	// AllowAnyOrigin allows all origins to pass.
	AllowAnyOrigin = func(_ *context.Context, _ string) bool {
		return true
	}

	// DefaultErrorHandler is the default error handler which
	// fires forbidden status (403) on disallowed origins.
	DefaultErrorHandler = func(ctx *context.Context, _ error) {
		ctx.StopWithStatus(http.StatusForbidden)
	}

	// DefaultOriginExtractor is the default method which
	// an origin is extracted. It returns the value of the request's "Origin" header
	// and always true, means that it allows empty origin headers as well.
	DefaultOriginExtractor = func(ctx *context.Context) (string, bool) {
		header := ctx.GetHeader(originRequestHeader)
		return header, true
	}

	// StrictOriginExtractor is an ExtractOriginFunc type
	// which is a bit more strictly than the DefaultOriginExtractor.
	// It allows only non-empty "Origin" header values to be passed.
	// If the header is missing, the middleware will not allow the execution
	// of the next handler(s).
	StrictOriginExtractor = func(ctx *context.Context) (string, bool) {
		header := ctx.GetHeader(originRequestHeader)
		return header, header != ""
	}
)

Types

type AllowOriginFunc

type AllowOriginFunc = func(ctx *context.Context, origin string) bool

AllowOriginFunc describes the function which is called when the middleware decides if the request's origin should be allowed or not.

type CORS

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

CORS holds the customizations developers can do on the cors middleware.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS.

func New

func New() *CORS

New returns the default CORS middleware. For a more advanced type of protection middleware with more options please refer to: https://github.com/iris-contrib/middleware repository instead.

Example Code:

	import "github.com/kataras/iris/v12/middleware/cors"
 import "github.com/kataras/iris/v12/x/errors"

 app.UseRouter(cors.New().
     HandleErrorFunc(func(ctx iris.Context, err error) {
         errors.FailedPrecondition.Err(ctx, err)
     }).
     ExtractOriginFunc(cors.StrictOriginExtractor).
     ReferrerPolicy(cors.NoReferrerWhenDowngrade).
     AllowOrigin("domain1.com,domain2.com,domain3.com").
     Handler())

func (*CORS) AllowHeaders

func (c *CORS) AllowHeaders(headers ...string) *CORS

AllowHeaders sets the "Access-Control-Allow-Headers" header value.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-headers.

func (*CORS) AllowOrigin

func (c *CORS) AllowOrigin(originLine string) *CORS

AllowOrigin calls the "AllowOriginFunc" method and registers a function which accepts any incoming request with origin of the given "originLine". The originLine can contain one or more domains separated by comma. See "AllowOrigins" to set a list of strings instead.

func (*CORS) AllowOriginFunc

func (c *CORS) AllowOriginFunc(fn AllowOriginFunc) *CORS

AllowOriginFunc sets the function which decides if an origin(domain) is allowed to continue or not.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-origin.

func (*CORS) AllowOriginMatcherFunc

func (c *CORS) AllowOriginMatcherFunc(fn func(origin string) bool) *CORS

AllowOriginMatcherFunc sets the allow origin func without iris.Context as its first parameter, i.e. a regular expression.

func (*CORS) AllowOriginRegex

func (c *CORS) AllowOriginRegex(regexpLines ...string) *CORS

AllowOriginRegex calls the "AllowOriginFunc" method and registers a function which accepts any incoming request with origin that matches at least one of the given "regexpLines".

func (*CORS) AllowOrigins

func (c *CORS) AllowOrigins(origins ...string) *CORS

AllowOrigins calls the "AllowOriginFunc" method and registers a function which accepts any incoming request with origin of one of the given "origins".

func (*CORS) DisallowCredentials

func (c *CORS) DisallowCredentials() *CORS

DisallowCredentials sets the "Access-Control-Allow-Credentials" header to false.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-allow-credentials.

func (*CORS) ExposeHeaders

func (c *CORS) ExposeHeaders(headers ...string) *CORS

ExposeHeaders sets the "Access-Control-Expose-Headers" header value.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-expose-headers.

func (*CORS) ExtractOriginFunc

func (c *CORS) ExtractOriginFunc(fn ExtractOriginFunc) *CORS

ExtractOriginFunc sets the function which should return the request's origin.

func (*CORS) HandleErrorFunc

func (c *CORS) HandleErrorFunc(fn HandleErrorFunc) *CORS

HandleErrorFunc sets the function which is called when an error of origin not allowed is fired.

func (*CORS) Handler

func (c *CORS) Handler() context.Handler

Handler method returns the Iris CORS Handler with basic features. Note that the caller should NOT modify any of the CORS instance fields afterwards.

func (*CORS) MaxAge

func (c *CORS) MaxAge(d time.Duration) *CORS

MaxAge sets the "Access-Control-Max-Age" header value.

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#access-control-max-age.

func (*CORS) ReferrerPolicy

func (c *CORS) ReferrerPolicy(referrerPolicy ReferrerPolicy) *CORS

ReferrerPolicy sets the "Referrer-Policy" header value. Defaults to "no-referrer-when-downgrade".

Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy and https://developer.mozilla.org/en-US/docs/Web/Security/Referer_header:_privacy_and_security_concerns.

type ExtractOriginFunc

type ExtractOriginFunc = func(ctx *context.Context) (string, bool)

ExtractOriginFunc describes the function which should return the request's origin or false.

type HandleErrorFunc

type HandleErrorFunc = func(ctx *context.Context, err error)

HandleErrorFunc describes the function which is fired when a request by a specific (or empty) origin was not allowed to pass through.

type ReferrerPolicy

type ReferrerPolicy string

ReferrerPolicy type for referrer-policy header value.

const (
	NoReferrer                  ReferrerPolicy = "no-referrer"
	NoReferrerWhenDowngrade     ReferrerPolicy = "no-referrer-when-downgrade"
	Origin                      ReferrerPolicy = "origin"
	OriginWhenCrossOrigin       ReferrerPolicy = "origin-when-cross-origin"
	SameOrigin                  ReferrerPolicy = "same-origin"
	StrictOrigin                ReferrerPolicy = "strict-origin"
	StrictOriginWhenCrossOrigin ReferrerPolicy = "strict-origin-when-cross-origin"
	UnsafeURL                   ReferrerPolicy = "unsafe-url"
)

All available referrer policies. Read more at: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy.

func (ReferrerPolicy) String

func (r ReferrerPolicy) String() string

String returns the text representation of the "r" ReferrerPolicy.