Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Make snapshot revert all or nothing and trust its metadata less

Jacky84b9f7d0a004
diff --git a/Documents/Guides/snapshots.md b/Documents/Guides/snapshots.md
index c32fa9f9..134f99b9 100644
--- a/Documents/Guides/snapshots.md
+++ b/Documents/Guides/snapshots.md
@@ -29,6 +29,13 @@ The three files move together. The Secure Enclave's anti-replay counters live in
a `SEPStorage` from another makes the SEP panic on the next boot, so a snapshot
always takes all three at once and a revert always puts all three back.
+A revert is all or nothing. If it fails partway, it puts the VM's own files
+back and reports the error, so the VM is as it was. In the rare case that
+putting them back fails too, the error says so: revert to a snapshot again
+before starting the VM. A snapshot whose `Snapshot.plist` does not list all
+three files, or lists a file that is not part of a snapshot, is refused as
+damaged before anything changes.
+
`list` and `delete` work while the VM runs; neither touches its live files.
## What a snapshot holds
diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift
index 08f779a3..9f1cdda6 100644
--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift
+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift
@@ -203,6 +203,10 @@ public enum VPhoneMachineSnapshots {
encoder.outputFormat = .xml
try encoder.encode(metadata).write(to: staging.appendingPathComponent(metadataFileName))
try VPhoneHostFilePermissions.makeAccessible(at: staging)
+ // Checked again before the snapshot is published: a VM started
+ // while the files were cloned may have moved one of them, and the
+ // copies would then come from different moments.
+ try VPhoneBundleActivity.requireStopped(bundle)
// Exclusive: a snapshot of the same name made meanwhile is not replaced.
guard renamex_np(staging.path, destination.path, UInt32(RENAME_EXCL)) == 0 else {
if errno == EEXIST {
@@ -225,16 +229,16 @@ public enum VPhoneMachineSnapshots {
/// snapshot.
///
/// Every file is cloned into a hidden directory in the machine folder
- /// first; only when all of them are there does each one replace its live
- /// file with `rename(2)`. A failure while cloning leaves the live set
- /// untouched, and the switch itself is a handful of renames on one volume.
+ /// first; only when all of them are there does the live set change, by
+ /// `rename(2)` on one volume. Each live file is moved aside into that
+ /// directory before its snapshot copy takes its place, and a failure
+ /// partway puts the moved files back, so the live set is either the old
+ /// one or the snapshot's, never a mix.
@discardableResult
public static func revert(to name: String, of bundle: VPhoneBundle) throws -> VPhoneMachineSnapshot {
let snapshot = try snapshot(named: name, of: bundle)
let source = directory(of: bundle).appendingPathComponent(name, isDirectory: true)
- for file in snapshot.files + snapshot.absentFiles {
- try requireStateFileName(file, snapshot: name)
- }
+ try requireValidFileLists(of: snapshot, bundle: bundle)
try VPhoneBundleActivity.requireStopped(bundle)
let fm = FileManager.default
@@ -257,19 +261,71 @@ public enum VPhoneMachineSnapshots {
// Checked again just before the live files change: the clones above
// take a moment, and nothing may open the machine meanwhile.
try VPhoneBundleActivity.requireStopped(bundle)
- for file in snapshot.files {
- let live = bundle.url.appendingPathComponent(file)
- guard rename(staging.appendingPathComponent(file).path, live.path) == 0 else {
- throw VPhoneMachineSnapshotError.failed(path: live.path, reason: currentErrorText())
+ try replaceLiveFiles(with: snapshot, staged: staging, in: bundle)
+ return snapshot
+ }
+
+ /// One step of the swap: `file` was moved aside (or did not exist live),
+ /// and a snapshot copy may have taken its place.
+ private struct SwapStep {
+ let file: String
+ let movedAside: Bool
+ var placed = false
+ }
+
+ /// Replaces each live file in `snapshot.files` with its copy in `staging`
+ /// and removes each one in `snapshot.absentFiles`. A live file is first
+ /// renamed to `staging/old-<name>`, so it is deleted only with the staging
+ /// directory once every step has succeeded. On a failure the steps done
+ /// are undone in reverse.
+ private static func replaceLiveFiles(with snapshot: VPhoneMachineSnapshot, staged staging: URL, in bundle: VPhoneBundle) throws {
+ let absent = Set(snapshot.absentFiles)
+ var steps: [SwapStep] = []
+ do {
+ for file in snapshot.files + snapshot.absentFiles {
+ let live = bundle.url.appendingPathComponent(file).path
+ let aside = staging.appendingPathComponent("old-\(file)").path
+ let movedAside = rename(live, aside) == 0
+ if !movedAside, errno != ENOENT {
+ throw VPhoneMachineSnapshotError.failed(path: live, reason: currentErrorText())
+ }
+ steps.append(SwapStep(file: file, movedAside: movedAside))
+ if absent.contains(file) { continue }
+ guard rename(staging.appendingPathComponent(file).path, live) == 0 else {
+ throw VPhoneMachineSnapshotError.failed(path: live, reason: currentErrorText())
+ }
+ steps[steps.count - 1].placed = true
}
+ } catch {
+ let notRestored = undo(steps, staging: staging, bundle: bundle)
+ guard notRestored.isEmpty else {
+ throw VPhoneMachineSnapshotError.revertIncomplete(
+ machine: bundle.name,
+ reason: "\(error)",
+ files: notRestored,
+ )
+ }
+ throw error
}
- for file in snapshot.absentFiles {
- let live = bundle.url.appendingPathComponent(file)
- if unlink(live.path) != 0, errno != ENOENT {
- throw VPhoneMachineSnapshotError.failed(path: live.path, reason: currentErrorText())
+ }
+
+ /// Puts each live file moved aside back, and removes a snapshot copy
+ /// placed where there was no live file. Best effort, in reverse; returns
+ /// the files it could not put back.
+ private static func undo(_ steps: [SwapStep], staging: URL, bundle: VPhoneBundle) -> [String] {
+ var notRestored: [String] = []
+ for step in steps.reversed() {
+ let live = bundle.url.appendingPathComponent(step.file).path
+ if step.movedAside {
+ // Replaces the placed snapshot copy, if any, in one rename.
+ if rename(staging.appendingPathComponent("old-\(step.file)").path, live) != 0 {
+ notRestored.append(step.file)
+ }
+ } else if step.placed, unlink(live) != 0, errno != ENOENT {
+ notRestored.append(step.file)
}
}
- return snapshot
+ return notRestored.reversed()
}
// MARK: Delete
@@ -293,13 +349,29 @@ public enum VPhoneMachineSnapshots {
}
}
- /// A file named in a snapshot's metadata is written into the machine
- /// folder on revert, so it must be one plain name and never the manifest.
- private static func requireStateFileName(_ file: String, snapshot: String) throws {
- guard VPhoneVirtualMachineManifest.isPlainFileName(file),
- file != "config.plist", file != metadataFileName, file != directoryName
- else {
- throw VPhoneMachineSnapshotError.damaged(name: snapshot, reason: "it names the file '\(file)'")
+ /// Revert replaces every file in `files` and deletes every file in
+ /// `absentFiles` in the machine folder, by names read from metadata anyone
+ /// can edit. So the lists must name state files only, each once, and
+ /// `files` must hold the disk image, `SEPStorage` and `nvram.bin`: a revert
+ /// that put back the disk alone would pair it with the live `SEPStorage`.
+ private static func requireValidFileLists(of snapshot: VPhoneMachineSnapshot, bundle: VPhoneBundle) throws {
+ func damaged(_ reason: String) -> VPhoneMachineSnapshotError {
+ .damaged(name: snapshot.name, reason: reason)
+ }
+ let required = VPhoneBundleActivity.stateFileNames(of: bundle)
+ let known = Set(required + optionalStateFileNames)
+ let listed = snapshot.files + snapshot.absentFiles
+ if let unknown = listed.first(where: { !known.contains($0) }) {
+ throw damaged("it names '\(unknown)', which is not a state file")
+ }
+ if let missing = required.first(where: { !snapshot.files.contains($0) }) {
+ throw damaged("it does not hold \(missing), which must be restored with the other state files")
+ }
+ if let both = snapshot.files.first(where: { snapshot.absentFiles.contains($0) }) {
+ throw damaged("it lists \(both) as both captured and absent")
+ }
+ if Set(listed).count != listed.count {
+ throw damaged("it lists a state file more than once")
}
}
@@ -343,6 +415,8 @@ public enum VPhoneMachineSnapshotError: Error, Equatable {
case notCloneable(path: String)
case damaged(name: String, reason: String)
case failed(path: String, reason: String)
+ /// A revert failed partway and some live files could not be put back.
+ case revertIncomplete(machine: String, reason: String, files: [String])
}
extension VPhoneMachineSnapshotError: CustomStringConvertible, LocalizedError {
@@ -362,6 +436,10 @@ extension VPhoneMachineSnapshotError: CustomStringConvertible, LocalizedError {
"Snapshot '\(name)' is damaged: \(reason). Delete it."
case let .failed(path, reason):
"Snapshot operation failed at \(path): \(reason)."
+ case let .revertIncomplete(machine, reason, files):
+ "Reverting VM '\(machine)' failed (\(reason)), and its previous "
+ + "\(files.joined(separator: ", ")) could not be put back. Its state files may be "
+ + "inconsistent: revert to a snapshot again before starting it."
}
}
diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/BundleSnapshotsTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/BundleSnapshotsTests.swift
index e789760d..5244d47f 100644
--- a/VPhoneKit/VPhoneCoreKitTests/Bundle/BundleSnapshotsTests.swift
+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/BundleSnapshotsTests.swift
@@ -38,6 +38,28 @@ struct BundleSnapshotsTests {
VPhoneMachineSnapshots.directory(of: bundle).appendingPathComponent(name)
}
+ /// Every visible file in the machine folder, by name.
+ private func liveFiles(of bundle: VPhoneBundle) throws -> [String: Data] {
+ var files: [String: Data] = [:]
+ for name in try FileManager.default.contentsOfDirectory(atPath: bundle.url.path) where !name.hasPrefix(".") {
+ let url = bundle.url.appendingPathComponent(name)
+ if VPhoneVirtualMachineManifest.fileKind(at: url) == .regularFile {
+ files[name] = try Data(contentsOf: url)
+ }
+ }
+ return files
+ }
+
+ /// Rewrites a snapshot's `Snapshot.plist` as a hand edit would.
+ private func editMetadata(of name: String, in bundle: VPhoneBundle, _ edit: (inout [String: Any]) -> Void) throws {
+ let url = snapshotDirectory(name, of: bundle).appendingPathComponent(VPhoneMachineSnapshots.metadataFileName)
+ var plist = try #require(
+ PropertyListSerialization.propertyList(from: Data(contentsOf: url), format: nil) as? [String: Any],
+ )
+ edit(&plist)
+ try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0).write(to: url)
+ }
+
// MARK: - Create
@Test func `create clones every present state file byte for byte`() throws {
@@ -192,6 +214,92 @@ struct BundleSnapshotsTests {
#expect(hidden.isEmpty)
}
+ @Test func `revert refuses metadata that does not list the state files exactly`() throws {
+ let (root, bundle) = try makeBundle()
+ defer { try? FileManager.default.removeItem(at: root) }
+ try VPhoneMachineSnapshots.create("edited", of: bundle)
+ let full = ["Disk.img", "SEPStorage", "nvram.bin", "PatchReceipt.plist"]
+ let cases: [(files: [String], absent: [String])] = [
+ // The disk without its SEPStorage and NVRAM.
+ (["Disk.img"], ["restore-info.json"]),
+ (full.filter { $0 != "nvram.bin" }, ["restore-info.json", "nvram.bin"]),
+ // Files that are not state files.
+ (full + ["launchpad.json"], ["restore-info.json"]),
+ (full + ["config.plist"], ["restore-info.json"]),
+ (full, ["restore-info.json", "launchpad.json"]),
+ (full, ["restore-info.json", "../Disk.img"]),
+ // Overlapping or repeated.
+ (full, ["restore-info.json", "Disk.img"]),
+ (full, ["restore-info.json", "PatchReceipt.plist"]),
+ (full + ["Disk.img"], ["restore-info.json"]),
+ (full, ["restore-info.json", "restore-info.json"]),
+ ]
+
+ // The live set differs from the snapshot, and Launchpad has its binding.
+ try write([5, 5], to: "Disk.img", in: bundle)
+ try write([6, 6], to: "SEPStorage", in: bundle)
+ try write([7, 7], to: "nvram.bin", in: bundle)
+ try write(Array("{}".utf8), to: "restore-info.json", in: bundle)
+ try write(Array("{}".utf8), to: "launchpad.json", in: bundle)
+ let before = try liveFiles(of: bundle)
+
+ for (files, absent) in cases {
+ try editMetadata(of: "edited", in: bundle) {
+ $0["Files"] = files
+ $0["AbsentFiles"] = absent
+ }
+ do {
+ try VPhoneMachineSnapshots.revert(to: "edited", of: bundle)
+ Issue.record("revert accepted Files \(files), AbsentFiles \(absent)")
+ } catch let VPhoneMachineSnapshotError.damaged(name, _) {
+ #expect(name == "edited")
+ }
+ #expect(try liveFiles(of: bundle) == before, "Files \(files), AbsentFiles \(absent)")
+ }
+ let hidden = try FileManager.default.contentsOfDirectory(atPath: bundle.url.path).filter { $0.hasPrefix(".") }
+ #expect(hidden.isEmpty)
+ }
+
+ /// The swap moves each live file aside, then puts the snapshot's in its
+ /// place. An immutable live file cannot be moved, so the swap fails there:
+ /// at `nvram.bin` after the disk and SEPStorage were replaced, or at
+ /// `restore-info.json`, the file the snapshot records as absent, after
+ /// every captured file was.
+ @Test(arguments: ["nvram.bin", "restore-info.json"])
+ func `a revert that fails partway puts every live file back`(blocked: String) throws {
+ let (root, bundle) = try makeBundle()
+ defer { try? FileManager.default.removeItem(at: root) }
+ try VPhoneMachineSnapshots.create("before", of: bundle)
+
+ try write([9, 9, 9, 9], to: "Disk.img", in: bundle)
+ try write([8, 8], to: "SEPStorage", in: bundle)
+ try write([7], to: "nvram.bin", in: bundle)
+ try write(Array("receipt-2".utf8), to: "PatchReceipt.plist", in: bundle)
+ try write(Array("{}".utf8), to: "restore-info.json", in: bundle)
+ let before = try liveFiles(of: bundle)
+
+ let blockedPath = bundle.url.appendingPathComponent(blocked).path
+ #expect(chflags(blockedPath, UInt32(UF_IMMUTABLE)) == 0)
+ defer { chflags(blockedPath, 0) }
+
+ do {
+ try VPhoneMachineSnapshots.revert(to: "before", of: bundle)
+ Issue.record("revert succeeded with \(blocked) immutable")
+ } catch let VPhoneMachineSnapshotError.failed(path, _) {
+ #expect(path == blockedPath)
+ }
+ #expect(try liveFiles(of: bundle) == before)
+ let hidden = try FileManager.default.contentsOfDirectory(atPath: bundle.url.path).filter { $0.hasPrefix(".") }
+ #expect(hidden.isEmpty)
+
+ // Nothing was lost: with the file unblocked the revert goes through.
+ chflags(blockedPath, 0)
+ try VPhoneMachineSnapshots.revert(to: "before", of: bundle)
+ #expect(try read("Disk.img", in: bundle.url) == Data([1, 2, 3]))
+ #expect(try read("nvram.bin", in: bundle.url) == Data([7, 8, 9]))
+ #expect(!FileManager.default.fileExists(atPath: bundle.url.appendingPathComponent("restore-info.json").path))
+ }
+
@Test func `unknown snapshots are reported`() throws {
let (root, bundle) = try makeBundle()
defer { try? FileManager.default.removeItem(at: root) }