From 7972ebb52c61d711e7fbd3960084656bd03567ee Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Fri, 29 May 2026 12:13:26 +0200
Subject: [PATCH] async_hooks: remove legacy AsyncLocalStorage implementation

Remove the async_hooks-based AsyncLocalStorage fallback and the
--no-async-context-frame flag, making AsyncContextFrame the sole
implementation.
---
 doc/api/cli.md                                |  13 --
 doc/node-config-schema.json                   |   4 -
 doc/node.1                                    |   8 -
 lib/async_hooks.js                            |   4 +-
 lib/internal/async_context_frame.js           |  43 +----
 .../async_local_storage/async_hooks.js        | 153 ------------------
 src/async_context_frame.cc                    |   5 -
 src/node_options.cc                           |   5 -
 src/node_options.h                            |   1 -
 .../test-async-local-storage-gcable.js        |  11 +-
 test/parallel/parallel.status                 |   4 -
 .../test-als-defaultvalue-original.js         |  37 -----
 test/parallel/test-als-defaultvalue.js        |   1 -
 ...st-internal-async-context-frame-disable.js |   9 --
 ...st-internal-async-context-frame-enabled.js |   9 --
 ...est-stream-finished-async-local-storage.js |   2 +-
 .../test-stream-finished-default-path.js      |  22 ---
 .../test-without-async-context-frame.mjs      |  24 ---
 18 files changed, 10 insertions(+), 345 deletions(-)
 delete mode 100644 lib/internal/async_local_storage/async_hooks.js
 delete mode 100644 test/parallel/test-als-defaultvalue-original.js
 delete mode 100644 test/parallel/test-internal-async-context-frame-disable.js
 delete mode 100644 test/parallel/test-internal-async-context-frame-enabled.js
 delete mode 100644 test/parallel/test-stream-finished-default-path.js
 delete mode 100644 test/sequential/test-without-async-context-frame.mjs

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 85ca8c8d8376a2..d35393e73f04c2 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -2002,17 +2002,6 @@ Disable the `node-addons` exports condition as well as disable loading
 native addons. When `--no-addons` is specified, calling `process.dlopen` or
 requiring a native C++ addon will fail and throw an exception.
 
-### `--no-async-context-frame`
-
-<!-- YAML
-added: v24.0.0
--->
-
-Disables the use of [`AsyncLocalStorage`][] backed by `AsyncContextFrame` and
-uses the prior implementation which relied on async\_hooks. The previous model
-is retained for compatibility with Electron and for cases where the context
-flow may differ. However, if a difference in flow is found please report it.
-
 ### `--no-deprecation`
 
 <!-- YAML
@@ -3825,7 +3814,6 @@ one is included in the list below.
 * `--napi-modules`
 * `--network-family-autoselection-attempt-timeout`
 * `--no-addons`
-* `--no-async-context-frame`
 * `--no-deprecation`
 * `--no-experimental-global-navigator`
 * `--no-experimental-repl-await`
@@ -4420,7 +4408,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--require`]: #-r---require-module
 [`--use-env-proxy`]: #--use-env-proxy
 [`--use-system-ca`]: #--use-system-ca
-[`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md#class-buffer
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html
 [`ERR_INVALID_TYPESCRIPT_SYNTAX`]: errors.md#err_invalid_typescript_syntax
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
index a78031061dca87..5ae8c212db5eb1 100644
--- a/doc/node-config-schema.json
+++ b/doc/node-config-schema.json
@@ -111,10 +111,6 @@
               "type": "boolean",
               "description": "allow worker threads when any permissions are set"
             },
