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.mdindex 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 ina `SEPStorage` from another makes the SEP panic on the next boot, so a snapshotalways 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 holdsdiff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swiftindex 08f779a3..9f1cdda6 100644--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineSnapshots.swift@@ -203,6 +203,10 @@ public enum VPhoneMachineSnapshots {encoder.outputFormat = .xmltry 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.@discardableResultpublic 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.swiftindex 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) }