diff options
Diffstat (limited to 'vendor/github.com/gin-contrib/cors')
| -rw-r--r-- | vendor/github.com/gin-contrib/cors/README.md | 211 | ||||
| -rw-r--r-- | vendor/github.com/gin-contrib/cors/config.go | 2 |
2 files changed, 182 insertions, 31 deletions
diff --git a/vendor/github.com/gin-contrib/cors/README.md b/vendor/github.com/gin-contrib/cors/README.md index d43523295..a8747dd6a 100644 --- a/vendor/github.com/gin-contrib/cors/README.md +++ b/vendor/github.com/gin-contrib/cors/README.md @@ -1,47 +1,89 @@ -# CORS gin's middleware +# gin-contrib/cors [](https://github.com/gin-contrib/cors/actions/workflows/go.yml) [](https://codecov.io/gh/gin-contrib/cors) [](https://goreportcard.com/report/github.com/gin-contrib/cors) [](https://godoc.org/github.com/gin-contrib/cors) -Gin middleware/handler to enable CORS support. +- [gin-contrib/cors](#gin-contribcors) + - [Overview](#overview) + - [Installation](#installation) + - [Quick Start](#quick-start) + - [Advanced Usage](#advanced-usage) + - [Custom Configuration](#custom-configuration) + - [DefaultConfig Reference](#defaultconfig-reference) + - [Default() Convenience](#default-convenience) + - [Configuration Reference](#configuration-reference) + - [Notes on Configuration](#notes-on-configuration) + - [Examples](#examples) + - [Advanced Options](#advanced-options) + - [Custom Origin Validation](#custom-origin-validation) + - [With Gin Context](#with-gin-context) + - [Helper Methods](#helper-methods) + - [Validation \& Error Handling](#validation--error-handling) + - [Important Notes](#important-notes) -## Usage +--- -### Start using it +## Overview -Download and install it: +**CORS (Cross-Origin Resource Sharing)** middleware for [Gin](https://github.com/gin-gonic/gin). + +- Enables flexible CORS handling for your Gin-based APIs. +- Highly configurable: origins, methods, headers, credentials, and more. + +--- + +## Installation ```sh go get github.com/gin-contrib/cors ``` -Import it in your code: +Import in your Go code: ```go import "github.com/gin-contrib/cors" ``` -### Canonical example +--- + +## Quick Start + +Allow all origins (default): ```go -package main +import ( + "github.com/gin-contrib/cors" + "github.com/gin-gonic/gin" +) + +func main() { + router := gin.Default() + router.Use(cors.Default()) // All origins allowed by default + router.Run() +} +``` + +> ⚠️ **Warning:** Allowing all origins disables cookies for clients. For credentialed requests, **do not** allow all origins. + +--- + +## Advanced Usage +### Custom Configuration + +Configure allowed origins, methods, headers, and more: + +```go import ( "time" - "github.com/gin-contrib/cors" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() - // CORS for https://foo.com and https://github.com origins, allowing: - // - PUT and PATCH methods - // - Origin header - // - Credentials share - // - Preflight requests cached for 12 hours router.Use(cors.New(cors.Config{ AllowOrigins: []string{"https://foo.com"}, AllowMethods: []string{"PUT", "PATCH"}, @@ -57,15 +99,20 @@ func main() { } ``` -### Using DefaultConfig as start point +--- + +### DefaultConfig Reference + +Start with library defaults and customize as needed: ```go +import ( + "github.com/gin-contrib/cors" + "github.com/gin-gonic/gin" +) + func main() { router := gin.Default() - // - No origin allowed by default - // - GET,POST, PUT, HEAD methods - // - Credentials share disabled - // - Preflight requests cached for 12 hours config := cors.DefaultConfig() config.AllowOrigins = []string{"http://google.com"} // config.AllowOrigins = []string{"http://google.com", "http://facebook.com"} @@ -76,20 +123,124 @@ func main() { } ``` -Note: while Default() allows all origins, DefaultConfig() does not and you will still have to use AllowAllOrigins. +> **Note:** `Default()` allows all origins, but `DefaultConfig()` does **not**. To allow all origins, set `AllowAllOrigins = true`. + +--- + +### Default() Convenience -### Default() allows all origins +Enable all origins with a single call: ```go -func main() { - router := gin.Default() - // same as - // config := cors.DefaultConfig() - // config.AllowAllOrigins = true - // router.Use(cors.New(config)) - router.Use(cors.Default()) - router.Run() +router.Use(cors.Default()) // Equivalent to AllowAllOrigins = true +``` + +--- + +## Configuration Reference + +The middleware is controlled via the `cors.Config` struct. All fields are optional unless otherwise stated. + +| Field | Type | Default | Description | +|-------------------------------|-----------------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------| +| `AllowAllOrigins` | `bool` | `false` | If true, allows all origins. Credentials **cannot** be used. | +| `AllowOrigins` | `[]string` | `[]` | List of allowed origins. Supports exact match, `*`, and wildcards. | +| `AllowOriginFunc` | `func(string) bool` | `nil` | Custom function to validate origin. If set, `AllowOrigins` is ignored. | +| `AllowOriginWithContextFunc` | `func(*gin.Context,string)bool` | `nil` | Like `AllowOriginFunc`, but with request context. | +| `AllowMethods` | `[]string` | `[]string{"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"}` | Allowed HTTP methods. | +| `AllowPrivateNetwork` | `bool` | `false` | Adds [Private Network Access](https://wicg.github.io/private-network-access/) CORS header. | +| `AllowHeaders` | `[]string` | `[]` | List of non-simple headers permitted in requests. | +| `AllowCredentials` | `bool` | `false` | Allow cookies, HTTP auth, or client certs. Only if precise origins are used. | +| `ExposeHeaders` | `[]string` | `[]` | Headers exposed to the browser. | +| `MaxAge` | `time.Duration` | `12 * time.Hour` | Cache time for preflight requests. | +| `AllowWildcard` | `bool` | `false` | Enables wildcards in origins (e.g. `https://*.example.com`). | +| `AllowBrowserExtensions` | `bool` | `false` | Allow browser extension schemes as origins (e.g. `chrome-extension://`). | +| `CustomSchemas` | `[]string` | `nil` | Additional allowed URI schemes (e.g. `tauri://`). | +| `AllowWebSockets` | `bool` | `false` | Allow `ws://` and `wss://` schemas. | +| `AllowFiles` | `bool` | `false` | Allow `file://` origins (dangerous; use only if necessary). | +| `OptionsResponseStatusCode` | `int` | `204` | Custom status code for `OPTIONS` responses. | + +--- + +### Notes on Configuration + +- Only one of `AllowAllOrigins`, `AllowOrigins`, `AllowOriginFunc`, or `AllowOriginWithContextFunc` should be set. +- If `AllowAllOrigins` is true, other origin settings are ignored and credentialed requests are not allowed. +- If `AllowWildcard` is enabled, only one `*` is allowed per origin string. +- Use `AllowBrowserExtensions`, `AllowWebSockets`, or `AllowFiles` to permit non-HTTP(s) protocols as origins. +- Custom schemas allow, for example, usage in desktop apps via custom URI schemes (`tauri://`, etc.). +- If both `AllowOriginFunc` and `AllowOriginWithContextFunc` are set, the context-specific function is preferred. + +--- + +### Examples + +#### Advanced Options + +```go +config := cors.Config{ + AllowOrigins: []string{"https://*.foo.com", "https://bar.com"}, + AllowWildcard: true, + AllowMethods: []string{"GET", "POST"}, + AllowHeaders: []string{"Authorization", "Content-Type"}, + AllowCredentials: true, + AllowBrowserExtensions: true, + AllowWebSockets: true, + AllowFiles: false, + CustomSchemas: []string{"tauri://"}, + MaxAge: 24 * time.Hour, + ExposeHeaders: []string{"X-Custom-Header"}, + AllowPrivateNetwork: true, +} +``` + +#### Custom Origin Validation + +```go +config := cors.Config{ + AllowOriginFunc: func(origin string) bool { + // Allow any github.com subdomain or a custom rule + return strings.HasSuffix(origin, "github.com") + }, } ``` -Using all origins disables the ability for Gin to set cookies for clients. When dealing with credentials, don't allow all origins. +#### With Gin Context + +```go +config := cors.Config{ + AllowOriginWithContextFunc: func(c *gin.Context, origin string) bool { + // Allow only if a certain header is present + return c.Request.Header.Get("X-Allow-CORS") == "yes" + }, +} +``` + +--- + +## Helper Methods + +Dynamically add methods or headers to the config: + +```go +config.AddAllowMethods("DELETE", "OPTIONS") +config.AddAllowHeaders("X-My-Header") +config.AddExposeHeaders("X-Other-Header") +``` + +--- + +## Validation & Error Handling + +- Calling `Validate()` on a `Config` checks for misconfiguration (called internally). +- If `AllowAllOrigins` is set, you cannot also set `AllowOrigins` or any `AllowOriginFunc`. +- If neither `AllowAllOrigins`, `AllowOriginFunc`, nor `AllowOrigins` is set, an error is raised. +- If an `AllowOrigin` contains a wildcard but `AllowWildcard` is not enabled, or more than one `*` is present, a panic is triggered. +- Invalid origin schemas or unsupported wildcards are rejected. + +--- + +## Important Notes + +- **Enabling all origins disables cookies:** When `AllowAllOrigins` is enabled, Gin cannot set cookies for clients. If you need credential sharing (cookies, authentication headers), **do not** allow all origins. +- For detailed documentation and configuration options, see the [GoDoc](https://godoc.org/github.com/gin-contrib/cors). diff --git a/vendor/github.com/gin-contrib/cors/config.go b/vendor/github.com/gin-contrib/cors/config.go index a955c3171..76e15a880 100644 --- a/vendor/github.com/gin-contrib/cors/config.go +++ b/vendor/github.com/gin-contrib/cors/config.go @@ -87,7 +87,7 @@ func (cors *cors) applyCors(c *gin.Context) { return } - if c.Request.Method == "OPTIONS" { + if c.Request.Method == http.MethodOptions { cors.handlePreflight(c) defer c.AbortWithStatus(cors.optionsResponseStatusCode) } else { |