Extraction & Download Operations
Relevant source files
The following files were used as context for generating this wiki page:
Extraction and Download Operations form the core of the Numan install transaction, ensuring that package artifacts are securely retrieved, verified, and deployed to the local filesystem. These operations are designed to be "inert," meaning they only write to the $NUMAN_ROOT and do not modify the active Nushell configuration until a separate activation step is performed.
The system prioritizes security through mandatory SHA256 integrity checks for plugin binaries and uses atomic filesystem operations to prevent partial-write corruption. It supports multiple archive formats including ZIP, TarGz, TarXz, and plain Tar, while implementing safeguards against common archive-based attacks like directory traversal and "archive bombs."
Sources: README.md:12-25, AGENTS.md:168-176, src/install/transaction.rs:16-30
Download Lifecycle & Integrity
The download process is managed as a multi-stage transaction to ensure that only verified artifacts reach the immutable package store. Artifacts are initially downloaded to a temporary .part file before undergoing SHA256 verification.
Download Flow
- Cache Check: Numan checks the
cache/downloadsdirectory for an existing binary named after the artifact's SHA256 hash. - Streaming Download: If not cached, the file is downloaded to a
.partextension to prevent the use of incomplete files. - Integrity Verification: The downloaded file is hashed and compared against the mandatory SHA256 checksum provided by the registry.
- Promotion: Upon successful verification, the
.partfile is atomically renamed to its final cache name.
This diagram illustrates the transition from a network request to a verified local cache entry.
Sources: src/install/transaction.rs:160-188, AGENTS.md:154-157
Download Components
| Component | Description |
|---|---|
cache/downloads | The directory within $NUMAN_ROOT where verified artifacts are stored. |
.part Files | Temporary files used during the download process to ensure atomicity. |
artifact_sha256 | Mandatory checksum for plugins used to verify the integrity of the downloaded archive. |
Sources: src/install/transaction.rs:168-175, AGENTS.md:173-173
Archive Extraction & Security
Numan supports a variety of archive formats and enforces strict security boundaries during extraction. The extraction logic is centralized in src/install/extract.rs and utilizes specialized decoders for different compression types.
Supported Formats
| Format | Suffixes Supported | Implementation |
|---|---|---|
| ZIP | .zip | ZipArchive |
| TarGz | .tar.gz, .tgz | GzDecoder + TarArchive |
| TarXz | .tar.xz, .txz | XzDecoder + TarArchive |
| Tar | .tar | TarArchive |
Sources: src/install/extract.rs:25-50
Extraction Security Safeguards
To protect the host system, the extraction engine implements three primary security layers:
- Path Traversal Protection: Numan rejects any archive entry containing
..or absolute paths that would resolve outside the designated staging directory. - Archive Bomb Prevention: The system enforces a maximum file count (default 10,000) and a maximum uncompressed size (default 100 MB).
- Atomic Deployment: Extraction occurs in a temporary staging directory on the same volume as the final target. The directory is moved to the final versioned path only after all files are successfully extracted and validated.
The sequence above shows how the staging directory acts as a buffer before the immutable package path is established.
Sources: src/install/extract.rs:114-140, src/install/transaction.rs:210-230, AGENTS.md:113-113
Staging and Immutable Paths
Extraction results in a content-addressed, versioned directory structure:
$NUMAN_ROOT/packages/<type>/<owner>/<name>/<version>-<sha8prefix>/
This layout ensures that updates do not overwrite existing files, facilitating safe rollbacks and side-by-side versioning.
Sources: src/install/transaction.rs:150-160, AGENTS.md:109-110
Implementation Details
Artifact Resolution
Artifact selection is platform-aware. The system resolves the appropriate binary for the compile-time OS/Arch/Libc triple using the Platform and Resolver components.
// src/install/transaction.rs:88-100
let target = resolved
.artifact
.targets
.get(&options.platform.triple)
.with_context(|| {
format!(
"No binary available for '{}' on {}. {}",
id,
options.platform.triple,
hints::run(CMD_REGISTRY_SYNC)
)
})?;
Path Normalization
Numan uses a strict normalization process for archive suffixes to handle query strings and URL fragments, ensuring correct format detection from remote URLs.
// src/install/extract.rs:35-41
fn normalize_url_path(url: &str) -> String {
let without_query = url.split_once('?').map_or(url, |(path, _)| path);
without_query
.split_once('#')
.map_or(without_query, |(path, _)| path)
.to_ascii_lowercase()
}
Sources: src/install/extract.rs:35-41, src/install/transaction.rs:88-100
Summary
Extraction and Download Operations provide a reliable foundation for Numan's package management. By combining mandatory integrity verification, robust archive handling, and atomic filesystem movements, the system ensures that package installations are both secure and reproducible. The "inert install" architecture ensures that these operations remain safely decoupled from the active Nushell environment.