docs: add documentation about underlying Engine.IO connection

Related: socketio/socket.io-adapter#78

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:

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" />

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>

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
   });
 });
 ```