Run a virtual iPhone on an Apple Silicon Mac.
Swift
import Darwin
import Foundation
// MARK: - Build steps
/// What was done to a template's guest after `cfw install` and before it was
/// frozen. Each later stage records its own work here while the template is
/// still being built (see ``VPhoneMachineTemplates/recordSteps(inBundle:_:)``):
/// the offline trim after the CFW install sets `trimTier`, the setup boot sets
/// the rest. A template is frozen only when these match what its key promises.
public struct VPhoneMachineTemplateSteps: Codable, Equatable, Sendable {
/// The guest's `orig-fs` APFS snapshot was deleted, so trimmed files free
/// their space. Not part of the key: it changes what the template costs,
/// not what a clone gets.
public var snapshotDeleted: Bool
/// The setup boot finished: Setup skipped, first-boot work settled, shut
/// down cleanly.
public var setupDone: Bool
public var serviceProfile: String
public var serviceGroups: [String]
public var removedApps: [String]
public var trimTier: String
/// The removed apps vphoned had to unregister more than once, with the
/// number of attempts. Not part of the key: a record of how the setup
/// boot went, kept so the race with first-boot registration can be
/// counted afterwards.
public var unregisterAttempts: [String: Int]
public init(
snapshotDeleted: Bool = false,
setupDone: Bool = false,
serviceProfile: String = "none",
serviceGroups: [String] = [],
removedApps: [String] = [],
trimTier: String = "none",
unregisterAttempts: [String: Int] = [:],
) {
self.snapshotDeleted = snapshotDeleted
self.setupDone = setupDone
self.serviceProfile = serviceProfile
self.serviceGroups = Array(Set(serviceGroups)).sorted()
self.removedApps = Array(Set(removedApps)).sorted()
self.trimTier = trimTier
self.unregisterAttempts = unregisterAttempts
}
/// Why a template with these steps must not be frozen, or nothing.
///
/// A trim with the `orig-fs` snapshot still in place is refused rather
/// than warned about: the snapshot keeps every deleted block, so such a
/// template costs exactly what an untrimmed one does while its clones
/// have lost the files, and its key would promise savings it never made.
/// Refusing keeps every frozen template either trimmed and smaller, or
/// untrimmed and whole.
public var problems: [String] {
var problems: [String] = []
if trimTier != "none", !snapshotDeleted {
problems.append(
"trim \(trimTier) frees nothing while the guest's orig-fs snapshot exists; "
+ "the setup boot deletes it (apfs.snapshot.delete)",
)
}
return problems
}
/// The slimming these steps produced, as a key states it.
public var slimming: VPhoneMachineTemplateSlimming {
VPhoneMachineTemplateSlimming(
trimTier: trimTier,
setupBoot: setupDone,
serviceProfile: serviceProfile,
serviceGroups: serviceGroups,
removedApps: removedApps,
)
}
private enum CodingKeys: String, CodingKey {
case snapshotDeleted = "SnapshotDeleted"
case setupDone = "SetupDone"
case serviceProfile = "ServiceProfile"
case serviceGroups = "ServiceGroups"
case removedApps = "RemovedApps"
case trimTier = "TrimTier"
case unregisterAttempts = "UnregisterAttempts"
}
public init(from decoder: any Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
snapshotDeleted = try container.decodeIfPresent(Bool.self, forKey: .snapshotDeleted) ?? false
setupDone = try container.decodeIfPresent(Bool.self, forKey: .setupDone) ?? false
serviceProfile = try container.decodeIfPresent(String.self, forKey: .serviceProfile) ?? "none"
serviceGroups = try container.decodeIfPresent([String].self, forKey: .serviceGroups) ?? []
removedApps = try container.decodeIfPresent([String].self, forKey: .removedApps) ?? []
trimTier = try container.decodeIfPresent(String.self, forKey: .trimTier) ?? "none"
unregisterAttempts = try container.decodeIfPresent([String: Int].self, forKey: .unregisterAttempts) ?? [:]
}
}
// MARK: - Source
/// `TemplateSource.plist`, in a machine cloned from a template: which
/// template it shares blocks with.
///
/// The identifier names a key, and a key outlives any one template built for
/// it: a template deleted and built again gets the same identifier, but the
/// new one shares no block with machines cloned from the old one. `Build`
/// names the build, so only machines of the template that exists now count
/// as its users.
public struct VPhoneMachineTemplateSource: Codable, Equatable, Sendable {
public var identifier: String
/// The ``VPhoneMachineTemplateRecord/build`` of the template it was cloned
/// from; nil in a record written before builds had one, or for a
/// template without one.
public var build: String?
public var cloned: Date
public init(identifier: String, build: String? = nil, cloned: Date = Date()) {
self.identifier = identifier
self.build = build
self.cloned = VPhoneMachineTemplates.wholeSeconds(cloned)
}
/// Whether a machine with this record was cloned from the template
/// `record` describes, and not from an earlier one with the same key.
/// Both sides having a build decides it. Otherwise (a record written
/// before builds were recorded, on either side) the dates do: a machine
/// cloned before the template was frozen cannot have come from it.
public func isClone(of record: VPhoneMachineTemplateRecord) -> Bool {
guard identifier == record.identifier else { return false }
if let build, let other = record.build {
return build == other
}
return cloned >= (record.frozenAt ?? record.created)
}
private enum CodingKeys: String, CodingKey {
case identifier = "Identifier"
case build = "Build"
case cloned = "Cloned"
}
}
/// How a machine's ``VPhoneMachineTemplateSource`` stands to the template
/// that has its identifier in the library now. `vm list --json` and `vm info
/// --json` report it as `templateMatch`, and Launchpad's inspector shows it
/// from there, so the match is decided only here
/// (``VPhoneMachineTemplateSource/isClone(of:)``).
public enum VPhoneMachineTemplateMatch: String, Codable, Equatable, Sendable {
/// Cloned from the template that has the identifier now.
case current
/// Cloned from an earlier build with the same key, since deleted.
case earlierBuild
/// No template has the identifier now (or its record cannot be read, so
/// `vm template list` does not list it).
case deleted
}
// MARK: - Sources
/// The IPSW sources a template was built from, as the create named them: a
/// URL or a local path for each. `vm template find` matches a request
/// against them, so a create finds its template after the IPSWs it came
/// from were deleted, without downloading them again to read their builds.
public struct VPhoneMachineTemplateSources: Codable, Equatable, Sendable {
public var iPhone: String
public var cloudOS: String
public init(iPhone: String, cloudOS: String) {
self.iPhone = iPhone
self.cloudOS = cloudOS
}
private enum CodingKeys: String, CodingKey {
case iPhone = "IPhone"
case cloudOS = "CloudOS"
}
}
/// The guest device and the two OS builds a request's key starts from, and
/// where they came from.
public struct VPhoneMachineTemplateBuilds: Equatable, Sendable {
public enum Origin: String, Sendable {
/// Read from the IPSWs: local files, or remote ones already cached.
case ipsw
/// Taken from the key of a template whose record names the same two
/// sources (``VPhoneMachineTemplates/templates(builtFrom:device:in:)``).
case template
}
public var device: String
public var ios: VPhoneRestoreInfo.OSVersion
public var cloudOS: VPhoneRestoreInfo.OSVersion
public var origin: Origin
/// The template the builds were taken from, for ``Origin/template``.
public var template: String?
public init(
device: String,
ios: VPhoneRestoreInfo.OSVersion,
cloudOS: VPhoneRestoreInfo.OSVersion,
origin: Origin,
template: String? = nil,
) {
self.device = device
self.ios = ios
self.cloudOS = cloudOS
self.origin = origin
self.template = template
}
}
// MARK: - Record
/// `Template.plist`, in the template's machine folder.
public struct VPhoneMachineTemplateRecord: Codable, Equatable, Sendable {
public var identifier: String
public var key: VPhoneMachineTemplateKey
public var created: Date
/// The `VPhone.bundle` whose `vphone-cli` built or adopted the template.
public var builtWithBundleVersion: String?
/// The bundle that patched and restored the boot chain, when known.
public var bootChainBundleVersion: String?
/// The machine the template was adopted from, or the machine whose create
/// built it. A clone's `--mdns on` name follows from it to the clone's.
public var sourceMachine: String?
/// Set once the template is complete. A frozen template is never booted.
public var frozen: Bool
public var frozenAt: Date?
public var steps: VPhoneMachineTemplateSteps
/// The IPSWs it was built from, when the build named them; nil for a
/// template adopted without them. Not part of the key: two URLs of the
/// same build make the same template.
public var sources: VPhoneMachineTemplateSources?
/// A UUID set each time a template is frozen or adopted, and copied into
/// each clone's `TemplateSource.plist`. The identifier stays the same
/// when a template is deleted and built again; this does not, so the
/// clones of an earlier build are not counted as the new one's users.
/// Nil for a template frozen before it was recorded.
public var build: String?
public init(
key: VPhoneMachineTemplateKey,
created: Date = Date(),
builtWithBundleVersion: String? = nil,
bootChainBundleVersion: String? = nil,
sourceMachine: String? = nil,
frozen: Bool = false,
frozenAt: Date? = nil,
steps: VPhoneMachineTemplateSteps = VPhoneMachineTemplateSteps(),
sources: VPhoneMachineTemplateSources? = nil,
build: String? = nil,
) {
identifier = key.identifier
self.key = key
self.created = VPhoneMachineTemplates.wholeSeconds(created)
self.builtWithBundleVersion = builtWithBundleVersion
self.bootChainBundleVersion = bootChainBundleVersion
self.sourceMachine = sourceMachine
self.frozen = frozen
self.frozenAt = frozenAt.map(VPhoneMachineTemplates.wholeSeconds)
self.steps = steps
self.sources = sources
self.build = build
}
private enum CodingKeys: String, CodingKey {
case identifier = "Identifier"
case key = "Key"
case created = "Created"
case builtWithBundleVersion = "BuiltWithBundleVersion"
case bootChainBundleVersion = "BootChainBundleVersion"
case sourceMachine = "SourceMachine"
case frozen = "Frozen"
case frozenAt = "FrozenAt"
case steps = "Steps"
case sources = "Sources"
case build = "Build"
}
public init(from decoder: any Decoder) throws {
let container = try decoder.container(keyedBy: CodingKeys.self)
identifier = try container.decode(String.self, forKey: .identifier)
key = try container.decode(VPhoneMachineTemplateKey.self, forKey: .key)
created = try container.decode(Date.self, forKey: .created)
builtWithBundleVersion = try container.decodeIfPresent(String.self, forKey: .builtWithBundleVersion)
bootChainBundleVersion = try container.decodeIfPresent(String.self, forKey: .bootChainBundleVersion)
sourceMachine = try container.decodeIfPresent(String.self, forKey: .sourceMachine)
frozen = try container.decodeIfPresent(Bool.self, forKey: .frozen) ?? false
frozenAt = try container.decodeIfPresent(Date.self, forKey: .frozenAt)
steps = try container.decodeIfPresent(VPhoneMachineTemplateSteps.self, forKey: .steps) ?? VPhoneMachineTemplateSteps()
sources = try container.decodeIfPresent(VPhoneMachineTemplateSources.self, forKey: .sources)
build = try container.decodeIfPresent(String.self, forKey: .build)
}
}
// MARK: - Template
/// A frozen template in `<library>/.templates/<identifier>/`.
public struct VPhoneMachineTemplate: Sendable {
public let url: URL
public let record: VPhoneMachineTemplateRecord
public var identifier: String {
record.identifier
}
public var key: VPhoneMachineTemplateKey {
record.key
}
public func bundle() throws -> VPhoneBundle {
try VPhoneBundle.load(at: url)
}
/// Why a create with the same options would not use this template as it
/// is, or nothing when it is current.
///
/// - Parameters:
/// - currentSeries: This `vphone-cli`'s bundle series. Templates never
/// cross a series: a new series rebuilds them.
/// - freshKey: The key a create with this template's options resolves
/// to now, or nil when it cannot be resolved (an unknown preset).
/// - driftedPatches: Boot-chain patches the plan wants that the
/// template's receipt does not record as live, or the reverse.
public func staleReasons(currentSeries: String?, freshKey: VPhoneMachineTemplateKey?, driftedPatches: [String] = []) -> [String] {
var reasons: [String] = []
if key.formatVersion != VPhoneMachineTemplateKey.currentFormatVersion {
reasons.append("keyed by format \(key.formatVersion); this vphone-cli uses \(VPhoneMachineTemplateKey.currentFormatVersion)")
}
if let currentSeries, currentSeries != key.bundleSeries {
reasons.append("built by bundle series \(key.bundleSeries); this vphone-cli is \(currentSeries)")
}
if let freshKey {
let changed = key.differences(from: freshKey).filter { !$0.hasPrefix("bundle series") && !$0.hasPrefix("key format") }
if !changed.isEmpty {
reasons.append("a create with the same options now resolves differently (\(changed.joined(separator: "; ")))")
}
} else {
reasons.append("its preset \(key.patchPreset) cannot be resolved by this vphone-cli")
}
if !driftedPatches.isEmpty {
reasons.append("boot-chain patches differ from its receipt: \(driftedPatches.joined(separator: ", "))")
}
return reasons
}
}
/// A build folder in `.templates`: `.building-<identifier>-<uuid>`. Its
/// machine folder is inside it, named by the identifier.
public struct VPhoneMachineTemplateStaging: Sendable {
public let name: String
public let url: URL
public let identifier: String?
/// Whether a build holds the identifier's lock now.
public let isActive: Bool
}
public struct VPhoneMachineTemplateListing: Sendable {
public var templates: [VPhoneMachineTemplate] = []
public var staging: [VPhoneMachineTemplateStaging] = []
/// Folders in `.templates` that look like templates but cannot be read.
public var damaged: [VPhoneLibrarySkip] = []
}
// MARK: - Lock
/// `flock` on `.templates/.lock-<identifier>`, held while a template with
/// that key is being built, so a second create of the same key waits for the
/// first instead of restoring a second copy. Released on `release()` or when
/// the process exits.
public final class VPhoneMachineTemplateLock: @unchecked Sendable {
private var descriptor: Int32
fileprivate init(descriptor: Int32) {
self.descriptor = descriptor
}
public func release() {
guard descriptor >= 0 else { return }
flock(descriptor, LOCK_UN)
close(descriptor)
descriptor = -1
}
deinit {
release()
}
}
/// A template being built: the staging folder, and the machine folder in it.
public struct VPhoneMachineTemplateBuild: Sendable {
public let identifier: String
/// `.templates/.building-<identifier>-<uuid>`.
public let stagingURL: URL
public init(identifier: String, stagingURL: URL) {
self.identifier = identifier
self.stagingURL = stagingURL
}
/// The library the machine folder is created in: the staging folder.
public var library: VPhoneLibrary {
VPhoneLibrary(root: stagingURL)
}
/// `<staging>/<identifier>`, the machine folder the build fills.
public var bundleURL: URL {
stagingURL.appendingPathComponent(identifier, isDirectory: true)
}
}
// MARK: - Templates
/// Machine templates: complete, never-booted machines that new machines are
/// cloned from with a new identity, sharing every unchanged block through
/// APFS. They live in `<library>/.templates/<identifier>/`, on the library's
/// volume so clones are `clonefile(2)` copies, in a hidden folder so
/// `vm list` and Launchpad never show them, and under a name `vm launch`
/// cannot resolve.
///
/// A template must never boot once it is frozen: a clone made before such a
/// boot would diverge from it in every block the boot wrote, and every clone
/// made after it would inherit that boot's state. `vphone-vm` and `vm launch`
/// refuse a frozen template.
public enum VPhoneMachineTemplates {
public static let directoryName = ".templates"
public static let recordFileName = "Template.plist"
static let stagingPrefix = ".building-"
static let lockPrefix = ".lock-"
public static func directory(in library: VPhoneLibrary) -> URL {
library.root.appendingPathComponent(directoryName, isDirectory: true)
}
public static func url(of identifier: String, in library: VPhoneLibrary) -> URL {
directory(in: library).appendingPathComponent(identifier, isDirectory: true)
}
// MARK: Records
/// The template record in a machine folder, or nil when there is none.
public static func readRecord(inBundle url: URL) throws -> VPhoneMachineTemplateRecord? {
let file = url.appendingPathComponent(recordFileName)
guard VPhoneVirtualMachineManifest.fileKind(at: file) != .missing else { return nil }
guard VPhoneVirtualMachineManifest.fileKind(at: file) == .regularFile else {
throw VPhoneMachineTemplateError.damaged(name: url.lastPathComponent, reason: "\(recordFileName) is not a regular file")
}
do {
return try PropertyListDecoder().decode(VPhoneMachineTemplateRecord.self, from: Data(contentsOf: file))
} catch {
throw VPhoneMachineTemplateError.damaged(name: url.lastPathComponent, reason: "\(recordFileName) is unreadable")
}
}
/// Atomic: a link at `Template.plist` is replaced, not written through.
public static func writeRecord(_ record: VPhoneMachineTemplateRecord, inBundle url: URL) throws {
let encoder = PropertyListEncoder()
encoder.outputFormat = .xml
let file = url.appendingPathComponent(recordFileName)
try encoder.encode(record).write(to: file, options: .atomic)
try VPhoneHostFilePermissions.makeAccessible(at: file)
}
/// Changes the build steps of a template that is still being built. A
/// frozen template is refused: it is shared by its clones, and nothing
/// may change it.
///
/// A machine without a record (one Launchpad is building in the library
/// before it adopts it) gets the unfrozen record `creating` returns
/// first; without `creating` it is refused.
public static func recordSteps(
inBundle url: URL,
creating: (() throws -> VPhoneMachineTemplateRecord)? = nil,
_ body: (inout VPhoneMachineTemplateSteps) -> Void,
) throws {
var existing = try readRecord(inBundle: url)
if existing == nil, let creating {
existing = try creating()
existing?.frozen = false
existing?.frozenAt = nil
}
guard var record = existing else {
throw VPhoneMachineTemplateError.notBeingBuilt(path: url.path)
}
guard !record.frozen else {
throw VPhoneMachineTemplateError.frozen(identifier: record.identifier)
}
body(&record.steps)
try writeRecord(record, inBundle: url)
}
// MARK: Booting
/// Why the machine at `bundleURL` must not boot, or nil when it may: it
/// is a frozen template, or a folder directly in `.templates`. A machine
/// still being built in a staging folder may boot (the setup boot does).
public static func bootRefusal(bundleURL: URL) -> VPhoneMachineTemplateError? {
let url = bundleURL.absoluteURL.standardizedFileURL
if url.deletingLastPathComponent().lastPathComponent == directoryName {
return .notBootable(identifier: url.lastPathComponent)
}
switch Result(catching: { try readRecord(inBundle: url) }) {
case let .success(record?) where record.frozen:
return .notBootable(identifier: record.identifier)
case .success:
return nil
case .failure:
// A record that cannot be read may be a frozen one.
return .notBootable(identifier: url.lastPathComponent)
}
}
public static func requireBootable(bundleURL: URL) throws {
if let refusal = bootRefusal(bundleURL: bundleURL) {
throw refusal
}
}
// MARK: List
public static func list(in library: VPhoneLibrary) throws -> VPhoneMachineTemplateListing {
let root = directory(in: library)
let fm = FileManager.default
var listing = VPhoneMachineTemplateListing()
guard isDirectory(root) else { return listing }
for name in try fm.contentsOfDirectory(atPath: root.path).sorted() {
let url = root.appendingPathComponent(name, isDirectory: true)
if name.hasPrefix(stagingPrefix), isDirectory(url) {
let identifier = stagingIdentifier(name)
listing.staging.append(VPhoneMachineTemplateStaging(
name: name,
url: url,
identifier: identifier,
isActive: identifier.map { isLocked($0, in: library) } ?? false,
))
continue
}
guard !name.hasPrefix("."), isDirectory(url) else { continue }
do {
try listing.templates.append(load(url))
} catch {
listing.damaged.append(VPhoneLibrarySkip(name: name, reason: "\(error)"))
}
}
listing.templates.sort { ($0.record.created, $0.identifier) < ($1.record.created, $1.identifier) }
return listing
}
/// The frozen template with this identifier, or with this unique prefix
/// of one (at least four digits).
public static func template(_ identifier: String, in library: VPhoneLibrary) throws -> VPhoneMachineTemplate {
if VPhoneMachineTemplateKey.isIdentifier(identifier) {
let url = url(of: identifier, in: library)
guard isDirectory(url) else { throw VPhoneMachineTemplateError.notFound(identifier) }
return try load(url)
}
let lowered = identifier.lowercased()
guard lowered.count >= 4, lowered.count < VPhoneMachineTemplateKey.identifierLength,
lowered.utf8.allSatisfy({ ($0 >= 0x30 && $0 <= 0x39) || ($0 >= 0x61 && $0 <= 0x66) })
else {
throw VPhoneMachineTemplateError.invalidIdentifier(identifier)
}
let matches = try list(in: library).templates.filter { $0.identifier.hasPrefix(lowered) }
guard let only = matches.first else { throw VPhoneMachineTemplateError.notFound(identifier) }
guard matches.count == 1 else {
throw VPhoneMachineTemplateError.ambiguous(identifier, matches: matches.map(\.identifier))
}
return only
}
/// The frozen templates whose record says they were built from these two
/// sources, newest first. Their keys give the builds those sources hold,
/// so a request can be keyed without the IPSWs, which may have been
/// deleted since. A template for another `device` is left out when one
/// is named.
public static func templates(
builtFrom sources: VPhoneMachineTemplateSources,
device: String? = nil,
in library: VPhoneLibrary,
) -> [VPhoneMachineTemplate] {
let templates = (try? list(in: library).templates) ?? []
return templates
.filter { $0.record.sources == sources && (device == nil || $0.key.device == device) }
.sorted { $0.record.created > $1.record.created }
}
/// Why ``resolveBuilds(sources:device:in:local:)`` found nothing.
public static let unresolvedBuildsReason = "the IPSWs are not downloaded and no template records these sources"
/// The builds a request names, without downloading anything: first
/// `local`, which reads the two IPSWs when both are local files or in
/// the IPSW cache and returns nil otherwise (a local path that no longer
/// exists included); then the newest template recorded with the same
/// two sources (and `device`, when one is named). Nil when neither has
/// them: only a download would tell. `vm template find` and `vm create`
/// both resolve this way, so a create clones the template find reports
/// and downloads only for a build.
public static func resolveBuilds(
sources: VPhoneMachineTemplateSources,
device: String?,
in library: VPhoneLibrary,
local: () throws -> VPhoneMachineTemplateBuilds?,
) throws -> VPhoneMachineTemplateBuilds? {
if let builds = try local() {
return builds
}
guard let template = templates(builtFrom: sources, device: device, in: library).first else {
return nil
}
let key = template.key
return VPhoneMachineTemplateBuilds(
device: key.device,
ios: .init(version: key.iOSVersion, build: key.iOSBuild),
cloudOS: .init(version: key.cloudOSVersion, build: key.cloudOSBuild),
origin: .template,
template: template.identifier,
)
}
/// The template whose key this is, if one is frozen.
public static func template(for key: VPhoneMachineTemplateKey, in library: VPhoneLibrary) throws -> VPhoneMachineTemplate? {
let url = url(of: key.identifier, in: library)
guard isDirectory(url) else { return nil }
return try load(url)
}
/// Reads a template folder and checks it is what its name says: a frozen
/// record whose key hashes to the folder's name, and a loadable machine.
static func load(_ url: URL) throws -> VPhoneMachineTemplate {
let name = url.lastPathComponent
guard VPhoneMachineTemplateKey.isIdentifier(name) else {
throw VPhoneMachineTemplateError.damaged(name: name, reason: "the folder name is not a template identifier")
}
guard let record = try readRecord(inBundle: url) else {
throw VPhoneMachineTemplateError.damaged(name: name, reason: "it has no \(recordFileName)")
}
guard record.frozen else {
throw VPhoneMachineTemplateError.damaged(name: name, reason: "it was never frozen")
}
guard record.identifier == name, record.key.identifier == name else {
throw VPhoneMachineTemplateError.damaged(name: name, reason: "its key does not match its folder name")
}
_ = try VPhoneBundle.load(at: url)
return VPhoneMachineTemplate(url: url, record: record)
}
// MARK: Lock
/// Takes the build lock for `identifier`. `wait: false` throws
/// `.busy` when another build holds it.
public static func lock(_ identifier: String, in library: VPhoneLibrary, wait: Bool) throws -> VPhoneMachineTemplateLock {
guard VPhoneMachineTemplateKey.isIdentifier(identifier) else {
throw VPhoneMachineTemplateError.invalidIdentifier(identifier)
}
try ensureDirectory(in: library)
let path = directory(in: library).appendingPathComponent(lockPrefix + identifier).path
let fd = open(path, O_RDWR | O_CREAT | O_NOFOLLOW | O_CLOEXEC, 0o666)
guard fd >= 0 else {
throw VPhoneMachineTemplateError.failed(path: path, reason: String(cString: strerror(errno)))
}
fchmod(fd, 0o777)
if flock(fd, LOCK_EX | (wait ? 0 : LOCK_NB)) != 0 {
let code = errno
close(fd)
if code == EWOULDBLOCK {
throw VPhoneMachineTemplateError.busy(identifier: identifier)
}
throw VPhoneMachineTemplateError.failed(path: path, reason: String(cString: strerror(code)))
}
return VPhoneMachineTemplateLock(descriptor: fd)
}
static func isLocked(_ identifier: String, in library: VPhoneLibrary) -> Bool {
let path = directory(in: library).appendingPathComponent(lockPrefix + identifier).path
let fd = open(path, O_RDONLY | O_NOFOLLOW | O_CLOEXEC)
guard fd >= 0 else { return false }
defer { close(fd) }
if flock(fd, LOCK_EX | LOCK_NB) == 0 {
flock(fd, LOCK_UN)
return false
}
return errno == EWOULDBLOCK
}
// MARK: Build
/// Makes the staging folder a template with `key` is built in. The caller
/// holds the key's lock, creates the machine in `build.library` named by
/// the identifier, writes an unfrozen record into it, fills it, and ends
/// with ``freeze(_:record:now:)`` or ``abandon(_:)``.
public static func beginBuild(_ key: VPhoneMachineTemplateKey, in library: VPhoneLibrary) throws -> VPhoneMachineTemplateBuild {
try ensureDirectory(in: library)
let identifier = key.identifier
if isDirectory(url(of: identifier, in: library)) {
throw VPhoneMachineTemplateError.alreadyExists(identifier)
}
let staging = directory(in: library)
.appendingPathComponent("\(stagingPrefix)\(identifier)-\(UUID().uuidString)", isDirectory: true)
try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: false)
try VPhoneHostFilePermissions.makeDirectoryAccessible(at: staging)
return VPhoneMachineTemplateBuild(identifier: identifier, stagingURL: staging)
}
/// Marks the built machine frozen and moves it to `.templates/<identifier>`
/// in one rename, so a listed template is always complete. Refused when
/// its steps did not produce what its key promises or left a trim without
/// its snapshot deletion (``VPhoneMachineTemplateSteps/problems``), or a
/// template with the identifier appeared meanwhile; the build is then
/// left in place. The restore tree is removed: templates never keep it.
@discardableResult
public static func freeze(_ build: VPhoneMachineTemplateBuild, now: Date = Date()) throws -> VPhoneMachineTemplate {
guard var record = try readRecord(inBundle: build.bundleURL) else {
throw VPhoneMachineTemplateError.notBeingBuilt(path: build.bundleURL.path)
}
guard record.identifier == build.identifier, record.key.identifier == build.identifier else {
throw VPhoneMachineTemplateError.damaged(name: build.identifier, reason: "its record names another key")
}
guard record.steps.slimming == record.key.slimming else {
throw VPhoneMachineTemplateError.stepsDoNotMatchKey(
identifier: build.identifier,
differences: record.key.slimmingDifferences(from: record.steps.slimming),
)
}
guard record.steps.problems.isEmpty else {
throw VPhoneMachineTemplateError.incomplete(identifier: build.identifier, problems: record.steps.problems)
}
let bundle = try VPhoneBundle.load(at: build.bundleURL)
try VPhoneBundleActivity.requireStopped(bundle)
try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
record.build = UUID().uuidString
try writeRecord(record, inBundle: build.bundleURL)
let destination = url(of: build.identifier, in: build.libraryRoot)
do {
try removeIfPresent(build.bundleURL.appendingPathComponent("vphone.sock"))
try renameExclusive(build.bundleURL, to: destination, identifier: build.identifier)
} catch {
record.frozen = false
record.frozenAt = nil
record.build = nil
try? writeRecord(record, inBundle: build.bundleURL)
throw error
}
rmdir(build.stagingURL.path)
try VPhoneHostFilePermissions.makeDirectoryAccessible(at: destination)
return VPhoneMachineTemplate(url: destination, record: record)
}
/// Removes a build's staging folder and everything in it.
public static func abandon(_ build: VPhoneMachineTemplateBuild) throws {
try FileManager.default.removeItem(at: build.stagingURL)
}
// MARK: Adopt
/// Freezes a stopped machine of the library into the template `record`
/// describes: writes the frozen record into its folder and renames the
/// folder to `.templates/<identifier>`. The machine is gone from the
/// library afterwards.
///
/// Refused when the machine runs, has snapshots (a template carries no
/// history, and they would keep their blocks for as long as it lives),
/// its steps fall short of the key or have problems, or a template with
/// that key exists. On a failure the machine is left as it was, except
/// that a restore tree it kept is removed before the rename: templates
/// never keep it.
@discardableResult
public static func adopt(
machineNamed name: String,
in library: VPhoneLibrary,
record proposed: VPhoneMachineTemplateRecord,
now: Date = Date(),
) throws -> VPhoneMachineTemplate {
let bundle = try library.bundle(named: name)
try VPhoneBundleActivity.requireStopped(bundle)
if let snapshots = try? VPhoneMachineSnapshots.list(of: bundle), !snapshots.isEmpty {
throw VPhoneMachineTemplateError.hasSnapshots(machine: name, count: snapshots.count)
}
if isDirectory(VPhoneMachineSnapshots.directory(of: bundle)) {
// Unreadable snapshot folders hold blocks all the same.
let entries = (try? FileManager.default.contentsOfDirectory(atPath: VPhoneMachineSnapshots.directory(of: bundle).path)) ?? []
if !entries.isEmpty {
throw VPhoneMachineTemplateError.hasSnapshots(machine: name, count: entries.count)
}
}
let previous = try readRecord(inBundle: bundle.url)
if let previous, previous.frozen {
throw VPhoneMachineTemplateError.damaged(name: name, reason: "it already carries a frozen \(recordFileName)")
}
var record = proposed
record.identifier = record.key.identifier
guard record.steps.slimming == record.key.slimming else {
throw VPhoneMachineTemplateError.stepsDoNotMatchKey(
identifier: record.identifier,
differences: record.key.slimmingDifferences(from: record.steps.slimming),
)
}
guard record.steps.problems.isEmpty else {
throw VPhoneMachineTemplateError.incomplete(identifier: record.identifier, problems: record.steps.problems)
}
let destination = url(of: record.identifier, in: library)
if isDirectory(destination) {
throw VPhoneMachineTemplateError.alreadyExists(record.identifier)
}
try ensureDirectory(in: library)
// Gone even if the rename below fails: it is only ever rebuilt from
// the IPSW, and a template must not carry it.
try removeRestoreTree(of: bundle)
record.frozen = true
record.frozenAt = Self.wholeSeconds(now)
record.build = UUID().uuidString
try writeRecord(record, inBundle: bundle.url)
do {
// Checked again just before the rename: nothing may have opened
// the machine while the record was written.
try VPhoneBundleActivity.requireStopped(bundle)
try removeIfPresent(bundle.url.appendingPathComponent("vphone.sock"))
try renameExclusive(bundle.url, to: destination, identifier: record.identifier)
} catch {
if let previous {
try? writeRecord(previous, inBundle: bundle.url)
} else {
try? removeIfPresent(bundle.url.appendingPathComponent(recordFileName))
}
throw error
}
try VPhoneHostFilePermissions.makeDirectoryAccessible(at: destination)
return VPhoneMachineTemplate(url: destination, record: record)
}
// MARK: Clone
/// A new machine `newName` in the library, cloned from the template with a
/// new identity: a new ECID, MAC address and UDID on its first start, the
/// template's disk, SEP storage and NVRAM shared block for block until
/// either side writes. The clone is an ordinary machine: it carries no
/// `Template.plist` and boots normally.
@discardableResult
public static func cloneMachine(
from template: VPhoneMachineTemplate,
to newName: String,
in library: VPhoneLibrary,
) throws -> VPhoneBundle {
let source = try template.bundle()
let clone = try VPhoneBundleOperations.clone(
source,
sourceName: template.record.sourceMachine ?? template.identifier,
to: newName,
in: library,
newIdentity: true,
)
do {
try writeSource(
VPhoneMachineTemplateSource(identifier: template.identifier, build: template.record.build),
inBundle: clone.url,
)
} catch {
try? FileManager.default.removeItem(at: clone.url)
throw error
}
return clone
}
// MARK: Source
/// `TemplateSource.plist`, in a machine cloned from a template. A plain
/// `vm clone` of such a machine keeps it (the copy shares the template's
/// blocks too); an export leaves it out, since an imported machine
/// shares nothing with any template.
public static let sourceFileName = "TemplateSource.plist"
/// The template a machine was cloned from, or nil for a machine that was
/// not, or whose record cannot be read.
public static func readSource(inBundle url: URL) -> VPhoneMachineTemplateSource? {
let file = url.appendingPathComponent(sourceFileName)
guard VPhoneVirtualMachineManifest.fileKind(at: file) == .regularFile,
let data = try? Data(contentsOf: file),
let source = try? PropertyListDecoder().decode(VPhoneMachineTemplateSource.self, from: data),
VPhoneMachineTemplateKey.isIdentifier(source.identifier)
else { return nil }
return source
}
/// Whether the template `source` names is still in `library` and is the
/// build the machine was cloned from.
public static func match(of source: VPhoneMachineTemplateSource, in library: VPhoneLibrary) -> VPhoneMachineTemplateMatch {
guard let template = try? template(source.identifier, in: library) else { return .deleted }
return source.isClone(of: template.record) ? .current : .earlierBuild
}
static func writeSource(_ source: VPhoneMachineTemplateSource, inBundle url: URL) throws {
let encoder = PropertyListEncoder()
encoder.outputFormat = .xml
let file = url.appendingPathComponent(sourceFileName)
try encoder.encode(source).write(to: file, options: .atomic)
try VPhoneHostFilePermissions.makeAccessible(at: file)
}
/// The machines of the library cloned from each template, by template
/// identifier, sorted by name. Templates adopted from such a machine
/// count too, under `.templates/<id>`: they share its blocks as well.
///
/// A machine counts only for the template it was cloned from
/// (``VPhoneMachineTemplateSource/isClone(of:)``): one cloned from an
/// earlier template with the same key, since deleted and built again,
/// shares nothing with the template that exists now and is left out. A
/// machine whose template no longer exists is listed under its identifier.
public static func usage(in library: VPhoneLibrary) -> [String: [String]] {
let templates = (try? list(in: library).templates) ?? []
var records: [String: VPhoneMachineTemplateRecord] = [:]
for template in templates {
records[template.identifier] = template.record
}
var users: [String: [String]] = [:]
func count(_ source: VPhoneMachineTemplateSource, as user: String) {
if let record = records[source.identifier], !source.isClone(of: record) {
return
}
users[source.identifier, default: []].append(user)
}
for bundle in (try? library.bundles()) ?? [] {
if let source = readSource(inBundle: bundle.url) {
count(source, as: bundle.name)
}
}
for template in templates {
if let source = readSource(inBundle: template.url), source.identifier != template.identifier {
count(source, as: "\(directoryName)/\(template.identifier)")
}
}
return users.mapValues { $0.sorted() }
}
/// The template `source` names, when it still exists, the deleted machine
/// was cloned from it (not from an earlier template with the same key),
/// and nothing in the library uses it any more: what `vm delete` reports
/// after deleting a machine cloned from it. Never deletes it.
public static func unusedTemplate(after source: VPhoneMachineTemplateSource?, in library: VPhoneLibrary) -> VPhoneMachineTemplate? {
guard let source,
let template = try? Self.template(source.identifier, in: library),
source.isClone(of: template.record),
usage(in: library)[template.identifier, default: []].isEmpty
else { return nil }
return template
}
/// The bytes a folder's files take on disk (`st_blocks`), without
/// following links: what deleting it would free once nothing shares it.
public static func allocatedBytes(of url: URL) -> UInt64 {
var total: UInt64 = 0
let keys: [URLResourceKey] = [.totalFileAllocatedSizeKey, .isSymbolicLinkKey]
guard let walker = FileManager.default.enumerator(at: url, includingPropertiesForKeys: keys, options: []) else {
return 0
}
for case let file as URL in walker {
guard let values = try? file.resourceValues(forKeys: Set(keys)), values.isSymbolicLink != true else { continue }
total += UInt64(values.totalFileAllocatedSize ?? 0)
}
return total
}
// MARK: Restore tree
/// Templates never keep the restore tree: the ~11 GB of prepared
/// firmware a full `cfw install` reads would stay pinned for as long as
/// the template lives, and no clone can use it. `freeze` and `adopt`
/// remove it. Returns the folder's name, or nil when there was none.
@discardableResult
public static func removeRestoreTree(of bundle: VPhoneBundle) throws -> String? {
try VPhoneRestoreInfo.removeBuiltFirmware(fromBundle: bundle)
}
/// The restore tree's name in a machine folder, or nil.
public static func restoreTree(of bundle: VPhoneBundle) -> String? {
(try? VPhoneConfinedDirectory(root: bundle.url.path)).flatMap(VPhoneRestoreInfo.findRestoreDirectory(in:))
}
// MARK: Delete
/// What `vm template delete` says about the space it freed, from what is
/// known. `machines` is what ``usage(in:)`` listed for the template before
/// it was deleted: the machines that use it now. Machines cloned from it
/// and deleted since are not among them, so the note never claims it was
/// never cloned. With no user its blocks are freed, unless a local Time
/// Machine snapshot taken while it existed keeps them; with users, the
/// blocks they share stay allocated until they change them or are deleted.
public static func deletionNote(machines: [String]) -> String {
guard !machines.isEmpty else {
return "no machine uses it now; deleting frees its blocks "
+ "(a local Time Machine snapshot may keep them until it expires)"
}
return "\(machines.count) machine(s) use it (\(machines.joined(separator: ", "))); "
+ "the blocks they share with it stay allocated until they change them or are deleted"
}
/// Removes a frozen template, by identifier or unique prefix, or a staging
/// folder by its `.building-…` name that no build holds. Returns what was
/// removed. Machines cloned from the template keep working: they share
/// its blocks, they do not refer to it, and the shared blocks are freed
/// only once no clone uses them either.
@discardableResult
public static func delete(_ name: String, in library: VPhoneLibrary) throws -> URL {
if name.hasPrefix(stagingPrefix) {
guard let staging = try list(in: library).staging.first(where: { $0.name == name }) else {
throw VPhoneMachineTemplateError.notFound(name)
}
if staging.isActive {
throw VPhoneMachineTemplateError.busy(identifier: staging.identifier ?? name)
}
try FileManager.default.removeItem(at: staging.url)
return staging.url
}
let url: URL
do {
url = try template(name, in: library).url
} catch VPhoneMachineTemplateError.damaged where VPhoneMachineTemplateKey.isIdentifier(name) {
// A damaged template is deleted all the same, by its full name.
url = self.url(of: name, in: library)
}
// The empty `.lock-<identifier>` file stays: removing a lock file
// another process may be about to open would let two builds hold
// "the" lock on different inodes.
try FileManager.default.removeItem(at: url)
return url
}
// MARK: - Files
/// An XML property list keeps dates to the second; a record returned is
/// the record read back.
static func wholeSeconds(_ date: Date) -> Date {
Date(timeIntervalSince1970: date.timeIntervalSince1970.rounded(.down))
}
static func ensureDirectory(in library: VPhoneLibrary) throws {
let root = directory(in: library)
var info = stat()
if lstat(root.path, &info) == 0 {
guard info.st_mode & S_IFMT == S_IFDIR else {
throw VPhoneMachineTemplateError.failed(path: root.path, reason: "not a directory")
}
return
}
try FileManager.default.createDirectory(at: library.root, withIntermediateDirectories: true)
if mkdir(root.path, 0o777) != 0, errno != EEXIST {
throw VPhoneMachineTemplateError.failed(path: root.path, reason: String(cString: strerror(errno)))
}
try VPhoneHostFilePermissions.makeDirectoryAccessible(at: root)
}
private static func stagingIdentifier(_ name: String) -> String? {
let rest = name.dropFirst(stagingPrefix.count)
let identifier = String(rest.prefix(VPhoneMachineTemplateKey.identifierLength))
return VPhoneMachineTemplateKey.isIdentifier(identifier) ? identifier : nil
}
private static func renameExclusive(_ source: URL, to destination: URL, identifier: String) throws {
guard renamex_np(source.path, destination.path, UInt32(RENAME_EXCL)) == 0 else {
if errno == EEXIST {
throw VPhoneMachineTemplateError.alreadyExists(identifier)
}
throw VPhoneMachineTemplateError.failed(path: destination.path, reason: String(cString: strerror(errno)))
}
}
private static func isDirectory(_ url: URL) -> Bool {
var info = stat()
return lstat(url.path, &info) == 0 && info.st_mode & S_IFMT == S_IFDIR
}
private static func removeIfPresent(_ url: URL) throws {
do {
try FileManager.default.removeItem(at: url)
} catch CocoaError.fileNoSuchFile {
return
}
}
}
extension VPhoneMachineTemplateBuild {
/// The library whose `.templates` holds the staging folder.
var libraryRoot: VPhoneLibrary {
VPhoneLibrary(root: stagingURL.deletingLastPathComponent().deletingLastPathComponent())
}
}
extension VPhoneMachineTemplateKey {
func slimmingDifferences(from done: VPhoneMachineTemplateSlimming) -> [String] {
var copy = self
copy.slimming = done
return differences(from: copy)
}
}
// MARK: - Error
public enum VPhoneMachineTemplateError: Error, Equatable {
case invalidIdentifier(String)
case notFound(String)
case ambiguous(String, matches: [String])
case alreadyExists(String)
case busy(identifier: String)
case damaged(name: String, reason: String)
case notBootable(identifier: String)
case frozen(identifier: String)
case notBeingBuilt(path: String)
case hasSnapshots(machine: String, count: Int)
case stepsDoNotMatchKey(identifier: String, differences: [String])
case incomplete(identifier: String, problems: [String])
case conflicts(identifier: String, options: [String])
case stale(identifier: String, reasons: [String])
case failed(path: String, reason: String)
}
extension VPhoneMachineTemplateError: CustomStringConvertible, LocalizedError {
public var description: String {
switch self {
case let .invalidIdentifier(text):
"'\(text)' is not a template identifier. List them with vm template list."
case let .notFound(text):
"No template '\(text)'. List them with vm template list."
case let .ambiguous(text, matches):
"'\(text)' matches several templates (\(matches.joined(separator: ", "))). Give more of the identifier."
case let .alreadyExists(identifier):
"A template with key \(identifier) already exists. Create machines from it with vm create --template \(identifier), or delete it first with vm template delete \(identifier)."
case let .busy(identifier):
"Template \(identifier) is being built by another process. Wait for it to finish."
case let .damaged(name, reason):
"Template '\(name)' is damaged: \(reason). Delete it with vm template delete."
case let .notBootable(identifier):
"This is machine template \(identifier), which never boots: every machine cloned from it shares its disk. Create a machine from it with vm create <name> --template \(identifier), and boot that."
case let .frozen(identifier):
"Template \(identifier) is frozen and cannot change."
case let .notBeingBuilt(path):
"\(path) is not a template being built: it has no \(VPhoneMachineTemplates.recordFileName)."
case let .hasSnapshots(machine, count):
"VM '\(machine)' has \(count) snapshot(s). A template carries no history: delete them with vm snapshot delete, then adopt it."
case let .stepsDoNotMatchKey(identifier, differences):
"Template \(identifier) was not built as its key says (\(differences.joined(separator: "; "))). It was not frozen."
case let .incomplete(identifier, problems):
"Template \(identifier) is not finished: \(problems.joined(separator: "; ")). It was not frozen."
case let .conflicts(identifier, options):
"Template \(identifier) cannot give this machine what was asked: \(options.joined(separator: "; ")). Use another template, or create the machine without one (--no-template)."
case let .stale(identifier, reasons):
"Template \(identifier) is stale: \(reasons.joined(separator: "; ")). Delete it with vm template delete \(identifier) to build a new one, or pass --no-template."
case let .failed(path, reason):
"Template operation failed at \(path): \(reason)."
}
}
public var errorDescription: String? {
description
}
}