net: add setTOS and getTOS to Socket

PR-URL: #61503
Fixes: #61489
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

Author: amyssnippet

doc/api/net.md

@@ -733,6 +733,9 @@ it to interact with the client.
 <!-- YAML
 added: v0.3.4
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/61503
+    description: Added `typeOfService` option.
   - version: v15.14.0
     pr-url: https://github.com/nodejs/node/pull/37735
     description: AbortSignal support was added.
@@ -774,6 +777,7 @@ changes:
     otherwise ignored. **Default:** `false`.
   * `signal` {AbortSignal} An Abort signal that may be used to destroy the
     socket.
+  * `typeOfService` {number} The initial Type of Service (TOS) value.
   * `writable` {boolean} Allow writes on the socket when an `fd` is passed,
     otherwise ignored. **Default:** `false`.
 * Returns: {net.Socket}
@@ -1447,6 +1451,45 @@ If `timeout` is 0, then the existing idle timeout is disabled.
 The optional `callback` parameter will be added as a one-time listener for the
 [`'timeout'`][] event.
 
+### `socket.getTypeOfService()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {integer} The current TOS value.
+
+Returns the current Type of Service (TOS) field for IPv4 packets or Traffic
+Class for IPv6 packets for this socket.
+
+`setTypeOfService()` may be called before the socket is connected; the value
+will be cached and applied when the socket establishes a connection.
+`getTypeOfService()` will return the currently set value even before connection.
+
+On some platforms (e.g., Linux), certain TOS/ECN bits may be masked or ignored,
+and behavior can differ between IPv4 and IPv6 or dual-stack sockets. Callers
+should verify platform-specific semantics.
+
+### `socket.setTypeOfService(tos)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `tos` {integer} The TOS value to set (0-255).
+* Returns: {net.Socket} The socket itself.
+
+Sets the Type of Service (TOS) field for IPv4 packets or Traffic Class for IPv6
+Packets sent from this socket. This can be used to prioritize network traffic.
+
+`setTypeOfService()` may be called before the socket is connected; the value
+will be cached and applied when the socket establishes a connection.
+`getTypeOfService()` will return the currently set value even before connection.
+
+On some platforms (e.g., Linux), certain TOS/ECN bits may be masked or ignored,
+and behavior can differ between IPv4 and IPv6 or dual-stack sockets. Callers
+should verify platform-specific semantics.
+
 ### `socket.timeout`
 
 <!-- YAML

lib/net.js

@@ -55,6 +55,7 @@ const {
 const assert = require('internal/assert');
 const {
   UV_EADDRINUSE,
+  UV_EBADF,
   UV_EINVAL,
   UV_ENOTCONN,
   UV_ECANCELED,
@@ -359,6 +360,7 @@ const kBytesWritten = Symbol('kBytesWritten');
 const kSetNoDelay = Symbol('kSetNoDelay');
 const kSetKeepAlive = Symbol('kSetKeepAlive');
 const kSetKeepAliveInitialDelay = Symbol('kSetKeepAliveInitialDelay');
+const kSetTOS = Symbol('kSetTOS');
 
 function Socket(options) {
   if (!(this instanceof Socket)) return new Socket(options);
@@ -474,6 +476,10 @@ function Socket(options) {
   this[kSetNoDelay] = Boolean(options.noDelay);
   this[kSetKeepAlive] = Boolean(options.keepAlive);
   this[kSetKeepAliveInitialDelay] = ~~(options.keepAliveInitialDelay / 1000);
+  if (options.typeOfService !== undefined) {
+    validateInt32(options.typeOfService, 'options.typeOfService', 0, 255);
+  }
+  this[kSetTOS] = options.typeOfService;
 
   // Shut down the socket when we're finished with it.
   this.on('end', onReadableStreamEnd);
@@ -653,6 +659,59 @@ Socket.prototype.setKeepAlive = function(enable, initialDelayMsecs) {
 };
 
 
+Socket.prototype.setTypeOfService = function(tos) {
+  if (NumberIsNaN(tos)) {
+    throw new ERR_INVALID_ARG_TYPE('tos', 'number', tos);
+  }
+  validateInt32(tos, 'tos', 0, 255);
+
+  if (!this._handle) {
+    this[kSetTOS] = tos;
+    return this;
+  }
+
+  if (!this._handle.setTypeOfService) {
+    this[kSetTOS] = tos;
+    return this;
+  }
+
+  if (tos !== this[kSetTOS]) {
+    this[kSetTOS] = tos;
+    const err = this._handle.setTypeOfService(tos);
+    // On Windows, setting TOS is often restricted or returns error codes even if partially applied.
+    // We treat this as a "best effort" operation and do not throw on Windows.
+    if (err && !isWindows) {
+      throw new ErrnoException(err, 'setTypeOfService');
+    }
+  }
+
+  return this;
+};
+
+
+Socket.prototype.getTypeOfService = function() {
+  if (!this._handle) {
+    // Return cached value if set, otherwise default to 0
+    return this[kSetTOS] !== undefined ? this[kSetTOS] : 0;
+  }
+
+  if (!this._handle.getTypeOfService) {
+    return this[kSetTOS] !== undefined ? this[kSetTOS] : 0;
+  }
+
+  const res = this._handle.getTypeOfService();
+  if (typeof res === 'number' && res < 0) {
+    // On Windows, getsockopt(IP_TOS) often fails. In that case, fall back
+    // to the cached value we attempted to set, or 0.
+    if (isWindows) {
+      return this[kSetTOS] !== undefined ? this[kSetTOS] : 0;
+    }
+    throw new ErrnoException(res, 'getTypeOfService');
+  }
+  return res;
+};
+
+
 Socket.prototype.address = function() {
   return this._getsockname();
 };
@@ -1628,6 +1687,15 @@ function afterConnect(status, handle, req, readable, writable) {
       self._handle.setKeepAlive(true, self[kSetKeepAliveInitialDelay]);
     }
 
+    if (self[kSetTOS] !== undefined && self._handle.setTypeOfService) {
+      const err = self._handle.setTypeOfService(self[kSetTOS]);
+      // On Windows, setting TOS is best-effort. If it fails, we shouldn't destroy
+      // the connection or emit an error, as the socket is otherwise healthy.
+      if (err && err !== UV_EBADF && !isWindows) {
+        self.emit('error', new ErrnoException(err, 'setTypeOfService'));
+      }
+    }
+
     self.emit('connect');
     self.emit('ready');