src: add web locks api #58666

IlyasShabi · 2025-06-10T19:40:42Z

This PR implements the Web Locks API, Locks are used to coordinate access to shared resources across multiple threads.

This implementation is based on previous work in #22719 and #36502, but takes a C++ native approach for better performance and reliability, this solution uses a singleton LockManager with thread-safe data structures to coordinate locks across all workers.

Closes: #22702
Refs: https://w3c.github.io/web-locks

nodejs-github-bot · 2025-06-10T19:40:47Z

Review requested:

@nodejs/gyp
@nodejs/startup
@nodejs/web-standards

codecov · 2025-06-10T20:48:24Z

Codecov Report

Attention: Patch coverage is 85.87786% with 111 lines in your changes missing coverage. Please review.

Project coverage is 90.08%. Comparing base (462c741) to head (9f2f57a).
Report is 30 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_locks.cc	78.58%	52 Missing and 45 partials ⚠️
lib/internal/locks.js	95.22%	14 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #58666      +/-   ##
==========================================
- Coverage   90.15%   90.08%   -0.08%     
==========================================
  Files         639      643       +4     
  Lines      188201   189048     +847     
  Branches    36915    37062     +147     
==========================================
+ Hits       169675   170302     +627     
- Misses      11274    11419     +145     
- Partials     7252     7327      +75

Files with missing lines	Coverage Δ
lib/internal/navigator.js	`99.37% <100.00%> (+0.04%)`	⬆️
lib/worker_threads.js	`100.00% <100.00%> (ø)`
src/node_binding.cc	`82.67% <ø> (ø)`
src/node_external_reference.h	`100.00% <ø> (ø)`
src/node_locks.h	`100.00% <100.00%> (ø)`
lib/internal/locks.js	`95.22% <95.22%> (ø)`
src/node_locks.cc	`78.58% <78.58%> (ø)`

... and 65 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

lib/internal/locks.js

src/node_locks.cc

lib/internal/locks.js

mcollina

lgtm

Ethan-Arrowood

this lgtm. I looked through the WPT and other tests and they look all good. I reviewed the JS api to make sure it aligns with expectations and analyzed its source. All is good for a first implementation. I did a cursory review of the C++ part as I'm less experienced there, but in general it looks okay too. Nice work!

panva · 2025-06-16T16:11:43Z

Adding semver-major PRs that contain breaking changes and should be released in the next major version. as this adds new globals (Lock, LockManager)

doc/api/globals.md

github-actions · 2025-06-23T13:27:06Z

Failed to start CI

   ⚠  Commits were pushed since the last approving review:
   ⚠  - worker: add web locks api
   ⚠  - use WebIDL convertors
   ⚠  - add lock and lockmanager to globals doc
   ⚠  - remove lock and lockmanager from globals
   ⚠  - attemp to atach catch on c++ by defering to next microtask
   ⚠  - separate promise fulfillment and rejection handlers
   ⚠  - add cjs/esm code in locks doc
   ⚠  - add more tests and doc
   ✘  Refusing to run CI on potentially unsafe PR

https://github.com/nodejs/node/actions/runs/15825543437

nodejs-github-bot · 2025-06-23T13:54:55Z

CI: https://ci.nodejs.org/job/node-test-pull-request/67621/

jasnell · 2025-06-24T04:13:16Z

There are relevant test failures in CI (web locks web platform tests)

jasnell · 2025-06-24T04:17:12Z

src/node_locks.cc