-            "async-context-frame": {
-              "type": "boolean",
-              "description": "Improve AsyncLocalStorage performance with AsyncContextFrame"
-            },
             "conditions": {
               "oneOf": [
                 {
diff --git a/doc/node.1 b/doc/node.1
index 5934919ae2aa8b..086d97abf7338a 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -1051,12 +1051,6 @@ Disable the \fBnode-addons\fR exports condition as well as disable loading
 native addons. When \fB--no-addons\fR is specified, calling \fBprocess.dlopen\fR or
 requiring a native C++ addon will fail and throw an exception.
 .
-.It Fl -no-async-context-frame
-Disables the use of \fBAsyncLocalStorage\fR backed by \fBAsyncContextFrame\fR and
-uses the prior implementation which relied on async_hooks. The previous model
-is retained for compatibility with Electron and for cases where the context
-flow may differ. However, if a difference in flow is found please report it.
-.
 .It Fl -no-deprecation
 Silence deprecation warnings.
 .
@@ -2008,8 +2002,6 @@ one is included in the list below.
 .It
 \fB--no-addons\fR
 .It
-\fB--no-async-context-frame\fR
-.It
 \fB--no-deprecation\fR
 .It
 \fB--no-experimental-global-navigator\fR
diff --git a/lib/async_hooks.js b/lib/async_hooks.js
index 5922971b9be68b..06752806b59cb4 100644
--- a/lib/async_hooks.js
+++ b/lib/async_hooks.js
@@ -282,9 +282,7 @@ class AsyncResource {
 module.exports = {
   // Public API
   get AsyncLocalStorage() {
-    return AsyncContextFrame.enabled ?
-      require('internal/async_local_storage/async_context_frame') :
-      require('internal/async_local_storage/async_hooks');
+    return require('internal/async_local_storage/async_context_frame');
   },
   createHook,
   executionAsyncId,
diff --git a/lib/internal/async_context_frame.js b/lib/internal/async_context_frame.js
index cac193e3318805..c12e74124a25d3 100644
--- a/lib/internal/async_context_frame.js
+++ b/lib/internal/async_context_frame.js
@@ -1,7 +1,6 @@
 'use strict';
 
 const {
-  ObjectSetPrototypeOf,
   SafeMap,
 } = primordials;
 
@@ -10,11 +9,10 @@ const {
   setContinuationPreservedEmbedderData,
 } = internalBinding('async_context_frame');
 
-let enabled_;
-
-class ActiveAsyncContextFrame extends SafeMap {
-  static get enabled() {
-    return true;
+class AsyncContextFrame extends SafeMap {
+  constructor(store, data) {
+    super(AsyncContextFrame.current());
+    this.set(store, data);
   }
 
   static current() {
@@ -35,39 +33,6 @@ class ActiveAsyncContextFrame extends SafeMap {
     const frame = this.current();
     frame?.disable(store);
   }
-}
-
-function checkEnabled() {
-  const enabled = require('internal/options')
-    .getOptionValue('--async-context-frame');
-
-  // If enabled, swap to active prototype so we don't need to check status
-  // on every interaction with the async context frame.
-  if (enabled) {
-    // eslint-disable-next-line no-use-before-define
-    ObjectSetPrototypeOf(AsyncContextFrame, ActiveAsyncContextFrame);
-  }
-
-  return enabled;
-}
-
-class InactiveAsyncContextFrame extends SafeMap {
-  static get enabled() {
-    enabled_ ??= checkEnabled();
-    return enabled_;
-  }
-
-  static current() {}
-  static set(frame) {}
-  static exchange(frame) {}
-  static disable(store) {}
-}
-
-class AsyncContextFrame extends InactiveAsyncContextFrame {
-  constructor(store, data) {
-    super(AsyncContextFrame.current());
-    this.set(store, data);
-  }
 
   disable(store) {
     this.delete(store);
diff --git a/lib/internal/async_local_storage/async_hooks.js b/lib/internal/async_local_storage/async_hooks.js
deleted file mode 100644
index 552092d89bf305..00000000000000
--- a/lib/internal/async_local_storage/async_hooks.js
+++ /dev/null
@@ -1,153 +0,0 @@
-'use strict';
-
-const {
-  ArrayPrototypeIndexOf,
-  ArrayPrototypePush,
-  ArrayPrototypeSplice,
-  ObjectIs,
-  ReflectApply,
-  Symbol,
-} = primordials;
-
-const {
-  validateObject,
-} = require('internal/validators');
-
-const {
-  AsyncResource,
-  createHook,
-  executionAsyncResource,
-} = require('async_hooks');
-
-const RunScope = require('internal/async_local_storage/run_scope');
-
-const storageList = [];
-const storageHook = createHook({
-  init(asyncId, type, triggerAsyncId, resource) {
-    const currentResource = executionAsyncResource();
-    // Value of currentResource is always a non null object
-    for (let i = 0; i < storageList.length; ++i) {
-      storageList[i]._propagate(resource, currentResource, type);
-    }
-  },
-});
-
-class AsyncLocalStorage {
-  #defaultValue = undefined;
-  #name = undefined;
-
-  /**
-   * @typedef {object} AsyncLocalStorageOptions
-   * @property {any} [defaultValue] - The default value to use when no value is set.
-   * @property {string} [name] - The name of the storage.
-   */
-  /**
-   * @param {AsyncLocalStorageOptions} [options]
-   */
-  constructor(options = {}) {
-    this.kResourceStore = Symbol('kResourceStore');
-    this.enabled = false;
-    validateObject(options, 'options');
-    this.#defaultValue = options.defaultValue;
-
-    if (options.name !== undefined) {
-      this.#name = `${options.name}`;
-    }
-
-    this._enable();
-  }
-
-  /** @type {string} */
-  get name() { return this.#name || ''; }
-
-  static bind(fn) {
-    return AsyncResource.bind(fn);
-  }
-
-  static snapshot() {
-    return AsyncLocalStorage.bind((cb, ...args) => cb(...args));
-  }
-
-  disable() {
-    if (this.enabled) {
-      this.enabled = false;
-      // If this.enabled, the instance must be in storageList
-      const index = ArrayPrototypeIndexOf(storageList, this);
-      ArrayPrototypeSplice(storageList, index, 1);
-      if (storageList.length === 0) {
-        storageHook.disable();
-      }
-    }
-  }
-
-  _enable() {
-    if (!this.enabled) {
-      this.enabled = true;
-      ArrayPrototypePush(storageList, this);
-      storageHook.enable();
-    }
-  }
-
-  // Propagate the context from a parent resource to a child one
-  _propagate(resource, triggerResource, type) {
-    const store = triggerResource[this.kResourceStore];
-    if (this.enabled) {
-      resource[this.kResourceStore] = store;
-    }
-  }
-
-  enterWith(store) {
-    this._enable();
-    const resource = executionAsyncResource();
-    resource[this.kResourceStore] = store;
-  }
-
-  run(store, callback, ...args) {
-    // Avoid creation of an AsyncResource if store is already active
-    if (ObjectIs(store, this.getStore())) {
-      return ReflectApply(callback, null, args);
-    }
-
-    this._enable();
-
-    const resource = executionAsyncResource();
-    const oldStore = resource[this.kResourceStore];
-
-    resource[this.kResourceStore] = store;
-
-    try {
-      return ReflectApply(callback, null, args);
-    } finally {
-      resource[this.kResourceStore] = oldStore;
-    }
-  }
-
-  exit(callback, ...args) {
-    if (!this.enabled) {
-      return ReflectApply(callback, null, args);
-    }
-    this.disable();
-    try {
-      return ReflectApply(callback, null, args);
-    } finally {
-      this._enable();
-    }
-  }
-
-  getStore() {
-    if (this.enabled) {
-      const resource = executionAsyncResource();
-      if (!(this.kResourceStore in resource)) {
-        return this.#defaultValue;
-      }
-      return resource[this.kResourceStore];
-    }
-    return this.#defaultValue;
-  }
-
-  withScope(store) {
-    return new RunScope(this, store);
-  }
-}
-
-module.exports = AsyncLocalStorage;
diff --git a/src/async_context_frame.cc b/src/async_context_frame.cc
index 8e5fb3dff9575f..33f029e30a1aa7 100644
--- a/src/async_context_frame.cc
+++ b/src/async_context_frame.cc
@@ -38,11 +38,6 @@ Local<Value> current(Isolate* isolate) {
 }
 
 void set(Isolate* isolate, Local<Value> value) {
-  auto env = Environment::GetCurrent(isolate);
-  if (!env->options()->async_context_frame) {
-    return;
-  }
-
   isolate->SetContinuationPreservedEmbedderDataV2(value);
 }
 
diff --git a/src/node_options.cc b/src/node_options.cc
index b7cb32f67cf614..4243dd7a8169b8 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -739,11 +739,6 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption(
       "--experimental-wasi-unstable-preview1", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--expose-gc", "expose gc extension", V8Option{}, kAllowedInEnvvar);
-  AddOption("--async-context-frame",
-            "Improve AsyncLocalStorage performance with AsyncContextFrame",
-            &EnvironmentOptions::async_context_frame,
-            kAllowedInEnvvar,
-            true);
   AddOption("--expose-internals", "", &EnvironmentOptions::expose_internals);
   AddOption("--frozen-intrinsics",
             "experimental frozen intrinsics support",
diff --git a/src/node_options.h b/src/node_options.h
index ab74dd31daab05..2bdd196debb09d 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -155,7 +155,6 @@ class EnvironmentOptions : public Options {
   bool allow_worker_threads = false;
   bool experimental_repl_await = true;
   bool experimental_vm_modules = EXPERIMENTALS_DEFAULT_VALUE;
-  bool async_context_frame = true;
   bool expose_internals = false;
   bool force_node_api_uncaught_exceptions_policy = false;
   bool frozen_intrinsics = false;
diff --git a/test/async-hooks/test-async-local-storage-gcable.js b/test/async-hooks/test-async-local-storage-gcable.js
index 57bb1b7ace13dc..303442e60c8851 100644
--- a/test/async-hooks/test-async-local-storage-gcable.js
+++ b/test/async-hooks/test-async-local-storage-gcable.js
@@ -1,12 +1,11 @@
 'use strict';
-// Flags: --expose_gc --expose-internals
+// Flags: --expose_gc
 
 // This test ensures that AsyncLocalStorage gets gced once it was disabled
 // and no strong references remain in userland.
 
 const common = require('../common');
 const { AsyncLocalStorage } = require('async_hooks');
-const AsyncContextFrame = require('internal/async_context_frame');
 const { onGC } = require('../common/gc');
 
 let asyncLocalStorage = new AsyncLocalStorage();
@@ -17,11 +16,9 @@ asyncLocalStorage.run({}, common.mustCall(() => {
   onGC(asyncLocalStorage, { ongc: common.mustCall() });
 }));
 
-if (AsyncContextFrame.enabled) {
-  // This disable() is needed to remove reference form AsyncContextFrame
-  // created during exit of run() to the AsyncLocalStore instance.
-  asyncLocalStorage.disable();
-}
+// This disable() is needed to remove reference from AsyncContextFrame
+// created during exit of run() to the AsyncLocalStore instance.
+asyncLocalStorage.disable();
 
 asyncLocalStorage = null;
 global.gc();
diff --git a/test/parallel/parallel.status b/test/parallel/parallel.status
index 73a866bbef8b75..570a4882081dc6 100644
--- a/test/parallel/parallel.status
+++ b/test/parallel/parallel.status
@@ -30,9 +30,6 @@ test-fs-cp-sync-symlink-points-to-dest-error: SKIP
 test-fs-cp-async-symlink-points-to-dest: SKIP
 test-fs-cp-sync-unicode-folder-names: SKIP
 
-# https://github.com/nodejs/node/issues/56751
-test-without-async-context-frame: PASS, FLAKY
-
 # Windows on ARM
 [$system==win32 && $arch==arm64]
 
@@ -144,7 +141,6 @@ test-http-pipeline-flood: SKIP
 test-inspector-network-fetch:  SKIP
 test-inspector-network-content-type: SKIP
 test-fetch:  SKIP
-test-without-async-context-frame: SKIP
 test-process-cpuUsage: PASS, FLAKY
 test-web-locks: SKIP
 test-http2-allow-http1-upgrade-ws: SKIP
diff --git a/test/parallel/test-als-defaultvalue-original.js b/test/parallel/test-als-defaultvalue-original.js
deleted file mode 100644
index 1bfe239abfcf69..00000000000000
--- a/test/parallel/test-als-defaultvalue-original.js
+++ /dev/null
@@ -1,37 +0,0 @@
-// Flags: --no-async-context-frame
-'use strict';
-
-require('../common');
-
-const {
-  AsyncLocalStorage,
-} = require('async_hooks');
-
-const assert = require('assert');
-
-// ============================================================================
-// The defaultValue option
-const als1 = new AsyncLocalStorage();
-assert.strictEqual(als1.getStore(), undefined);
-
-const als2 = new AsyncLocalStorage({ defaultValue: 'default' });
-assert.strictEqual(als2.getStore(), 'default');
-
-const als3 = new AsyncLocalStorage({ defaultValue: 42 });
-assert.strictEqual(als3.getStore(), 42);
-
-const als4 = new AsyncLocalStorage({ defaultValue: null });
-assert.strictEqual(als4.getStore(), null);
-
-assert.throws(() => new AsyncLocalStorage(null), {
-  code: 'ERR_INVALID_ARG_TYPE',
-});
-
-// ============================================================================
-// The name option
-
-const als5 = new AsyncLocalStorage({ name: 'test' });
-assert.strictEqual(als5.name, 'test');
-
-const als6 = new AsyncLocalStorage();
-assert.strictEqual(als6.name, '');
diff --git a/test/parallel/test-als-defaultvalue.js b/test/parallel/test-als-defaultvalue.js
index 5b5b43b57a72e6..f86cec3c962bc6 100644
--- a/test/parallel/test-als-defaultvalue.js
+++ b/test/parallel/test-als-defaultvalue.js
@@ -1,4 +1,3 @@
-// Flags: --async-context-frame
 'use strict';
 
 require('../common');
diff --git a/test/parallel/test-internal-async-context-frame-disable.js b/test/parallel/test-internal-async-context-frame-disable.js
deleted file mode 100644
index 61e351dc795906..00000000000000
--- a/test/parallel/test-internal-async-context-frame-disable.js
+++ /dev/null
@@ -1,9 +0,0 @@
-// Flags: --expose-internals --no-async-context-frame
-'use strict';
-
-require('../common');
-const assert = require('assert');
-const AsyncContextFrame = require('internal/async_context_frame');
-
-// Test that AsyncContextFrame can be disabled.
-assert(!AsyncContextFrame.enabled);
diff --git a/test/parallel/test-internal-async-context-frame-enabled.js b/test/parallel/test-internal-async-context-frame-enabled.js
deleted file mode 100644
index 1c99ff42519d8e..00000000000000
--- a/test/parallel/test-internal-async-context-frame-enabled.js
+++ /dev/null
@@ -1,9 +0,0 @@
-// Flags: --expose-internals
-'use strict';
-
-require('../common');
-const assert = require('assert');
-const AsyncContextFrame = require('internal/async_context_frame');
-
-// Test that AsyncContextFrame is enabled by default.
-assert(AsyncContextFrame.enabled);
diff --git a/test/parallel/test-stream-finished-async-local-storage.js b/test/parallel/test-stream-finished-async-local-storage.js
index b6d8f6722b05c3..aed249705e54d0 100644
--- a/test/parallel/test-stream-finished-async-local-storage.js
+++ b/test/parallel/test-stream-finished-async-local-storage.js
@@ -15,7 +15,7 @@ const readable = new Readable();
 
 als.run('test-context-1', common.mustCall(() => {
   finished(readable, common.mustCall(() => {
-    assert.strictEqual(AsyncContextFrame.enabled || enabledHooksExist(), true);
+    assert.strictEqual(!!AsyncContextFrame.current() || enabledHooksExist(), true);
     assert.strictEqual(als.getStore(), 'test-context-1');
   }));
 }));
diff --git a/test/parallel/test-stream-finished-default-path.js b/test/parallel/test-stream-finished-default-path.js
deleted file mode 100644
index 5d992ab657a4aa..00000000000000
--- a/test/parallel/test-stream-finished-default-path.js
+++ /dev/null
@@ -1,22 +0,0 @@
-// Flags: --expose-internals --no-async-context-frame
-'use strict';
-
-const common = require('../common');
-const { Readable, finished } = require('stream');
-const assert = require('assert');
-const AsyncContextFrame = require('internal/async_context_frame');
-const { enabledHooksExist } = require('internal/async_hooks');
-
-// This test verifies that when there are no active async hooks, stream.finished() uses the default callback path
-
-const readable = new Readable();
-
-finished(readable, common.mustCall(() => {
-  assert.strictEqual(enabledHooksExist(), false);
-  assert.strictEqual(
-    AsyncContextFrame.current() || enabledHooksExist(),
-    false,
-  );
-}));
-
-readable.destroy();
diff --git a/test/sequential/test-without-async-context-frame.mjs b/test/sequential/test-without-async-context-frame.mjs
deleted file mode 100644
index e7342f03a4ee88..00000000000000
--- a/test/sequential/test-without-async-context-frame.mjs
+++ /dev/null
@@ -1,24 +0,0 @@
-import { isWindows } from '../common/index.mjs';
-import { spawn } from 'node:child_process';
-import { once } from 'node:events';
-import { fileURLToPath } from 'node:url';
-import assert from 'node:assert';
-
-const python = process.env.PYTHON || (isWindows ? 'python' : 'python3');
-
-const testRunner = fileURLToPath(
-  new URL('../../tools/test.py', import.meta.url)
-);
-
-const proc = spawn(python, [
-  testRunner,
-  `--mode=${process.features.debug ? 'debug' : 'release'}`,
-  `--shell=${process.execPath}`,
-  '--node-args=--no-async-context-frame',
-  '*/test-async-local-storage-*',
-], {
-  stdio: ['inherit', 'inherit', 'inherit'],
-});
-
-const [code] = await once(proc, 'exit');
-assert.strictEqual(code, 0);