README
¶
cors
This package defines a handler that can be used for endpoints that serve a resource that needs to be accessible from multiple origins.
A Cross Origin http request for a given resource is made when a user agent is used to retrieve resources from a given domain which themselves depend on resources from another domain (such as an image stored on a foreign CDN for instance).
The current package can be used to specify the conditions under which we allow a resource at a given endpoint to be accessed.
The default being same-origin policy (same domain, same protocol, same port, same host), it can be relaxed by specifying the type of Cross Origin requests the server allows (by Origin, by Headers, Content-type, etc.)
Specification
How to use it?
A CORS Handler controls the access to resources available on the server by defining constraints (request origin, http methods allowed, headers allowed, etc.)
type Handler struct {
Parameters
Preflight *PreflightHandler
next xhttp.Handler
}
The Parameter field holds the configuration options.
// Parameters defines the set of actionable components that are used to define a
// response to a Cross-Origin request.
// "*" is used to denote that anything is accepted (resp. Headers, Methods,
// Content-Types).
// The fields AllowedOrigins, AllowedHeaders, AllowedMethods, ExposeHeaders and
// AllowedContentTypes are sets of strings. A string may be inserted by using
// the `Add(str string, caseSensitive bool)` method.
// It is also possible to lookup for the existence of a string within a set
// thanks to the `Contains(str string, caseSensitive bool)` method.
type Parameters struct {
AllowedOrigins set
AllowedHeaders set
AllowedContentTypes set
ExposeHeaders set
AllowedMethods set
AllowCredentials bool
}
Except for the case of simple requests (as defined in the spec.), a preflight request is sent, which aims at verifying that a request is well-formed for a given endpoint, i.e. the headers, method and origin are expected by the server.
// PreflightHandler holds the elements required to build and register
// the http response logic to a preflight request.
type PreflightHandler struct {
*Parameters
MxAge time.Duration
mux *xhttp.ServeMux
pat string
next xhttp.Handler
}
The preflight result may be cached on the user-agent and it is even possible to pick for how long the result will stay valid in cache. The handler is automatically registered on the OPTION method of a xhttp.ServeMux
It is likely that this handler will be registered early in the the request-handling chain. Registration is only for an explicitly given path.
Dependencies
These are the only two external dependencies required as they are necessary to take into account the execution context of a request-handling goroutine.
License
BSD 3-clause
Documentation
¶
Overview ¶
Package cors implements the server-side logic that is employed in response to a Cross Origin request.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // SimpleRequestMethods is the set of methods for which CORS is allowed // without preflight. SimpleRequestMethods = newSet().Add("GET", "HEAD", "POST") // SimpleRequestHeaders is the set of headers for which CORS is allowed // without preflight. SimpleRequestHeaders = newSet().Add("Accept", "Accept-Language", "Content-Language", "Content-Type") // SimpleRequestContentTypes is the set of headers for which CORS is allowed // without preflight. SimpleRequestContentTypes = newSet().Add("application/x-www-form-urlencoded", "multipart/form-data", "text/plain") // SimpleResponseHeaders is the set of header field names for which CORS is // allows a response to a request without preflight. SimpleResponseHeaders = newSet().Add("Cache-Control", "Content-Language", "Content-Type", "Expires", "Last-Modified", "Pragma") )
Functions ¶
This section is empty.
Types ¶
type Handler ¶
type Handler struct {
*Parameters
Preflight *PreflightHandler
// contains filtered or unexported fields
}
Handler is used to specify and enforce a Cross Origin Resource Sharing policy on incoming http requests. CORS controls the access to resources available on the server by defining constraints (request origin, http methods allowed, headers allowed, etc.)
func NewHandler ¶
func NewHandler() Handler
NewHandler creates a new, CORS policy enforcing, request handler.
func (Handler) EnablePreflight ¶
EnablePreflight will allow the handling of preflighted requests via the OPTIONS http method. Preflight result mayt be cached by the client
func (Handler) Link ¶
func (h Handler) Link(hn xhttp.Handler) xhttp.HandlerLinker
Link enables the linking of a xhttp.Handler to the cors request handler.
func (Handler) WithCredentials ¶
WithCredentials will allow the emmission of cookies, authorization headers, TLS client certificates with the http requests by the client.
type Parameters ¶
type Parameters struct {
AllowedOrigins set
AllowedHeaders set
AllowedContentTypes set
ExposeHeaders set
AllowedMethods set
AllowCredentials bool
}
Parameters defines the set of actionable components that are used to define a response to a Cross-Origin request. "*" is used to denote that anything is accepted (resp. Headers, Methods, Content-Types). The fields AllowedOrigins, AllowedHeaders, AllowedMethods, ExposeHeaders and AllowedContentTypes are sets of strings. A string may be inserted by using the `Add(str string, caseSensitive bool)` method. It is also possible to lookup for the existence of a string within a set thanks to the `Contains(str string, caseSensitive bool)` method.
type PreflightHandler ¶
type PreflightHandler struct {
*Parameters
MxAge time.Duration
// contains filtered or unexported fields
}
PreflightHandler holds the elements required to build and register the http response logic to a preflight request.
func (*PreflightHandler) Link ¶
func (p *PreflightHandler) Link(h xhttp.Handler) xhttp.HandlerLinker
Link enables the linking of a xhttp.Handler to the preflight request handler.
func (*PreflightHandler) MaxAge ¶
func (p *PreflightHandler) MaxAge(t time.Duration)
MaxAge sets a limit to the validity of a preflight result in cache.
func (*PreflightHandler) ServeHTTP ¶
func (p *PreflightHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
Source Files