+                       External::New(isolate, reject_holder))
+             .ToLocal(&on_rejected_callback)) {
+      delete fulfill_holder;
+      delete reject_holder;


These might need to be handled separately. If the first call succeeds, then the first created function will take ownership over the fulfill_holder. If the second call then fails for whatever reason, we are deleting the fulfill_holder while it's external is still holding the reference to it that it assumes it owns. It would be best to separate this into two separate calls rather than aggregating them together like this. Create one, create it's external and it's function, then create the second...

Or, can we at least be certain that we won't end up with a free-after-free type error when deleting these while the External is still holding them?

jasnell · 2025-06-24T04:19:18Z

src/node_locks.cc

+        Local<Value> rejection_value = promise->Result();
+        grantable_request->waiting_promise()
+            ->Reject(context, rejection_value)
+            .Check();


Not something to do here, but using Check() here has the same issue as using ToLocalChecked() in that it will just crash the process rather than propagate the error. This is a common issue throughout the code, however, so not something I would block this PR on. We need to handle these better in general.

If you did want to handle this here, then changing these to check if the return value is empty then doing some proper error propagation similar to the way the ToLocal(...) results are handled would be ideal.

jasnell · 2025-06-24T04:20:43Z

src/node_locks.cc

+        grantable_request->waiting_promise()
+            ->Resolve(context, callback_result)
+            .Check();
+        USE(promise->Then(


We should avoid using USE for the same error propagation reasons. Calling Then(...) can cause a JavaScript error to be scheduled. USE would cause that to be ignored when we ought to propagate it.

jasnell · 2025-06-24T04:21:15Z

src/node_locks.cc

+          ->Resolve(context, callback_result)
+          .Check();
+      Local<Value> promise_args[] = {callback_result};
+      USE(on_fulfilled_callback->Call(


Likewise here. Calling the callback could throw. The error should be appropriately propagated.

jasnell · 2025-06-24T04:24:44Z

src/node_locks.cc

+  CHECK(args[0]->IsString());
+  CHECK(args[1]->IsString());
+  CHECK(args[2]->IsString());
+  CHECK(args[3]->IsBoolean());
+  CHECK(args[4]->IsBoolean());
+  CHECK(args[5]->IsFunction());


Suggested change

CHECK(args[0]->IsString());

CHECK(args[1]->IsString());

CHECK(args[2]->IsString());

CHECK(args[3]->IsBoolean());

CHECK(args[4]->IsBoolean());

CHECK(args[5]->IsFunction());

CHECK(args[0]->IsString()); // name

CHECK(args[1]->IsString()); // clientId

CHECK(args[2]->IsString()); // mode

CHECK(args[3]->IsBoolean()); // steal

CHECK(args[4]->IsBoolean()); // ifAvailable

CHECK(args[5]->IsFunction()); // callback

Just to help connect these back to the documentation comment at the top

jasnell · 2025-06-24T04:25:33Z

src/node_locks.cc

+  Local<Promise::Resolver> waiting_promise;
+  if (!Promise::Resolver::New(context).ToLocal(&waiting_promise)) {
+    return;
+  }
+  Local<Promise::Resolver> released_promise;
+  if (!Promise::Resolver::New(context).ToLocal(&released_promise)) {
+    return;
+  }


Suggested change

Local<Promise::Resolver> waiting_promise;

if (!Promise::Resolver::New(context).ToLocal(&waiting_promise)) {

return;

}

Local<Promise::Resolver> released_promise;

if (!Promise::Resolver::New(context).ToLocal(&released_promise)) {

return;

}

Local<Promise::Resolver> waiting_promise;

Local<Promise::Resolver> released_promise;

if (!Promise::Resolver::New(context).ToLocal(&waiting_promise) ||

!Promise::Resolver::New(context).ToLocal(&released_promise)) {

return;

}

jasnell · 2025-06-24T04:26:49Z

src/node_locks.cc

+    return;
+  }
+
+  args.GetReturnValue().Set(released_promise->GetPromise());


It's a bit unusual (by convention) to set the return value and then perform additional actions. It makes it rather easy to miss that the return value is set at all. Could this be moved to the end of the function?

jasnell · 2025-06-24T04:27:28Z

src/node_locks.cc

+  if (!Promise::Resolver::New(context).ToLocal(&resolver)) {
+    return;
+  }
+  args.GetReturnValue().Set(resolver->GetPromise());


Likewise here... setting the return value in the middle here is a bit unusual.

jasnell · 2025-06-24T04:28:27Z

src/node_locks.cc

+    for (const auto& resource_entry : manager->held_locks_) {
+      for (const auto& held_lock : resource_entry.second) {
+        if (held_lock->env() == env) {
+          Local<Object> lock_info =


You might consider moving the declaration for the Local<Object> lock_info to outside of the for loop and just reset it here so that we're reusing the same declaration on each iteration rather than creating a new one.

jasnell · 2025-06-24T04:29:18Z

src/node_locks.cc

+    index = 0;
+    for (const auto& pending_request : manager->pending_queue_) {
+      if (pending_request->env() == env) {
+        Local<Object> lock_info =


Same here... if the Local<Object> lock_info; is moved outside of the for loops then it can just be reused here.

jasnell · 2025-06-24T04:29:37Z

src/node_locks.cc

+  result->Set(context, FIXED_ONE_BYTE_STRING(isolate, "held"), held_list)
+      .Check();
+  result->Set(context, FIXED_ONE_BYTE_STRING(isolate, "pending"), pending_list)
+      .Check();


Let's avoid using Check() here and propagate the errors appropriately.

jasnell · 2025-06-24T04:31:02Z

src/node_locks.cc

+  Local<Object> obj = Object::New(isolate);
+
+  Local<String> name_string;
+  if (!String::NewFromTwoByte(isolate,


TODO for later (no need to do it in this PR)... we should add a ToV8Value variant that accepts the std::u16string

jasnell · 2025-06-24T04:31:29Z

src/node_locks.cc

+    return Local<Object>();
+  }
+  obj->Set(context, FIXED_ONE_BYTE_STRING(isolate, "name"), name_string)
+      .Check();


Avoid Check here... and elsewhere in this function. Specifically, if you can modify this function to return a MaybeLocal<Object> instead, then if these return IsNothing() == true, you should just return an empty MaybeLocal<Object> to propagate the error.

jasnell · 2025-06-24T04:31:51Z

src/node_locks.cc

+  LockManager::GetCurrent()->CleanupEnvironment(env);
+}
+
+static Local<Object> CreateLockInfoObject(Isolate* isolate,


Consider having this return a MaybeLocal<Object> to better facilitate error propagation

jasnell · 2025-06-24T04:34:33Z

src/node_locks.cc

+  if (String::NewFromUtf8(isolate, kSharedMode).ToLocal(&shared_mode)) {
+    target->Set(FIXED_ONE_BYTE_STRING(isolate, "LOCK_MODE_SHARED"),
+                shared_mode);
+  }


Would NODE_DEFINE_STRING_CONSTANT work for these here instead?

jasnell · 2025-06-24T04:37:19Z

I think this is very close! Added a few comments and notice that there are WPT test failures.

nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jun 10, 2025

IlyasShabi changed the title ~~Add web locks api~~ src: add web locks api Jun 10, 2025

IlyasShabi force-pushed the web-locks-api branch from 370462f to ba53a01 Compare June 10, 2025 19:42

IlyasShabi marked this pull request as ready for review June 10, 2025 19:47

IlyasShabi force-pushed the web-locks-api branch from ba53a01 to 5d52680 Compare June 10, 2025 19:57

jasnell requested a review from addaleax June 10, 2025 21:00

jasnell added the semver-minor PRs that contain new features and should be released in the next minor version. label Jun 10, 2025

IlyasShabi force-pushed the web-locks-api branch from 5d52680 to 6fdd577 Compare June 10, 2025 21:08

jasnell reviewed Jun 10, 2025

View reviewed changes

panva reviewed Jun 11, 2025

View reviewed changes

lib/internal/locks.js Outdated Show resolved Hide resolved

atlowChemi reviewed Jun 11, 2025

View reviewed changes

lib/internal/locks.js Outdated Show resolved Hide resolved

IlyasShabi requested review from panva, jasnell and KhafraDev June 11, 2025 19:34

mcollina approved these changes Jun 14, 2025

View reviewed changes

Ethan-Arrowood approved these changes Jun 16, 2025

View reviewed changes

panva added semver-major PRs that contain breaking changes and should be released in the next major version. and removed semver-minor PRs that contain new features and should be released in the next minor version. labels Jun 16, 2025

panva added the request-ci Add this label to start a Jenkins CI on a PR. label Jun 16, 2025

panva reviewed Jun 16, 2025

View reviewed changes

doc/api/globals.md Outdated Show resolved Hide resolved

panva added web-standards Issues and PRs related to Web APIs and removed request-ci Add this label to start a Jenkins CI on a PR. labels Jun 16, 2025

IlyasShabi requested a review from panva June 17, 2025 09:53

panva approved these changes Jun 17, 2025

View reviewed changes

panva added the request-ci Add this label to start a Jenkins CI on a PR. label Jun 17, 2025

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jun 17, 2025

add more tests and doc

1a9d467

BridgeAR added the request-ci Add this label to start a Jenkins CI on a PR. label Jun 23, 2025

github-actions bot added request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. and removed request-ci Add this label to start a Jenkins CI on a PR. labels Jun 23, 2025

IlyasShabi requested a review from jasnell June 23, 2025 13:29

marco-ippolito approved these changes Jun 23, 2025

View reviewed changes

marco-ippolito added request-ci Add this label to start a Jenkins CI on a PR. and removed request-ci-failed An error occurred while starting CI via request-ci label, and manual interventon is needed. labels Jun 23, 2025

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Jun 23, 2025

update bootstrap modules

9f2f57a

benjamingr approved these changes Jun 24, 2025

View reviewed changes

jasnell reviewed Jun 24, 2025

View reviewed changes

Uh oh!

src: add web locks api #58666

Are you sure you want to change the base?

src: add web locks api #58666

Conversation

IlyasShabi commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Jun 10, 2025

Uh oh!

codecov bot commented Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

Ethan-Arrowood left a comment

Choose a reason for hiding this comment

Uh oh!

panva commented Jun 16, 2025

Uh oh!

Uh oh!

github-actions bot commented Jun 23, 2025

Uh oh!

nodejs-github-bot commented Jun 23, 2025

Uh oh!

jasnell commented Jun 24, 2025

Uh oh!

jasnell Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Jun 24, 2025

Uh oh!

Uh oh!

IlyasShabi commented Jun 10, 2025 •

edited

Loading

codecov bot commented Jun 10, 2025 •

edited

Loading

jasnell Jun 24, 2025 •

edited

Loading

jasnell Jun 24, 2025 •

edited

Loading

jasnell Jun 24, 2025 •

edited

Loading