From b932ba7de347391c0dfe3ced6878755f6cc39328 Mon Sep 17 00:00:00 2001
From: Asaf Federman <46937909+Asaf-Federman@users.noreply.github.com>
Date: Mon, 28 Jul 2025 08:06:16 +0300
Subject: [PATCH 1/3] src: add percentage support to --max-old-space-size

This commit adds support for specifying --max-old-space-size as a
percentage of system memory, in addition to the existing MB format.
A new HandleMaxOldSpaceSizePercentage method parses percentage values,
validates that they are within the 0-100% range, and provides clear
error messages for invalid input. The heap size is now calculated
based on available system memory when a percentage is used.

Test coverage has been added for both valid and invalid cases.
Documentation and the JSON schema for CLI options have been updated
with examples for both formats.

Refs: https://github.com/nodejs/node/issues/57447
PR-URL: https://github.com/nodejs/node/pull/59082
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: theanarkh <theratliter@gmail.com>
Reviewed-By: Daeyeon Jeong <daeyeon.dev@gmail.com>
---
 doc/api/cli.md                                |  17 +++
 doc/node-config-schema.json                   |   3 +
 doc/node.1                                    |  10 ++
 src/node.cc                                   |   7 +
 src/node_options.cc                           |  48 +++++++
 src/node_options.h                            |   4 +
 .../test-max-old-space-size-percentage.js     | 134 ++++++++++++++++++
 7 files changed, 223 insertions(+)
 create mode 100644 test/parallel/test-max-old-space-size-percentage.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index fe680b06a3b949..912bab3e868ba2 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1702,6 +1702,22 @@ changes:
 
 Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB.
 
+### `--max-old-space-size-percentage=PERCENTAGE`
+
+Sets the max memory size of V8's old memory section as a percentage of available system memory.
+This flag takes precedence over `--max-old-space-size` when both are specified.
+
+The `PERCENTAGE` parameter must be a number greater than 0 and up to 100. representing the percentage
+of available system memory to allocate to the V8 heap.
+
+```bash
+# Using 50% of available system memory
+node --max-old-space-size-percentage=50 index.js
+
+# Using 75% of available system memory
+node --max-old-space-size-percentage=75 index.js
+```
+
 ### `--napi-modules`
 
 <!-- YAML
@@ -3387,6 +3403,7 @@ one is included in the list below.
 * `--inspect`
 * `--localstorage-file`
 * `--max-http-header-size`
+* `--max-old-space-size-percentage`
 * `--napi-modules`
 * `--network-family-autoselection-attempt-timeout`
 * `--no-addons`
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
index b78dfa32aec179..58f316c19a969e 100644
--- a/doc/node-config-schema.json
+++ b/doc/node-config-schema.json
@@ -278,6 +278,9 @@
         "max-http-header-size": {
           "type": "number"
         },
+        "max-old-space-size-percentage": {
+          "type": "string"
+        },
         "network-family-autoselection": {
           "type": "boolean"
         },
diff --git a/doc/node.1 b/doc/node.1
index e3b2c45af01b2e..1ca3d1cdc9642d 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -346,6 +346,16 @@ The file used to store localStorage data.
 .It Fl -max-http-header-size Ns = Ns Ar size
 Specify the maximum size of HTTP headers in bytes. Defaults to 16 KiB.
 .
+.It Fl -max-old-space-size-percentage Ns = Ns Ar percentage
+Sets the max memory size of V8's old memory section as a percentage of available system memory.
+This flag takes precedence over
+.Fl -max-old-space-size
+when both are specified.
+The
+.Ar percentage
+parameter must be a number greater than 0 and up to 100, representing the percentage
+of available system memory to allocate to the V8 heap.
+.
 .It Fl -napi-modules
 This option is a no-op.
 It is kept for compatibility.
