Add docs from gofiber/fiber@73e9196

Author: github-actions[bot]

docs/core/middleware/cors.md

@@ -169,6 +169,12 @@ The CORS middleware works by adding the necessary CORS headers to responses from
 
 When a request comes in, the middleware first checks if it's a preflight request, which is a CORS mechanism to determine whether the actual request is safe to send. Preflight requests are HTTP OPTIONS requests with specific CORS headers. If it's a preflight request, the middleware responds with the appropriate CORS headers and ends the request.
 
+:::note
+Preflight requests are typically sent by browsers before making actual cross-origin requests, especially for methods other than GET or POST, or when custom headers are used.
+
+A preflight request is an HTTP OPTIONS request that includes the `Origin`, `Access-Control-Request-Method`, and optionally `Access-Control-Request-Headers` headers. The browser sends this request to check if the server allows the actual request method and headers.
+:::
+
 If it's not a preflight request, the middleware adds the CORS headers to the response and passes the request to the next handler. The actual CORS headers added depend on the configuration of the middleware.
 
 The `AllowOrigins` option controls which origins can make cross-origin requests. The middleware handles different `AllowOrigins` configurations as follows:
@@ -197,6 +203,171 @@ The `MaxAge` option indicates how long the results of a preflight request can be
 
 The `Vary` header is used in this middleware to inform the client that the server's response to a request. For or both preflight and actual requests, the Vary header is set to `Access-Control-Request-Method` and `Access-Control-Request-Headers`. For preflight requests, the Vary header is also set to `Origin`. The `Vary` header is important for caching. It helps caches (like a web browser's cache or a CDN) determine when a cached response can be used in response to a future request, and when the server needs to be queried for a new response.
 
