Files
delino[bot]GitHubclaude[bot] <41898282+claude[bot]@users.noreply.github.com>ClaudeDonny/강동윤
3528ba9b2a fix(bindings): Improve ARM64 and Alpine Linux (musl) binary loading and validation (#11173)
## Summary

This PR addresses segmentation fault crashes reported for @swc/core on
ARM64 and Alpine Linux (musl) platforms:
- Fixes #11120 - @swc/core v1.13.19 segfaults on ARM64 during
postinstall
- Fixes #11126 - @swc/core v1.13.20 crashes on Alpine Linux (musl) with
SIGSEGV

## Problem

Users are experiencing segmentation faults when installing or using
@swc/core on:
- ARM64 architecture (both GNU and musl libc)
- Alpine Linux and other musl-based distributions

The issues appear during the postinstall validation phase when the
native binary is loaded.

## Root Cause Analysis

After investigation, the current swc_malloc configuration is actually
correct:
- Musl targets intentionally use the system allocator (not mimalloc or
jemalloc)
- This is because both mimalloc and jemalloc have known
segfault/threading issues on musl
- The crashes are likely related to binary loading/compatibility, not
memory allocation

## Changes

### 1. Enhanced Error Handling in postinstall.js
- Added `SWC_SKIP_VALIDATION` environment variable to allow users to
bypass validation
- Collect and display detailed system information (platform, arch, Node
version, libc) on errors
- Provide actionable troubleshooting guidance specific to ARM64/Alpine
users
- Better error messages to help diagnose issues

### 2. Documentation for swc_malloc
- Added comprehensive documentation explaining allocator selection
strategy
- Clarified that musl using system allocator is intentional and correct
- Documented why mimalloc and jemalloc don't work well with musl
- Added references to upstream issues for transparency

### 3. Binary Validation Script
Created `scripts/validate-binary.js` for CI/CD:
- Validates native binary can load successfully
- Tests core functionality (getTargetTriple, parseSync, transformSync)
- Provides detailed diagnostics on failure
- Catches binary loading issues before running full test suite

### 4. Enabled ARM64 Musl Testing in CI
- Uncommented and updated `test-linux-aarch64-musl-binding` job
- Added binary validation step using QEMU for ARM64 emulation
- Made this test a required dependency for the publish step
- Prevents publishing broken binaries for ARM64 musl

## Testing Strategy

The PR enables comprehensive testing for ARM64 musl in CI:
- Binary validation runs first to catch loading issues immediately
- Full test suite runs after validation passes
- Uses QEMU for ARM64 emulation on x86_64 runners
- Tests against node:lts-alpine Docker image

## User Impact

### Immediate Workaround
Users experiencing segfaults can now skip validation:
```bash
SWC_SKIP_VALIDATION=1 npm install @swc/core
```

### Better Diagnostics
On failure, users will see:
- Platform and architecture information
- Node.js version
- libc type and version
- Specific error details
- Links to related issues

### Future Prevention
CI will now catch ARM64/Alpine issues before release, preventing broken
versions from being published.

## Test Plan

- [x] cargo fmt --all (required by project guidelines)
- [ ] CI tests pass for all platforms
- [ ] ARM64 musl binary validation passes
- [ ] Verify postinstall error messages display correctly
- [ ] Test SWC_SKIP_VALIDATION environment variable

## Notes

This is marked as a draft because:
1. Need to verify CI passes with the new ARM64 musl tests enabled
2. Want to get feedback on the approach before merging
3. May need to adjust timeout values for QEMU-emulated tests

The changes are conservative and focused on:
- Better error reporting and diagnostics
- User workarounds for existing issues
- Preventing future releases with binary loading problems

This does NOT change the allocator configuration, as that is already
correct.

## References

- https://github.com/microsoft/mimalloc/issues/556 - mimalloc issues on
ARM64 musl
- https://github.com/jemalloc/jemalloc/issues/1443 - jemalloc threading
issues with musl
- https://www.tweag.io/blog/2023-08-10-rust-static-link-with-mimalloc/ -
Best practices for musl

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Donny/강동윤 <[email protected]>
2025-10-24 07:07:03 +09:00

165 lines
7.6 KiB
JavaScript

"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
__setModuleDefault(result, mod);
return result;
};
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
Object.defineProperty(exports, "__esModule", { value: true });
/**
* A postinstall script runs after `@swc/core` is installed.
*
* It checks if corresponding optional dependencies for native binary is installed and can be loaded properly.
* If it fails, it'll internally try to install `@swc/wasm` as fallback.
*/
const fs_1 = require("fs");
const assert = __importStar(require("assert"));
const path = __importStar(require("path"));
const child_process = __importStar(require("child_process"));
const fs = __importStar(require("fs"));
function removeRecursive(dir) {
for (const entry of fs.readdirSync(dir)) {
const entryPath = path.join(dir, entry);
let stats;
try {
stats = fs.lstatSync(entryPath);
}
catch (_a) {
continue; // Guard against https://github.com/nodejs/node/issues/4760
}
if (stats.isDirectory())
removeRecursive(entryPath);
else
fs.unlinkSync(entryPath);
}
fs.rmdirSync(dir);
}
/**
* Trying to validate @swc/core's native binary installation, then installs if it is not supported.
*/
const validateBinary = () => __awaiter(void 0, void 0, void 0, function* () {
var _a;
try {
const { name } = require(path.resolve(process.env.INIT_CWD, "package.json"));
if (name === "@swc/core" || name === "@swc/workspace") {
return;
}
}
catch (_) {
return;
}
// Allow users to skip validation if they encounter issues
if (process.env.SWC_SKIP_VALIDATION === "1" || process.env.SWC_SKIP_VALIDATION === "true") {
console.log("Skipping @swc/core native binary validation (SWC_SKIP_VALIDATION is set)");
return;
}
// TODO: We do not take care of the case if user try to install with `--no-optional`.
// For now, it is considered as deliberate decision.
let binding;
try {
binding = require("./binding.js");
// Check if binding binary actually works.
// For the latest version, checks target triple. If it's old version doesn't have target triple, use parseSync instead.
const triple = binding.getTargetTriple
? binding.getTargetTriple()
: binding.parseSync("console.log()", Buffer.from(JSON.stringify({ syntax: "ecmascript" })));
assert.ok(triple, "Failed to read target triple from native binary.");
}
catch (error) {
// Collect system information for better diagnostics
const systemInfo = {
platform: process.platform,
arch: process.arch,
nodeVersion: process.version,
libc: process.report ? process.report.getReport().header.glibcVersionRuntime : "unknown"
};
// if error is unsupported architecture, ignore to display.
if (!((_a = error.message) === null || _a === void 0 ? void 0 : _a.includes("Unsupported architecture"))) {
console.warn("Failed to load @swc/core native binding.");
console.warn("System information:", JSON.stringify(systemInfo, null, 2));
console.warn("Error details:", error.message || error);
console.warn("\nIf you are experiencing segmentation faults on ARM64 or Alpine Linux,");
console.warn("you can skip validation by setting: SWC_SKIP_VALIDATION=1");
}
console.warn(`@swc/core was not able to resolve native bindings installation. It'll try to use @swc/wasm as fallback instead.`);
}
if (!!binding) {
return;
}
// User choose to override the binary installation. Skip remanining validation.
if (!!process.env["SWC_BINARY_PATH"]) {
console.warn(`@swc/core could not resolve native bindings installation, but found manual override config SWC_BINARY_PATH specified. Skipping remaning validation.`);
return;
}
// Check if top-level package.json installs @swc/wasm separately already
let wasmBinding;
try {
wasmBinding = require.resolve(`@swc/wasm`);
}
catch (_) { }
if (!!wasmBinding && (0, fs_1.existsSync)(wasmBinding)) {
return;
}
const env = Object.assign(Object.assign({}, process.env), { npm_config_global: undefined });
const { version } = require(path.join(path.dirname(require.resolve("@swc/core")), "package.json"));
// We want to place @swc/wasm next to the @swc/core as if normal installation was done,
// but can't directly set cwd to INIT_CWD as npm seems to acquire lock to the working dir.
// Instead, create a temporary inner and move it out.
const coreDir = path.dirname(require.resolve("@swc/core"));
const installDir = path.join(coreDir, "npm-install");
try {
fs.mkdirSync(installDir);
fs.writeFileSync(path.join(installDir, "package.json"), "{}");
// Instead of carrying over own dependencies to download & resolve package which increases installation sizes of `@swc/core`,
// assume & relies on system's npm installation.
child_process.execSync(`npm install --no-save --loglevel=error --prefer-offline --no-audit --progress=false @swc/wasm@${version}`, { cwd: installDir, stdio: "pipe", env });
const installedBinPath = path.join(installDir, "node_modules", `@swc/wasm`);
// INIT_CWD is injected via npm. If it doesn't exists, can't proceed.
fs.renameSync(installedBinPath, path.resolve(process.env.INIT_CWD, "node_modules", `@swc/wasm`));
}
catch (error) {
console.error(error);
console.error(`Failed to install fallback @swc/wasm@${version}. @swc/core will not properly.
Please install @swc/wasm manually, or retry whole installation.
If there are unexpected errors, please report at https://github.com/swc-project/swc/issues`);
}
finally {
try {
removeRecursive(installDir);
}
catch (_) {
// Gracefully ignore any failures. This'll make few leftover files but it shouldn't block installation.
}
}
});
validateBinary().catch((error) => {
// for now just throw the error as-is.
throw error;
});