github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs_src/src/guide/advanced/cors.md (about)

     1  ---
     2  meta:
     3    - name: "og:title"
     4      content: "CORS - Goyave"
     5    - name: "twitter:title"
     6      content: "CORS - Goyave"
     7    - name: "title"
     8      content: "CORS - Goyave"
     9  ---
    10  
    11  # CORS <Badge text="Since v2.3.0"/>
    12  
    13  [[toc]]
    14  
    15  ## Introduction
    16  
    17  CORS, or "[Cross-Origin Resource Sharing](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)" is a mechanism that uses additional HTTP headers to tell browsers to give a web application running at one origin, **access to selected resources from a different origin**. A web application executes a cross-origin HTTP request when it requests a resource that has a different origin (domain, protocol, or port) from its own. Enabling CORS is done by adding a set of specific headers allowing the browser and server to communicate about which requests, methods and headers are or are not allowed. CORS support also comes with **pre-flight** `OPTIONS` requests support.
    18  
    19  Most of the time, the API is using another domain as the clients. For security reasons, browsers restrict cross-origin HTTP requests initiated from scripts. That's why you should configure CORS for your API.
    20  
    21  ## Enabling CORS
    22  
    23  All functions below require the `cors` package to be imported.
    24  
    25  ``` go
    26  import "github.com/System-Glitch/goyave/v2/cors"
    27  ```
    28  
    29  CORS options are set on **routers**. If the passed options are not `nil`, the CORS core middleware is automatically added.
    30  
    31  ``` go
    32  router.CORS(cors.Default())
    33  ```
    34  
    35  CORS options should be defined **before middleware and route definition**. All of this router's sub-routers **inherit** CORS options by default. If you want to remove the options from a sub-router, or use different ones, simply create another `cors.Options` object and assign it.
    36  
    37  ``` go
    38  router.CORS(cors.Default())
    39  
    40  subrouter := router.Subrouter("/products")
    41  subrouter.CORS(nil) // Remove CORS options
    42  
    43  options := cors.Default()
    44  options.AllowCredentials = true
    45  subrouter.CORS(options) // Different CORS options
    46  ```
    47  
    48  ::: tip
    49  All routes defined in a router having CORS options will match the `OPTIONS` HTTP method to allow **pre-flight** requests, even if it's not explicitly told in the route definition.
    50  :::
    51  
    52  ## Options
    53  
    54  `cors.Default()` can be used as a starting point for custom configuration.
    55  
    56  ``` go
    57  options := cors.Default()
    58  options.AllowedOrigins = []string{"https://google.com", "https://images.google.com"}
    59  router.CORS(options)
    60  ```
    61  
    62  Find the options reference below:
    63  
    64  ### AllowOrigins
    65  
    66  A list of origins a cross-domain request can be executed from. If the first value in the slice is `*` or if the slice is empty, all origins will be allowed.
    67  
    68  **Type:** `[]string`
    69  **Default:** `["*"]`
    70  
    71  ### AllowedMethods
    72  
    73  A list of methods the client is allowed to use with cross-domain requests.
    74  
    75  **Type:** `[]string`
    76  **Default:** `["HEAD", "GET", "POST", "PUT", "PATCH", "DELETE"]`
    77  
    78  ### AllowedHeaders
    79  
    80  A list of non simple headers the client is allowed to use with cross-domain requests. If the first value in the slice is `*`, all headers will be allowed. If the slice is empty, the request's headers will be reflected.
    81  
    82  **Type:** `[]string`
    83  **Default:** `["Origin", "Accept", "Content-Type", "X-Requested-With", "Authorization"]`
    84  
    85  ### ExposedHeaders
    86  
    87  Indicates which headers are safe to expose to the API of a CORS API specification.
    88  
    89  **Type:** `[]string`
    90  **Default:** `[]`
    91  
    92  ### MaxAge
    93  
    94  Indicates how long the results of a preflight request can be cached.
    95  
    96  **Type:** `time.Duration`
    97  **Default:** `12 hours (43200 seconds)`
    98  
    99  ### AllowCredentials
   100  
   101  Indicates whether the request can include user credentials like cookies, HTTP authentication or client side SSL certificates.
   102  
   103  **Type:** `bool`
   104  **Default:** `false`
   105  
   106  ### OptionsPassthrough
   107  
   108  Instructs **pre-flight** to let other potential next handlers to process the `OPTIONS` method. Turn this on if your application handles `OPTIONS`.
   109  
   110  **Type:** `bool`
   111  **Default:** `false`