tls: only do off-thread certificate loading on loading tls

[joyeecheung]

tls: only do off-thread certificate loading on loading tls

This patch makes the off-thread loading lazy and only done when the
tls builtin is actually loaded by the application. Thus if the
application never uses tls, it would not get hit by the extra
off-thread loading overhead. paving the way to enable --use-system-ca
by default.

tls: load bundled and extra certificates off-thread

This patch makes the certificate pre-loading thread load the bundled
and extra certificates from the other thread as well.

With this patch, when running this snippet

const tls = require('tls');
// Simulate common application initialization that keeps the main thread busy while the
// certificate loading thread does its work before the first TLS connection is made.
setTimeout(() => {
  const start = performance.now();
  tls.createSecureContext();
  console.log(`TLS context created after ${performance.now() - start}ms`);
}, 300);

When creating the context for the first time without --use-system-ca (so only the bundled certificates are used):

$ ./node_main create-context.js
TLS context created after 11.054625000000044ms

$ out/Release/node create-context.js
TLS context created after 3.7832089999999994ms

When using --use-system-ca on macOS with 8 certificates installed:

$ ./node_main --use-system-ca create-context.js
TLS context created after 12.462124999999958ms

$ out/Release/node --use-system-ca create-context.js
TLS context created after 3.0597910000000184ms

And when starting an empty script without using tls, but with --use-system-ca enabled:

hyperfine "./node_main --use-system-ca empty.js" "out/Release/node --use-system-ca empty.js" --warmup 5
Benchmark 1: ./node_main --use-system-ca empty.js
  Time (mean ± σ):      38.2 ms ±   4.8 ms    [User: 22.5 ms, System: 6.2 ms]
  Range (min … max):    35.2 ms …  71.3 ms    75 runs

Benchmark 2: out/Release/node --use-system-ca empty.js
  Time (mean ± σ):      19.6 ms ±   3.2 ms    [User: 14.2 ms, System: 3.3 ms]
  Range (min … max):    17.6 ms …  46.2 ms    133 runs

Summary
  out/Release/node --use-system-ca empty.js ran
    1.94 ± 0.40 times faster than ./node_main --use-system-ca empty.js

[nodejs-github-bot]

Review requested:

• @nodejs/crypto
• @nodejs/net
• @nodejs/startup

[codecov]

Codecov Report

❌ Patch coverage is 39.77273% with 53 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.24%. Comparing base (f1b56d6) to head (53f70cb).
⚠️ Report is 46 commits behind head on main.

Files with missing lines	Patch %	Lines
src/crypto/crypto_context.cc	23.80%	29 Missing and 3 partials ⚠️
lib/tls.js	54.34%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #59856      +/-   ##
==========================================
- Coverage   88.27%   88.24%   -0.04%     
==========================================
  Files         702      702              
  Lines      206706   206743      +37     
  Branches    39757    39765       +8     
==========================================
- Hits       182469   182439      -30     
- Misses      16231    16322      +91     
+ Partials     8006     7982      -24     

Files with missing lines	Coverage Δ
src/crypto/crypto_util.h	74.79% <ø> (ø)
src/debug_utils.h	80.00% <ø> (ø)
src/node.cc	75.77% <ø> (+0.40%)	⬆️
lib/tls.js	92.02% <54.34%> (-4.22%)	⬇️
src/crypto/crypto_context.cc	68.68% <23.80%> (-2.13%)	⬇️

... and 42 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.

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

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

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/59856
✔  Done loading data for nodejs/node/pull/59856
----------------------------------- PR info ------------------------------------
Title      tls: only do off-thread certificate loading on loading tls (#59856)
Author     Joyee Cheung <[email protected]> (@joyeecheung)
Branch     joyeecheung:tls-ca-default -> nodejs:main
Labels     tls, crypto, c++, lib / src, needs-ci, review wanted, commit-queue-rebase
Commits    2
 - tls: only do off-thread certificate loading on loading tls
 - tls: load bundled and extra certificates off-thread
Committers 1
 - Joyee Cheung <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/59856
Reviewed-By: James M Snell <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/59856
Reviewed-By: James M Snell <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Thu, 11 Sep 2025 15:18:59 GMT
   ✔  Approvals: 1
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/59856#pullrequestreview-3220753871
   ✘  This PR needs to wait 20 more hours to land (or 0 hours if there is one more approval)
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2025-09-17T16:52:22Z: https://ci.nodejs.org/job/node-test-pull-request/69273/
- Querying data for job/node-test-pull-request/69273/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

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

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/59856
✔  Done loading data for nodejs/node/pull/59856
----------------------------------- PR info ------------------------------------
Title      tls: only do off-thread certificate loading on loading tls (#59856)
Author     Joyee Cheung <[email protected]> (@joyeecheung)
Branch     joyeecheung:tls-ca-default -> nodejs:main
Labels     tls, crypto, c++, lib / src, needs-ci, review wanted, commit-queue-rebase
Commits    2
 - tls: only do off-thread certificate loading on loading tls
 - tls: load bundled and extra certificates off-thread
Committers 1
 - Joyee Cheung <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/59856
Reviewed-By: James M Snell <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/59856
Reviewed-By: James M Snell <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Thu, 11 Sep 2025 15:18:59 GMT
   ✔  Approvals: 1
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/59856#pullrequestreview-3220753871
   ✘  This PR needs to wait 0 more hours to land (or 0 hours if there is one more approval)
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2025-09-17T19:00:22Z: https://ci.nodejs.org/job/node-test-pull-request/69273/
- Querying data for job/node-test-pull-request/69273/
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

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

[nodejs-github-bot]

Landed in d9959a5...57f61ad