Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
12.1 KB
Raw Blame
import ArchiveKit
import Foundation

/// Unpacks an archive onto disk.
///
/// The format and the compressor are detected, so there is no `--zstd` to
/// pass and no way to get it wrong. What the caller does choose is where the
/// files end up belonging, which is the part that differs between unpacking
/// onto a mounted guest volume and unpacking into a scratch directory.
public enum VPhoneArchiveExtractor {
    /// Bytes handed to libarchive per read. 10 KiB is libarchive's own
    /// suggestion and there is no reason here to argue with it.
    private static let blockSize = 10240

    public struct Progress: Sendable {
        public let entriesWritten: Int
        public let bytesWritten: Int64
        public let currentPath: String
    }

    /// Unpack `archive` into `destination`.
    ///
    /// `bytesRead` reports how far into the archive *file* the read has got —
    /// compressed bytes, so it can be shown against the file's size on disk.
    /// It fires per data block, not per entry, because a VM bundle's `Disk.img`
    /// is one entry of many gigabytes.
    ///
    /// - Returns: the number of entries written, not counting any skipped by
    ///   `noOverwriteDir`.
    @discardableResult
    public static func extract(
        _ archive: URL,
        into destination: URL,
        options: VPhoneArchiveExtractOptions,
        progress: ((Progress) -> Void)? = nil,
        bytesRead: ((Int64) -> Void)? = nil,
        isCancelled: (() -> Bool)? = nil,
    ) throws -> Int {
        try withArchiveLocale {
            try unpack(
                archive,
                into: destination,
                options: options,
                progress: progress,
                bytesRead: bytesRead,
                isCancelled: isCancelled,
            )
        }
    }

    private static func unpack(
        _ archive: URL,
        into destination: URL,
        options: VPhoneArchiveExtractOptions,
        progress: ((Progress) -> Void)?,
        bytesRead: ((Int64) -> Void)?,
        isCancelled: (() -> Bool)?,
    ) throws -> Int {
        let reader = archive_read_new()
        archive_read_support_format_all(reader)
        archive_read_support_filter_all(reader)
        defer { archive_read_free(reader) }

        let writer = archive_write_disk_new()
        archive_write_disk_set_options(writer, options.extractFlags)
        // Deliberately NOT archive_write_disk_set_standard_lookup(): see
        // VPhoneArchiveOwnership.preserveNumeric. Without it libarchive uses
        // the numeric ids straight from the archive, which is what we want.
        defer { archive_write_free(writer) }

        guard archive_read_open_filename(reader, archive.path, blockSize) == ARCHIVE_OK else {
            throw VPhoneArchiveError.cannotOpen(
                path: archive.path,
                reason: archiveErrorString(reader),
            )
        }

        // Resolved once, and every target is built from the resolved form.
        //
        // Not a tidy-up: ARCHIVE_EXTRACT_SECURE_SYMLINKS checks every
        // component of the path it is given, and on macOS /tmp and /var are
        // themselves symlinks into /private. Handing it an unresolved
        // /var/folders/... target makes it refuse the extraction outright,
        // with "Cannot extract through symlink /var/...". Resolving the
        // destination leaves only components *below* it for the flag to judge,
        // which is the part we actually want judged.
        let resolvedDestination = try VPhoneArchivePaths.resolved(destination)
        let destinationPath = resolvedDestination.path
        var written = 0
        var bytes: Int64 = 0

        while true {
            if isCancelled?() == true {
                throw VPhoneArchiveError.cancelled
            }

            var entry: OpaquePointer?
            let status = archive_read_next_header(reader, &entry)
            if status == ARCHIVE_EOF {
                break
            }
            guard status == ARCHIVE_OK || status == ARCHIVE_WARN, let entry else {
                throw VPhoneArchiveError.readFailed(
                    path: archive.path,
                    reason: archiveErrorString(reader),
                )
            }

            // A name libarchive could not convert comes back NULL. Treated as
            // "", it would resolve to the destination itself and pass the
            // containment check below.
            guard let rawPath = archive_entry_pathname(entry) else {
                throw VPhoneArchiveError.readFailed(
                    path: archive.path,
                    reason: archiveErrorString(reader),
                )
            }
            let memberPath = String(cString: rawPath)
            let target = resolvedDestination.appendingPathComponent(memberPath)

            // libarchive's SECURE_* flags already refuse absolute paths and
            // `..`, but they refuse them inside libarchive. Checking the
            // normalised result here as well means the answer does not rest on
            // one flag being set, and the error can name the member.
            // .standardized, not .standardizedFileURL: the latter resolves
            // symlinks as well, and on macOS that turns the /private/var we
            // just resolved back into /var, so the prefix comparison fails
            // against a destination that is perfectly fine. Collapsing "." and
            // ".." is all that is wanted here — the destination was already
            // resolved once, above.
            let targetPath = target.standardized.path
            guard targetPath == destinationPath || targetPath.hasPrefix(destinationPath + "/") else {
                throw VPhoneArchiveError.pathEscapesDestination(
                    member: memberPath,
                    destination: destinationPath,
                )
            }
            archive_entry_set_pathname(entry, targetPath)

            // A hardlink entry names its target as an archive-relative path,
            // and libarchive resolves that against the process's working
            // directory. Since the entry's own path has just been made
            // absolute, the target has to be too, or extraction fails with
            // "Hard-link target 'x' does not exist" — which is what happened.
            //
            // Symlinks are deliberately left alone: their target is data,
            // stored and restored verbatim, and rewriting one would change
            // what the link says.
            if let rawLink = archive_entry_hardlink(entry) {
                let linkPath = String(cString: rawLink)
                let linkTarget = resolvedDestination.appendingPathComponent(linkPath)
                let resolvedLink = linkTarget.standardized.path
                guard resolvedLink.hasPrefix(destinationPath + "/") else {
                    throw VPhoneArchiveError.pathEscapesDestination(
                        member: linkPath,
                        destination: destinationPath,
                    )
                }
                archive_entry_set_hardlink(entry, resolvedLink)
            }

            if options.noOverwriteDir, shouldSkipExistingDirectory(entry, at: target) {
                // Skip the header only. Everything under this directory that
                // does not yet exist is still written on its own entry, which
                // is what GNU tar does too.
                continue
            }

            guard archive_write_header(writer, entry) == ARCHIVE_OK else {
                throw VPhoneArchiveError.writeFailed(
                    path: target.path,
                    reason: archiveErrorString(writer),
                )
            }

            if archive_entry_size(entry) > 0 {
                bytes += try copyData(
                    from: reader,
                    to: writer,
                    isCancelled: isCancelled,
                    onBlock: bytesRead.map { report in
                        { report(archive_filter_bytes(reader, -1)) }
                    },
                )
            }

            guard archive_write_finish_entry(writer) == ARCHIVE_OK else {
                throw VPhoneArchiveError.writeFailed(
                    path: target.path,
                    reason: archiveErrorString(writer),
                )
            }

            written += 1
            progress?(Progress(entriesWritten: written, bytesWritten: bytes, currentPath: memberPath))
            // filter -1 is the bottom filter, the archive file itself, so this
            // is the compressed position. Entries with no data never reach the
            // per-block report above, and small ones are most of a bundle.
            bytesRead?(archive_filter_bytes(reader, -1))
        }

        return written
    }

