lib: add navigator.deviceMemory

Author: Uzlopak

LICENSE

@@ -2170,3 +2170,34 @@ The externally maintained libraries used by Node.js are:
     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   """
+
+- GetApproximatedDeviceMemory, located at src/node_os.cc, is licensed as follows:
+  """
+    // Copyright 2017 The Chromium Authors
+    //
+    // Redistribution and use in source and binary forms, with or without
+    // modification, are permitted provided that the following conditions are
+    // met:
+    //
+    //    * Redistributions of source code must retain the above copyright
+    // notice, this list of conditions and the following disclaimer.
+    //    * Redistributions in binary form must reproduce the above
+    // copyright notice, this list of conditions and the following disclaimer
+    // in the documentation and/or other materials provided with the
+    // distribution.
+    //    * Neither the name of Google Inc. nor the names of its
+    // contributors may be used to endorse or promote products derived from
+    // this software without specific prior written permission.
+    //
+    // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+    // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+    // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+    // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+    // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+    // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+  """

doc/api/globals.md

@@ -629,6 +629,27 @@ logical processors available to the current Node.js instance.
 console.log(`This process is running on ${navigator.hardwareConcurrency}`);
 ```
 
+### `navigator.deviceMemory`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* {number}
+
+The `navigator.deviceMemory` read-only property indicates the approximate
+amount of available RAM on the device. It is part of the 
+[Device Memory API](https://www.w3.org/TR/device-memory/).
+
+The amount of device RAM can be used as a fingerprinting variable, so values
+are intentionally coarse to reduce the potential for its misuse.
+
+```js
+console.log(`The process has approximately ${navigator.deviceMemory} GiB of RAM`);
+```
+
 ## `PerformanceEntry`
 
 <!-- YAML

lib/internal/navigator.js

@@ -15,13 +15,15 @@ const {
 
 const {
   getAvailableParallelism,
+  getApproximatedDeviceMemory,
 } = internalBinding('os');
 
 const kInitialize = Symbol('kInitialize');
 
 class Navigator {
   // Private properties are used to avoid brand validations.
   #availableParallelism;
+  #deviceMemory;
 
   constructor() {
     if (arguments[0] === kInitialize) {
@@ -37,10 +39,19 @@ class Navigator {
     this.#availableParallelism ??= getAvailableParallelism();
     return this.#availableParallelism;
   }
+
+  /**
+   * @returns {number}
+   */
+  get deviceMemory() {
+    this.#deviceMemory ??= getApproximatedDeviceMemory();
+    return this.#deviceMemory;
+  }
 }
 
 ObjectDefineProperties(Navigator.prototype, {
   hardwareConcurrency: kEnumerableProperty,
+  deviceMemory: kEnumerableProperty,
 });
 
 module.exports = {

src/node_os.cc

@@ -146,6 +146,40 @@ static void GetTotalMemory(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(amount);
 }
 
+// The calculations in this method are described in the specification:
+// https://w3c.github.io/device-memory/.
+static void GetApproximatedDeviceMemory(
+    const FunctionCallbackInfo<Value>& args) {
+  float approximated_device_memory_gb_ = 0.0;
+  double physical_memory_mb_ =
+      static_cast<double>(uv_get_total_memory() / (1024 * 1024));
+  DCHECK_GT(physical_memory_mb_, 0);
+  int power = 0;
+  int lower_bound = physical_memory_mb_;
+
+  // Extract the most-significant-bit and its location.
+  while (lower_bound > 1) {
+    lower_bound >>= 1;
+    power++;
+  }
+  // The remaining should always be equal to exactly 1.
+  DCHECK_EQ(lower_bound, 1);
+
+  int64_t upper_bound = lower_bound + 1;
+  lower_bound = lower_bound << power;
+  upper_bound = upper_bound << power;
+
+  // Find the closest bound, and convert it to GB.
+  if (physical_memory_mb_ - lower_bound <= upper_bound - physical_memory_mb_)
+    approximated_device_memory_gb_ = static_cast<float>(lower_bound) / 1024.0;
+  else
+    approximated_device_memory_gb_ = static_cast<float>(upper_bound) / 1024.0;
+
+  // Max-limit the reported value to 8GB to reduce fingerprintability of
+  // high-spec machines.
+  if (approximated_device_memory_gb_ > 8) approximated_device_memory_gb_ = 8.0;
+  args.GetReturnValue().Set(approximated_device_memory_gb_);
+}
 
 static void GetUptime(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
@@ -394,6 +428,10 @@ void Initialize(Local<Object> target,
   SetMethod(context, target, "getLoadAvg", GetLoadAvg);
   SetMethod(context, target, "getUptime", GetUptime);
   SetMethod(context, target, "getTotalMem", GetTotalMemory);
+  SetMethod(context,
+            target,
+            "getApproximatedDeviceMemory",
+            GetApproximatedDeviceMemory);
   SetMethod(context, target, "getFreeMem", GetFreeMemory);
   SetMethod(context, target, "getCPUs", GetCPUInfo);
   SetMethod(context, target, "getInterfaceAddresses", GetInterfaceAddresses);
@@ -415,6 +453,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(GetHostname);
   registry->Register(GetLoadAvg);
   registry->Register(GetUptime);
+  registry->Register(GetApproximatedDeviceMemory);
   registry->Register(GetTotalMemory);
   registry->Register(GetFreeMemory);
   registry->Register(GetCPUInfo);

test/parallel/test-navigator.js

@@ -13,3 +13,5 @@ const is = {
 is.number(+navigator.hardwareConcurrency, 'hardwareConcurrency');
 is.number(navigator.hardwareConcurrency, 'hardwareConcurrency');
 assert.ok(navigator.hardwareConcurrency > 0);
+
+assert.strictEqual(typeof navigator.deviceMemory, 'number');

typings/internalBinding/os.d.ts

@@ -7,6 +7,7 @@ export interface OSBinding {
   getLoadAvg(array: Float64Array): void;
   getUptime(): number;
   getTotalMem(): number;
+  getApproximatedDeviceMemory(): number;
   getFreeMem(): number;
   getCPUs(): Array<string | number>;
   getInterfaceAddresses(ctx: InternalOSBinding.OSContext): Array<string | number | boolean> | undefined;