What is the "Upgrade" Header ?

The Upgrade header is an HTTP header that signals a request to switch to a different protocol on the same TCP connection. Although most common for upgrading from HTTP/1.1 to WebSocket, it can also be used for transitioning to other protocols (e.g., HTTP/2 or TLS-over-HTTP). This mechanism allows a client and server to maintain a persistent connection while changing the communication protocol on-the-fly.

How the Upgrade Header Works

When a client wants to switch from HTTP/1.1 to a different protocol, it adds an Upgrade header (and sometimes an Connection: Upgrade header) to its request. The server then evaluates whether it supports that protocol. If the server does accept, it returns a 101 Switching Protocols response, indicating a successful upgrade. If not, it either continues with the standard HTTP/1.1 communication or rejects the request.

Example of an Upgrade Request

GET /chat HTTP/1.1
Host: example.com
Connection: Upgrade
Upgrade: websocket

In this example, the client is requesting to upgrade from HTTP/1.1 to the WebSocket protocol.

Impact on Your Page and CDN Behavior

• WebSocket Communication: For applications that rely on real-time data transfer (e.g., chats, live feeds, or multiplayer games), the Upgrade header is crucial for switching to WebSocket. If this header is blocked or removed, users may experience failures or disconnects in real-time features.
• Protocol Compatibility: If your server or CDN (like VergeCloud) is not configured to handle protocol upgrades properly, users attempting to switch protocols could face connection errors. This might appear as blank pages, failed requests, or partial loading.
• Security Considerations: Unintended or malicious use of the Upgrade header can introduce potential security risks if the server accepts protocol switches without proper validation. Ensuring your CDN and server only allow upgrades to supported protocols reduces the risk.
• Caching and Edge Servers: Since the Upgrade header is generally used for protocols requiring persistent connections (like WebSockets), content associated with these requests is usually not cached. Additionally, some CDNs may require special rules or configurations to pass the Upgrade header through without stripping it or altering it.

Configuring Upgrade Headers in VergeCloud

VergeCloud, like many other CDNs, uses a reverse proxy to accelerate your website. In some cases, you may need to instruct VergeCloud to ignore or allow the Upgrade header. This is especially important for WebSocket traffic or other protocol upgrades. If VergeCloud strips or modifies this header, WebSocket connections or other protocol transitions may fail.

• Page Rules Configuration: Within VergeCloud’s Page Rules section, you can specify how headers are treated. For instance, you could create a rule to ignore or preserve the Upgrade header on specific URLs or paths that require protocol switching.
• Edge Settings: Some advanced settings in VergeCloud let you define whether certain headers are passed through, removed, or modified. Adjusting these ensures that WebSocket or other upgraded connections remain stable.

Best Practices

1. Enable "Upgrade" Only Where Needed: Restrict protocol upgrades to endpoints that require it (e.g., /ws for WebSockets). Avoid allowing upgrades on every path to minimize potential security risks.
2. Set Explicit Page Rules for VergeCloud: If using VergeCloud, define rules that specify how to treat the Upgrade header on endpoints relying on WebSockets or other protocols. This prevents unintended stripping or altering of headers.
3. Test Regularly: Use curl or browser dev tools to ensure the Upgrade header is present and your WebSocket or protocol transition is successful.
4. Monitor Logs: Check server and CDN logs for 101 Switching Protocols responses or upgrade failures. Early detection of misconfiguration saves time troubleshooting unexpected connection issues.