Skip to content

Commit 0b151bf

Browse files
authored
perf(node): Optimize macOS native addon first load (#12436)
**Description:** The first macOS load currently recompresses the decoded native addon with `ditto` for APFS self-replacement, then decodes another image for the current process. Use the existing verified cache directly on macOS to remove that synchronous work. This retains compressed downloads, full-byte integrity verification, locking, atomic publication, and corruption recovery. The installed carrier and uncompressed cache coexist. Linux/Windows loading policy, public APIs, environment variables, payload format, cache keys, and the directly tested APFS helpers stay unchanged. Extend the native fixture to cover persistent and temporary caches, custom-cache fallback, corruption repair, hardlinked/read-only installations, and eight concurrent first loads. Measure macOS cold samples with ordinary single-link carriers while preserving warm-cache measurements. Add a reproducible before/after comparison and [measurement details](docs/native-addon-macos-startup.md). **Performance:** Using the same release core addon on an Apple M5 Max/APFS, with three rounds of 15 fresh-process samples for each of Node 20 and 22: - First `require()` medians improve by **9.8–18.6%**, exceeding the 5% criterion in every round. - The second installed execution falls from **253–270 ms to 17–19 ms**; warm-cache performance is preserved. - Allocated binary storage increases from **11.03 MiB to 31.32–32.00 MiB** for this core artifact. Copies occur outside the timer. These are installation-first-load measurements; the OS page cache was not cleared. **Validation:** - `cargo fmt --all` and `cargo clippy --all --all-targets -- -D warnings`. - All three native Rust crate suites, including Rust 1.73 verification; explicit APFS replacement test. - Native JavaScript tests and core `pnpm build:dev && pnpm test`. - [Verification-only release workflow](https://github.com/swc-project/swc/actions/runs/36549130544): all 48 builds, 69 runtime jobs, four native lifecycle jobs, and the final gate passed, including all 16 macOS ARM64/Rosetta and Node 20/22 combinations. Publishing and tag creation were disabled. The initial Windows x64 core/Node 20 job exceeded its existing cold budget (571.99 ms versus 500 ms), with functional tests passing. One diagnostic rerun using identical artifacts and unchanged budgets passed at 374.45 ms. Both observations are recorded in the measurement document. **Related issue (if exists):** None.
1 parent 68586f0 commit 0b151bf

11 files changed

Lines changed: 586 additions & 18 deletions

File tree

‎.changeset/macos-native-startup.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
swc_core: patch
3+
---
4+
5+
perf(node): Reduce macOS native addon startup time by using the verified cache directly and skipping APFS recompression while retaining compressed downloads.

‎bindings/binding_native_addon/src/lib.rs‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,10 @@ fn replacement_carrier(
3333
mode: &CacheMode,
3434
resolve: impl FnOnce() -> Result<std::path::PathBuf>,
3535
) -> Option<std::path::PathBuf> {
36-
if *mode == CacheMode::Temporary {
36+
// APFS self-replacement recompresses the decoded image with ditto and
37+
// decodes it again for this process. Keep macOS first loads on the verified
38+
// cache path, even for writable installations, before resolving the carrier.
39+
if cfg!(target_os = "macos") || *mode == CacheMode::Temporary {
3740
return None;
3841
}
3942
match resolve() {
@@ -164,10 +167,25 @@ mod tests {
164167
}
165168

166169
#[test]
170+
#[cfg(not(target_os = "macos"))]
167171
fn unavailable_carrier_disables_replacement() {
168172
assert!(replacement_carrier(&CacheMode::Default, || {
169173
Err(Error::new(ErrorKind::Load, "carrier is unavailable"))
170174
})
171175
.is_none());
172176
}
177+
178+
#[test]
179+
#[cfg(target_os = "macos")]
180+
fn macos_persistent_modes_skip_carrier_resolution() {
181+
for mode in [
182+
CacheMode::Default,
183+
CacheMode::Custom("/custom/cache".into()),
184+
] {
185+
assert!(replacement_carrier(&mode, || -> Result<_> {
186+
panic!("macOS must not resolve the carrier for self-replacement")
187+
})
188+
.is_none());
189+
}
190+
}
173191
}

‎bindings/binding_native_addon/tests/carrier.rs‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ use std::{
44
process::Command,
55
};
66

7+
#[cfg(target_os = "macos")]
8+
#[path = "support/macos.rs"]
9+
mod macos;
10+
711
fn fixture_source(name: &str) -> PathBuf {
812
Path::new(env!("CARGO_MANIFEST_DIR"))
913
.join("../../crates/swc_native_addon/tests/fixtures")
@@ -126,6 +130,16 @@ fn real_carrier_forwards_registration_and_throws_loader_errors() {
126130
fs::copy(build.join("debug").join(artifact), &carrier).unwrap();
127131
sign(&carrier);
128132
let original_carrier = fs::read(&carrier).unwrap();
133+
#[cfg(target_os = "macos")]
134+
macos::check_cache_policy(
135+
&std::env::var_os("SWC_TEST_NODE").unwrap_or_else(|| "node".into()),
136+
&carrier,
137+
&raw_bytes,
138+
&swc_native_addon::format::Payload::parse(&packed)
139+
.unwrap()
140+
.header
141+
.cache_key(),
142+
);
129143
let cli = directory.path().join("swc");
130144
fs::write(&cli, b"sibling CLI must be preserved").unwrap();
131145

@@ -213,7 +227,11 @@ fn real_carrier_forwards_registration_and_throws_loader_errors() {
213227
);
214228
// Each child traverses the real N-API entry point against the same cold
215229
// cache/carrier. This covers registration as well as atomic materialization.
216-
let cache = directory.path().join("concurrent cache");
230+
let cache = directory
231+
.path()
232+
.canonicalize()
233+
.unwrap()
234+
.join("concurrent cache");
217235
let mut children = Vec::new();
218236
for _ in 0..8 {
219237
children.push(
@@ -236,6 +254,17 @@ fn real_carrier_forwards_registration_and_throws_loader_errors() {
236254
String::from_utf8_lossy(&result.stderr)
237255
);
238256
}
257+
#[cfg(target_os = "macos")]
258+
{
259+
assert_eq!(fs::read(&carrier).unwrap(), original_carrier);
260+
let images = fs::read_dir(swc_native_addon::cache::cache_directory(&cache).unwrap())
261+
.unwrap()
262+
.map(|entry| entry.unwrap().path())
263+
.filter(|path| path.extension().is_some_and(|ext| ext == "node"))
264+
.collect::<Vec<_>>();
265+
assert_eq!(images.len(), 1);
266+
assert_eq!(fs::read(&images[0]).unwrap(), raw_bytes);
267+
}
239268
assert_eq!(fs::read(&raw).unwrap(), raw_bytes);
240269
assert_eq!(fs::read(cli).unwrap(), b"sibling CLI must be preserved");
241270
}
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
//! Exercise the default macOS policy through the real signed carrier fixture.
2+
3+
use std::{
4+
ffi::OsStr,
5+
fs,
6+
os::unix::fs::{MetadataExt, PermissionsExt},
7+
path::Path,
8+
process::Command,
9+
};
10+
11+
use super::fixture_source;
12+
13+
#[derive(Clone, Copy, Debug)]
14+
enum Installation {
15+
Default,
16+
Empty,
17+
Custom,
18+
Fallback,
19+
Temporary,
20+
Hardlinked,
21+
ReadOnly,
22+
}
23+
24+
pub fn check_cache_policy(node: &OsStr, source: &Path, raw: &[u8], key: &str) {
25+
for installation in [
26+
Installation::Default,
27+
Installation::Empty,
28+
Installation::Custom,
29+
Installation::Fallback,
30+
Installation::Temporary,
31+
Installation::Hardlinked,
32+
Installation::ReadOnly,
33+
] {
34+
let temporary = tempfile::tempdir().unwrap();
35+
// Darwin's /var alias is intentionally not accepted by cache validation.
36+
let root = temporary.path().canonicalize().unwrap();
37+
let installed = root.join("installed");
38+
fs::create_dir(&installed).unwrap();
39+
let carrier = installed.join("carrier.node");
40+
fs::copy(source, &carrier).unwrap();
41+
let original = fs::read(&carrier).unwrap();
42+
let default = root.join("default");
43+
let custom = root.join("custom");
44+
let blocked = root.join("blocked");
45+
fs::write(&blocked, b"unusable cache root").unwrap();
46+
if matches!(installation, Installation::Hardlinked) {
47+
fs::hard_link(&carrier, installed.join("carrier-link.node")).unwrap();
48+
}
49+
if matches!(installation, Installation::ReadOnly) {
50+
fs::set_permissions(&carrier, fs::Permissions::from_mode(0o444)).unwrap();
51+
fs::set_permissions(&installed, fs::Permissions::from_mode(0o555)).unwrap();
52+
}
53+
let before = fs::metadata(&carrier).unwrap();
54+
let mut command = Command::new(node);
55+
command
56+
.arg(fixture_source("smoke.cjs"))
57+
.arg(&carrier)
58+
.arg("success")
59+
.env("XDG_CACHE_HOME", &default)
60+
.env_remove("SWC_NATIVE_BINDING_CACHE");
61+
let cache_root = match installation {
62+
Installation::Default => &default,
63+
Installation::Empty => {
64+
command.env("SWC_NATIVE_BINDING_CACHE", "");
65+
&default
66+
}
67+
Installation::Fallback => {
68+
command.env("SWC_NATIVE_BINDING_CACHE", &blocked);
69+
&default
70+
}
71+
Installation::Temporary => {
72+
command.env("SWC_NATIVE_BINDING_CACHE", "0");
73+
&default
74+
}
75+
_ => {
76+
command.env("SWC_NATIVE_BINDING_CACHE", &custom);
77+
&custom
78+
}
79+
};
80+
let mut image_identity = None;
81+
for load in 0..3 {
82+
// Each invocation is a fresh Node process: cold, warm, then repair.
83+
let output = command.output().unwrap();
84+
if !output.status.success() {
85+
fs::set_permissions(&installed, fs::Permissions::from_mode(0o755)).unwrap();
86+
panic!(
87+
"{installation:?}: {}",
88+
String::from_utf8_lossy(&output.stderr)
89+
);
90+
}
91+
let after = fs::metadata(&carrier).unwrap();
92+
assert_eq!(after.ino(), before.ino(), "{installation:?}");
93+
assert_eq!(after.mode(), before.mode(), "{installation:?}");
94+
assert_eq!(after.nlink(), before.nlink(), "{installation:?}");
95+
assert_eq!(fs::read(&carrier).unwrap(), original, "{installation:?}");
96+
let directory = swc_native_addon::cache::cache_directory(cache_root).unwrap();
97+
let image = directory.join(format!("{key}.node"));
98+
if matches!(installation, Installation::Temporary) {
99+
assert!(!image.exists());
100+
assert!(fs::read_dir(&directory).unwrap().all(|entry| {
101+
entry
102+
.unwrap()
103+
.path()
104+
.extension()
105+
.map_or(true, |ext| ext != "node")
106+
}));
107+
} else {
108+
assert_eq!(fs::read(&image).unwrap(), raw, "{installation:?}");
109+
let metadata = fs::metadata(&image).unwrap();
110+
if load == 0 {
111+
image_identity = Some((metadata.ino(), metadata.modified().unwrap()));
112+
} else if load == 1 {
113+
assert_eq!(
114+
Some((metadata.ino(), metadata.modified().unwrap())),
115+
image_identity,
116+
"verified cache hit must reuse the existing image"
117+
);
118+
// Same-length damage must be detected by the full-byte digest.
119+
let mut damaged = raw.to_vec();
120+
let last = damaged.last_mut().unwrap();
121+
*last ^= 1;
122+
fs::write(&image, damaged).unwrap();
123+
}
124+
}
125+
}
126+
assert_eq!(fs::read(&blocked).unwrap(), b"unusable cache root");
127+
fs::set_permissions(&installed, fs::Permissions::from_mode(0o755)).unwrap();
128+
}
129+
}

‎crates/swc_native_addon/README.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -159,9 +159,19 @@ the cleanup worker too, the temporary file can remain for manual cache cleanup.
159159

160160
## Transparent filesystem compression
161161

162-
On writable APFS/btrfs, persistent modes first try self-replacement. Only a
163-
completed compressed staging file beside the carrier is atomically renamed into
164-
place. The original mapped inode is never modified. The current process loads a
162+
On writable btrfs, persistent modes first try self-replacement. The macOS
163+
loader instead uses the verified cache directly, before even resolving the
164+
carrier path: synchronous APFS recompression and decoding a second image make
165+
the first load after installation unnecessarily expensive. macOS retains the
166+
zstd carrier and a separate uncompressed cache image, trading disk space for
167+
startup latency.
168+
Cache verification, repair, and temporary mode are unchanged. The low-level APFS
169+
replacement helper remains available for explicit filesystem tests; it is not
170+
part of normal macOS loading.
171+
172+
When self-replacement is attempted, only a completed compressed staging file
173+
beside the carrier is atomically renamed into place. The original mapped inode
174+
is never modified. The current process loads a
165175
separate verified temporary image, avoiding recursive lookup of the already
166176
mapped carrier. Competing first loads lock the original inode and recheck its
167177
identity before replacement. Hardlinked or differently owned images use the

‎docs/native-addon-carriers.md‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ warning and best-effort deletion when the materialized image is dropped. A DLL
5757
that remains mapped until process exit may remain on disk in that environment.
5858
The helper's integrity is still verified before any attempt to execute it.
5959

60-
On writable APFS or btrfs, the loader may atomically replace its installed
60+
On writable btrfs, the loader may atomically replace its installed
6161
carrier with the original addon under transparent filesystem compression.
6262
The current process loads a separate verified temporary image. Read-only,
6363
hardlinked, unsupported, or unsuitable installations use the cache. Windows
@@ -67,6 +67,15 @@ NTFS compression cleared before decoding; existing compressed entries remain
6767
fully verified and usable. The sibling CLI is never part of materialization or
6868
replacement.
6969

70+
macOS always uses the verified cache, without resolving the carrier for
71+
self-replacement or launching `ditto`. This avoids synchronous APFS recompression
72+
and a second payload decode on the first load after installation. The installed
73+
zstd carrier and the uncompressed raw cache coexist, increasing disk use in exchange
74+
for faster first loads. Full-byte verification, repair, and temporary mode retain
75+
the same behavior. The low-level APFS helper remains covered by explicit tests.
76+
See the [macOS startup measurements](native-addon-macos-startup.md) for the
77+
first-load, subsequent-load, and disk-space comparison.
78+
7079
## Release verification
7180

7281
The existing raw napi-rs build finishes first, including its final strip steps.
@@ -100,8 +109,11 @@ even beneath compressed home directories. Cold overhead is `coldMs - rawColdMs`;
100109
warm overhead is `warmMs - rawMs`. The gate rejects missing baselines or
101110
inconsistent arithmetic. Measurement caches use canonical paths beneath the
102111
executing user's home, including Docker, and are removed after the run. These are not claims
103-
about an empty operating-system page cache. Disposable hardlinked carrier
104-
copies prevent filesystem self-replacement from disguising warm-cache costs.
112+
about an empty operating-system page cache. Warm samples use disposable
113+
hardlinked carrier copies to prevent filesystem self-replacement from disguising
114+
warm-cache costs. macOS cold samples instead use ordinary single-link files to
115+
measure the first load after installation; other platforms retain their existing
116+
hardlinked cold samples.
105117
Representative x64 jobs require at most 500 ms cold overhead and 125 ms warm
106118
overhead over the corresponding raw addon. The macOS x64 jobs run under Rosetta
107119
on ARM64 runners and have a separately approved 1,500 ms cold limit; their warm

0 commit comments

Comments
 (0)