HTTP-to-WebSocket Upgrade — Complete Guide

In this tutorial, you will learn about HTTP. We cover key concepts, practical examples, and best practices to help you master this topic.

The Websocket connection starts with an HTTP upgrade request. The client sends a standard HTTP request with special headers indicating the desire to upgrade. The server responds with 101 Switching Protocols to confirm.

What You'll Learn

• HTTP upgrade request headers
• Sec-WebSocket-Key and response computation
• 101 Switching Protocols response
• Upgrade failure scenarios
• Proxy and gateway considerations

Why It Matters

The upgrade handshake is the only part of WebSocket that uses HTTP. Understanding it helps debug connection failures, configure proxies, and implement custom WebSocket servers.

Real-World Use

Load balancers and reverse proxies must support the Upgrade header to pass WebSocket traffic. Cloudflare, AWS ALB, and Nginx have specific WebSocket upgrade configurations.

sequenceDiagram
    Client->>Server: GET /chat HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
    Server->>Server: Compute accept key
    Server-->>Client: HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
    Client->>Server: WebSocket frames...

Teacher Mindset

The handshake is a standard HTTP GET with upgrade headers. The Sec-WebSocket-Key is a random base64 value. The server appends a fixed GUID, computes SHA-1, and returns the base64 digest in Sec-WebSocket-Accept.

Code Examples

// Example 1: Manual HTTP upgrade request
const http = require('http');
const crypto = require('crypto');

const key = crypto.randomBytes(16).toString('base64');

const req = http.request({
  hostname: 'localhost',
  port: 8080,
  path: '/chat',
  method: 'GET',
  headers: {
    'Upgrade': 'websocket',
    'Connection': 'Upgrade',
    'Sec-WebSocket-Key': key,
    'Sec-WebSocket-Version': '13'
  }
});

req.on('upgrade', (res, socket) => {
  const acceptKey = res.headers['sec-websocket-accept'];
  console.log('Upgrade successful, accept:', acceptKey);
  // Now socket is a WebSocket connection
});

req.end();

// Example 2: Server handling upgrade
const http = require('http');
const crypto = require('crypto');

const GUID = '258EAFA5-E914-47DA-95CA-5AB5A9DA63B2';

const server = http.createServer((req, res) => {
  if (req.headers.upgrade === 'websocket') {
    const key = req.headers['sec-websocket-key'];
    const accept = crypto
      .createHash('sha1')
      .update(key + GUID)
      .digest('base64');

    res.writeHead(101, {
      'Upgrade': 'websocket',
      'Connection': 'Upgrade',
      'Sec-WebSocket-Accept': accept
    });
    res.end();
  } else {
    res.writeHead(200);
    res.end('HTTP server running');
  }
});

# Example 3: Test upgrade with curl
curl -v -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  http://localhost:8080/chat

# Expected response:
# HTTP/1.1 101 Switching Protocols
# Upgrade: websocket
# Connection: Upgrade
# Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Common Mistakes

• Forgetting the Connection: Upgrade header along with the Upgrade header
• Using incorrect GUID for the accept key computation
• Not handling the case where the server does not support WebSocket (returns 200)
• Expecting the upgrade to work through HTTP/2 (WebSocket works over HTTP/1.1)
• Ignoring proxy headers that may interfere with the upgrade

Practice

1. Manually compute the Sec-WebSocket-Accept value from a given key.
2. Write a server that handles the upgrade handshake manually.
3. Attempt an upgrade with an invalid key and observe the response.
4. Test WebSocket upgrade through a proxy server.
5. Challenge: Implement a minimal WebSocket server using only the Node.js http module.

FAQ

Mini Project

Write a custom HTTP server that handles the WebSocket upgrade without using a WebSocket library. Implement the key validation, accept computation, and send a welcome message frame after the handshake.

What's Next

Next, you will learn about the WebSocket handshake in detail, including subprotocols and extensions.