Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js HTTP upgrade event

How the 'upgrade' event works on a Node.js http.Server and http.ClientRequest: the 101 handshake, the raw socket, the head buffer and a WebSocket accept key.

An HTTP/1.1 connection can switch to a different protocol part-way through its life. The client sends a request with the headers Connection: Upgrade and Upgrade: <protocol>; if the server agrees it answers 101 Switching Protocols, and from that moment the same TCP connection no longer speaks HTTP. WebSocket is the best-known protocol that starts this way.

Node does not hide the switch. When a request carries an upgrade, http.Server emits an 'upgrade' event instead of 'request', and hands you the raw net.Socket. On the client side, http.ClientRequest emits 'upgrade' when the server answers 101. After that, HTTP parsing stops: you read and write bytes on the socket yourself.

NODE
server.on('upgrade', (req, socket, head) => {
  socket.write('HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: echo\r\n\r\n');
});

Try it

Node.js A tiny custom protocol over upgrade

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js The WebSocket handshake key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How it works

Server side. The event signature is 'upgrade': (request, socket, head). request is an http.IncomingMessage with the headers. socket is the net.Socket (or tls.TLSSocket) for the connection. head is a Buffer with any bytes that arrived after the headers; with WebSocket this is often empty, but a protocol where the client writes immediately may deliver data here. You must write the 101 response yourself, in full, including the final blank line. If no 'upgrade' listener exists, Node closes the connection instead of answering normally.

Client side. req.on('upgrade', (response, socket, head) => ...) fires when the server replies with 101. If the server declines and answers with an ordinary status, you get 'response' as usual and no upgrade happens. When you do not listen for 'upgrade', a 101 reply closes the connection.

After the switch nothing in node:http touches the connection. The server's headersTimeout and request timers no longer apply, and server.close() waits for the upgraded sockets like any other open connection. Call socket.destroy() when you are done, or server.closeAllConnections() to drop them.

Usage notes

  • Check the headers. Compare req.headers.upgrade case-insensitively and answer 400 (or 426 Upgrade Required with an Upgrade header) when it is not what you serve.
  • Authenticate before replying 101. The handshake is a normal HTTP request, so cookies and Authorization headers are available in req.headers. After the switch you can no longer send an HTTP error status.
  • Keep an error handler on the socket, because a client that vanishes causes ECONNRESET on a raw socket, and an unhandled 'error' crashes the process.
  • Real applications use a library that implements the WebSocket framing (masking, fragmentation, ping/pong) on top of this event; the framing is not trivial. See WebSockets for what that involves.
  • HTTP/2 has no upgrade mechanism; WebSocket over HTTP/2 uses a different extended CONNECT method.
  • 'upgrade' and 'connect' are siblings: 'connect' handles the CONNECT method for tunnels, covered in The connect event.