cors

README

Go CORS handler

CORS is a net/http handler implementing Cross Origin Resource Sharing W3 specification in Golang.

Getting Started

After installing Go and setting up your GOPATH, create your first .go file. We'll call it server.go.

package main

import (
    "net/http"

    "github.com/rs/cors"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte("{\"hello\": \"world\"}"))
    })

    // cors.Default() setup the middleware with default options being
    // all origins accepted with simple methods (GET, POST). See
    // documentation below for more options.
    handler := cors.Default().Handler(mux)
    http.ListenAndServe(":8080", handler)
}

Install cors:

go get github.com/rs/cors

Then run your server:

go run server.go

The server now runs on localhost:8080:

$ curl -D - -H 'Origin: http://foo.com' http://localhost:8080/
HTTP/1.1 200 OK
Access-Control-Allow-Origin: foo.com
Content-Type: application/json
Date: Sat, 25 Oct 2014 03:43:57 GMT
Content-Length: 18

{"hello": "world"}

Allow * With Credentials Security Protection

This library has been modified to avoid a well known security issue when configured with AllowedOrigins to * and AllowCredentials to true. Such setup used to make the library reflects the request Origin header value, working around a security protection embedded into the standard that makes clients to refuse such configuration. This behavior has been removed with #55 and #57.

If you depend on this behavior and understand the implications, you can restore it using the AllowOriginFunc with func(origin string) {return true}.

Please refer to #55 for more information about the security implications.

More Examples

• net/http: examples/nethttp/server.go
• Goji: examples/goji/server.go
• Martini: examples/martini/server.go
• Negroni: examples/negroni/server.go
• Alice: examples/alice/server.go
• HttpRouter: examples/httprouter/server.go
• Gorilla: examples/gorilla/server.go
• Buffalo: examples/buffalo/server.go
• Gin: examples/gin/server.go
• Chi: examples/chi/server.go

Parameters

Parameters are passed to the middleware thru the cors.New method as follow:

c := cors.New(cors.Options{
    AllowedOrigins: []string{"http://foo.com", "http://foo.com:8080"},
    AllowCredentials: true,
    // Enable Debugging for testing, consider disabling in production
    Debug: true,
})

// Insert the middleware
handler = c.Handler(handler)

