From 562fc28cda29c3c438b4829e3cafe16821a37a33 Mon Sep 17 00:00:00 2001
From: theanarkh <theratliter@gmail.com>
Date: Wed, 10 Sep 2025 00:43:18 +0800
Subject: [PATCH] dns: support rotate dns servers

---
 doc/api/dns.md                            |   5 +
 lib/internal/dns/utils.js                 |  29 ++++--
 src/cares_wrap.cc                         |  25 ++++-
 src/cares_wrap.h                          |   5 +-
 test/parallel/test-dns-resolver-rotate.js | 108 ++++++++++++++++++++++
 5 files changed, 160 insertions(+), 12 deletions(-)
 create mode 100644 test/parallel/test-dns-resolver-rotate.js

diff --git a/doc/api/dns.md b/doc/api/dns.md
index 61846f6f621014..3a44e69232ccef 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -139,6 +139,9 @@ The following methods from the `node:dns` module are available:
 <!-- YAML
 added: v8.3.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/59829
+    description: The `options` object now accepts a `rotate` option.
   - version:
       - v16.7.0
       - v14.18.0
@@ -159,6 +162,8 @@ Create a new resolver.
     each name server before giving up. **Default:** `4`
   * `maxTimeout` {integer} The max retry timeout, in milliseconds.
     **Default:** `0`, disabled.
+  * `rotate` {boolean} Perform round-robin selection of the nameservers for each resolution.
+    **Default:** `undefined`, depends on system configuration and Node.js build settings.
 
 ### `resolver.cancel()`
 
