CORS Middleware

The CORS middleware handles Cross-Origin Resource Sharing (CORS) by setting the appropriate Access-Control-* headers on HTTP responses. This middleware is essential for web applications that need to handle requests from different origins, such as frontend applications running on different domains.

Basic Usage

middleware.go


httpx.Chain(
    middlewares.CORS(nil), // Uses default permissive settings
)

Configuration Options

Configure the middleware using CORSOptions:

middleware.go


httpx.Chain(
    middlewares.CORS(&middlewares.CORSOptions{
        AllowedOrigins: []string{"https://example.com", "https://app.example.com"},
        AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
        AllowedHeaders: []string{"Content-Type", "Authorization", "X-API-Key"},
    }),
)

CORS Options Fields

Field	Type	Default	Description
`AllowedOrigins`	`[]string`	`["*"]`	List of allowed origins. Use `["*"]` for all origins
`AllowedMethods`	`[]string`	`["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]`	HTTP methods that are allowed
`AllowedHeaders`	`[]string`	`["*"]`	Headers that clients can send

Common Configurations

Development (Permissive)


middlewares.CORS(&middlewares.CORSOptions{
    AllowedOrigins: []string{"*"},
    AllowedMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"},
    AllowedHeaders: []string{"*"},
})

It is the default configuration when no options are provided, allowing all origins, methods, and headers.

Production (Restrictive)


middlewares.CORS(&middlewares.CORSOptions{
    AllowedOrigins: []string{
        "https://myapp.com",
        "https://www.myapp.com",
    },
    AllowedMethods: []string{"GET", "POST", "PUT", "DELETE"},
    AllowedHeaders: []string{
        "Content-Type",
        "Authorization",
        "X-Requested-With",
    },
})

API with Multiple Clients


middlewares.CORS(&middlewares.CORSOptions{
    AllowedOrigins: []string{
        "https://admin.example.com",
        "https://app.example.com",
        "https://mobile.example.com",
    },
    AllowedMethods: []string{"GET", "POST", "PUT", "PATCH", "DELETE"},
    AllowedHeaders: []string{
        "Content-Type",
        "Authorization",
        "X-API-Key",
        "X-Client-Version",
    },
})

How It Works

Origin Validation: The middleware checks the Origin header against the allowed origins
Header Setting: Sets the appropriate Access-Control-* headers on the response
Preflight Handling: For OPTIONS requests, responds immediately with 204 No Content
Request Continuation: For non-OPTIONS requests, continues to the next handler

Headers Set

The middleware sets the following response headers:

Access-Control-Allow-Origin: The requesting origin (if allowed)
Access-Control-Allow-Methods: Comma-separated list of allowed methods
Access-Control-Allow-Headers: Comma-separated list of allowed headers

Important Notes

Wildcard Origin: When using ["*"] for origins, the middleware reflects the actual request origin rather than setting * directly
OPTIONS Requests: The middleware automatically handles preflight OPTIONS requests and returns 204 No Content
Default Values: If no options are provided, the middleware uses permissive defaults suitable for development
Security: Always use specific origins in production environments rather than wildcards

Troubleshooting

Common CORS Issues

Issue: Browser shows “CORS policy” error Solution: Ensure the requesting origin is included in AllowedOrigins

Issue: POST requests fail but GET requests work Solution: Add “POST” to AllowedMethods and ensure required headers are in AllowedHeaders

Issue: Custom headers not working Solution: Add your custom headers to AllowedHeaders

Debug Tips

Check browser developer tools for the actual CORS error message
Verify that the Origin header in the request matches your allowed origins exactly
For preflight requests, ensure both the method and headers are allowed
Use browser network tab to inspect the actual headers being sent and received