Documentation
¶
Overview ¶
Package cors provides a configurable CORS (Cross-Origin Resource Sharing) middleware for http.Handlers.
Usage ¶
The New function creates the middleware pipe, which can be configured with functional options (e.g., WithAllowedOrigins, WithAllowedMethods). The middleware automatically handles preflight (OPTIONS) requests and injects the appropriate CORS headers into responses for actual requests.
Example:
// Configure CORS to allow requests from a specific origin with
// restricted methods and additional headers.
pipe := cors.New(
cors.WithAllowedOrigins("https://example.com"),
cors.WithAllowedMethods(http.MethodGet, http.MethodOptions),
cors.WithAllowedHeaders("Authorization", "Content-Type"),
cors.WithMaxAge(12*time.Hour),
)
handler := http.HandlerFunc( ... )
// Apply the CORS middleware as one of the first layers.
chainedHandler := middleware.Chain(handler, pipe)
http.ListenAndServe(":8080", chainedHandler)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(opts ...Option) middleware.Pipe
New creates a middleware Pipe that handles CORS based on the provided options.
The middleware distinguishes between preflight and actual requests. Preflight (OPTIONS) requests are intercepted and terminated with a 204 No Content response. For actual requests, it adds the necessary CORS headers to the response before passing control to the next handler. Non-CORS requests are passed through without modification.
Types ¶
type Option ¶
type Option func(*config)
Option is a function that configures the CORS middleware.
func WithAllowCredentials ¶
WithAllowCredentials indicates whether the response to the request can be exposed when the credentials flag is true.
When used as part of a response to a preflight request, it indicates that the actual request can include cookies and other user credentials. This option defaults to false. Note that browsers require a specific origin (not a wildcard) in the Access-Control-Allow-Origin header when this is enabled.
func WithAllowedHeaders ¶
WithAllowedHeaders sets the allowed HTTP headers for CORS requests.
This is necessary for any non-standard headers the client needs to send, such as "Authorization" or custom "X-" headers. If not set, browsers will only permit requests with CORS-safelisted request headers.
func WithAllowedMethods ¶
WithAllowedMethods sets the allowed HTTP methods for CORS requests.
If no methods are provided, this header is omitted by default, and only simple methods (GET, POST, HEAD) are implicitly allowed by browsers for non-preflighted requests. It is recommended to list all methods your API supports, including OPTIONS.
func WithAllowedOrigins ¶
WithAllowedOrigins sets the allowed origins for CORS requests.
By default, all origins are allowed. The same behavior can be achieved by leaving the list empty or by manually including the special wildcard "*". In other cases, this option restricts requests to a specific whitelist. If credentials are enabled via WithAllowCredentials, browsers forbid a wildcard origin, and this middleware will dynamically reflect the request's Origin header if it is in the allowed list.
func WithExposedHeaders ¶
WithExposedHeaders sets the HTTP headers that are safe to expose to the API of a CORS API specification.
By default, client-side scripts can only access a limited set of simple response headers. This option lists additional headers (like a custom "X-Pagination-Total" header) that should be made accessible to the script.
func WithMaxAge ¶
WithMaxAge indicates how long the results of a preflight request can be cached by the browser, in seconds.
If set to 0 (the default), the header is omitted. Be aware that browsers have a default internal limit (usually 5 seconds) when this header is missing. This results in a preflight request for almost every API call, which can double the traffic to your server. It is recommended to set this to a higher value (e.g., 10 minutes) for stable APIs to reduce latency.
Source Files