diff --git a/lib/internal/dns/utils.js b/lib/internal/dns/utils.js
index d036c4c7255eab..61e202e9a76964 100644
--- a/lib/internal/dns/utils.js
+++ b/lib/internal/dns/utils.js
@@ -22,6 +22,7 @@ const { isIP } = require('internal/net');
 const { getOptionValue } = require('internal/options');
 const {
   validateArray,
+  validateBoolean,
   validateInt32,
   validateOneOf,
   validateString,
@@ -62,6 +63,14 @@ function validateTries(options) {
   return tries;
 }
 
+function validateRotate(options) {
+  const { rotate } = { ...options };
+  if (rotate !== undefined) {
+    validateBoolean(rotate, 'options.rotate');
+  }
+  return rotate;
+}
+
 const kSerializeResolver = Symbol('dns:resolver:serialize');
 const kDeserializeResolver = Symbol('dns:resolver:deserialize');
 const kSnapshotStates = Symbol('dns:resolver:config');
@@ -75,17 +84,18 @@ class ResolverBase {
     const timeout = validateTimeout(options);
     const tries = validateTries(options);
     const maxTimeout = validateMaxTimeout(options);
+    const rotate = validateRotate(options);
     // If we are building snapshot, save the states of the resolver along
     // the way.
     if (isBuildingSnapshot()) {
-      this[kSnapshotStates] = { timeout, tries, maxTimeout };
+      this[kSnapshotStates] = { timeout, tries, maxTimeout, rotate };
     }
-    this[kInitializeHandle](timeout, tries, maxTimeout);
+    this[kInitializeHandle](timeout, tries, maxTimeout, rotate);
   }
 
-  [kInitializeHandle](timeout, tries, maxTimeout) {
+  [kInitializeHandle](timeout, tries, maxTimeout, rotate) {
     const { ChannelWrap } = lazyBinding();
-    this._handle = new ChannelWrap(timeout, tries, maxTimeout);
+    this._handle = new ChannelWrap(timeout, tries, maxTimeout, rotate);
   }
 
   cancel() {
@@ -195,8 +205,15 @@ class ResolverBase {
   }
 
   [kDeserializeResolver]() {
-    const { timeout, tries, maxTimeout, localAddress, servers } = this[kSnapshotStates];
-    this[kInitializeHandle](timeout, tries, maxTimeout);
+    const {
+      timeout,
+      tries,
+      maxTimeout,
+      localAddress,
+      servers,
+      rotate,
+    } = this[kSnapshotStates];
+    this[kInitializeHandle](timeout, tries, maxTimeout, rotate);
     if (localAddress) {
       const { ipv4, ipv6 } = localAddress;
       this._handle.setLocalAddress(ipv4, ipv6);
diff --git a/src/cares_wrap.cc b/src/cares_wrap.cc
index e9516b03ec8960..35159ade98451d 100644
--- a/src/cares_wrap.cc
+++ b/src/cares_wrap.cc
@@ -62,6 +62,7 @@ namespace cares_wrap {
 
 using v8::Array;
 using v8::ArrayBuffer;
+using v8::Boolean;
 using v8::Context;
 using v8::EscapableHandleScope;
 using v8::Exception;
@@ -791,11 +792,13 @@ ChannelWrap::ChannelWrap(Environment* env,
                          Local<Object> object,
                          int timeout,
                          int tries,
-                         int max_timeout)
+                         int max_timeout,
+                         std::optional<bool> rotate)
     : AsyncWrap(env, object, PROVIDER_DNSCHANNEL),
       timeout_(timeout),
       tries_(tries),
-      max_timeout_(max_timeout) {
+      max_timeout_(max_timeout),
+      rotate_(rotate) {
   MakeWeak();
 
   Setup();
@@ -809,15 +812,21 @@ void ChannelWrap::MemoryInfo(MemoryTracker* tracker) const {
 
 void ChannelWrap::New(const FunctionCallbackInfo<Value>& args) {
   CHECK(args.IsConstructCall());
-  CHECK_EQ(args.Length(), 3);
+  CHECK_GE(args.Length(), 3);
   CHECK(args[0]->IsInt32());
   CHECK(args[1]->IsInt32());
   CHECK(args[2]->IsInt32());
+
   const int timeout = args[0].As<Int32>()->Value();
   const int tries = args[1].As<Int32>()->Value();
   const int max_timeout = args[2].As<Int32>()->Value();
+  std::optional<bool> rotate;
+  if (!args[3]->IsUndefined()) {
+    CHECK(args[3]->IsBoolean());
+    rotate = args[3].As<Boolean>()->Value();
+  }
   Environment* env = Environment::GetCurrent(args);
-  new ChannelWrap(env, args.This(), timeout, tries, max_timeout);
+  new ChannelWrap(env, args.This(), timeout, tries, max_timeout, rotate);
 }
 
 GetAddrInfoReqWrap::GetAddrInfoReqWrap(Environment* env,
@@ -889,7 +898,13 @@ void ChannelWrap::Setup() {
     options.maxtimeout = max_timeout_;
     optmask |= ARES_OPT_MAXTIMEOUTMS;
   }
-
+  if (rotate_.has_value()) {
+    if (rotate_.value()) {
+      optmask |= ARES_OPT_ROTATE;
+    } else {
+      optmask |= ARES_OPT_NOROTATE;
+    }
+  }
   r = ares_init_options(&channel_, &options, optmask);
 
   if (r != ARES_SUCCESS) {
diff --git a/src/cares_wrap.h b/src/cares_wrap.h
index fd66a67164b3d3..d8fd31089a5472 100644
--- a/src/cares_wrap.h
+++ b/src/cares_wrap.h
@@ -18,6 +18,7 @@
 #include "v8.h"
 #include "uv.h"
 
+#include <optional>
 #include <unordered_set>
 
 #ifdef __POSIX__
@@ -156,7 +157,8 @@ class ChannelWrap final : public AsyncWrap {
               v8::Local<v8::Object> object,
               int timeout,
               int tries,
-              int max_timeout);
+              int max_timeout,
+              std::optional<bool> rotate);
   ~ChannelWrap() override;
 
   static void New(const v8::FunctionCallbackInfo<v8::Value>& args);
@@ -192,6 +194,7 @@ class ChannelWrap final : public AsyncWrap {
   int timeout_;
   int tries_;
   int max_timeout_;
+  std::optional<bool> rotate_;
   int active_query_count_ = 0;
   NodeAresTask::List task_list_;
 };
diff --git a/test/parallel/test-dns-resolver-rotate.js b/test/parallel/test-dns-resolver-rotate.js
new file mode 100644
index 00000000000000..647591638fd249
--- /dev/null
+++ b/test/parallel/test-dns-resolver-rotate.js
@@ -0,0 +1,108 @@
+'use strict';
+const common = require('../common');
+const dnstools = require('../common/dns');
+const dns = require('dns');
+const assert = require('assert');
+const dgram = require('dgram');
+
+function validate() {
+  [
+    -1,
+    1.1,
+    NaN,
+    undefined,
+    {},
+    [],
+    null,
+    function() {},
+    Symbol(),
+    Infinity,
+  ].forEach((rotate) => {
+    try {
+      new dns.Resolver({ rotate });
+    } catch (e) {
+      assert.ok(/ERR_INVALID_ARG_TYPE/i.test(e.code));
+    }
+  });
+}
+
+const domain = 'example.org';
+const answers = [{ type: 'A', address: '1.2.3.4', ttl: 123, domain }];
+
+function createServer() {
+  return new Promise((resolve) => {
+    const server = dgram.createSocket('udp4');
+    server.on('message', (msg, { address, port }) => {
+      const parsed = dnstools.parseDNSPacket(msg);
+      server.send(dnstools.writeDNSPacket({
+        id: parsed.id,
+        questions: parsed.questions,
+        answers: answers,
+      }), port, address);
+    });
+    server.bind(0, common.mustCall(() => {
+      resolve(server);
+    }));
+  });
+}
+
+function check(result, answers) {
+  assert.strictEqual(result.length, answers.length);
+  assert.strictEqual(result[0].type, answers[0].type);
+  assert.strictEqual(result[0].address, answers[0].address);
+  assert.strictEqual(result[0].ttl, answers[0].ttl);
+}
+
+async function main() {
+  validate();
+  {
+    const resolver = new dns.promises.Resolver({ rotate: false });
+    const server1 = await createServer();
+    const server2 = await createServer();
+    const address1 = server1.address();
+    const address2 = server2.address();
+    resolver.setServers([
+      `127.0.0.1:${address1.port}`,
+      `127.0.0.1:${address2.port}`,
+    ]);
+    server2.on('message', common.mustNotCall());
+    const promises = [];
+    // All queries should be sent to the server1
+    for (let i = 0; i < 5; i++) {
+      promises.push(resolver.resolveAny(domain));
+    }
+    const results = await Promise.all(promises);
+    results.forEach((result) => check(result, answers));
+    server1.close();
+    server2.close();
+  }
+
+  {
+    const resolver = new dns.promises.Resolver({ rotate: true });
+    const serverPromises = [];
+    for (let i = 0; i < 10; i++) {
+      serverPromises.push(createServer());
+    }
+    const servers = await Promise.all(serverPromises);
+    const addresses = [];
+    let receiver = 0;
+    servers.forEach((server) => {
+      addresses.push(`127.0.0.1:${server.address().port}`);
+      server.once('message', () => {
+        receiver++;
+      });
+    });
+    resolver.setServers(addresses);
+    const queryPromises = [];
+    // All queries should be randomly sent to the server (Unless the same server is chosen every time)
+    for (let i = 0; i < 30; i++) {
+      queryPromises.push(resolver.resolveAny(domain));
+    }
+    const results = await Promise.all(queryPromises);
+    results.forEach((result) => check(result, answers));
+    assert.ok(receiver > 1, `receiver: ${receiver}`);
+    servers.forEach((server) => server.close());
+  }
+}
+
+main();