Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
import Testing
@testable import VPhoneCoreKit
/// Templates on disk: adopting a machine, building and freezing one, cloning
/// machines from it, and keeping it from ever booting. The temporary
/// directory is on the boot volume, which is APFS, so clones are real
/// `clonefile` copies.
struct MachineTemplatesTests {
// MARK: - Fixtures
private struct Fixture {
let root: URL
let library: VPhoneLibrary
let rom: URL
func cleanUp() {
try? FileManager.default.removeItem(at: root)
}
}
private func makeFixture() throws -> Fixture {
let fm = FileManager.default
let root = fm.temporaryDirectory.appendingPathComponent(UUID().uuidString)
try fm.createDirectory(at: root, withIntermediateDirectories: true)
let rom = root.appendingPathComponent("rom.bin")
try Data([0xAA]).write(to: rom)
return Fixture(root: root, library: VPhoneLibrary(root: root.appendingPathComponent("machines")), rom: rom)
}
/// A stopped machine with the files a created one has.
@discardableResult
private func makeMachine(_ name: String, in fixture: Fixture, library: VPhoneLibrary? = nil) throws -> VPhoneBundle {
let bundle = try VPhoneBundleOperations.create(
.init(name: name, cpuCount: 4, memoryMB: 4096, diskSizeGB: 1, romSource: fixture.rom, sepromSource: fixture.rom),
in: library ?? fixture.library,
)
try Data([0xD1, 0x5C, 0x00, 0x01]).write(to: bundle.url.appendingPathComponent("Disk.img"))
try Data([0x5E, 0x90]).write(to: bundle.url.appendingPathComponent("SEPStorage"))
try Data([1, 2, 3]).write(to: bundle.url.appendingPathComponent("nvram.bin"))
try Data([4]).write(to: bundle.url.appendingPathComponent("udid-prediction.txt"))
try Data().write(to: bundle.url.appendingPathComponent("vphone.sock"))
let manifest = bundle.manifest.updating(
machineIdentifier: Data([9, 9]),
networkConfig: bundle.manifest.networkConfig.with(
macAddress: "aa:bb:cc:dd:ee:ff",
localHostName: .some(VPhoneNetworking.localHostName(forVMName: name)),
),
)
try manifest.write(to: bundle.configURL)
return VPhoneBundle(url: bundle.url, manifest: manifest)
}
private func record(
_ key: VPhoneMachineTemplateKey = MachineTemplateKeyTests.key(),
source: String? = "src",
steps: VPhoneMachineTemplateSteps = VPhoneMachineTemplateSteps(),
) -> VPhoneMachineTemplateRecord {
VPhoneMachineTemplateRecord(
key: key,
created: Date(timeIntervalSince1970: 1_800_000_000),
builtWithBundleVersion: "2.8.0",
sourceMachine: source,
steps: steps,
)
}
private func exists(_ url: URL) -> Bool {
FileManager.default.fileExists(atPath: url.path)
}
// MARK: - Adopt
@Test func `adopt moves a stopped machine out of the library and freezes it`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let source = try makeMachine("src", in: fixture)
let disk = try Data(contentsOf: source.url.appendingPathComponent("Disk.img"))
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
let key = MachineTemplateKeyTests.key()
#expect(template.identifier == key.identifier)
#expect(template.url == VPhoneMachineTemplates.url(of: key.identifier, in: fixture.library))
#expect(template.record.frozen)
#expect(template.record.frozenAt != nil)
#expect(!exists(source.url))
#expect(try Data(contentsOf: template.url.appendingPathComponent("Disk.img")) == disk)
// The stopped machine's stale socket does not travel.
#expect(!exists(template.url.appendingPathComponent("vphone.sock")))
// Gone from every listing of machines, present in the template listing.
#expect(try fixture.library.bundles().isEmpty)
let listing = try VPhoneMachineTemplates.list(in: fixture.library)
#expect(listing.templates.map(\.identifier) == [key.identifier])
#expect(listing.staging.isEmpty)
#expect(listing.damaged.isEmpty)
#expect(try VPhoneMachineTemplates.readRecord(inBundle: template.url) == template.record)
}
@Test func `adopt refuses a running machine and leaves it in place`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let source = try makeMachine("src", in: fixture)
let fd = open(source.url.appendingPathComponent("Disk.img").path, O_RDONLY)
#expect(fd >= 0)
defer { close(fd) }
#expect(throws: VPhoneBundleActivityError.running(name: "src", pids: [getpid()])) {
try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
}
#expect(exists(source.url))
#expect(!exists(source.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName)))
#expect(try VPhoneMachineTemplates.list(in: fixture.library).templates.isEmpty)
}
@Test func `adopt refuses a key that already has a template`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("one", in: fixture)
let other = try makeMachine("two", in: fixture)
try VPhoneMachineTemplates.adopt(machineNamed: "one", in: fixture.library, record: record())
let identifier = MachineTemplateKeyTests.key().identifier
#expect(throws: VPhoneMachineTemplateError.alreadyExists(identifier)) {
try VPhoneMachineTemplates.adopt(machineNamed: "two", in: fixture.library, record: record())
}
#expect(exists(other.url))
#expect(!exists(other.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName)))
}
@Test func `adopt refuses a machine with snapshots`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let source = try makeMachine("src", in: fixture)
try VPhoneMachineSnapshots.create("clean", of: source)
#expect(throws: VPhoneMachineTemplateError.hasSnapshots(machine: "src", count: 1)) {
try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
}
#expect(exists(source.url))
}
@Test func `adopt refuses steps that do not match the key`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let source = try makeMachine("src", in: fixture)
#expect(throws: VPhoneMachineTemplateError.self) {
try VPhoneMachineTemplates.adopt(
machineNamed: "src",
in: fixture.library,
record: record(steps: .init(trimTier: "standard")),
)
}
#expect(exists(source.url))
}
// MARK: - Build and freeze
@Test func `a build is staged, records its steps, and freezes into place in one rename`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let key = MachineTemplateKeyTests.key(slimming: .init(trimTier: "standard"))
let lock = try VPhoneMachineTemplates.lock(key.identifier, in: fixture.library, wait: false)
defer { lock.release() }
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
#expect(build.stagingURL.lastPathComponent.hasPrefix(".building-\(key.identifier)-"))
#expect(build.bundleURL.path == build.stagingURL.appendingPathComponent(key.identifier).path)
try makeMachine(key.identifier, in: fixture, library: build.library)
try VPhoneMachineTemplates.writeRecord(record(key, source: "phone"), inBundle: build.bundleURL)
// Listed as a build in progress, never as a template or a machine.
var listing = try VPhoneMachineTemplates.list(in: fixture.library)
#expect(listing.templates.isEmpty)
#expect(listing.staging.map(\.name) == [build.stagingURL.lastPathComponent])
#expect(listing.staging.first?.identifier == key.identifier)
#expect(listing.staging.first?.isActive == true)
#expect(try fixture.library.bundles().isEmpty)
// A machine still being built may boot: the setup boot does.
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: build.bundleURL) == nil)
// The key promises trimming that has not happened yet.
#expect(throws: VPhoneMachineTemplateError.self) {
try VPhoneMachineTemplates.freeze(build)
}
#expect(try VPhoneMachineTemplates.readRecord(inBundle: build.bundleURL)?.frozen == false)
try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) { steps in
steps.trimTier = "standard"
steps.snapshotDeleted = true
}
let template = try VPhoneMachineTemplates.freeze(build)
#expect(template.url == VPhoneMachineTemplates.url(of: key.identifier, in: fixture.library))
#expect(template.record.frozen)
#expect(template.record.steps.snapshotDeleted)
#expect(!exists(build.stagingURL))
#expect(!exists(template.url.appendingPathComponent("vphone.sock")))
listing = try VPhoneMachineTemplates.list(in: fixture.library)
#expect(listing.templates.map(\.identifier) == [key.identifier])
#expect(listing.staging.isEmpty)
// Frozen means unchanging.
#expect(throws: VPhoneMachineTemplateError.frozen(identifier: key.identifier)) {
try VPhoneMachineTemplates.recordSteps(inBundle: template.url) { $0.setupDone = true }
}
#expect(throws: VPhoneMachineTemplateError.alreadyExists(key.identifier)) {
try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
}
}
@Test func `freeze refuses when the template appeared meanwhile and leaves the build unfrozen`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let key = MachineTemplateKeyTests.key()
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
try makeMachine(key.identifier, in: fixture, library: build.library)
try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
// Another create won the race.
try makeMachine("other", in: fixture)
try VPhoneMachineTemplates.adopt(machineNamed: "other", in: fixture.library, record: record(key))
#expect(throws: VPhoneMachineTemplateError.alreadyExists(key.identifier)) {
try VPhoneMachineTemplates.freeze(build)
}
#expect(exists(build.bundleURL))
#expect(try VPhoneMachineTemplates.readRecord(inBundle: build.bundleURL)?.frozen == false)
try VPhoneMachineTemplates.abandon(build)
#expect(!exists(build.stagingURL))
}
@Test func `the build lock admits one holder and a leftover build can be deleted once it is released`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let key = MachineTemplateKeyTests.key()
let lock = try VPhoneMachineTemplates.lock(key.identifier, in: fixture.library, wait: false)
#expect(throws: VPhoneMachineTemplateError.busy(identifier: key.identifier)) {
try VPhoneMachineTemplates.lock(key.identifier, in: fixture.library, wait: false)
}
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
let name = build.stagingURL.lastPathComponent
#expect(throws: VPhoneMachineTemplateError.busy(identifier: key.identifier)) {
try VPhoneMachineTemplates.delete(name, in: fixture.library)
}
lock.release()
#expect(try VPhoneMachineTemplates.list(in: fixture.library).staging.first?.isActive == false)
try VPhoneMachineTemplates.delete(name, in: fixture.library)
#expect(!exists(build.stagingURL))
// And the lock can be taken again.
try VPhoneMachineTemplates.lock(key.identifier, in: fixture.library, wait: false).release()
}
// MARK: - Never booting
@Test func `a frozen template refuses to boot, by every route`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: template.url) == .notBootable(identifier: template.identifier))
#expect(throws: VPhoneMachineTemplateError.notBootable(identifier: template.identifier)) {
var boot = VPhoneBootCommand(config: template.url.appendingPathComponent("config.plist"))
try boot.validate()
}
#expect(throws: VPhoneMachineTemplateError.notBootable(identifier: template.identifier)) {
var boot = VPhoneBootCommand(config: template.url.appendingPathComponent("config.plist"), dfu: true)
try boot.validate()
}
// A machine name never reaches into `.templates`.
for name in [".templates/\(template.identifier)", ".templates", "../machines/src"] {
#expect(throws: VPhoneLibraryError.invalidName(name)) {
try fixture.library.bundle(named: name)
}
}
// The same machine copied out by hand still carries its frozen record.
let copy = fixture.library.url(forName: "copy")
try FileManager.default.copyItem(at: template.url, to: copy)
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: copy) == .notBootable(identifier: template.identifier))
}
@Test func `a folder in templates without a record does not boot either, and an ordinary machine does`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("phone", in: fixture)
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: machine.url) == nil)
try VPhoneMachineTemplates.ensureDirectory(in: fixture.library)
let stray = VPhoneMachineTemplates.url(of: "0123456789ab", in: fixture.library)
try FileManager.default.copyItem(at: machine.url, to: stray)
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: stray) == .notBootable(identifier: "0123456789ab"))
// It is listed as damaged and can be deleted.
let listing = try VPhoneMachineTemplates.list(in: fixture.library)
#expect(listing.templates.isEmpty)
#expect(listing.damaged.map(\.name) == ["0123456789ab"])
try VPhoneMachineTemplates.delete("0123456789ab", in: fixture.library)
#expect(!exists(stray))
}
// MARK: - Clone
@Test func `a machine cloned from a template is ordinary, new, and takes config-only settings`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
let templateConfig = try Data(contentsOf: template.url.appendingPathComponent("config.plist"))
let clone = try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone-a", in: fixture.library)
#expect(clone.url == fixture.library.url(forName: "phone-a"))
#expect(try fixture.library.bundles().map(\.name) == ["phone-a"])
// A new identity, and no template record: it boots.
#expect(clone.manifest.machineIdentifier.isEmpty)
#expect(clone.manifest.networkConfig.macAddress.isEmpty)
#expect(!exists(clone.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName)))
#expect(!exists(clone.url.appendingPathComponent("udid-prediction.txt")))
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: clone.url) == nil)
// The mDNS name derived from the machine the template came from follows to the clone.
#expect(clone.manifest.networkConfig.localHostName == VPhoneNetworking.localHostName(forVMName: "phone-a"))
// The state files made by the restore are the template's.
for name in ["Disk.img", "SEPStorage", "nvram.bin"] {
#expect(try Data(contentsOf: clone.url.appendingPathComponent(name))
== Data(contentsOf: template.url.appendingPathComponent(name)), "\(name)")
}
// What `vm create --template` sets afterwards, through `vm config`'s path.
let configured = try VPhoneBundleOperations.updateConfig(
bundleNamed: "phone-a",
in: fixture.library,
cpuCount: 2,
memoryMB: 3072,
networkMode: .tunnel,
unlocksAtStartup: true,
)
#expect(configured.manifest.cpuCount == 2)
#expect(configured.manifest.memorySize == 3072 * 1024 * 1024)
#expect(configured.manifest.networkConfig.mode == .tunnel)
#expect(configured.manifest.unlocksScreenAtStartup)
// The template is untouched.
#expect(try Data(contentsOf: template.url.appendingPathComponent("config.plist")) == templateConfig)
// A second clone beside the first, and both survive the template's deletion.
let second = try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone-b", in: fixture.library)
#expect(throws: VPhoneLibraryError.alreadyExists(name: "phone-b")) {
try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone-b", in: fixture.library)
}
try VPhoneMachineTemplates.delete(template.identifier, in: fixture.library)
#expect(!exists(template.url))
#expect(try fixture.library.bundles().map(\.name) == ["phone-a", "phone-b"])
#expect(try Data(contentsOf: second.url.appendingPathComponent("Disk.img")) == Data([0xD1, 0x5C, 0x00, 0x01]))
}
@Test func `a plain clone of a machine drops a template record`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("src", in: fixture)
try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)
let clone = try VPhoneBundleOperations.clone(bundleNamed: "src", to: "dst", in: fixture.library)
#expect(!exists(clone.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName)))
#expect(clone.manifest.machineIdentifier == Data([9, 9]))
}
@Test func `a cloned template refuses to start while it is held open`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
let fd = open(template.url.appendingPathComponent("SEPStorage").path, O_RDONLY)
#expect(fd >= 0)
defer { close(fd) }
#expect(throws: VPhoneBundleActivityError.running(name: template.identifier, pids: [getpid()])) {
try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone", in: fixture.library)
}
#expect(!exists(fixture.library.url(forName: "phone")))
}
// MARK: - Lookup
@Test func `templates are found by identifier, unique prefix, or key`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("one", in: fixture)
try makeMachine("two", in: fixture)
let first = try VPhoneMachineTemplates.adopt(machineNamed: "one", in: fixture.library, record: record())
let otherKey = MachineTemplateKeyTests.key(disk: 128)
let second = try VPhoneMachineTemplates.adopt(machineNamed: "two", in: fixture.library, record: record(otherKey))
#expect(try VPhoneMachineTemplates.template(first.identifier, in: fixture.library).url == first.url)
#expect(try VPhoneMachineTemplates.template(String(second.identifier.prefix(6)), in: fixture.library).url == second.url)
#expect(try VPhoneMachineTemplates.template(for: otherKey, in: fixture.library)?.url == second.url)
#expect(try VPhoneMachineTemplates.template(for: MachineTemplateKeyTests.key(disk: 32), in: fixture.library) == nil)
#expect(throws: VPhoneMachineTemplateError.notFound("ffffffffffff")) {
try VPhoneMachineTemplates.template("ffffffffffff", in: fixture.library)
}
for bad in ["abc", "../x", ".templates", "0123456789abcdef"] {
#expect(throws: VPhoneMachineTemplateError.invalidIdentifier(bad)) {
try VPhoneMachineTemplates.template(bad, in: fixture.library)
}
}
}
// MARK: - Staleness
@Test func `stale reasons name the series, the resolution and the drift`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let key = MachineTemplateKeyTests.key()
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record(key))
#expect(template.staleReasons(currentSeries: "2.8", freshKey: key).isEmpty)
// A fresh key for another series differs only in the series, which is reported once.
#expect(template.staleReasons(currentSeries: "2.9", freshKey: key).count == 1)
var changed = key
changed.bootChainPlanDigest = "abd"
let reasons = template.staleReasons(currentSeries: "2.8", freshKey: changed, driftedPatches: ["kernel-x"])
#expect(reasons.count == 2)
#expect(reasons[0].contains("boot-chain plan"))
#expect(reasons[1].contains("kernel-x"))
#expect(template.staleReasons(currentSeries: "2.8", freshKey: nil).count == 1)
}
// MARK: - Trim and the snapshot
@Test func `a trim without its snapshot deletion is never frozen or adopted`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let trim = VPhoneSystemTrimSpec.standard.keyValue
let key = MachineTemplateKeyTests.key(slimming: .init(trimTier: trim, setupBoot: true))
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
try makeMachine(key.identifier, in: fixture, library: build.library)
try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) {
$0.trimTier = trim
$0.setupDone = true
}
#expect(VPhoneMachineTemplateSteps(trimTier: trim).problems.count == 1)
#expect(throws: VPhoneMachineTemplateError.self) {
try VPhoneMachineTemplates.freeze(build)
}
#expect(try VPhoneMachineTemplates.readRecord(inBundle: build.bundleURL)?.frozen == false)
try VPhoneMachineTemplates.recordSteps(inBundle: build.bundleURL) { $0.snapshotDeleted = true }
#expect(try VPhoneMachineTemplates.freeze(build).record.steps.trimTier == trim)
// Adopt follows the same rule.
try makeMachine("src", in: fixture)
let adoptKey = MachineTemplateKeyTests.key(bootChain: "other", slimming: .init(trimTier: trim, setupBoot: true))
#expect(throws: VPhoneMachineTemplateError.self) {
try VPhoneMachineTemplates.adopt(
machineNamed: "src",
in: fixture.library,
record: record(adoptKey, steps: .init(setupDone: true, trimTier: trim)),
)
}
#expect(exists(fixture.library.url(forName: "src")))
#expect(VPhoneMachineTemplateSteps(snapshotDeleted: true, trimTier: trim).problems.isEmpty)
#expect(VPhoneMachineTemplateSteps().problems.isEmpty)
}
@Test func `a key asking for a trim needs the setup boot`() {
let trim = VPhoneSystemTrimSpec.standard.keyValue
#expect(VPhoneMachineTemplateSlimming(trimTier: trim).problems.count == 1)
#expect(VPhoneMachineTemplateSlimming(trimTier: trim, setupBoot: true).problems.isEmpty)
#expect(VPhoneMachineTemplateSlimming.none.problems.isEmpty)
}
@Test func `steps can be recorded on a library machine that has no record yet`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("src", in: fixture)
#expect(throws: VPhoneMachineTemplateError.notBeingBuilt(path: machine.url.path)) {
try VPhoneMachineTemplates.recordSteps(inBundle: machine.url) { $0.trimTier = "conservative/1" }
}
var frozen = record()
frozen.frozen = true
try VPhoneMachineTemplates.recordSteps(inBundle: machine.url, creating: { frozen }) { $0.trimTier = "conservative/1" }
let written = try #require(try VPhoneMachineTemplates.readRecord(inBundle: machine.url))
#expect(!written.frozen)
#expect(written.steps.trimTier == "conservative/1")
// It still boots: only a frozen record refuses.
#expect(VPhoneMachineTemplates.bootRefusal(bundleURL: machine.url) == nil)
}
// MARK: - Restore tree
@Test func `a template never keeps the restore tree`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("src", in: fixture)
let tree = machine.url.appendingPathComponent("iPhone17,3_27.0_24A435_Restore")
try FileManager.default.createDirectory(at: tree, withIntermediateDirectories: true)
try Data([1]).write(to: tree.appendingPathComponent("kernelcache"))
#expect(VPhoneMachineTemplates.restoreTree(of: machine) == tree.lastPathComponent)
let adopted = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
#expect(!exists(adopted.url.appendingPathComponent(tree.lastPathComponent)))
#expect(exists(adopted.url.appendingPathComponent("Disk.img")))
let key = MachineTemplateKeyTests.key(bootChain: "built")
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
let built = try makeMachine(key.identifier, in: fixture, library: build.library)
try FileManager.default.createDirectory(at: built.url.appendingPathComponent("iPhone17,3_27.0_24A435_Restore"), withIntermediateDirectories: true)
try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
let frozen = try VPhoneMachineTemplates.freeze(build)
#expect(try VPhoneMachineTemplates.restoreTree(of: frozen.bundle()) == nil)
}
// MARK: - Source and usage
@Test func `clones record their template, plain clones keep it, and the last one leaving is noticed`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
try makeMachine("own", in: fixture)
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
#expect(VPhoneMachineTemplates.readSource(inBundle: template.url) == nil)
let a = try VPhoneMachineTemplates.cloneMachine(from: template, to: "phone-a", in: fixture.library)
#expect(VPhoneMachineTemplates.readSource(inBundle: a.url)?.identifier == template.identifier)
#expect(VPhoneBundleReport(bundle: a).template == template.identifier)
#expect(try VPhoneBundleReport(bundle: fixture.library.bundle(named: "own")).template == nil)
// A plain clone of a clone shares the template's blocks too.
let b = try VPhoneBundleOperations.clone(bundleNamed: "phone-a", to: "phone-b", in: fixture.library, newIdentity: true)
#expect(VPhoneMachineTemplates.readSource(inBundle: b.url)?.identifier == template.identifier)
#expect(VPhoneMachineTemplates.usage(in: fixture.library) == [template.identifier: ["phone-a", "phone-b"]])
// An export leaves it out: an import shares nothing.
#expect(VPhoneBundleOperations.exportExcludePatterns.contains { fnmatch($0, VPhoneMachineTemplates.sourceFileName, 0) == 0 })
// Deleting one of two: still used.
let sourceA = VPhoneMachineTemplates.readSource(inBundle: a.url)
try VPhoneBundleOperations.delete(bundleNamed: "phone-a", in: fixture.library)
#expect(VPhoneMachineTemplates.unusedTemplate(after: sourceA, in: fixture.library) == nil)
// Deleting the last: noticed, and the template is still there.
let sourceB = VPhoneMachineTemplates.readSource(inBundle: b.url)
try VPhoneBundleOperations.delete(bundleNamed: "phone-b", in: fixture.library)
let unused = try #require(VPhoneMachineTemplates.unusedTemplate(after: sourceB, in: fixture.library))
#expect(unused.identifier == template.identifier)
#expect(exists(template.url))
#expect(VPhoneMachineTemplates.allocatedBytes(of: template.url) > 0)
// A machine that was never cloned, or a template already deleted: nothing to say.
#expect(VPhoneMachineTemplates.unusedTemplate(after: nil, in: fixture.library) == nil)
try VPhoneMachineTemplates.delete(template.identifier, in: fixture.library)
#expect(VPhoneMachineTemplates.unusedTemplate(after: sourceB, in: fixture.library) == nil)
}
@Test func `an unreadable or foreign source record is ignored`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("m", in: fixture)
let file = machine.url.appendingPathComponent(VPhoneMachineTemplates.sourceFileName)
try Data("junk".utf8).write(to: file)
#expect(VPhoneMachineTemplates.readSource(inBundle: machine.url) == nil)
try VPhoneMachineTemplates.writeSource(VPhoneMachineTemplateSource(identifier: "../../etc"), inBundle: machine.url)
#expect(VPhoneMachineTemplates.readSource(inBundle: machine.url) == nil)
#expect(VPhoneMachineTemplates.usage(in: fixture.library).isEmpty)
}
// MARK: - Sources
@Test func `a record keeps the IPSW sources it was built from, and an older record has none`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("src", in: fixture)
var built = record()
built.sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/iPhone17,3_27.0_24A435_Restore.ipsw", cloudOS: "/tmp/cloudos.ipsw")
try VPhoneMachineTemplates.writeRecord(built, inBundle: machine.url)
#expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.sources == built.sources)
let plist = try String(contentsOf: machine.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName), encoding: .utf8)
#expect(plist.contains("<key>Sources</key>"))
#expect(plist.contains("<key>IPhone</key>"))
#expect(plist.contains("<key>CloudOS</key>"))
// A record written before sources were kept reads as none.
try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)
#expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.sources == nil)
}
@Test func `templates built from the same sources are found by them, newest first, per device`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/c")
try makeMachine("one", in: fixture)
try makeMachine("two", in: fixture)
try makeMachine("three", in: fixture)
var older = record()
older.sources = sources
let newer = VPhoneMachineTemplateRecord(
key: MachineTemplateKeyTests.key(disk: 128),
created: Date(timeIntervalSince1970: 1_900_000_000),
sourceMachine: "two",
sources: sources,
)
let other = VPhoneMachineTemplateRecord(key: MachineTemplateKeyTests.key(disk: 32), sourceMachine: "three")
let first = try VPhoneMachineTemplates.adopt(machineNamed: "one", in: fixture.library, record: older)
let second = try VPhoneMachineTemplates.adopt(machineNamed: "two", in: fixture.library, record: newer)
try VPhoneMachineTemplates.adopt(machineNamed: "three", in: fixture.library, record: other)
let found = VPhoneMachineTemplates.templates(builtFrom: sources, in: fixture.library)
#expect(found.map(\.identifier) == [second.identifier, first.identifier])
#expect(VPhoneMachineTemplates.templates(builtFrom: sources, device: "iPhone17,3", in: fixture.library).count == 2)
#expect(VPhoneMachineTemplates.templates(builtFrom: sources, device: "iPad16,1", in: fixture.library).isEmpty)
let elsewhere = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/other")
#expect(VPhoneMachineTemplates.templates(builtFrom: elsewhere, in: fixture.library).isEmpty)
}
@Test func `builds come from the IPSWs first, then from a template with the same sources, and never from a download`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let sources = VPhoneMachineTemplateSources(iPhone: "https://example.invalid/a.ipsw", cloudOS: "https://example.invalid/c")
let fromIPSW = VPhoneMachineTemplateBuilds(
device: "iPhone17,3",
ios: .init(version: "27.0.1", build: "24A446"),
cloudOS: .init(version: "26.4", build: "23E5207q"),
origin: .ipsw,
)
// Nothing local, no template: unresolved, so only a build (which
// downloads) can tell; the local reader is asked once.
var looks = 0
let none = try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) {
looks += 1
return nil
}
#expect(none == nil)
#expect(looks == 1)
try makeMachine("src", in: fixture)
var built = record()
built.sources = sources
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: built)
// The IPSWs are here: they win over the template's record.
let local = try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { fromIPSW }
#expect(local == fromIPSW)
// Not here (deleted, or a local path that no longer exists): the
// template recorded with the same sources gives the builds.
let recorded = try #require(try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { nil })
#expect(recorded.origin == .template)
#expect(recorded.template == template.identifier)
#expect(recorded.device == template.key.device)
#expect(recorded.ios == .init(version: template.key.iOSVersion, build: template.key.iOSBuild))
#expect(recorded.cloudOS == .init(version: template.key.cloudOSVersion, build: template.key.cloudOSBuild))
// ...for its device only, and only for the same two sources.
#expect(try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: "iPad16,1", in: fixture.library) { nil } == nil)
let other = VPhoneMachineTemplateSources(iPhone: sources.iPhone, cloudOS: "https://example.invalid/other")
#expect(try VPhoneMachineTemplates.resolveBuilds(sources: other, device: nil, in: fixture.library) { nil } == nil)
// A local reader that fails (an IPSW that is there but unreadable)
// fails the resolution rather than quietly using a template.
struct Unreadable: Error {}
#expect(throws: Unreadable.self) {
try VPhoneMachineTemplates.resolveBuilds(sources: sources, device: nil, in: fixture.library) { throw Unreadable() }
}
}
@Test func `deleting a template says its blocks are freed unless machines use it`() {
let free = VPhoneMachineTemplates.deletionNote(machines: [])
#expect(free.hasPrefix("no machine uses it now; deleting frees its blocks"))
// Never claims it was never cloned, and does not promise free space a
// local Time Machine snapshot may keep.
#expect(!free.contains("cloned"))
#expect(free.contains("Time Machine snapshot"))
let shared = VPhoneMachineTemplates.deletionNote(machines: ["phone-a", "phone-b"])
#expect(shared.hasPrefix("2 machine(s) use it (phone-a, phone-b); "))
#expect(shared.contains("stay allocated until they change them or are deleted"))
}
// MARK: - Builds
@Test func `a template rebuilt with the same key does not count the old build's clones`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let first = try VPhoneMachineTemplates.adopt(
machineNamed: "src", in: fixture.library, record: record(), now: Date(timeIntervalSince1970: 1_800_000_100),
)
let firstBuild = try #require(first.record.build)
let old = try VPhoneMachineTemplates.cloneMachine(from: first, to: "old", in: fixture.library)
#expect(VPhoneMachineTemplates.readSource(inBundle: old.url)?.build == firstBuild)
#expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])
// What `vm list --json` reports as `templateMatch`, and Launchpad shows.
func match(_ machine: VPhoneBundle) -> VPhoneMachineTemplateMatch? {
VPhoneBundleReport(bundle: machine).templateMatch
}
#expect(match(old) == .current)
// Deleted and built again under the same identifier, with a new build.
try VPhoneMachineTemplates.delete(first.identifier, in: fixture.library)
#expect(VPhoneMachineTemplates.usage(in: fixture.library) == [first.identifier: ["old"]])
#expect(match(old) == .deleted)
try makeMachine("src2", in: fixture)
let second = try VPhoneMachineTemplates.adopt(machineNamed: "src2", in: fixture.library, record: record(source: "src2"))
#expect(second.identifier == first.identifier)
#expect(second.record.build != nil && second.record.build != firstBuild)
#expect(VPhoneMachineTemplates.usage(in: fixture.library)[second.identifier] == nil)
let new = try VPhoneMachineTemplates.cloneMachine(from: second, to: "new", in: fixture.library)
#expect(VPhoneMachineTemplates.usage(in: fixture.library) == [second.identifier: ["new"]])
#expect(match(old) == .earlierBuild)
// The spelling Launchpad decodes.
let json = try String(decoding: JSONEncoder().encode(VPhoneBundleReport(bundle: old)), as: UTF8.self)
#expect(json.contains(#""templateMatch":"earlierBuild""#))
#expect(match(new) == .current)
// Deleting the old build's clone says nothing about the new template;
// deleting the new one's last clone does.
let oldSource = VPhoneMachineTemplates.readSource(inBundle: old.url)
try VPhoneBundleOperations.delete(bundleNamed: "old", in: fixture.library)
#expect(VPhoneMachineTemplates.unusedTemplate(after: oldSource, in: fixture.library) == nil)
let newSource = VPhoneMachineTemplates.readSource(inBundle: new.url)
try VPhoneBundleOperations.delete(bundleNamed: "new", in: fixture.library)
#expect(VPhoneMachineTemplates.unusedTemplate(after: newSource, in: fixture.library)?.identifier == second.identifier)
}
@Test func `a clone record without a build is matched by its clone date`() {
let frozenAt = Date(timeIntervalSince1970: 1_800_000_100)
var template = record()
template.frozen = true
template.frozenAt = frozenAt
template.build = UUID().uuidString
let id = template.identifier
// Written before builds were recorded: the date decides.
#expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt).isClone(of: template))
#expect(VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt + 60).isClone(of: template))
#expect(!VPhoneMachineTemplateSource(identifier: id, cloned: frozenAt - 1).isClone(of: template))
// A build on both sides decides, whatever the dates say.
#expect(VPhoneMachineTemplateSource(identifier: id, build: template.build, cloned: frozenAt - 600).isClone(of: template))
#expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: template))
// A template frozen before builds were recorded: the date again.
var legacy = template
legacy.build = nil
#expect(VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt + 60).isClone(of: legacy))
#expect(!VPhoneMachineTemplateSource(identifier: id, build: UUID().uuidString, cloned: frozenAt - 60).isClone(of: legacy))
// Without a freeze date, the creation date.
legacy.frozenAt = nil
#expect(VPhoneMachineTemplateSource(identifier: id, cloned: template.created).isClone(of: legacy))
#expect(!VPhoneMachineTemplateSource(identifier: id, cloned: template.created - 1).isClone(of: legacy))
// Another key never.
#expect(!VPhoneMachineTemplateSource(identifier: "000000000000", build: template.build, cloned: frozenAt).isClone(of: template))
}
@Test func `a legacy clone record of a deleted template is left out by date`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
try makeMachine("src", in: fixture)
let template = try VPhoneMachineTemplates.adopt(machineNamed: "src", in: fixture.library, record: record())
let frozenAt = try #require(template.record.frozenAt)
// Two clones whose records predate builds: one of an earlier template
// with this key, one of this one.
let earlier = try makeMachine("earlier", in: fixture)
try VPhoneMachineTemplates.writeSource(
VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt - 3600), inBundle: earlier.url,
)
let current = try makeMachine("current", in: fixture)
try VPhoneMachineTemplates.writeSource(
VPhoneMachineTemplateSource(identifier: template.identifier, cloned: frozenAt + 1), inBundle: current.url,
)
#expect(VPhoneMachineTemplates.usage(in: fixture.library) == [template.identifier: ["current"]])
#expect(VPhoneBundleReport(bundle: earlier).templateMatch == .earlierBuild)
#expect(VPhoneBundleReport(bundle: current).templateMatch == .current)
}
@Test func `a record without a build reads, and a frozen one gets one`() throws {
let fixture = try makeFixture()
defer { fixture.cleanUp() }
let machine = try makeMachine("src", in: fixture)
// An older record: no Build key at all.
try VPhoneMachineTemplates.writeRecord(record(), inBundle: machine.url)
let raw = try Data(contentsOf: machine.url.appendingPathComponent(VPhoneMachineTemplates.recordFileName))
#expect(!String(decoding: raw, as: UTF8.self).contains("<key>Build</key>"))
#expect(try VPhoneMachineTemplates.readRecord(inBundle: machine.url)?.build == nil)
let source = try PropertyListDecoder().decode(
VPhoneMachineTemplateSource.self,
from: PropertyListSerialization.data(
fromPropertyList: ["Identifier": "52b1fcc75e0c", "Cloned": Date(timeIntervalSince1970: 1_800_000_000)],
format: .xml, options: 0,
),
)
#expect(source.build == nil)
let key = MachineTemplateKeyTests.key(bootChain: "built")
let build = try VPhoneMachineTemplates.beginBuild(key, in: fixture.library)
try makeMachine(key.identifier, in: fixture, library: build.library)
try VPhoneMachineTemplates.writeRecord(record(key), inBundle: build.bundleURL)
let frozen = try VPhoneMachineTemplates.freeze(build)
#expect(frozen.record.build != nil)
#expect(try VPhoneMachineTemplates.template(frozen.identifier, in: fixture.library).record.build == frozen.record.build)
}
}