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.
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
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.
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.upgradecase-insensitively and answer400(or426 Upgrade Requiredwith anUpgradeheader) when it is not what you serve. - Authenticate before replying
101. The handshake is a normal HTTP request, so cookies andAuthorizationheaders are available inreq.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
ECONNRESETon 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
CONNECTmethod. 'upgrade'and'connect'are siblings:'connect'handles theCONNECTmethod for tunnels, covered in The connect event.