+## Infrastructure Considerations
+
+When deploying Fiber applications behind infrastructure components like CDNs, API gateways, load balancers, or reverse proxies, you have two main options for handling CORS:
+
+### Option 1: Use Infrastructure-Level CORS (Recommended)
+
+**For most production deployments, it's often preferable to handle CORS at the infrastructure level** rather than in your Fiber application. This approach offers several advantages:
+
+- **Better Performance**: CORS headers are added at the edge, closer to the client
+- **Reduced Server Load**: Preflight requests are handled without reaching your application
+- **Centralized Configuration**: Manage CORS policies alongside other infrastructure settings
+- **Built-in Caching**: Infrastructure providers optimize CORS response caching
+
+**Common infrastructure CORS solutions:**
+
+- **CDNs**: CloudFront, CloudFlare, Azure CDN - handle CORS at edge locations
+- **API Gateways**: AWS API Gateway, Google Cloud API Gateway - centralized CORS management
+- **Load Balancers**: Application Load Balancers with CORS rules
+- **Reverse Proxies**: Nginx, Apache with CORS modules
+
+If using infrastructure-level CORS, **disable Fiber's CORS middleware** to avoid conflicts:
+
+```go
+// Don't use both - choose one approach
+// app.Use(cors.New()) // Remove this line when using infrastructure CORS
+```
+
+### Option 2: Application-Level CORS (Fiber Middleware)
+
+Use Fiber's CORS middleware when you need:
+
+- **Dynamic origin validation** based on application logic
+- **Fine-grained control** over CORS policies per route
+- **Integration with application state** (database-driven origins, etc.)
+- **Development environments** where infrastructure CORS isn't available
+
+If choosing this approach, ensure that **all CORS headers reach your Fiber application unchanged**.
+
+### Required Headers for CORS Preflight Requests
+
+For CORS preflight requests to work correctly, these headers **must not be stripped or modified by caching layers**:
+
+- `Origin` - Required to identify the requesting origin
+- `Access-Control-Request-Method` - Required to identify the HTTP method for the actual request
+- `Access-Control-Request-Headers` - Optional, contains custom headers the actual request will use
+- `Access-Control-Request-Private-Network` - Optional, for private network access requests
+
+:::warning Critical Preflight Requirement
+If the `Access-Control-Request-Method` header is missing from an OPTIONS request, Fiber will not recognize them as CORS preflight requests. Instead, they'll be treated as regular OPTIONS requests, which typically return `405 Method Not Allowed` since most applications don't define explicit OPTIONS handlers.
+:::
+
+### CORS Response Headers (Set by Fiber)
+
+The middleware sets these response headers based on your configuration:
+
+**For all CORS requests:**
+
+- `Access-Control-Allow-Origin` - Set to the allowed origin or "*"
+- `Access-Control-Allow-Credentials` - Set to "true" when `AllowCredentials: true`
+- `Access-Control-Expose-Headers` - Lists headers the client can access
+- `Vary` - Set to "Origin" (unless wildcard origins are used)
+
+**For preflight responses only:**
+
+- `Access-Control-Allow-Methods` - Lists allowed HTTP methods
+- `Access-Control-Allow-Headers` - Lists allowed request headers (or echoes the request)
+- `Access-Control-Max-Age` - Cache duration for preflight results (if MaxAge > 0)
+- `Access-Control-Allow-Private-Network` - Set to "true" when private network access is allowed
+- `Vary` - Set to "Access-Control-Request-Method, Access-Control-Request-Headers, Origin"
+
+### Common Infrastructure Issues
+
+**CDNs (CloudFront, CloudFlare, etc.)**:
+
+- Configure cache policies to forward all CORS headers
+- Ensure OPTIONS requests are not cached inappropriately or cache them correctly with proper Vary headers
+- Don't strip or modify CORS request headers
+
+**API Gateways**:
+
+- Choose either gateway-level CORS OR application-level CORS, not both
+- If using gateway CORS, disable Fiber's CORS middleware
+- If forwarding to Fiber, ensure all headers pass through unchanged
+
+**Load Balancers/Reverse Proxies**:
+
+- Preserve all HTTP headers, especially CORS-related ones
+- Don't modify or strip `Origin`, `Access-Control-Request-*` headers
+
+**WAFs/Security Services**:
+
+- Whitelist CORS headers in security rules
+- Ensure OPTIONS requests with CORS headers aren't blocked
+
+### Debugging CORS Issues
+
+Add this middleware **before** your CORS configuration to debug what headers Fiber receives:
+
+```go
+// Debug middleware to log CORS preflight requests
+// Only use in development or testing environments
+app.Use(func(c *fiber.Ctx) error {
+    if c.Method() == "OPTIONS" {
+        fmt.Printf("OPTIONS %s\n", c.Path())
+        fmt.Printf("  Origin: %s\n", c.Get("Origin"))
+        fmt.Printf("  Access-Control-Request-Method: %s\n", c.Get("Access-Control-Request-Method"))
+        fmt.Printf("  Access-Control-Request-Headers: %s\n", c.Get("Access-Control-Request-Headers"))
+    }
+    return c.Next()
+})
+
+app.Use(cors.New(cors.Config{
+    AllowOrigins: []string{"https://yourdomain.com"},
+    AllowMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
+}))
+```
+
+Test CORS preflight directly with curl:
+
+```bash
+# Test preflight request
+curl -X OPTIONS https://your-app.com/api/test \
+  -H "Origin: https://yourdomain.com" \
+  -H "Access-Control-Request-Method: POST" \
+  -H "Access-Control-Request-Headers: Content-Type" \
+  -v
+
+# Test simple CORS request
+curl -X GET https://your-app.com/api/test \
+  -H "Origin: https://yourdomain.com" \
+  -v
+```
+
+### Caching Considerations
+
+The middleware sets appropriate `Vary` headers to ensure proper caching:
+
+- **Non-wildcard origins**: `Vary: Origin` is set to cache responses per origin
+- **Preflight requests**: `Vary: Access-Control-Request-Method, Access-Control-Request-Headers, Origin`
+- **OPTIONS without preflight headers**: `Vary: Origin` to avoid cache poisoning
+
+Ensure your infrastructure respects these `Vary` headers for correct caching behavior.
+
+### Choosing the Right Approach
+
+| Scenario | Recommended Approach |
+|----------|---------------------|
+| Production with CDN/API Gateway | Infrastructure-level CORS |
+| Dynamic origin validation needed | Application-level CORS |
+| Microservices with different CORS policies | Application-level CORS |
+| Simple static origins | Infrastructure-level CORS |
+| Development/testing | Application-level CORS |
+| High traffic applications | Infrastructure-level CORS |
+
+:::tip Infrastructure CORS Configuration
+Most cloud providers offer comprehensive CORS documentation:
+
+- [AWS CloudFront CORS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/header-caching.html#header-caching-web-cors)
+- [Google Cloud CORS](https://cloud.google.com/storage/docs/cross-origin)
+- [Azure CDN CORS](https://docs.microsoft.com/en-us/azure/cdn/cdn-cors)
+- [CloudFlare CORS](https://developers.cloudflare.com/fundamentals/get-started/reference/http-request-headers/#cf-connecting-ip)
+
+Configure CORS at the infrastructure level when possible for optimal performance and reduced complexity.
+:::
+
 ## Security Considerations
 
 When configuring CORS, misconfiguration can potentially expose your application to various security risks. Here are some secure configurations and common pitfalls to avoid: