Protocol upgrade mechanism

The HTTP protocol provides a special mechanism allowing an already established connection to upgrade to a new, incompatible, protocol. This mechanism is always client initiated, and the server may accept or refuse the switch to the new protocol.

Handshake

When the client wants to upgrade to a new protocol, it sends a normal request to the server (being a GET, POST or any other request type) and adds the Upgrade: header followed by the protocol it wants to upgrade to. It can specify several of them, in order of preference.

The server may either refuse the upgrade — in this case it merely ignores the Upgrade: header and sends back a regular response (200 OK if it can serve the requested resource, a 30x status code if it wants to perform a redirect, a 40x or 50x one if it can't serve the requested resource) — or accept the upgrade. In this case it sends back a 101 Switching Protocols along with an Upgrade header containing the protocol chosen.

Right after sending the 101 status code, an eventual handshake for the new protocol happens, if the new protocol requires it, then the server sends the answer requested for the previous request, following the new protocol rules.

The Upgrade: header

 

The 101 status code

 

Common usages of this mechanism

Upgrading to an Websocket connection

Upgrading to HTTP over TLS

References

Document Tags and Contributors

 Contributors to this page: TheT0dd, Sheppy, teoli
 Last updated by: TheT0dd,