exarch-rs 0.4.0 → 0.5.0

package/src/lib.rs

@@ -44,6 +44,8 @@
 #![allow(clippy::trailing_empty_array)]
 
 use napi::bindgen_prelude::*;
+use napi::threadsafe_function::ThreadsafeFunction;
+use napi::threadsafe_function::ThreadsafeFunctionCallMode;
 use napi_derive::napi;
 
 mod config;
@@ -52,6 +54,7 @@ mod report;
 mod utils;
 
 use config::CreationConfig;
+use config::ExtractionOptions;
 use config::SecurityConfig;
 use error::convert_error;
 use report::ArchiveManifest;
@@ -117,8 +120,12 @@ use utils::validate_path;
 /// console.log(`Extracted ${report.filesExtracted} files`);
 ///
 /// // Customize security settings
-/// const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+/// const config = new SecurityConfig().setMaxFileSize(100 * 1024 * 1024);
 /// const report = await extractArchive('archive.tar.gz', '/tmp/output', config);
+///
+/// // Customize extraction options
+/// const opts = new ExtractionOptions().withSkipDuplicates(false);
+/// const report = await extractArchive('archive.tar.gz', '/tmp/output', null, opts);
 /// ```
 #[napi]
 #[allow(clippy::needless_pass_by_value, clippy::trailing_empty_array)]
