git.sr.ht/~pingoo/stdx@v0.0.0-20240218134121-094174641f6e/httpx/cors/README.md (about)

     1  # Go CORS handler [![godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/git.sr.ht/~pingoo/stdx/cors) [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://raw.githubusercontent.com/rs/cors/master/LICENSE) [![build](https://img.shields.io/travis/rs/cors.svg?style=flat)](https://travis-ci.org/rs/cors) [![Coverage](http://gocover.io/_badge/git.sr.ht/~pingoo/stdx/cors)](http://gocover.io/git.sr.ht/~pingoo/stdx/cors)
     2  
     3  CORS 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  
     7  After 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
    10  package main
    11  
    12  import (
    13      "net/http"
    14  
    15      "git.sr.ht/~pingoo/stdx/cors"
    16  )
    17  
    18  func 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  
    33  Install `cors`:
    34  
    35      go get git.sr.ht/~pingoo/stdx/cors
    36  
    37  Then run your server:
    38  
    39      go run server.go
    40  
    41  The 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  
    54  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](https://git.sr.ht/~pingoo/stdx/cors/issues/55) and [#57](https://git.sr.ht/~pingoo/stdx/cors/issues/57).
    55  
    56  If you depend on this behavior and understand the implications, you can restore it using the `AllowOriginFunc` with `func(origin string) {return true}`.
    57  
    58  Please refer to [#55](https://git.sr.ht/~pingoo/stdx/cors/issues/55) for more information about the security implications.
    59  
    60  ### More Examples
    61  
    62  * `net/http`: [examples/nethttp/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/nethttp/server.go)
    63  * [Goji](https://goji.io): [examples/goji/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/goji/server.go)
    64  * [Martini](http://martini.codegangsta.io): [examples/martini/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/martini/server.go)
    65  * [Negroni](https://github.com/codegangsta/negroni): [examples/negroni/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/negroni/server.go)
    66  * [Alice](https://github.com/justinas/alice): [examples/alice/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/alice/server.go)
    67  * [HttpRouter](https://github.com/julienschmidt/httprouter): [examples/httprouter/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/httprouter/server.go)
    68  * [Gorilla](http://www.gorillatoolkit.org/pkg/mux): [examples/gorilla/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/gorilla/server.go)
    69  * [Buffalo](https://gobuffalo.io): [examples/buffalo/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/buffalo/server.go)
    70  * [Gin](https://gin-gonic.github.io/gin): [examples/gin/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/gin/server.go)
    71  * [Chi](https://github.com/go-chi/chi): [examples/chi/server.go](https://git.sr.ht/~pingoo/stdx/cors/blob/master/examples/chi/server.go)
    72  
    73  ## Parameters
    74  
    75  Parameters are passed to the middleware thru the `cors.New` method as follow:
    76  
    77  ```go
    78  c := 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
    86  handler = 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  * **OptionsSuccessStatus** `int`: Provides a status code to use for successful OPTIONS requests. Default value is `http.StatusNoContent` (`204`).
    99  * **Debug** `bool`: Debugging flag adds additional output to debug server side CORS issues.
   100  
   101  See [API documentation](http://godoc.org/git.sr.ht/~pingoo/stdx/cors) for more info.
   102  
   103  ## Benchmarks
   104  
   105      BenchmarkWithout          20000000    64.6 ns/op      8 B/op    1 allocs/op
   106      BenchmarkDefault          3000000      469 ns/op    114 B/op    2 allocs/op
   107      BenchmarkAllowedOrigin    3000000      608 ns/op    114 B/op    2 allocs/op
   108      BenchmarkPreflight        20000000    73.2 ns/op      0 B/op    0 allocs/op
   109      BenchmarkPreflightHeader  20000000    73.6 ns/op      0 B/op    0 allocs/op
   110      BenchmarkParseHeaderList  2000000      847 ns/op    184 B/op    6 allocs/op
   111      BenchmarkParse…Single     5000000      290 ns/op     32 B/op    3 allocs/op
   112      BenchmarkParse…Normalized 2000000      776 ns/op    160 B/op    6 allocs/op
   113  
   114  ## Licenses
   115  
   116  All source code is licensed under the [MIT License](https://raw.git.sr.ht/~pingoo/stdx/cors/master/LICENSE).