From 37cd60c1140376093501b7e9bf4ddf238d7cf993 Mon Sep 17 00:00:00 2001
From: Damien Arrachequesne <damien.arrachequesne@gmail.com>
Date: Mon, 15 Nov 2021 07:08:35 +0100
Subject: [PATCH] docs: add documentation about underlying Engine.IO connection

Related: https://github.com/socketio/socket.io-adapter/pull/78
---
 .../02-Server/server-socket-instance.md       | 31 +++++++++++++++++
 .../03-Client/client-socket-instance.md       | 32 +++++++++++++++++
 docs/client-api.md                            | 34 +++++++++++++++++++
 docs/server-api.md                            | 25 +++++++++++---
 4 files changed, 117 insertions(+), 5 deletions(-)

diff --git a/docs/categories/02-Server/server-socket-instance.md b/docs/categories/02-Server/server-socket-instance.md
index 3164c0c5..37804255 100644
--- a/docs/categories/02-Server/server-socket-instance.md
+++ b/docs/categories/02-Server/server-socket-instance.md
@@ -117,6 +117,37 @@ console.log(sockets[0].data.username); // "alice"
 
 More information [here](server-instance.md#utility-methods).
 
+## Socket#conn
+
+A reference to the underlying Engine.IO socket (see [here](../01-Documentation/how-it-works.md)).
+
+```js
+io.on("connection", (socket) => {
+  console.log("initial transport", socket.conn.transport.name); // prints "polling"
+
+  socket.conn.once("upgrade", () => {
+    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
+    console.log("upgraded transport", socket.conn.transport.name); // prints "websocket"
+  });
+
+  socket.conn.on("packet", ({ type, data }) => {
+    // called for each packet received
+  });
+
+  socket.conn.on("packetCreate", ({ type, data }) => {
+    // called for each packet sent
+  });
+
+  socket.conn.on("drain", () => {
+    // called when the write buffer is drained
+  });
+
+  socket.conn.on("close", (reason) => {
+    // called when the underlying connection is closed
+  });
+});
+```
+
 ## Additional attributes
 
 As long as you do not overwrite any existing attribute, you can attach any attribute to the Socket instance and use it later:
diff --git a/docs/categories/03-Client/client-socket-instance.md b/docs/categories/03-Client/client-socket-instance.md
index 6620a6c3..da0cddba 100644
--- a/docs/categories/03-Client/client-socket-instance.md
+++ b/docs/categories/03-Client/client-socket-instance.md
@@ -43,6 +43,38 @@ socket.on("disconnect", () => {
 });
 ```
 
+## Socket#io
+
+A reference to the underlying [Manager](../../client-api.md#manager).
+
+```js
+socket.on("connect", () => {
+  const engine = socket.io.engine;
+  console.log(engine.transport.name); // in most cases, prints "polling"
+
+  engine.once("upgrade", () => {
+    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
+    console.log(engine.transport.name); // in most cases, prints "websocket"
+  });
+
+  engine.on("packet", ({ type, data }) => {
+    // called for each packet received
+  });
+
+  engine.on("packetCreate", ({ type, data }) => {
+    // called for each packet sent
+  });
+
+  engine.on("drain", () => {
+    // called when the write buffer is drained
+  });
+
+  engine.on("close", (reason) => {
+    // called when the underlying connection is closed
+  });
+});
+```
+
 ## Lifecycle
 
 <img src="/images/client_socket_events.png" alt="Lifecycle diagram" />
diff --git a/docs/client-api.md b/docs/client-api.md
index 066b6f2f..d43f2835 100644
--- a/docs/client-api.md
+++ b/docs/client-api.md
@@ -287,6 +287,40 @@ socket.on("connect", () => {
 });
 ```
 
+### socket.io
+
+  - [Manager](#manager)
+
+A reference to the underlying [Manager](#manager).
+
+```js
+socket.on("connect", () => {
+  const engine = socket.io.engine;
+  console.log(engine.transport.name); // in most cases, prints "polling"
+
+  engine.once("upgrade", () => {
+    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
+    console.log(engine.transport.name); // in most cases, prints "websocket"
+  });
+
+  engine.on("packet", ({ type, data }) => {
+    // called for each packet received
+  });
+
+  engine.on("packetCreate", ({ type, data }) => {
+    // called for each packet sent
+  });
+
+  engine.on("drain", () => {
+    // called when the write buffer is drained
+  });
+
+  engine.on("close", (reason) => {
+    // called when the underlying connection is closed
+  });
+});
+```
+
 ### socket.connect()
 
 <span class="changelog">Added in v1.0.0</span>
diff --git a/docs/server-api.md b/docs/server-api.md
index 57197b94..5ac54ddc 100644
--- a/docs/server-api.md
+++ b/docs/server-api.md
@@ -791,12 +791,27 @@ A reference to the underlying `Client` transport connection (engine.io `Socket`
 
 ```js
 io.on("connection", (socket) => {
-  const transport = socket.conn.transport.name; // for example, "polling"
-  console.log("current transport", transport);
+  console.log("initial transport", socket.conn.transport.name); // prints "polling"
 
-  socket.conn.on("upgrade", () => {
-    const newTransport = socket.conn.transport.name; // for example, "websocket"
-    console.log("new transport", newTransport);
+  socket.conn.once("upgrade", () => {
+    // called when the transport is upgraded (i.e. from HTTP long-polling to WebSocket)
+    console.log("upgraded transport", socket.conn.transport.name); // prints "websocket"
+  });
+
+  socket.conn.on("packet", ({ type, data }) => {
+    // called for each packet received
+  });
+
+  socket.conn.on("packetCreate", ({ type, data }) => {
+    // called for each packet sent
+  });
+
+  socket.conn.on("drain", () => {
+    // called when the write buffer is drained
+  });
+
+  socket.conn.on("close", (reason) => {
+    // called when the underlying connection is closed
   });
 });
 ```