• AllowedOrigins []string: A list of origins a cross-domain request can be executed from. If the special * value is present in the list, all origins will be allowed. An origin may contain a wildcard (*) to replace 0 or more characters (i.e.: http://*.domain.com). Usage of wildcards implies a small performance penality. Only one wildcard can be used per origin. The default value is *.
• AllowOriginFunc func (origin string) bool: A custom function to validate the origin. It takes the origin as an argument and returns true if allowed, or false otherwise. If this option is set, the content of AllowedOrigins is ignored.
• AllowOriginRequestFunc func (r *http.Request, origin string) bool: A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise. If this option is set, the contents of AllowedOrigins and AllowOriginFunc are ignored. Deprecated: use AllowOriginVaryRequestFunc instead.
• AllowOriginVaryRequestFunc func(r *http.Request, origin string) (bool, []string): A custom function to validate the origin. It takes the HTTP Request object and the origin as argument and returns true if allowed or false otherwise with a list of headers used to take that decision if any so they can be added to the Vary header. If this option is set, the contents of AllowedOrigins, AllowOriginFunc and AllowOriginRequestFunc are ignored.
• AllowedMethods []string: A list of methods the client is allowed to use with cross-domain requests. Default value is simple methods (GET and POST).
• AllowedHeaders []string: A list of non simple headers the client is allowed to use with cross-domain requests.
• ExposedHeaders []string: Indicates which headers are safe to expose to the API of a CORS API specification.
• AllowCredentials bool: Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates. The default is false.
• AllowPrivateNetwork bool: Indicates whether to accept cross-origin requests over a private network.
• MaxAge int: Indicates how long (in seconds) the results of a preflight request can be cached. The default is 0 which stands for no max age.
• OptionsPassthrough bool: Instructs preflight to let other potential next handlers to process the OPTIONS method. Turn this on if your application handles OPTIONS.
• OptionsSuccessStatus int: Provides a status code to use for successful OPTIONS requests. Default value is http.StatusNoContent (204).
• Debug bool: Debugging flag adds additional output to debug server side CORS issues.

See API documentation for more info.

Benchmarks

goos: darwin
goarch: arm64
pkg: github.com/rs/cors
BenchmarkWithout-10            	135325480	         8.124 ns/op	       0 B/op	       0 allocs/op
BenchmarkDefault-10            	24082140	        51.40 ns/op	       0 B/op	       0 allocs/op
BenchmarkAllowedOrigin-10      	16424518	        88.25 ns/op	       0 B/op	       0 allocs/op
BenchmarkPreflight-10          	 8010259	       147.3 ns/op	       0 B/op	       0 allocs/op
BenchmarkPreflightHeader-10    	 6850962	       175.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkWildcard/match-10     	253275342	         4.714 ns/op	       0 B/op	       0 allocs/op
BenchmarkWildcard/too_short-10 	1000000000	         0.6235 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	github.com/rs/cors	99.131s

Licenses

All source code is licensed under the MIT License.

Documentation

Overview

Package cors is net/http handler to handle CORS related requests as defined by http://www.w3.org/TR/cors/

You can configure it by passing an option struct to cors.New:

c := cors.New(cors.Options{
    AllowedOrigins:   []string{"foo.com"},
    AllowedMethods:   []string{http.MethodGet, http.MethodPost, http.MethodDelete},
    AllowCredentials: true,
})

Then insert the handler in the chain:

handler = c.Handler(handler)

See Options documentation for more options.

The resulting handler is a standard net/http handler.

Index

• type Cors
  • func AllowAll() *Cors
  • func Default() *Cors
  • func New(options Options) *Cors
  • func (c *Cors) Handler(h http.Handler) http.Handler
  • func (c *Cors) HandlerFunc(w http.ResponseWriter, r *http.Request)
  • func (c *Cors) OriginAllowed(r *http.Request) bool
  • func (c *Cors) ServeHTTP(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• type Logger
• type Options

Types

type Cors

type Cors struct {
	// Debug logger
	Log Logger
	// contains filtered or unexported fields
}

Cors http handler

func AllowAll

func AllowAll() *Cors

AllowAll create a new Cors handler with permissive configuration allowing all origins with all standard methods with any header and credentials.

func Default

func Default() *Cors

Default creates a new Cors handler with default options.

func New

func New(options Options) *Cors

New creates a new Cors handler with the provided options.

func (*Cors) Handler

func (c *Cors) Handler(h http.Handler) http.Handler

Handler apply the CORS specification on the request, and add relevant CORS headers as necessary.

func (*Cors) HandlerFunc

func (c *Cors) HandlerFunc(w http.ResponseWriter, r *http.Request)

HandlerFunc provides Martini compatible handler

func (*Cors) OriginAllowed

func (c *Cors) OriginAllowed(r *http.Request) bool

check the Origin of a request. No origin at all is also allowed.

func (*Cors) ServeHTTP

func (c *Cors) ServeHTTP(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

Negroni compatible interface

type Logger

type Logger interface {
	Printf(string, ...interface{})
}

Logger generic interface for logger

type Options

type Options struct {
	// AllowedOrigins is a list of origins a cross-domain request can be executed from.
	// If the special "*" value is present in the list, all origins will be allowed.
	// An origin may contain a wildcard (*) to replace 0 or more characters
	// (i.e.: http://*.domain.com). Usage of wildcards implies a small performance penalty.
	// Only one wildcard can be used per origin.
	// Default value is ["*"]
	AllowedOrigins []string
	// AllowOriginFunc is a custom function to validate the origin. It take the
	// origin as argument and returns true if allowed or false otherwise. If
	// this option is set, the content of `AllowedOrigins` is ignored.
	AllowOriginFunc func(origin string) bool
	// AllowOriginRequestFunc is a custom function to validate the origin. It
	// takes the HTTP Request object and the origin as argument and returns true
	// if allowed or false otherwise. If headers are used take the decision,
	// consider using AllowOriginVaryRequestFunc instead. If this option is set,
	// the contents of `AllowedOrigins`, `AllowOriginFunc` are ignored.
	//
	// Deprecated: use `AllowOriginVaryRequestFunc` instead.
	AllowOriginRequestFunc func(r *http.Request, origin string) bool
	// AllowOriginVaryRequestFunc is a custom function to validate the origin.
	// It takes the HTTP Request object and the origin as argument and returns
	// true if allowed or false otherwise with a list of headers used to take
	// that decision if any so they can be added to the Vary header. If this
	// option is set, the contents of `AllowedOrigins`, `AllowOriginFunc` and
	// `AllowOriginRequestFunc` are ignored.
	AllowOriginVaryRequestFunc func(r *http.Request, origin string) (bool, []string)
	// AllowedMethods is a list of methods the client is allowed to use with
	// cross-domain requests. Default value is simple methods (HEAD, GET and POST).
	AllowedMethods []string
	// AllowedHeaders is list of non simple headers the client is allowed to use with
	// cross-domain requests.
	// If the special "*" value is present in the list, all headers will be allowed.
	// Default value is [].
	AllowedHeaders []string
	// ExposedHeaders indicates which headers are safe to expose to the API of a CORS
	// API specification
	ExposedHeaders []string
	// MaxAge indicates how long (in seconds) the results of a preflight request
	// can be cached. Default value is 0, which stands for no
	// Access-Control-Max-Age header to be sent back, resulting in browsers
	// using their default value (5s by spec). If you need to force a 0 max-age,
	// set `MaxAge` to a negative value (ie: -1).
	MaxAge int
	// AllowCredentials indicates whether the request can include user credentials like
	// cookies, HTTP authentication or client side SSL certificates.
	AllowCredentials bool
	// AllowPrivateNetwork indicates whether to accept cross-origin requests over a
	// private network.
	AllowPrivateNetwork bool
	// OptionsPassthrough instructs preflight to let other potential next handlers to
	// process the OPTIONS method. Turn this on if your application handles OPTIONS.
	OptionsPassthrough bool
	// Provides a status code to use for successful OPTIONS requests.
	// Default value is http.StatusNoContent (204).
	OptionsSuccessStatus int
	// Debugging flag adds additional output to debug server side CORS issues
	Debug bool
	// Adds a custom logger, implies Debug is true
	Logger Logger
}

Options is a configuration container to setup the CORS middleware.