@@ -126,6 +133,7 @@ pub async fn extract_archive(
     archive_path: String,
     output_dir: String,
     config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
 ) -> Result<ExtractionReport> {
     // Validate paths at boundary
     // NOTE: Defense-in-depth - paths are validated here and again in core
@@ -134,9 +142,11 @@ pub async fn extract_archive(
     validate_path(&archive_path)?;
     validate_path(&output_dir)?;
 
-    // Get owned config - clone only when config is Some, use default otherwise
+    // Get owned config/options - clone only when Some, use default otherwise
     let config_owned: exarch_core::SecurityConfig =
         config.map(|c| c.as_core().clone()).unwrap_or_default();
+    let options_owned: exarch_core::ExtractionOptions =
+        options.map(|o| o.as_core().clone()).unwrap_or_default();
 
     // Run extraction on tokio thread pool
     //
@@ -150,11 +160,21 @@ pub async fn extract_archive(
     // For maximum security with untrusted archives, use extractArchiveSync()
     // or ensure exclusive file access (e.g., flock) during extraction.
     let report = tokio::task::spawn_blocking(move || {
-        exarch_core::extract_archive(&archive_path, &output_dir, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::extract_archive_with_options(
+                &archive_path,
+                &output_dir,
+                &config_owned,
+                &options_owned,
+            )
+            .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive extraction"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(ExtractionReport::from(report))
 }
@@ -187,7 +207,7 @@ pub async fn extract_archive(
 /// console.log(`Extracted ${report.filesExtracted} files`);
 ///
 /// // Customize security settings
-/// const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+/// const config = new SecurityConfig().setMaxFileSize(100 * 1024 * 1024);
 /// const report = extractArchiveSync('archive.tar.gz', '/tmp/output', config);
 /// ```
 #[napi]
@@ -196,6 +216,7 @@ pub fn extract_archive_sync(
     archive_path: String,
     output_dir: String,
     config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
 ) -> Result<ExtractionReport> {
     // Validate paths at boundary
     // NOTE: Defense-in-depth - paths are validated here and again in core
@@ -204,14 +225,21 @@ pub fn extract_archive_sync(
     validate_path(&archive_path)?;
     validate_path(&output_dir)?;
 
-    // Get config reference or use default
     let default_config = exarch_core::SecurityConfig::default();
     let config_ref = config.map_or(&default_config, |c| c.as_core());
 
+    let default_options = exarch_core::ExtractionOptions::default();
+    let options_ref = options.map_or(&default_options, |o| o.as_core());
+
     // Run extraction synchronously with panic safety
     // CRITICAL: Never panic across FFI boundary
     let report = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-        exarch_core::extract_archive(&archive_path, &output_dir, config_ref)
+        exarch_core::extract_archive_with_options(
+            &archive_path,
+            &output_dir,
+            config_ref,
+            options_ref,
+        )
     }))
     .map_err(|_| Error::from_reason("Internal panic during archive extraction"))?
     .map_err(convert_error)?;
@@ -264,12 +292,17 @@ pub async fn create_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let report = tokio::task::spawn_blocking(move || {
-        let sources_refs: Vec<&str> = sources.iter().map(String::as_str).collect();
-        exarch_core::create_archive(&output_path, &sources_refs, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let sources_refs: Vec<&str> = sources.iter().map(String::as_str).collect();
+            exarch_core::create_archive(&output_path, &sources_refs, &config_owned)
+                .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive creation"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(CreationReport::from(report))
 }
@@ -364,11 +397,15 @@ pub async fn list_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let manifest = tokio::task::spawn_blocking(move || {
-        exarch_core::list_archive(&archive_path, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::list_archive(&archive_path, &config_owned).map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive listing"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(ArchiveManifest::from(manifest))
 }
@@ -461,11 +498,15 @@ pub async fn verify_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let report = tokio::task::spawn_blocking(move || {
-        exarch_core::verify_archive(&archive_path, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::verify_archive(&archive_path, &config_owned).map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive verification"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(VerificationReport::from(report))
 }
@@ -517,10 +558,170 @@ pub fn verify_archive_sync(
     Ok(VerificationReport::from(report))
 }
 
-// NOTE: Progress callback support (createArchiveWithProgress) is planned for
-// a future release. The napi-rs 3.x ThreadsafeFunction API requires additional
-// work to properly bridge Rust ProgressCallback trait to JavaScript callbacks.
-// For now, use createArchive/createArchiveSync without progress tracking.
+/// Extract an archive to the specified directory with a progress callback
+/// (async).
+///
+/// The `progress` callback is called once per entry with
+/// `(path, total, current, bytesWritten)` where:
+/// - `path` — entry path inside the archive
+/// - `total` — total number of entries as `number` (0 for TAR-family formats
+///   because the entry count is unknown until the stream is fully read)
+/// - `current` — 1-based index of the current entry as `number`
+/// - `bytesWritten` — cumulative bytes written to disk so far as `number`
+///   (always 0 during extraction because the core library does not emit
+///   byte-level progress events for extraction; only entry-level events fire)
+///
+/// Extraction runs on the tokio blocking thread pool. The progress callback is
+/// dispatched back to the JavaScript thread via a threadsafe function.
+///
+/// # Arguments
+///
+/// * `archive_path` - Path to the archive file
+/// * `output_dir` - Directory where files will be extracted
+/// * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
+/// * `options` - Optional `ExtractionOptions` (uses defaults if omitted)
+/// * `progress` - Optional progress callback `(path: string, total: number,
+///   current: number, bytesWritten: number) => void`
+///
+/// # Returns
+///
+/// Promise resolving to `ExtractionReport` with extraction statistics
+///
+/// # Errors
+///
+/// Returns error for security violations or I/O errors. Error messages are
+/// prefixed with error codes for discrimination in JavaScript. See
+/// `extractArchive` for the full list of error codes.
+///
+/// # Examples
+///
+/// ```javascript
+/// const report = await extractArchiveWithProgress(
+///   'archive.tar.gz',
+///   '/tmp/output',
+///   null,
+///   null,
+///   (path, total, current, bytesWritten) => {
+///     console.log(`${current}/${total}: ${path}`);
+///   },
+/// );
+/// console.log(`Extracted ${report.filesExtracted} files`);
+/// ```
+#[napi]
+#[allow(clippy::needless_pass_by_value, clippy::trailing_empty_array)]
+pub async fn extract_archive_with_progress(
+    archive_path: String,
+    output_dir: String,
+    config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
+    progress: Option<ThreadsafeFunction<(String, i64, i64, i64)>>,
+) -> Result<ExtractionReport> {
+    validate_path(&archive_path)?;
+    validate_path(&output_dir)?;
+
+    let config_owned: exarch_core::SecurityConfig =
+        config.map(|c| c.as_core().clone()).unwrap_or_default();
+    let options_owned: exarch_core::ExtractionOptions =
+        options.map(|o| o.as_core().clone()).unwrap_or_default();
+
+    let report = tokio::task::spawn_blocking(move || {
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            run_extract_with_optional_progress(
+                &archive_path,
+                &output_dir,
+                &config_owned,
+                &options_owned,
+                progress,
+            )
+            .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive extraction with progress"))
+        .flatten()
+    })
+    .await
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
+
+    Ok(ExtractionReport::from(report))
+}
+
+/// Runs `extract_archive_with_options_and_progress` routing to the JS callback
+/// when present or to [`exarch_core::NoopProgress`] when absent.
+fn run_extract_with_optional_progress(
+    archive_path: &str,
+    output_dir: &str,
+    config: &exarch_core::SecurityConfig,
+    options: &exarch_core::ExtractionOptions,
+    progress: Option<ThreadsafeFunction<(String, i64, i64, i64)>>,
+) -> exarch_core::Result<exarch_core::ExtractionReport> {
+    progress.map_or_else(
+        || {
+            let mut noop = exarch_core::NoopProgress;
+            exarch_core::extract_archive_with_options_and_progress(
+                archive_path,
+                output_dir,
+                config,
+                options,
+                &mut noop,
+            )
+        },
+        |tsfn| {
+            let mut callback = NodeProgressAdapter::new(tsfn);
+            exarch_core::extract_archive_with_options_and_progress(
+                archive_path,
+                output_dir,
+                config,
+                options,
+                &mut callback,
+            )
+        },
+    )
+}
+
+/// Adapter that calls a JavaScript progress callback from a Rust worker thread.
+///
+/// The JavaScript callback receives `(path: string, total: number, current:
+/// number, bytesWritten: number)` where `bytesWritten` is the number of bytes
+/// written **for the current entry so far** (starts at 0 when the entry begins,
+/// grows as chunks are flushed to disk; always 0 during extraction because the
+/// core library does not emit byte-level progress events for extraction).
+struct NodeProgressAdapter {
+    tsfn: ThreadsafeFunction<(String, i64, i64, i64)>,
+    current_entry_bytes: i64,
+    total: usize,
+}
+
+impl NodeProgressAdapter {
+    fn new(tsfn: ThreadsafeFunction<(String, i64, i64, i64)>) -> Self {
+        Self {
+            tsfn,
+            current_entry_bytes: 0,
+            total: 0,
+        }
+    }
+}
+
+impl exarch_core::ProgressCallback for NodeProgressAdapter {
+    fn on_entry_start(&mut self, path: &std::path::Path, total: usize, current: usize) {
+        self.current_entry_bytes = 0;
+        self.total = total;
+        let path_str = path.to_string_lossy().into_owned();
+        let total_i64 = i64::try_from(total).unwrap_or(i64::MAX);
+        let current_i64 = i64::try_from(current).unwrap_or(i64::MAX);
+        self.tsfn.call(
+            Ok((path_str, total_i64, current_i64, self.current_entry_bytes)),
+            ThreadsafeFunctionCallMode::NonBlocking,
+        );
+    }
+
+    fn on_bytes_written(&mut self, bytes: u64) {
+        self.current_entry_bytes = self.current_entry_bytes.saturating_add(bytes.cast_signed());
+    }
+
+    fn on_entry_complete(&mut self, _path: &std::path::Path) {}
+
+    fn on_complete(&mut self) {}
+}
 
 #[cfg(test)]
 #[allow(
@@ -539,6 +740,7 @@ mod tests {
             "/tmp/test\0malicious.tar".to_string(),
             "/tmp/output".to_string(),
             None,
+            None,
         )
         .await;
 
@@ -555,6 +757,7 @@ mod tests {
             "/tmp/test.tar".to_string(),
             "/tmp/output\0malicious".to_string(),
             None,
+            None,
         )
         .await;
 
@@ -568,7 +771,7 @@ mod tests {
     #[tokio::test]
     async fn test_extract_archive_rejects_excessively_long_archive_path() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive(long_path, "/tmp/output".to_string(), None).await;
+        let result = extract_archive(long_path, "/tmp/output".to_string(), None, None).await;
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -580,7 +783,7 @@ mod tests {
     #[tokio::test]
     async fn test_extract_archive_rejects_excessively_long_output_dir() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive("/tmp/test.tar".to_string(), long_path, None).await;
+        let result = extract_archive("/tmp/test.tar".to_string(), long_path, None, None).await;
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -593,7 +796,7 @@ mod tests {
     async fn test_extract_archive_accepts_empty_paths() {
         // Empty paths should be accepted at boundary validation
         // Core library will handle actual path validation
-        let result = extract_archive("".to_string(), "".to_string(), None).await;
+        let result = extract_archive("".to_string(), "".to_string(), None, None).await;
 
         // If it fails, ensure it's not a boundary path validation error
         // (empty paths pass boundary validation; core handles semantic validation)
@@ -615,6 +818,7 @@ mod tests {
             "/tmp/test\0malicious.tar".to_string(),
             "/tmp/output".to_string(),
             None,
+            None,
         );
 
         assert!(result.is_err(), "should reject null bytes in archive path");
@@ -630,6 +834,7 @@ mod tests {
             "/tmp/test.tar".to_string(),
             "/tmp/output\0malicious".to_string(),
             None,
+            None,
         );
 
         assert!(result.is_err(), "should reject null bytes in output path");
@@ -642,7 +847,7 @@ mod tests {
     #[test]
     fn test_extract_archive_sync_rejects_excessively_long_archive_path() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive_sync(long_path, "/tmp/output".to_string(), None);
+        let result = extract_archive_sync(long_path, "/tmp/output".to_string(), None, None);
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -654,7 +859,7 @@ mod tests {
     #[test]
     fn test_extract_archive_sync_rejects_excessively_long_output_dir() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive_sync("/tmp/test.tar".to_string(), long_path, None);
+        let result = extract_archive_sync("/tmp/test.tar".to_string(), long_path, None, None);
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -672,6 +877,7 @@ mod tests {
             "/tmp/valid_test_path.tar".to_string(),
             "/tmp/valid_output_path".to_string(),
             None,
+            None,
         );
 
         // If it fails, ensure it's not a path validation error
@@ -693,6 +899,7 @@ mod tests {
             "relative_test.tar".to_string(),
             "relative_output".to_string(),
             None,
+            None,
         );
 
         // If it fails, ensure it's not a path validation error
@@ -717,6 +924,7 @@ mod tests {
             "custom_test.tar".to_string(),
             "custom_output".to_string(),
             Some(&config),
+            None,
         );
 
         // If it fails, ensure it's not a path validation error

package/tests/extraction-options.test.js

@@ -0,0 +1,133 @@
+/**
+ * Tests for ExtractionOptions class
+ */
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { ExtractionOptions, extractArchiveSync, createArchiveSync } = require('../index.js');
+
+function createTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'exarch-test-'));
+}
+
+function createValidArchive(archivePath, tempDir) {
+  const sourceDir = path.join(tempDir, 'source');
+  fs.mkdirSync(sourceDir);
+  fs.writeFileSync(path.join(sourceDir, 'hello.txt'), 'Hello, World!');
+  createArchiveSync(archivePath, [sourceDir]);
+}
+
+describe('ExtractionOptions', () => {
+  describe('constructor', () => {
+    it('should create options with skipDuplicates defaulting to true', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('static default()', () => {
+    it('should return options equivalent to constructor', () => {
+      const opts = ExtractionOptions.default();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('withSkipDuplicates()', () => {
+    it('should set skipDuplicates to false', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      assert.strictEqual(opts.skipDuplicates, false);
+    });
+
+    it('should set skipDuplicates to true', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      opts.withSkipDuplicates(true);
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+
+    it('should default to true when called with no argument', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      opts.withSkipDuplicates();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('build()', () => {
+    it('should return self for builder consistency', () => {
+      const opts = new ExtractionOptions();
+      const result = opts.build();
+      assert.strictEqual(result, opts);
+    });
+  });
+
+  describe('withAtomic()', () => {
+    it('should have atomic defaulting to false', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.atomic, false);
+    });
+
+    it('should set atomic to true via withAtomic', () => {
+      const opts = new ExtractionOptions();
+      opts.withAtomic(true);
+      assert.strictEqual(opts.atomic, true);
+    });
+  });
+
+  describe('withSkipDuplicates() round-trip', () => {
+    it('should have skipDuplicates defaulting to true', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+
+    it('should set skipDuplicates to false via withSkipDuplicates', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      assert.strictEqual(opts.skipDuplicates, false);
+    });
+  });
+});
+
+describe('extractArchiveSync with ExtractionOptions', () => {
+  let tempDir;
+  let archivePath;
+  let outputDir;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+    archivePath = path.join(tempDir, 'test.tar.gz');
+    outputDir = path.join(tempDir, 'output');
+    fs.mkdirSync(outputDir);
+    createValidArchive(archivePath, tempDir);
+  });
+
+  afterEach(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should extract with default ExtractionOptions', () => {
+    const opts = new ExtractionOptions();
+    const report = extractArchiveSync(archivePath, outputDir, null, opts);
+
+    assert.strictEqual(report.filesExtracted, 1);
+    assert.ok(report.bytesWritten >= 13);
+  });
+
+  it('should extract with skip_duplicates=false on non-duplicate archive', () => {
+    const opts = new ExtractionOptions();
+    opts.withSkipDuplicates(false);
+    const report = extractArchiveSync(archivePath, outputDir, null, opts);
+
+    assert.strictEqual(report.filesExtracted, 1);
+  });
+
+  it('should extract without options (null) as before', () => {
+    const report = extractArchiveSync(archivePath, outputDir, null, null);
+    assert.strictEqual(report.filesExtracted, 1);
+  });
+});

package/tests/security-config.test.js

@@ -112,6 +112,19 @@ describe('SecurityConfig', () => {
       assert.strictEqual(config.allowWorldWritable, true);
     });
 
+    it('should default allowSolidArchives to false', () => {
+      const config = new SecurityConfig();
+
+      assert.strictEqual(config.allowSolidArchives, false);
+    });
+
+    it('should set allow solid archives', () => {
+      const config = new SecurityConfig();
+      config.setAllowSolidArchives(true);
+
+      assert.strictEqual(config.allowSolidArchives, true);
+    });
+
     it('should set preserve permissions', () => {
       const config = new SecurityConfig();
       config.setPreservePermissions(true);