uv_extract/
error.rs

1use std::{ffi::OsString, path::PathBuf};
2
3use crate::validate_archive_member_name;
4
5#[derive(Debug, thiserror::Error)]
6pub enum Error {
7    #[error("I/O operation failed during extraction")]
8    Io(#[source] std::io::Error),
9    #[error("Invalid zip file structure")]
10    AsyncZip(#[source] async_zip::error::ZipError),
11    #[error("Invalid tar file")]
12    Tar(
13        #[source]
14        #[from]
15        tokio_tar::TarError,
16    ),
17    #[error("Invalid tar file")]
18    TarCodec(
19        #[source]
20        #[from]
21        tar_codec::ExtractError<tar_codec::DecodeError>,
22    ),
23    #[error(transparent)]
24    DirectoryHash(#[from] crate::dirhash::DirhashError),
25    #[error(
26        "The top-level of the archive must only contain a list directory, but it contains: {0:?}"
27    )]
28    NonSingularArchive(Vec<OsString>),
29    #[error("The top-level of the archive must only contain a list directory, but it's empty")]
30    EmptyArchive,
31    #[error("ZIP local header filename at offset {offset} does not use UTF-8 encoding")]
32    LocalHeaderNotUtf8 { offset: u64 },
33    #[error("ZIP central directory entry filename at index {index} does not use UTF-8 encoding")]
34    CentralDirectoryEntryNotUtf8 { index: u64 },
35    #[error("Bad CRC (got {computed:08x}, expected {expected:08x}) for file: {}", path.display())]
36    BadCrc32 {
37        path: PathBuf,
38        computed: u32,
39        expected: u32,
40    },
41    #[error("Bad uncompressed size (got {computed:08x}, expected {expected:08x}) for file: {}", path.display())]
42    BadUncompressedSize {
43        path: PathBuf,
44        computed: u64,
45        expected: u64,
46    },
47    #[error("Bad compressed size (got {computed:08x}, expected {expected:08x}) for file: {}", path.display())]
48    BadCompressedSize {
49        path: PathBuf,
50        computed: u64,
51        expected: u64,
52    },
53    #[error("ZIP file contains multiple entries with different contents for: {}", path.display())]
54    DuplicateLocalFileHeader { path: PathBuf },
55    #[error("ZIP file contains multiple entries for the same output path: {}", path.display())]
56    DuplicateOutputPath { path: PathBuf },
57    #[error("ZIP file contains a local file header without a corresponding central-directory record entry for: {} ({offset})", path.display())]
58    MissingCentralDirectoryEntry { path: PathBuf, offset: u64 },
59    #[error("ZIP file contains an end-of-central-directory record entry, but no local file header for: {} ({offset}", path.display())]
60    MissingLocalFileHeader { path: PathBuf, offset: u64 },
61    #[error("ZIP file uses conflicting paths for the local file header at {} (got {}, expected {})", offset, local_path.display(), central_directory_path.display())]
62    ConflictingPaths {
63        offset: u64,
64        local_path: PathBuf,
65        central_directory_path: PathBuf,
66    },
67    #[error("ZIP file uses conflicting entry types for the local file header and central-directory record for: {} ({offset})", path.display())]
68    ConflictingEntryTypes { path: PathBuf, offset: u64 },
69    #[error("ZIP file uses conflicting checksums for the local file header and central-directory record (got {local_crc32}, expected {central_directory_crc32}) for: {} ({offset})", path.display())]
70    ConflictingChecksums {
71        path: PathBuf,
72        offset: u64,
73        local_crc32: u32,
74        central_directory_crc32: u32,
75    },
76    #[error("ZIP file uses conflicting compressed sizes for the local file header and central-directory record (got {local_compressed_size}, expected {central_directory_compressed_size}) for: {} ({offset})", path.display())]
77    ConflictingCompressedSizes {
78        path: PathBuf,
79        offset: u64,
80        local_compressed_size: u64,
81        central_directory_compressed_size: u64,
82    },
83    #[error("ZIP file uses conflicting uncompressed sizes for the local file header and central-directory record (got {local_uncompressed_size}, expected {central_directory_uncompressed_size}) for: {} ({offset})", path.display())]
84    ConflictingUncompressedSizes {
85        path: PathBuf,
86        offset: u64,
87        local_uncompressed_size: u64,
88        central_directory_uncompressed_size: u64,
89    },
90    #[error("ZIP file contains trailing contents after the end-of-central-directory record")]
91    TrailingContents,
92    #[error(
93        "ZIP file reports a number of entries in the central directory that conflicts with the actual number of entries (got {actual}, expected {expected})"
94    )]
95    ConflictingNumberOfEntries { actual: u64, expected: u64 },
96    #[error("Data descriptor is missing for file: {}", path.display())]
97    MissingDataDescriptor { path: PathBuf },
98    #[error("File contains an unexpected data descriptor: {}", path.display())]
99    UnexpectedDataDescriptor { path: PathBuf },
100    #[error(
101        "ZIP file end-of-central-directory record contains a comment that appears to be an embedded ZIP file"
102    )]
103    ZipInZip,
104    #[error("ZIP64 end-of-central-directory record contains unsupported extensible data")]
105    ExtensibleData,
106    #[error("ZIP file end-of-central-directory record contains multiple entries with the same path, but conflicting modes: {}", path.display())]
107    DuplicateExecutableFileHeader { path: PathBuf },
108    #[error("Archive contains a file with an empty filename")]
109    EmptyFilename,
110    #[error("Archive contains unacceptable filename: {filename}")]
111    UnacceptableFilename { filename: String },
112    #[error(
113        "Archive contains a file with an unsupported compression method; files must be compressed with 'stored', 'DEFLATE', or 'zstd'"
114    )]
115    UnsupportedCompression,
116}
117
118impl From<async_zip::error::ZipError> for Error {
119    fn from(err: async_zip::error::ZipError) -> Self {
120        match err {
121            async_zip::error::ZipError::CompressionNotSupported(_) => Self::UnsupportedCompression,
122            async_zip::error::ZipError::FileNameContainsNul { filename } => {
123                let filename = String::from_utf8_lossy(&filename);
124                validate_archive_member_name(&filename)
125                    .expect_err("a filename containing an embedded NUL must be rejected")
126            }
127            error => Self::AsyncZip(error),
128        }
129    }
130}
131
132impl Error {
133    /// When reading from a ZIP archive, the error can either be an I/O error from the underlying
134    /// operating system, or an error with the archive. Both get wrapped into an I/O error through
135    /// e.g., `io::copy`. This method extracts ZIP errors to distinguish them from invalid archives.
136    pub(crate) fn io_or_zip(err: std::io::Error) -> Self {
137        if err.kind() != std::io::ErrorKind::Other {
138            return Self::Io(err);
139        }
140
141        let err = match err.downcast::<async_zip::error::ZipError>() {
142            Ok(zip_err) => return Self::from(zip_err),
143            Err(err) => err,
144        };
145        Self::Io(err)
146    }
147
148    /// When reading a tar archive, the error can either be an I/O error from the underlying
149    /// reader or an error with the archive. Both get wrapped into an I/O error through operations
150    /// such as `io::copy`. This method extracts tar errors to distinguish them from I/O errors.
151    pub(crate) fn io_or_tar(err: std::io::Error) -> Self {
152        if err.kind() != std::io::ErrorKind::Other {
153            return Self::Io(err);
154        }
155
156        match err.downcast::<tokio_tar::TarError>() {
157            Ok(tar_err) => Self::Tar(tar_err),
158            Err(err) => Self::Io(err),
159        }
160    }
161
162    /// Returns `true` if the error is due to the server not supporting HTTP streaming. Most
163    /// commonly, this is due to serving ZIP files with features that are incompatible with
164    /// streaming, like data descriptors.
165    pub fn is_http_streaming_unsupported(&self) -> bool {
166        matches!(
167            self,
168            Self::AsyncZip(async_zip::error::ZipError::FeatureNotSupported(_))
169        )
170    }
171
172    /// Returns `true` if the error is due to HTTP streaming request failed.
173    pub fn is_http_streaming_failed(&self) -> bool {
174        fn contains_reqwest_error(error: &(dyn std::error::Error + 'static)) -> bool {
175            if error.downcast_ref::<reqwest::Error>().is_some() {
176                return true;
177            }
178            // `std::io::Error::source` forwards to the source of its custom error and can skip the
179            // custom error itself, so inspect `get_ref` before following the standard chain.
180            if let Some(error) = error.downcast_ref::<std::io::Error>()
181                && let Some(inner) = error.get_ref()
182                && contains_reqwest_error(inner)
183            {
184                return true;
185            }
186            error.source().is_some_and(contains_reqwest_error)
187        }
188
189        if matches!(
190            self,
191            Self::AsyncZip(async_zip::error::ZipError::UpstreamReadError(_))
192        ) {
193            return true;
194        }
195        contains_reqwest_error(self)
196    }
197}
uv_extract/error.rs

uv_extract/
error.rs
