docs: how to disconnect a specific client

Related: socketio/socket.io-redis-streams-adapter#30

Author: darrachequesne

src/pages/get-started/index.md

@@ -46,3 +46,4 @@ If you are new to Socket.IO, we recommend checking out our [tutorial](/docs/v4/t
 - [get the IP address of the client](/how-to/get-the-ip-address-of-the-client)
 - [count the number of connected clients](/how-to/count-connected-clients)
 - [count the number of connected users](/how-to/count-connected-users)
+- [disconnect a specific client](/how-to/disconnect-a-specific-client)

src/pages/how-to/disconnect-a-specific-client.md

@@ -0,0 +1,75 @@
+---
+title: How to disconnect a specific client
+---
+
+# How to disconnect a specific client
+
+## Standalone
+
+```js
+function disconnectSocket(id) {
+  io.of("/").sockets.get(id)?.disconnect();
+}
+```
+
+## Cluster
+
+### Without acknowledgement
+
+```js
+function disconnectSocket(id) {
+  io.in(id).disconnectSockets();
+}
+```
+
+Reference: [`server.disconnectSockets([close])`](/docs/v4/server-api/#serverdisconnectsocketsclose)
+
+:::tip
+
+This method can also be used to disconnect a given user:
+
+```js
+function computeUserId(socket) {
+  // to be implemented
+}
+
+io.on("connection", (socket) => {
+  const userId = computeUserId(socket);
+  socket.join(userId); // use a room named after the user ID
+});
+
+function disconnectUser(userId) {
+  io.in(userId).disconnectSockets();
+}
+```
+
+:::
+
+### With acknowledgement
+
+```js
+function disconnectLocalSocket(id) {
+  return io.of("/").sockets.get(id)?.disconnect() !== undefined;
+}
+
+io.on("disconnectSocket", (id, cb) => {
+  cb(disconnectLocalSocket(id));
+});
+
+async function disconnectSocket(id) {
+  if (disconnectLocalSocket(id)) {
+    return true;
+  }
+  try {
+    const res = await io.serverSideEmitWithAck("disconnectSocket", id);
+    return res.some(v => v);
+  } catch (e) {
+    // something went wrong
+  }
+}
+```
+
+Reference: [`server.serverSideEmitWithAck(eventName[, ...args]);`](/docs/v4/server-api/#serverserversideemitwithackeventname-args)
+
+
+[< Back to the list of examples](/get-started/)