cpp-httplib/docs-src/pages/en/cookbook/w03-websocket-close.md

title, order, status

title	order	status
W03. Handle Connection Close	53	draft

A WebSocket ends when either side closes it explicitly, or when the network drops. Handle close cleanly, and your cleanup and reconnect logic stays tidy.

Detect a closed connection

When ws.read() returns ReadResult::Fail, the connection is gone — either cleanly or with an error. Break out of the loop and the handler will finish.

svr.WebSocket("/chat", [](const httplib::Request &req, httplib::ws::WebSocket &ws) {
  std::string msg;
  while (ws.is_open()) {
    auto result = ws.read(msg);
    if (result == httplib::ws::ReadResult::Fail) {
      std::cout << "disconnected" << std::endl;
      break;
    }
    handle_message(ws, msg);
  }

  // cleanup runs once we're out of the loop
  cleanup_user_session(req);
});

You can also check ws.is_open() — it's the same signal from a different angle.

Close from the server side

To close explicitly, call close().

ws.close(httplib::ws::CloseStatus::Normal, "bye");

The first argument is the close status; the second is an optional reason. Common CloseStatus values:

Value	Meaning
Normal (1000)	Normal closure
GoingAway (1001)	Server is shutting down
ProtocolError (1002)	Protocol violation detected
UnsupportedData (1003)	Received data that can't be handled
PolicyViolation (1008)	Violated a policy
MessageTooBig (1009)	Message too large
InternalError (1011)	Server-side error

Close from the client side

The client API is identical.

cli.close(httplib::ws::CloseStatus::Normal);

Destroying the client also closes the connection, but calling close() explicitly makes the intent clearer.

Graceful shutdown

To notify in-flight clients that the server is going down, use GoingAway.

ws.close(httplib::ws::CloseStatus::GoingAway, "server restarting");

The client can inspect that status and decide whether to reconnect.

Example: a tiny chat with quit

svr.WebSocket("/chat", [](const auto &req, auto &ws) {
  std::string msg;
  while (ws.is_open()) {
    if (ws.read(msg) == httplib::ws::ReadResult::Fail) break;

    if (msg == "/quit") {
      ws.send("goodbye");
      ws.close(httplib::ws::CloseStatus::Normal, "user quit");
      break;
    }

    ws.send("echo: " + msg);
  }
});

Note: On a sudden network drop, read() returns Fail with no chance to call close(). Put your cleanup at the end of the handler, and both paths — clean close and abrupt disconnect — end up in the same place.