cors

package module
Version: v0.0.0-...-97b4a9d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 20, 2016 License: MIT Imports: 4 Imported by: 0

README

CORS for Gin GoDoc Build Status Coverage Status

gin-cors is a middleware written in Go (Golang) specifically for the Gin Framework that implements the Cross Origin Resource Sharing specification from the W3C. Implementing CORS headers enable pages within a modern web browser to consume resources (such as REST APIs) from servers that are on a different domain.

Getting Started

To use this library, add the following code into your Gin router setup:

import "github.com/itsjamie/gin-cors"

// Initialize a new Gin router
router := gin.New()

// Apply the middleware to the router (works with groups too)
router.Use(cors.Middleware(cors.Config{
	Origins:        "*",
	Methods:        "GET, PUT, POST, DELETE",
	RequestHeaders: "Origin, Authorization, Content-Type",
	ExposedHeaders: "",
	MaxAge: 50 * time.Second,
	Credentials: true,
	ValidateHeaders: false,
}))

Setup Options

The middleware can be configured with four options, which match the HTTP headers that it generates:

Parameter Type Details
Origins string A comma delimited list of origins which have access. For example: "http://localhost, http://api.server.com, http://files.server.com"
RequestHeaders string A comma delimited list of allowed HTTP that is passed to the browser in the Access-Control-Allow-Headers header.
ExposeHeaders string A comma delimited list of HTTP headers that should be exposed to the CORS client via the Access-Control-Expose-Headers header.
Methods string A comma delimited list of allowed HTTP methods that is passed to the browser in the Access-Control-Allow-Methods.
MaxAge time.Duration The amount of time a preflight request should be cached, if not specified, the header Access-Control-Max-Age will not be set.
Credentials bool This is passed in the Access-Control-Allow-Credentials header. If true Cookies, HTTP authentication and the client-side SSL certificates will be sent on previous interactions with the origin.
ValidateHeaders bool If false we skip validating the requested headers/methods with the list of allowed ones, and instead just respond with all what we support, it is up to the client implementating CORS to deny the request. This is an optimization allowed by the specification.

CORS Resources

Special Thanks

Special thanks to benpate for providing a foundation to work from.

License

The code is licensed under the MIT License. See LICENSE file for more details.

Documentation

Overview

This code implements the flow chart that can be found here. http://www.html5rocks.com/static/images/cors_server_flowchart.png

A Default Config for example is below:

cors.Config{
	Origins:        "*",
	Methods:        "GET, PUT, POST, DELETE",
	RequestHeaders: "Origin, Authorization, Content-Type",
	ExposedHeaders: "",
	MaxAge: 1 * time.Minute,
	Credentials: true,
	ValidateHeaders: false,
}

Index

Examples

Constants

View Source
const (
	AllowOriginKey      string = "Access-Control-Allow-Origin"
	AllowCredentialsKey        = "Access-Control-Allow-Credentials"
	AllowHeadersKey            = "Access-Control-Allow-Headers"
	AllowMethodsKey            = "Access-Control-Allow-Methods"
	MaxAgeKey                  = "Access-Control-Max-Age"

	OriginKey         = "Origin"
	RequestMethodKey  = "Access-Control-Request-Method"
	RequestHeadersKey = "Access-Control-Request-Headers"
	ExposeHeadersKey  = "Access-Control-Expose-Headers"
)

Variables

This section is empty.

Functions

func Middleware

func Middleware(config Config) gin.HandlerFunc

Middleware generates a middleware handler function that works inside of a Gin request to set the correct CORS headers. It accepts a cors.Options struct for configuration.

Example
// Initialize the gin-gonic router
router := gin.New()

// Set up CORS middleware options
config := cors.Config{
	Origins:         "*",
	RequestHeaders:  "Authorization",
	Methods:         "GET, POST, PUT",
	Credentials:     true,
	ValidateHeaders: false,
	MaxAge:          1 * time.Minute,
}

// Apply the middleware to the router (works on groups too)
router.Use(cors.Middleware(config))
Output:

Types

type Config

type Config struct {
	// Enabling this causes us to compare Request-Method and Request-Headers to confirm they contain a subset of the Allowed Methods and Allowed Headers
	// The spec however allows for the server to always match, and simply return the allowed methods and headers. Either is supported in this middleware.
	ValidateHeaders bool

	// Comma delimited list of origin domains. Wildcard "*" is also allowed, and matches all origins.
	// If the origin does not match an item in the list, then the request is denied.
	Origins string

	// This are the headers that the resource supports, and will accept in the request.
	// Default is "Authorization".
	RequestHeaders string

	// These are headers that should be accessable by the CORS client, they are in addition to those defined by the spec as "simple response headers"
	//	 Cache-Control
	//	 Content-Language
	//	 Content-Type
	//	 Expires
	//	 Last-Modified
	//	 Pragma
	ExposedHeaders string

	// Comma delimited list of acceptable HTTP methods.
	Methods string

	// The amount of time in seconds that the client should cache the Preflight request
	MaxAge time.Duration

	// If true, then cookies and Authorization headers are allowed along with the request.  This
	// is passed to the browser, but is not enforced.
	Credentials bool
	// contains filtered or unexported fields
}

Config defines the configuration options available to control how the CORS middleware should function.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL