README.md
1# Go CORS handler [](https://godoc.org/github.com/rs/cors) [](https://raw.githubusercontent.com/rs/cors/master/LICENSE) [](https://travis-ci.org/rs/cors) [](http://gocover.io/github.com/rs/cors)
2
3CORS is a `net/http` handler implementing [Cross Origin Resource Sharing W3 specification](http://www.w3.org/TR/cors/) in Golang.
4
5## Getting Started
6
7After installing Go and setting up your [GOPATH](http://golang.org/doc/code.html#GOPATH), create your first `.go` file. We'll call it `server.go`.
8
9```go
10package main
11
12import (
13 "net/http"
14
15 "github.com/rs/cors"
16)
17
18func main() {
19 mux := http.NewServeMux()
20 mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
21 w.Header().Set("Content-Type", "application/json")
22 w.Write([]byte("{\"hello\": \"world\"}"))
23 })
24
25 // cors.Default() setup the middleware with default options being
26 // all origins accepted with simple methods (GET, POST). See
27 // documentation below for more options.
28 handler := cors.Default().Handler(mux)
29 http.ListenAndServe(":8080", handler)
30}
31```
32
33Install `cors`:
34
35 go get github.com/rs/cors
36
37Then run your server:
38
39 go run server.go
40
41The server now runs on `localhost:8080`:
42
43 $ curl -D - -H 'Origin: http://foo.com' http://localhost:8080/
44 HTTP/1.1 200 OK
45 Access-Control-Allow-Origin: foo.com
46 Content-Type: application/json
47 Date: Sat, 25 Oct 2014 03:43:57 GMT
48 Content-Length: 18
49
50 {"hello": "world"}
51
52### Allow * With Credentials Security Protection
53
54This 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](https://github.com/rs/cors/issues/55) and [#57](https://github.com/rs/cors/issues/57).
55
56If you depend on this behavior and understand the implications, you can restore it using the `AllowOriginFunc` with `func(origin string) {return true}`.
57
58Please refer to [#55](https://github.com/rs/cors/issues/55) for more information about the security implications.
59
60### More Examples
61
62* `net/http`: [examples/nethttp/server.go](https://github.com/rs/cors/blob/master/examples/nethttp/server.go)
63* [Goji](https://goji.io): [examples/goji/server.go](https://github.com/rs/cors/blob/master/examples/goji/server.go)
64* [Martini](http://martini.codegangsta.io): [examples/martini/server.go](https://github.com/rs/cors/blob/master/examples/martini/server.go)
65* [Negroni](https://github.com/codegangsta/negroni): [examples/negroni/server.go](https://github.com/rs/cors/blob/master/examples/negroni/server.go)
66* [Alice](https://github.com/justinas/alice): [examples/alice/server.go](https://github.com/rs/cors/blob/master/examples/alice/server.go)
67* [HttpRouter](https://github.com/julienschmidt/httprouter): [examples/httprouter/server.go](https://github.com/rs/cors/blob/master/examples/httprouter/server.go)
68* [Gorilla](http://www.gorillatoolkit.org/pkg/mux): [examples/gorilla/server.go](https://github.com/rs/cors/blob/master/examples/gorilla/server.go)
69* [Buffalo](https://gobuffalo.io): [examples/buffalo/server.go](https://github.com/rs/cors/blob/master/examples/buffalo/server.go)
70* [Gin](https://gin-gonic.github.io/gin): [examples/gin/server.go](https://github.com/rs/cors/blob/master/examples/gin/server.go)
71* [Chi](https://github.com/go-chi/chi): [examples/chi/server.go](https://github.com/rs/cors/blob/master/examples/chi/server.go)
72
73## Parameters
74
75Parameters are passed to the middleware thru the `cors.New` method as follow:
76
77```go
78c := cors.New(cors.Options{
79 AllowedOrigins: []string{"http://foo.com", "http://foo.com:8080"},
80 AllowCredentials: true,
81 // Enable Debugging for testing, consider disabling in production
82 Debug: true,
83})
84
85// Insert the middleware
86handler = c.Handler(handler)
87```
88
89* **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 `*`.
90* **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.
91* **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 content of `AllowedOrigins` and `AllowOriginFunc` is ignored
92* **AllowedMethods** `[]string`: A list of methods the client is allowed to use with cross-domain requests. Default value is simple methods (`GET` and `POST`).
93* **AllowedHeaders** `[]string`: A list of non simple headers the client is allowed to use with cross-domain requests.
94* **ExposedHeaders** `[]string`: Indicates which headers are safe to expose to the API of a CORS API specification
95* **AllowCredentials** `bool`: Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates. The default is `false`.
96* **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.
97* **OptionsPassthrough** `bool`: Instructs preflight to let other potential next handlers to process the `OPTIONS` method. Turn this on if your application handles `OPTIONS`.
98* **Debug** `bool`: Debugging flag adds additional output to debug server side CORS issues.
99
100See [API documentation](http://godoc.org/github.com/rs/cors) for more info.
101
102## Benchmarks
103
104 BenchmarkWithout 20000000 64.6 ns/op 8 B/op 1 allocs/op
105 BenchmarkDefault 3000000 469 ns/op 114 B/op 2 allocs/op
106 BenchmarkAllowedOrigin 3000000 608 ns/op 114 B/op 2 allocs/op
107 BenchmarkPreflight 20000000 73.2 ns/op 0 B/op 0 allocs/op
108 BenchmarkPreflightHeader 20000000 73.6 ns/op 0 B/op 0 allocs/op
109 BenchmarkParseHeaderList 2000000 847 ns/op 184 B/op 6 allocs/op
110 BenchmarkParse…Single 5000000 290 ns/op 32 B/op 3 allocs/op
111 BenchmarkParse…Normalized 2000000 776 ns/op 160 B/op 6 allocs/op
112
113## Licenses
114
115All source code is licensed under the [MIT License](https://raw.github.com/rs/cors/master/LICENSE).
116
){kind=link}
){kind=link}
){kind=link}