@hakobu/hakobu 1.0.0

package/lib-es5/addon-extract.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Hakobu Native Addon Extraction
+ *
+ * Native .node addons cannot be loaded from an in-memory snapshot —
+ * they must exist as real files on the filesystem because dlopen()
+ * requires a real file path.
+ *
+ * This module extracts addons from the snapshot blob to a deterministic
+ * cache location on disk, keyed by content hash. This ensures:
+ *
+ *   1. Deterministic: same addon content → same extraction path
+ *   2. Idempotent: re-extraction is a no-op if the file already exists
+ *   3. Safe: permissions are narrowed appropriately
+ *   4. Cache-friendly: old versions can be garbage-collected
+ *
+ * Extraction path:
+ *   {cacheDir}/{contentHash}/{addonFilename}
+ *
+ *   e.g.: ~/.hakobu/addons/a1b2c3d4.../binding.node
+ *
+ * The extracted path replaces the snapshot path in require() resolution
+ * so that dlopen() can load the real file.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanAddonCache = exports.extractAllAddons = exports.extractAddon = exports.getAddonCacheDir = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const os_1 = __importDefault(require("os"));
+const snapshot_path_1 = require("./snapshot-path");
+const runtime_diagnostics_1 = require("./runtime-diagnostics");
+// ─────────────────────────────────────────────────────────────────────
+// Cache directory
+// ─────────────────────────────────────────────────────────────────────
+/**
+ * Get the addon extraction cache directory.
+ *
+ * Resolution order:
+ *   1. HAKOBU_ADDON_CACHE env var
+ *   2. $HOME/.hakobu/addons (default)
+ *   3. os.tmpdir()/hakobu-addons (fallback when home unavailable)
+ */
+function getAddonCacheDir() {
+    if (process.env.HAKOBU_ADDON_CACHE) {
+        return process.env.HAKOBU_ADDON_CACHE;
+    }
+    try {
+        const home = os_1.default.homedir();
+        if (home) {
+            return path_1.default.join(home, '.hakobu', 'addons');
+        }
+    }
+    catch { /* home unavailable */ }
+    return path_1.default.join(os_1.default.tmpdir(), 'hakobu-addons');
+}
+exports.getAddonCacheDir = getAddonCacheDir;
+/**
+ * Extract a native addon from the snapshot to the real filesystem.
+ *
+ * If the addon is already cached (same content hash), returns the
+ * existing path without re-extracting. This makes extraction idempotent.
+ *
+ * @param snapshotPath - The addon's path in the snapshot
+ * @param sfs - The SnapshotFS instance
+ * @param cacheDir - Override cache directory (for testing)
+ * @returns ExtractedAddon with the real filesystem path
+ */
+function extractAddon(snapshotPath, sfs, cacheDir) {
+    const canonical = (0, snapshot_path_1.toCanonical)(snapshotPath);
+    const content = sfs.readFileSync(canonical);
+    // Compute content hash for deterministic path
+    const contentHash = crypto_1.default
+        .createHash('sha256')
+        .update(content)
+        .digest('hex');
+    // Build extraction path: {cacheDir}/{hash}/{filename}
+    const fileName = path_1.default.basename(canonical);
+    const dir = path_1.default.join(cacheDir || getAddonCacheDir(), contentHash);
+    const extractedPath = path_1.default.join(dir, fileName);
+    // Check cache: if file exists with correct size, skip extraction
+    if (fs_1.default.existsSync(extractedPath)) {
+        try {
+            const stat = fs_1.default.statSync(extractedPath);
+            if (stat.size === content.length) {
+                return {
+                    snapshotPath: canonical,
+                    extractedPath,
+                    contentHash,
+                    freshlyExtracted: false,
+                };
+            }
+        }
+        catch {
+            // Fall through to extract
+        }
+    }
+    // Extract: create directory and write the addon
+    try {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(extractedPath, content);
+    }
+    catch (err) {
+        throw (0, runtime_diagnostics_1.addonExtractionFailed)(canonical, extractedPath, err);
+    }
+    // Set executable permission (some addons need it)
+    try {
+        fs_1.default.chmodSync(extractedPath, 0o755);
+    }
+    catch {
+        // chmod may fail on some platforms — non-fatal
+    }
+    return {
+        snapshotPath: canonical,
+        extractedPath,
+        contentHash,
+        freshlyExtracted: true,
+    };
+}
+exports.extractAddon = extractAddon;
+/**
+ * Extract all native addons from the snapshot.
+ * Returns a map from snapshot path → extracted filesystem path.
+ */
+function extractAllAddons(sfs, cacheDir) {
+    const index = sfs.index;
+    const results = new Map();
+    for (const entry of index.entries) {
+        if (entry.kind === 'native-addon') {
+            const result = extractAddon(entry.path, sfs, cacheDir);
+            results.set(entry.path, result);
+        }
+    }
+    return results;
+}
+exports.extractAllAddons = extractAllAddons;
+/**
+ * Clean old addon cache entries that are no longer referenced.
+ * @param keepHashes - Set of content hashes to keep
+ * @param cacheDir - Cache directory to clean
+ */
+function cleanAddonCache(keepHashes, cacheDir) {
+    const dir = cacheDir || getAddonCacheDir();
+    if (!fs_1.default.existsSync(dir))
+        return 0;
+    let removed = 0;
+    for (const entry of fs_1.default.readdirSync(dir)) {
+        if (!keepHashes.has(entry)) {
+            try {
+                fs_1.default.rmSync(path_1.default.join(dir, entry), { recursive: true, force: true });
+                removed++;
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+    }
+    return removed;
+}
+exports.cleanAddonCache = cleanAddonCache;
+//# sourceMappingURL=addon-extract.js.map