    // MARK: - --no-overwrite-dir

    /// Whether this entry is a directory that already exists and should be
    /// left exactly as it is.
    ///
    /// GNU tar's `--no-overwrite-dir` has no libarchive equivalent, and
    /// neither of the two things libarchive does offer is the same:
    ///
    /// - The default, per `man 3 archive_write_disk`, is that "existing
    ///   directories will have their permissions updated". That is precisely
    ///   what must not happen. `iosbinpack64.tar` carries entries for `usr/`,
    ///   `usr/local/` and `System/`, and unpacking it onto an installed iOS
    ///   volume would stamp the archive's modes and owners over the real
    ///   ones.
    ///
    /// - `ARCHIVE_EXTRACT_NO_OVERWRITE` is too broad in the other direction:
    ///   it skips any existing object of any type, so an ordinary file that
    ///   should be replaced silently is not. libarchive decides per entry, so
    ///   skipping a directory does not affect new files beneath it — the
    ///   problem is only what it does to regular files.
    ///
    /// So: look for a directory entry whose target already exists as a
    /// directory, and skip writing its header. The path is left in place; only
    /// its metadata is left alone.
    private static func shouldSkipExistingDirectory(
        _ entry: OpaquePointer,
        at target: URL,
    ) -> Bool {
        // S_IFDIR rather than AE_IFDIR: the AE_* names are C macros that Swift
        // does not import, and they are defined to the same values as the
        // S_IF* ones precisely so they can be compared like this.
        guard mode_t(archive_entry_filetype(entry)) == S_IFDIR else { return false }

        var info = stat()
        // lstat, not stat: a symlink that points at a directory is a symlink,
        // and replacing it is a different decision from updating a directory.
        guard lstat(target.path, &info) == 0 else { return false }
        return (info.st_mode & S_IFMT) == S_IFDIR
    }

    // MARK: - Data

    private static func copyData(
        from reader: OpaquePointer?,
        to writer: OpaquePointer?,
        isCancelled: (() -> Bool)?,
        onBlock: (() -> Void)? = nil,
    ) throws -> Int64 {
        var total: Int64 = 0
        while true {
            // Cancellation is checked per block, not per entry: a single
            // multi-gigabyte disk image is one entry, and a check that only
            // happens between entries would not interrupt it.
            if isCancelled?() == true {
                throw VPhoneArchiveError.cancelled
            }

            var buffer: UnsafeRawPointer?
            var size = 0
            var offset: la_int64_t = 0

            let status = archive_read_data_block(reader, &buffer, &size, &offset)
            if status == ARCHIVE_EOF {
                return total
            }
            guard status == ARCHIVE_OK || status == ARCHIVE_WARN else {
                throw VPhoneArchiveError.readFailed(
                    path: "<member data>",
                    reason: archiveErrorString(reader),
                )
            }

            guard archive_write_data_block(writer, buffer, size, offset) >= ARCHIVE_OK else {
                throw VPhoneArchiveError.writeFailed(
                    path: "<member data>",
                    reason: archiveErrorString(writer),
                )
            }
            total += Int64(size)
            onBlock?()
        }
    }
}