diff --git a/src/node.cc b/src/node.cc
index d0890e5d77da40..2d8d0000d52411 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -818,6 +818,13 @@ static ExitCode ProcessGlobalArgsInternal(std::vector<std::string>* args,
   // anymore.
   v8_args.emplace_back("--no-harmony-import-assertions");
 
+  if (!per_process::cli_options->per_isolate->max_old_space_size_percentage
+           .empty()) {
+    v8_args.emplace_back(
+        "--max_old_space_size=" +
+        per_process::cli_options->per_isolate->max_old_space_size);
+  }
+
   auto env_opts = per_process::cli_options->per_isolate->per_env;
   if (std::find(v8_args.begin(), v8_args.end(),
                 "--abort-on-uncaught-exception") != v8_args.end() ||
diff --git a/src/node_options.cc b/src/node_options.cc
index ed85bf11f6f325..cecab4b081beec 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -7,6 +7,7 @@
 #include "node_external_reference.h"
 #include "node_internals.h"
 #include "node_sea.h"
+#include "uv.h"
 #if HAVE_OPENSSL
 #include "openssl/opensslv.h"
 #endif
@@ -14,6 +15,7 @@
 #include <algorithm>
 #include <array>
 #include <charconv>
+#include <cstdint>
 #include <limits>
 #include <sstream>
 #include <string_view>
@@ -103,8 +105,49 @@ void PerProcessOptions::CheckOptions(std::vector<std::string>* errors,
   per_isolate->CheckOptions(errors, argv);
 }
 
+void PerIsolateOptions::HandleMaxOldSpaceSizePercentage(
+    std::vector<std::string>* errors,
+    std::string* max_old_space_size_percentage) {
+  std::string original_input_for_error = *max_old_space_size_percentage;
+  // Parse the percentage value
+  char* end_ptr;
+  double percentage =
+      std::strtod(max_old_space_size_percentage->c_str(), &end_ptr);
+
+  // Validate the percentage value
+  if (*end_ptr != '\0' || percentage <= 0.0 || percentage > 100.0) {
+    errors->push_back("--max-old-space-size-percentage must be greater "
+                      "than 0 and up to 100. Got: " +
+                      original_input_for_error);
+    return;
+  }
+
+  // Get available memory in bytes
+  uint64_t total_memory = uv_get_total_memory();
+  uint64_t constrained_memory = uv_get_constrained_memory();
+
+  // Use constrained memory if available, otherwise use total memory
+  // This logic correctly handles the documented guarantees.
+  // Use uint64_t for the result to prevent data loss on 32-bit systems.
+  uint64_t available_memory =
+      (constrained_memory > 0 && constrained_memory != UINT64_MAX)
+          ? constrained_memory
+          : total_memory;
+
+  // Convert to MB and calculate the percentage
+  uint64_t memory_mb = available_memory / (1024 * 1024);
+  uint64_t calculated_mb = static_cast<size_t>(memory_mb * percentage / 100.0);
+
+  // Convert back to string
+  max_old_space_size = std::to_string(calculated_mb);
+}
+
 void PerIsolateOptions::CheckOptions(std::vector<std::string>* errors,
                                      std::vector<std::string>* argv) {
+  if (!max_old_space_size_percentage.empty()) {
+    HandleMaxOldSpaceSizePercentage(errors, &max_old_space_size_percentage);
+  }
+
   per_env->CheckOptions(errors, argv);
 }
 
@@ -987,6 +1030,11 @@ PerIsolateOptionsParser::PerIsolateOptionsParser(
             V8Option{},
             kAllowedInEnvvar);
   AddOption("--max-old-space-size", "", V8Option{}, kAllowedInEnvvar);
+  AddOption("--max-old-space-size-percentage",
+            "set V8's max old space size as a percentage of available memory "
+            "(e.g., '50%'). Takes precedence over --max-old-space-size.",
+            &PerIsolateOptions::max_old_space_size_percentage,
+            kAllowedInEnvvar);
   AddOption("--max-semi-space-size", "", V8Option{}, kAllowedInEnvvar);
   AddOption("--perf-basic-prof", "", V8Option{}, kAllowedInEnvvar);
   AddOption(
diff --git a/src/node_options.h b/src/node_options.h
index cdbd9ca39e907a..1339c5077e2a5b 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -283,6 +283,8 @@ class PerIsolateOptions : public Options {
   bool report_uncaught_exception = false;
   bool report_on_signal = false;
   bool experimental_shadow_realm = false;
+  std::string max_old_space_size_percentage;
+  std::string max_old_space_size;
   int64_t stack_trace_limit = 10;
   std::string report_signal = "SIGUSR2";
   bool build_snapshot = false;
@@ -290,6 +292,8 @@ class PerIsolateOptions : public Options {
   inline EnvironmentOptions* get_per_env_options();
   void CheckOptions(std::vector<std::string>* errors,
                     std::vector<std::string>* argv) override;
+  void HandleMaxOldSpaceSizePercentage(std::vector<std::string>* errors,
+                                       std::string* max_old_space_size);
 
   inline std::shared_ptr<PerIsolateOptions> Clone() const;
 
diff --git a/test/parallel/test-max-old-space-size-percentage.js b/test/parallel/test-max-old-space-size-percentage.js
new file mode 100644
index 00000000000000..511a10109f9d2b
--- /dev/null
+++ b/test/parallel/test-max-old-space-size-percentage.js
@@ -0,0 +1,134 @@
+'use strict';
+
+// This test validates the --max-old-space-size-percentage flag functionality
+
+require('../common');
+const assert = require('node:assert');
+const { spawnSync } = require('child_process');
+const os = require('os');
+
+// Valid cases
+const validPercentages = [
+  '1', '10', '25', '50', '75', '99', '100', '25.5',
+];
+
+// Invalid cases
+const invalidPercentages = [
+  ['', /--max-old-space-size-percentage= requires an argument/],
+  ['0', /--max-old-space-size-percentage must be greater than 0 and up to 100\. Got: 0/],
+  ['101', /--max-old-space-size-percentage must be greater than 0 and up to 100\. Got: 101/],
+  ['-1', /--max-old-space-size-percentage must be greater than 0 and up to 100\. Got: -1/],
+  ['abc', /--max-old-space-size-percentage must be greater than 0 and up to 100\. Got: abc/],
+  ['1%', /--max-old-space-size-percentage must be greater than 0 and up to 100\. Got: 1%/],
+];
+
+// Test valid cases
+validPercentages.forEach((input) => {
+  const result = spawnSync(process.execPath, [
+    `--max-old-space-size-percentage=${input}`,
+  ], { stdio: ['pipe', 'pipe', 'pipe'] });
+  assert.strictEqual(result.status, 0, `Expected exit code 0 for valid input ${input}`);
+  assert.strictEqual(result.stderr.toString(), '', `Expected empty stderr for valid input ${input}`);
+});
+
+// Test invalid cases
+invalidPercentages.forEach((input) => {
+  const result = spawnSync(process.execPath, [
+    `--max-old-space-size-percentage=${input[0]}`,
+  ], { stdio: ['pipe', 'pipe', 'pipe'] });
+  assert.notStrictEqual(result.status, 0, `Expected non-zero exit for invalid input ${input[0]}`);
+  assert(input[1].test(result.stderr.toString()), `Unexpected error message for invalid input ${input[0]}`);
+});
+
+// Test NODE_OPTIONS with valid percentages
+validPercentages.forEach((input) => {
+  const result = spawnSync(process.execPath, [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, NODE_OPTIONS: `--max-old-space-size-percentage=${input}` }
+  });
+  assert.strictEqual(result.status, 0, `NODE_OPTIONS: Expected exit code 0 for valid input ${input}`);
+  assert.strictEqual(result.stderr.toString(), '', `NODE_OPTIONS: Expected empty stderr for valid input ${input}`);
+});
+
+// Test NODE_OPTIONS with invalid percentages
+invalidPercentages.forEach((input) => {
+  const result = spawnSync(process.execPath, [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, NODE_OPTIONS: `--max-old-space-size-percentage=${input[0]}` }
+  });
+  assert.notStrictEqual(result.status, 0, `NODE_OPTIONS: Expected non-zero exit for invalid input ${input[0]}`);
+  assert(input[1].test(result.stderr.toString()), `NODE_OPTIONS: Unexpected error message for invalid input ${input[0]}`);
+});
+
+// Test percentage calculation validation
+function getHeapSizeForPercentage(percentage) {
+  const result = spawnSync(process.execPath, [
+    '--max-old-space-size=3000', // This value should be ignored, since percentage takes precedence
+    `--max-old-space-size-percentage=${percentage}`,
+    '--max-old-space-size=1000', // This value should be ignored, since percentage take precedence
+    '-e', `
+      const v8 = require('v8');
+      const stats = v8.getHeapStatistics();
+      const heapSizeLimitMB = Math.floor(stats.heap_size_limit / 1024 / 1024);
+      console.log(heapSizeLimitMB);
+    `,
+  ], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      NODE_OPTIONS: `--max-old-space-size=2000` // This value should be ignored, since percentage takes precedence
+    }
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`Failed to get heap size for ${percentage}: ${result.stderr.toString()}`);
+  }
+
+  return parseInt(result.stdout.toString(), 10);
+}
+
+const testPercentages = [25, 50, 75, 100];
+const heapSizes = {};
+
+// Get heap sizes for all test percentages
+testPercentages.forEach((percentage) => {
+  heapSizes[percentage] = getHeapSizeForPercentage(percentage);
+});
+
+// Test relative relationships between percentages
+// 50% should be roughly half of 100%
+const ratio50to100 = heapSizes[50] / heapSizes[100];
+assert(
+  ratio50to100 >= 0.4 && ratio50to100 <= 0.6,
+  `50% heap size should be roughly half of 100% (got ${ratio50to100.toFixed(2)}, expected ~0.5)`
+);
+
+// 25% should be roughly quarter of 100%
+const ratio25to100 = heapSizes[25] / heapSizes[100];
+assert(
+  ratio25to100 >= 0.15 && ratio25to100 <= 0.35,
+  `25% heap size should be roughly quarter of 100% (got ${ratio25to100.toFixed(2)}, expected ~0.25)`
+);
+
+// 75% should be roughly three-quarters of 100%
+const ratio75to100 = heapSizes[75] / heapSizes[100];
+assert(
+  ratio75to100 >= 0.65 && ratio75to100 <= 0.85,
+  `75% heap size should be roughly three-quarters of 100% (got ${ratio75to100.toFixed(2)}, expected ~0.75)`
+);
+
+// Validate heap sizes against system memory
+const totalMemoryMB = Math.floor(os.totalmem() / 1024 / 1024);
+const margin = 10; // 5% margin
+testPercentages.forEach((percentage) => {
+  const upperLimit = totalMemoryMB * ((percentage + margin) / 100);
+  assert(
+    heapSizes[percentage] <= upperLimit,
+    `Heap size for ${percentage}% (${heapSizes[percentage]} MB) should not exceed upper limit (${upperLimit} MB)`
+  );
+  const lowerLimit = totalMemoryMB * ((percentage - margin) / 100);
+  assert(
+    heapSizes[percentage] >= lowerLimit,
+    `Heap size for ${percentage}% (${heapSizes[percentage]} MB) should not be less than lower limit (${lowerLimit} MB)`
+  );
+});

From cf0bc760f3a7493e97aa26e443b4b6238b261e37 Mon Sep 17 00:00:00 2001
From: Asaf Federman <asaf1235588@gmail.com>
Date: Mon, 18 Aug 2025 09:51:48 +0300
Subject: [PATCH 2/3] src: assert memory calc for max-old-space-size-percentage

Add validation to ensure that --max-old-space-size-percentage cannot
be used when available memory cannot be calculated, preventing
undefined behavior when memory detection fails.

Also enhance test-process-constrained-memory.js to support testing
in constrained environments where memory calculation may fail.

PR-URL: https://github.com/nodejs/node/pull/59460
Reviewed-By: theanarkh <theratliter@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
---
 src/node_options.cc                                 |  5 +++++
 test/parallel/test-max-old-space-size-percentage.js | 11 ++++++++---
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/node_options.cc b/src/node_options.cc
index cecab4b081beec..e12c3e7790038c 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -134,6 +134,11 @@ void PerIsolateOptions::HandleMaxOldSpaceSizePercentage(
           ? constrained_memory
           : total_memory;
 
+  if (available_memory == 0) {
+    errors->push_back("the available memory can not be calculated");
+    return;
+  }
+
   // Convert to MB and calculate the percentage
   uint64_t memory_mb = available_memory / (1024 * 1024);
   uint64_t calculated_mb = static_cast<size_t>(memory_mb * percentage / 100.0);
diff --git a/test/parallel/test-max-old-space-size-percentage.js b/test/parallel/test-max-old-space-size-percentage.js
index 511a10109f9d2b..e55c426d7ee1a8 100644
--- a/test/parallel/test-max-old-space-size-percentage.js
+++ b/test/parallel/test-max-old-space-size-percentage.js
@@ -119,14 +119,19 @@ assert(
 
 // Validate heap sizes against system memory
 const totalMemoryMB = Math.floor(os.totalmem() / 1024 / 1024);
-const margin = 10; // 5% margin
+const uint64Max = 2 ** 64 - 1;
+const constrainedMemory = process.constrainedMemory();
+const constrainedMemoryMB = Math.floor(constrainedMemory / 1024 / 1024);
+const effectiveMemoryMB =
+  constrainedMemory > 0 && constrainedMemory !== uint64Max ? constrainedMemoryMB : totalMemoryMB;
+const margin = 10; // 10% margin
 testPercentages.forEach((percentage) => {
-  const upperLimit = totalMemoryMB * ((percentage + margin) / 100);
+  const upperLimit = effectiveMemoryMB * ((percentage + margin) / 100);
   assert(
     heapSizes[percentage] <= upperLimit,
     `Heap size for ${percentage}% (${heapSizes[percentage]} MB) should not exceed upper limit (${upperLimit} MB)`
   );
-  const lowerLimit = totalMemoryMB * ((percentage - margin) / 100);
+  const lowerLimit = effectiveMemoryMB * ((percentage - margin) / 100);
   assert(
     heapSizes[percentage] >= lowerLimit,
     `Heap size for ${percentage}% (${heapSizes[percentage]} MB) should not be less than lower limit (${lowerLimit} MB)`

From fa96235e13e0a311ca6a5a4fdb0c747c60510b77 Mon Sep 17 00:00:00 2001
From: Asaf Federman <asaf1235588@gmail.com>
Date: Thu, 9 Oct 2025 19:23:51 +0300
Subject: [PATCH 3/3] test,doc: skip --max-old-space-size-percentage on 32-bit
 platforms
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/60144
Reviewed-By: Richard Lau <richard.lau@ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
---
 doc/api/cli.md                                      | 9 ++++++---
 doc/node.1                                          | 6 +++++-
 test/parallel/test-max-old-space-size-percentage.js | 6 +++++-
 3 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 912bab3e868ba2..73d8fb3191e3f0 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1702,14 +1702,17 @@ changes:
 
 Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB.
 
-### `--max-old-space-size-percentage=PERCENTAGE`
+### `--max-old-space-size-percentage=percentage`
 
-Sets the max memory size of V8's old memory section as a percentage of available system memory.
+Sets the maximum memory size of V8's old memory section as a percentage of available system memory.
 This flag takes precedence over `--max-old-space-size` when both are specified.
 
-The `PERCENTAGE` parameter must be a number greater than 0 and up to 100. representing the percentage
+The `percentage` parameter must be a number greater than 0 and up to 100, representing the percentage
 of available system memory to allocate to the V8 heap.
 
+**Note:** This flag utilizes `--max-old-space-size`, which may be unreliable on 32-bit platforms due to
+integer overflow issues.
+
 ```bash
 # Using 50% of available system memory
 node --max-old-space-size-percentage=50 index.js
diff --git a/doc/node.1 b/doc/node.1
index 1ca3d1cdc9642d..196545e9d10c2d 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -347,7 +347,7 @@ The file used to store localStorage data.
 Specify the maximum size of HTTP headers in bytes. Defaults to 16 KiB.
 .
 .It Fl -max-old-space-size-percentage Ns = Ns Ar percentage
-Sets the max memory size of V8's old memory section as a percentage of available system memory.
+Sets the maximum memory size of V8's old memory section as a percentage of available system memory.
 This flag takes precedence over
 .Fl -max-old-space-size
 when both are specified.
@@ -355,6 +355,10 @@ The
 .Ar percentage
 parameter must be a number greater than 0 and up to 100, representing the percentage
 of available system memory to allocate to the V8 heap.
+.Pp
+Note: This flag utilizes
+.Fl -max-old-space-size ,
+which may be unreliable on 32-bit platforms due to integer overflow issues.
 .
 .It Fl -napi-modules
 This option is a no-op.
diff --git a/test/parallel/test-max-old-space-size-percentage.js b/test/parallel/test-max-old-space-size-percentage.js
index e55c426d7ee1a8..d4da10b3012662 100644
--- a/test/parallel/test-max-old-space-size-percentage.js
+++ b/test/parallel/test-max-old-space-size-percentage.js
@@ -2,7 +2,11 @@
 
 // This test validates the --max-old-space-size-percentage flag functionality
 
-require('../common');
+const common = require('../common');
+// This flag utilizes --max-old-space-size, which is unreliable on
+// 32-bit platforms due to integer overflow issues.
+common.skipIf32Bits();
+
 const assert = require('node:assert');
 const { spawnSync } = require('child_process');
 const os = require('os');