Run a virtual iPhone on an Apple Silicon Mac.
Swift
Add machine templates and template-backed vm create
Jacky8dbf3878f11d
diff --git a/Documents/Guides/create-and-run.md b/Documents/Guides/create-and-run.mdindex f3a4de91..faa8aeb6 100644--- a/Documents/Guides/create-and-run.md+++ b/Documents/Guides/create-and-run.md@@ -17,6 +17,10 @@ vphone-cli vm create myphone \Creation runs prepare → firmware patch → online DFU restore → host-mounted CFW installation → first GUI boot. It needs network access for the restore ticket. The caller must provide root privileges for CFW installation; this bundle has no authorization dialog or privilege helper. The default virtual disk is 64 GB. `--keep-artifacts` retains the large prepared restore tree; omit it when disk space matters.+By default that pipeline builds a [template](#templates) rather than the VM itself, and the VM is cloned from it. The next `vm create` for the same device, iOS and cloudOS builds, preset and disk size clones from the same template instead of restoring again. Pass `--no-template` to build the VM on its own, as before.++`--cpu`, `--memory`, `--network` and `--unlock-at-startup` set those `vm config` settings on the new VM (defaults: 8 cores, 8192 MB, nat, off). `--skip-first-boot` leaves out the final boot, for a caller that boots the VM itself.+`fw prepare` creates a temporary vphone VM, starts it in DFU, and restores the selected cloudOS IPSW using this project's restore backend. It mounts the restored System volume read-only, extracts the GPU bundle, then removes the temporary VM. This first restore supplies the GPU driver for the second, hybrid iPhone restore. The extracted bundle is cached per cloudOS build in `~/.vphone/gpu-drivers/`, so later machines on the same cloudOS skip the temporary restore. `vm create` and `fw prepare` also accept `--gpu-driver-bundle /path/to/AppleParavirtGPUMetalIOGPUFamily.bundle` to reuse a previously extracted bundle without the temporary restore. The CLI checks its iPhoneOS platform version against the selected cloudOS version. Each restore obtains its own ticket online.The build also ships an arm64e GPU compiler plugin in the bundle. `fw prepare` copies it into the staged GPU bundle before firmware patching and installation.@@ -36,6 +40,35 @@ Closing the VM window, ⌘Q, `vm stop` and Control-C in the `vm launch` terminalThe guest shows the VM's name as its device name, in Xcode's device list and `xcrun devicectl list devices`, and cannot be renamed from inside the guest or from Finder, Xcode or `idevicename`: a rename there reports success and changes nothing. `vphone-vm` hands the name to the guest each time it connects to vphoned, a few seconds into every boot, and the guest keeps it for the next boot. After `vm rename`, Finder and `ideviceinfo` see the new name as soon as the machine is up; Xcode and `devicectl` read it when the device appears and may show the old name until the following boot. An existing machine moved to a bundle with this feature receives the guest library with its environment update and uses it from the boot after that. The guest's own name stays in its preferences, untouched. A VM name of more than 255 UTF-8 bytes, or with a control character, is not used, and the guest shows its own name. See `Research/Guest/device_name_pinning.md`.+## Templates++A template is a complete machine that is never booted, kept in `<library>/.templates/<id>/`. `vm create` without `--no-template` works out the template key from its options and the two IPSWs before anything is restored: the guest device, the iOS and cloudOS versions and builds, the patch preset and the boot-chain patches it resolves to, the bundle series (`2.8` for 2.8.x), the disk size, and what was trimmed from the guest (nothing yet). Then:++- If a template with that key exists, the VM is cloned from it with a new identity, given the requested CPU, memory and network, and booted once to check vphoned. This takes seconds and needs neither root nor the IPSWs; nothing is downloaded.+- Otherwise the full pipeline runs into a staging folder, `.templates/.building-<id>-<uuid>/`, without the first boot; the result is frozen and renamed to `.templates/<id>/` in one step, and the VM is cloned from it. A second `vm create` with the same key waits for the first instead of restoring a second copy. A failed build stays in its staging folder for inspection.++```sh+vphone-cli vm create phone-a --iphone-source … --cloudos-source … # builds the template, clones phone-a+vphone-cli vm create phone-b --iphone-source … --cloudos-source … # clones phone-b, no restore+vphone-cli vm create phone-c --template 3f2a91c0d4e7 --cpu 4 --memory 6144+```++`--template <id>` clones from a template by its identifier (or a unique prefix of four or more digits) and takes no IPSW options. `--device`, `--preset` and `--disk-size`, when given, must match the template's; a clone cannot change them. CPU, memory, screen and network are not part of the key.++Every machine cloned from one template shares, with the template and with each other, its SEP root secret, its Data volume keys and the data the restore wrote. One clone could in principle decrypt another's Data volume. A VM that needs keys of its own, for example to sign in to Apple services for multi-device research, should be created with `--no-template`. Clones get a new ECID, UDID and MAC address on their first start, as with `vm clone --new-identity`, and share every unchanged block with the template on APFS: a new clone costs almost nothing until it starts writing.++```sh+vphone-cli vm template list # id, key summary, STALE with the reasons+vphone-cli vm template show <id> --json+vphone-cli vm template adopt myphone # freeze a stopped, newly created VM into a template+vphone-cli vm template delete <id>+```++- **Stale.** A template is listed as stale when this `vphone-cli` belongs to another bundle series, when its preset now resolves to other boot-chain patches, or when its patch receipt disagrees with its plan. A stale template is never used: `vm create` with its key fails and names it. Delete it to have the next `vm create` build a new one.+- **Adopt.** `vm template adopt <vm>` turns a stopped VM into a template, under the key its own records give (`restore-info.json`, `PatchPlan.plist`, `config.plist`, the disk image and Launchpad's `launchpad.json`). The VM leaves `vm list`. Adopt a VM straight after creating it: every clone inherits what its guest has done since its first boot. A VM with snapshots is refused, and so is one that would be stale unless `--force` is given.+- **Never booted.** `vm launch` and `vphone-vm` refuse a template, in DFU too; no machine name reaches into `.templates`, so `vm launch`, `clone`, `export`, `rename` and `delete` cannot pick one up by accident. A template that booted would write first-boot state into the blocks every later clone inherits, and the clones made before it would stop sharing them.+- **Deleting.** `vm template delete <id>` removes the template; machines cloned from it keep working. The blocks they still share with it are freed only when those machines change them or are deleted, so deleting a template frees less than its size while clones remain. Templates take disk space although `vm list` does not show them; look in `~/.vphone/machines/.templates`, keeping in mind that `du` counts a template and each of its clones in full.+## Manual stagesUse these when investigating or repeating one phase. Keep a DFU boot running while `restore` talks to it:diff --git a/Research/Host/machine_templates.md b/Research/Host/machine_templates.mdnew file mode 100644index 00000000..59271d5f--- /dev/null+++ b/Research/Host/machine_templates.md@@ -0,0 +1,124 @@+# Machine templates++A template is a complete machine that never boots. New machines are cloned+from it with `clonefile(2)` and a new identity (see+[machine identity and clone](machine_identity_and_clone.md)), so a second+machine for the same firmware costs a clone and a few hundred MB of first-boot+writes instead of a 20 GB restore. User-facing behavior is in+[Create and run](../../Documents/Guides/create-and-run.md#templates).++Code: `VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift` (the key,+pure), `VPhoneMachineTemplates.swift` (storage, freeze, adopt, clone, boot+refusal), `VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift`+(resolving a key from options or from a machine's records),+`VPhoneVirtualMachineCreator.swift` (`vm create`) and+`VPhoneVirtualMachineTemplateCommand.swift` (`vm template`). Tests:+`VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplate*Tests.swift`.++## Key++Everything a clone inherits and could not change without a restore:++| Field | Source for a create | Source for `adopt` |+| --- | --- | --- |+| device | `VPhoneIPSWCache.guestDevice` of the iPhone IPSW (and `--device`) | `config.plist` `guestProductType` |+| iOS version and build | iPhone IPSW `BuildManifest` | `restore-info.json` `ios` |+| cloudOS version and build | cloudOS IPSW `BuildManifest` | `restore-info.json` `cloudOS` |+| preset | `--preset` | `PatchPlan.plist` `Preset` |+| boot-chain plan digest | the preset resolved against the two versions | `PatchPlan.plist` `EnabledPatches`, `Parameters` |+| bundle series | this `vphone-cli`'s `Info.plist` | `launchpad.json` `bootChain`, else the `Guest` receipt part when `cfw install` wrote it, else this `vphone-cli` |+| disk size (decimal GB) | `--disk-size` | `Disk.img` length |+| slimming: trim tier, setup boot, service profile, removed apps | `none`, no, `none`, none | `Template.plist` steps of a machine still being built, else the same |+| format version | 1 | 1 |++The identifier is the first 12 hex digits of the SHA-256 of one+`name=value` line per field in a fixed order (`canonicalDescription`); a test+pins one value against `shasum`. Any change to what a field means raises the+format version instead, so old templates stop matching rather than matching+wrongly.++The plan digest hashes the sorted identifiers of the enabled patches whose+catalog target is `.firmware(*)` (AVPBooter, iBSS, iBEC, LLB, TXM, kernelcache,+DeviceTree), plus any enabled identifier the catalog does not know (an+external set's, counted to be safe), and the preset's parameters. Guest+patches are left out: `cfw update-environment` applies them to a clone in+either direction. The preset itself is a field because `standard` and+`experimental` also differ in `guest.identity`, which only a full+`cfw install` writes into Preboot.++Not in the key: CPU, memory, screen, network, unlock at startup. They are+`config.plist` settings that `vm create` sets on the clone.++A machine Launchpad created with per-patch overrides has a digest of its own,+so it never serves a create without them. A template's staleness check+re-resolves with the template's own `PatchSelection.plist`.++## Storage++```+<library>/.templates/+ <id>/ frozen template: a machine folder + Template.plist+ .building-<id>-<uuid>/<id>/ a build in progress, or one that failed+ .lock-<id> flock(2) held while <id> is built+```++- Same volume as the machines, so a clone is a `clonefile`; hidden, so+ `VPhoneLibrary.scan` (`.skipsHiddenFiles`) and with it `vm list` and+ Launchpad never list a template.+- `Template.plist`: `Identifier`, `Key`, `Created`, `BuiltWithBundleVersion`,+ `BootChainBundleVersion`, `SourceMachine` (the name a derived mDNS name+ follows from), `Frozen`, `FrozenAt`, `Steps` (`SnapshotDeleted`,+ `SetupDone`, `ServiceProfile`, `RemovedApps`, `TrimTier`).+- A build happens in `.building-<id>-<uuid>/<id>/` and is frozen by writing+ `Frozen = true` and one `renamex_np(RENAME_EXCL)` to `.templates/<id>`. A+ listed template is always complete; a race with another build of the same+ key fails the rename and leaves the build unfrozen.+- `freeze` and `adopt` refuse unless `Steps` produced the slimming the key+ promises.+- A clone drops `Template.plist`, `Snapshots/` and `vphone.sock`.++## Never booting++The P0 measurement: booting a template after clones exist raised one clone's+private bytes from 0.42 GB to 0.80 GB, and every later clone would inherit+that boot's state. Three layers keep a frozen template from booting:++1. `VPhoneLibrary.bundle(named:)` accepts only a machine name (one component,+ no leading `.`), so no verb taking a machine name reaches `.templates`.+2. `vm launch` checks `VPhoneMachineTemplates.requireBootable`.+3. `VPhoneBootCommand.validate`, which `vphone-vm` runs on its arguments,+ checks it too, DFU included: a folder directly in `.templates`, a frozen+ record, or an unreadable one is refused. A machine in a staging folder may+ boot; the setup boot of a later stage runs there.++## Lifecycle hooks++- **Offline trim** (later): runs inside the CFW install of a build and records+ `Steps.TrimTier` with `VPhoneMachineTemplates.recordSteps(inBundle:)` before+ the freeze.+- **Setup boot** (later): boots the staging machine through vphoned RPCs and+ records `SetupDone`, `ServiceProfile`, `RemovedApps`, `SnapshotDeleted`.+- The key's slimming fields then come from the requested switches; `freeze`+ refuses a build whose steps fell short.+- **Launchpad** builds a machine with its step-by-step pipeline, skips the+ first boot, and runs `vm template adopt <name>`; then+ `vm create <name> --template <id> --skip-first-boot` and its own first boot.++## Staleness++`vm template list` marks a template stale when any of these holds:++- its series differs from this `vphone-cli`'s (a new series rebuilds);+- its preset no longer resolves, or resolves to another boot-chain digest;+- `FirmwarePatchDrift` finds a boot-chain patch whose receipt part disagrees+ with what the plan wants.++A stale template is never used. Guest-environment updates within a series do+not make a template stale; the clone can take `cfw update-environment`.++## Shared secrets++Every clone of a template shares its SEP root secret, gigalocker, Data/User+volume keys, `mobileactivationd.uuid` and the Data contents the restore wrote.+A template that was never booted shares no trusted host, keychain or Setup+state. `vm create --no-template` builds a machine with secrets of its own.diff --git a/Research/README.md b/Research/README.mdindex f7ea6298..80173b65 100644--- a/Research/README.md+++ b/Research/README.md@@ -19,7 +19,7 @@ This directory keeps the evidence behind firmware patches, restore and the self-| Kernel | [CFW overview](Kernel/kernel_jb_patch_notes.md), [patcher verification](Kernel/kernel_patcher_verification.md), [FairPlay kexts](Kernel/kernel_fairplay_kexts.md), [base validation 1–5](Kernel/kernel_patch_base_first5_validation.md), [11–15](Kernel/kernel_patch_base_11_15_validation.md), [16–20](Kernel/kernel_patch_base_16_20_validation.md), [sandbox hooks](Kernel/kernel_patch_sandbox_hooks_17_26_validation.md), [individual patch notes](KernelCustomFirmwarePatches/README.md) || Other patches and captures | [Launchd jetsam](Patches/cfw_patch_launchd_jetsam.md), [user-mode hypervisor references](Patches/hv_vmm_present_usermode_xrefs.md), [reference capture](Patches/patch_reference_capture.md) || Restore | [DFU probe](Restore/virtual_dfu_probe.md), [in-process restore](Restore/native_restore_architecture.md) |-| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/runtime_dependency_tiers.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md), [guest MAC, fixed address, port forwarding and names](Host/network_fixed_address.md), [machine identity and `vm clone --new-identity`](Host/machine_identity_and_clone.md), [sharing identical disk blocks with `vm rebase`](Host/disk_rebase.md) |+| Host and archives | [Binary split](Host/host_binary_split.md), [runtime dependency tiers](Host/runtime_dependency_tiers.md), [archive extraction contracts](Host/archive_extraction_contracts.md), [libarchive validation](Host/libarchive_xcframework_validation.md), [guest MAC, fixed address, port forwarding and names](Host/network_fixed_address.md), [machine identity and `vm clone --new-identity`](Host/machine_identity_and_clone.md), [sharing identical disk blocks with `vm rebase`](Host/disk_rebase.md), [machine templates](Host/machine_templates.md) || Guest interaction and VM identity | [DevMode XPC](Guest/devmode_xpc_protocol.md), [keyboard events](Guest/keyboard_event_pipeline.md), [machine identifier](Guest/machine_identifier_storage_analysis.md), [Auto-Lock on the Lock Screen](Guest/lock_screen_idle_timer.md), [display refresh rate](Guest/display_refresh_rate.md), [GPU acceleration](Guest/gpu_acceleration.md), [RootHide bootstrap base](Guest/roothide_bootstrap_base.md), [the Mac's .local name](Guest/mac_name_resolution.md), [locationd startup deadlock](Guest/locationd_startup_deadlock.md), [trimming system services](Guest/service_trimming.md), [deleting the orig-fs snapshot for templates](Guest/template_snapshot_deletion.md) || Historical project records | [Migration ledger](History/intg_update_status.md), [manifest refactoring summary](History/manifest_and_refactoring_summary.md) |diff --git a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swiftindex 31b44c12..b4f1e275 100644--- a/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift+++ b/VPhoneExecutable/VPhoneCommand/FirmwarePatcher/Pipeline/FirmwarePipeline.swift@@ -409,9 +409,9 @@ public final class FirmwarePipeline {/// that conflicts with another or needs a newer PatchKit is refused without its/// code ever running.///- /// Internal rather than private so the tests can resolve a preset naming an- /// external set without a restore tree to patch.- func resolvePlan(iOSBase: VPhoneVersion?, cloudOS: VPhoneVersion?) throws -> VPhonePatchPlan? {+ /// Public so the tests and `vm create`'s template key can resolve a preset,+ /// external sets included, without a restore tree to patch.+ public func resolvePlan(iOSBase: VPhoneVersion?, cloudOS: VPhoneVersion?) throws -> VPhonePatchPlan? {guard let preset else { return nil }var available = patchSetsdiff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swiftindex 97183d27..c4c2340d 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/Firmware/VPhoneFirmwarePreparer.swift@@ -63,24 +63,13 @@ enum VPhoneFirmwarePreparer {try fm.removeItem(at: staleOriginals)}- // Remote IPSWs go to one cache shared by every machine; keeping them- // inside the machine downloaded both again for each new one (#513).- // Local IPSWs are read in place and are never copied into the cache.- print("[*] Resolving iPhone IPSW...")- let phone = try resolve(- iPhoneSource, in: ipswCacheDirectory, connections: downloadConnections, label: "downloading iPhone IPSW",+ let (phone, cloud, device) = try resolveSources(+ iPhoneSource: iPhoneSource,+ cloudOSSource: cloudOSSource,+ ipswCacheDirectory: ipswCacheDirectory,+ device: productType,+ downloadConnections: downloadConnections,)- print("[*] Resolving cloudOS IPSW...")- let cloud = try resolve(- cloudOSSource, in: ipswCacheDirectory, connections: downloadConnections, label: "downloading cloudOS IPSW",- )- try VPhoneIPSWCache.checkPair(iPhone: phone, cloudOS: cloud)- let device = VPhoneIPSWCache.guestDevice(for: phone, preferring: productType) ?? .default- if let productType, VPhoneGuestDevice.named(productType) != device {- throw Error.deviceNotInSource(productType, available: phone.productTypes)- }- try checkIPhoneName(iPhoneSource, archive: phone, device: device)- print("[+] \(device.productType) \(phone.version) (\(phone.build)); cloudOS \(cloud.version) (\(cloud.build))")let name = device.restoreTreeName(version: phone.version, build: phone.build)let destination = bundle.url.appendingPathComponent(name)@@ -157,6 +146,38 @@ enum VPhoneFirmwarePreparer {try recordGuestDevice(device, in: bundle)}+ /// Finds both IPSWs, downloading a remote one into the shared cache, and+ /// the guest device the iPhone IPSW gives, without extracting anything.+ /// `vm create` calls it before `prepare` to learn the template key; the+ /// second call finds both in place.+ static func resolveSources(+ iPhoneSource: String,+ cloudOSSource: String,+ ipswCacheDirectory: URL = VPhoneResources.ipswCacheDirectory(),+ device productType: String? = nil,+ downloadConnections: Int = VPhoneIPSWCache.defaultDownloadConnections,+ ) throws -> (phone: VPhoneIPSWCache.Archive, cloud: VPhoneIPSWCache.Archive, device: VPhoneGuestDevice) {+ // Remote IPSWs go to one cache shared by every machine; keeping them+ // inside the machine downloaded both again for each new one (#513).+ // Local IPSWs are read in place and are never copied into the cache.+ print("[*] Resolving iPhone IPSW...")+ let phone = try resolve(+ iPhoneSource, in: ipswCacheDirectory, connections: downloadConnections, label: "downloading iPhone IPSW",+ )+ print("[*] Resolving cloudOS IPSW...")+ let cloud = try resolve(+ cloudOSSource, in: ipswCacheDirectory, connections: downloadConnections, label: "downloading cloudOS IPSW",+ )+ try VPhoneIPSWCache.checkPair(iPhone: phone, cloudOS: cloud)+ let device = VPhoneIPSWCache.guestDevice(for: phone, preferring: productType) ?? .default+ if let productType, VPhoneGuestDevice.named(productType) != device {+ throw Error.deviceNotInSource(productType, available: phone.productTypes)+ }+ try checkIPhoneName(iPhoneSource, archive: phone, device: device)+ print("[+] \(device.productType) \(phone.version) (\(phone.build)); cloudOS \(cloud.version) (\(cloud.build))")+ return (phone, cloud, device)+ }+/// Resolves one source, with a progress bar while it downloads. Launchpad/// reads the bar as `progress` lines and shows the percentage on its/// firmware step (#590).diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swiftnew file mode 100644index 00000000..d6bf6b5f--- /dev/null+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneMachineTemplateKeys.swift@@ -0,0 +1,234 @@+import ArgumentParser+import FirmwarePatcher+import Foundation+import VPhoneCoreKit+import VPhonePatchKit++/// Resolves template keys: for a create, from the requested options and the+/// IPSWs before anything is restored; for a machine, from its own records.+/// Both go through ``key(device:ios:cloudOS:preset:blocked:allowed:diskSizeGB:series:slimming:)``,+/// so the same machine gets the same key either way.+///+/// Lives here rather than in VPhoneCoreKit because the boot-chain part needs+/// the patch catalog and the plan resolver (`FirmwarePatcher`).+enum VPhoneMachineTemplateKeys {+ /// The series of this `vphone-cli`'s bundle, or `unbundled` for a build+ /// outside `VPhone.bundle`.+ static var currentSeries: String {+ VPhoneBundleVersion.current().flatMap(VPhoneMachineTemplateKey.series(ofBundleVersion:)) ?? "unbundled"+ }++ // MARK: Boot chain++ /// The patches of a plan that only a restore (or `fw patch`, or+ /// `cfw update-kernel`) can change: every patch the catalog declares on a+ /// boot-chain component, and every patch it does not know at all (one+ /// from an external set, counted to be safe). Guest patches are left out:+ /// `cfw update-environment` applies them to a clone either way.+ static func bootChainPatches(_ enabled: some Sequence<String>) -> [String] {+ let targets = Dictionary(+ FirmwarePatchSetCatalog.allDeclarations.map { ($0.identifier, $0.target) },+ uniquingKeysWith: { first, _ in first },+ )+ return enabled.filter { identifier in+ guard let target = targets[identifier] else { return true }+ if case .firmware = target { return true }+ return false+ }.sorted()+ }++ /// Resolves the preset against the two versions the way `fw patch` will.+ static func plan(+ preset identifier: String,+ iOSVersion: String,+ cloudOSVersion: String,+ blocked: [String] = [],+ allowed: [String] = [],+ ) throws -> VPhonePatchPlan {+ guard let preset = VPhonePatchPresetStore.preset(named: identifier) else {+ let available = VPhonePatchPresetStore.availablePresets().map(\.identifier)+ throw ValidationError("Unknown patch preset '\(identifier)'. Available: \(available.joined(separator: ", "))")+ }+ let pipeline = FirmwarePipeline(+ vmDirectory: FileManager.default.temporaryDirectory,+ variant: .jb,+ verbose: false,+ preset: preset,+ blockedPatches: Set(blocked),+ allowedPatches: Set(allowed),+ )+ guard let plan = try pipeline.resolvePlan(iOSBase: VPhoneVersion(iOSVersion), cloudOS: VPhoneVersion(cloudOSVersion)) else {+ throw ValidationError("Patch preset '\(identifier)' did not resolve.")+ }+ return plan+ }++ static func key(+ device: String,+ ios: VPhoneRestoreInfo.OSVersion,+ cloudOS: VPhoneRestoreInfo.OSVersion,+ preset: String,+ blocked: [String] = [],+ allowed: [String] = [],+ diskSizeGB: UInt64,+ series: String = currentSeries,+ slimming: VPhoneMachineTemplateSlimming = .none,+ ) throws -> VPhoneMachineTemplateKey {+ let plan = try plan(+ preset: preset,+ iOSVersion: ios.version,+ cloudOSVersion: cloudOS.version,+ blocked: blocked,+ allowed: allowed,+ )+ return VPhoneMachineTemplateKey(+ device: device,+ iOSVersion: ios.version,+ iOSBuild: ios.build,+ cloudOSVersion: cloudOS.version,+ cloudOSBuild: cloudOS.build,+ patchPreset: plan.presetIdentifier,+ bootChainPlanDigest: VPhoneMachineTemplateKey.planDigest(+ bootChainPatches: bootChainPatches(plan.enabled),+ parameters: plan.parameters,+ ),+ bundleSeries: series,+ diskSizeGB: diskSizeGB,+ slimming: slimming,+ )+ }++ // MARK: Recorded machine++ /// What a machine's records say about it, for adopting it.+ struct Recorded {+ var key: VPhoneMachineTemplateKey+ /// The bundle that built the boot chain, when any record names it.+ var bootChainBundleVersion: String?+ /// Boot-chain patches whose receipt differs from the plan.+ var drift: [String]+ }++ /// The key a machine's own records give: the restored versions, the+ /// guest device, the boot-chain plan `fw patch` recorded, the disk, and+ /// the series of the bundle that built the boot chain. `slimming` is+ /// what was done to it; nothing is, before the setup boot exists.+ static func recorded(_ bundle: VPhoneBundle, slimming: VPhoneMachineTemplateSlimming = .none) throws -> Recorded {+ guard VPhoneRestoreInfo.customFirmwareInstalled(inBundle: bundle) == true else {+ throw ValidationError("VM '\(bundle.name)' has no completed CFW install, so it cannot be a template.")+ }+ guard let info = VPhoneRestoreInfo.load(fromBundle: bundle) else {+ throw ValidationError("VM '\(bundle.name)' records no restored iOS and cloudOS versions (restore-info.json).")+ }+ guard let plan = VPhonePatchPresetStore.plan(forVM: bundle.url) else {+ throw ValidationError("VM '\(bundle.name)' has no \(VPhonePatchPresetStore.planFileName): its boot chain is not described.")+ }+ let bootChainVersion = bootChainBundleVersion(of: bundle)+ let series = bootChainVersion.flatMap(VPhoneMachineTemplateKey.series(ofBundleVersion:)) ?? currentSeries+ let key = VPhoneMachineTemplateKey(+ device: bundle.manifest.guestDevice.productType,+ iOSVersion: info.ios.version,+ iOSBuild: info.ios.build,+ cloudOSVersion: info.cloudOS.version,+ cloudOSBuild: info.cloudOS.build,+ patchPreset: plan.presetIdentifier,+ bootChainPlanDigest: VPhoneMachineTemplateKey.planDigest(+ bootChainPatches: bootChainPatches(plan.enabledPatches),+ parameters: plan.parameters,+ ),+ bundleSeries: series,+ diskSizeGB: diskSizeGB(of: bundle),+ slimming: slimming,+ )+ return Recorded(+ key: key,+ bootChainBundleVersion: bootChainVersion,+ drift: drift(of: bundle, wanted: Set(plan.enabledPatches), planned: Set(plan.enabledPatches)),+ )+ }++ /// The machine's disk in decimal GB, the unit `vm new --disk-size` takes.+ static func diskSizeGB(of bundle: VPhoneBundle) -> UInt64 {+ let bytes = max(bundle.diskSizeBytes, 0)+ return (UInt64(bytes) + 500_000_000) / 1_000_000_000+ }++ /// Launchpad's binding names the bundle that built the boot chain; without+ /// it, the `cfw install` that finished the machine is the best witness,+ /// as long as no environment update has rewritten that part since.+ static func bootChainBundleVersion(of bundle: VPhoneBundle) -> String? {+ let binding = bundle.url.appendingPathComponent("launchpad.json")+ if VPhoneVirtualMachineManifest.fileKind(at: binding) == .regularFile,+ let data = try? Data(contentsOf: binding),+ let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],+ let version = object["bootChain"] as? String, !version.isEmpty+ {+ return version+ }+ if let guest = VPhonePatchPresetStore.receipt(forVM: bundle.url)?.parts[VPhoneVirtualMachinePatchReceipt.guestPart],+ guest.writer == "cfw install"+ {+ return guest.bundleVersion+ }+ return nil+ }++ /// Boot-chain patches whose live state, by the receipt, is not what+ /// `wanted` asks for. A part the receipt does not record reads as the+ /// plan, so a machine without receipts shows no drift.+ static func drift(of bundle: VPhoneBundle, wanted: Set<String>, planned: Set<String>?) -> [String] {+ let receipt = VPhonePatchPresetStore.receipt(forVM: bundle.url)+ let applied = receipt.map { receipt in+ receipt.parts.mapValues { Set($0.patches) }+ }+ let notApplicable = Set(receipt?.parts.values.flatMap(\.notApplicable) ?? [])+ let declarations = FirmwarePatchSetCatalog.allDeclarations.filter {+ if case .firmware = $0.target { return true }+ return false+ }+ return FirmwarePatchDrift.states(+ declarations: declarations,+ wanted: wanted,+ planned: planned,+ applied: applied,+ notApplicable: notApplicable,+ part: VPhoneVirtualMachinePatchReceipt.part(for:),+ )+ .filter { $0.isPending == true }+ .map(\.identifier)+ .sorted()+ }++ // MARK: Staleness++ /// Why `template` would not serve a fresh create with its own options.+ static func staleReasons(_ template: VPhoneMachineTemplate) -> [String] {+ let key = template.key+ let selection = VPhonePatchPresetStore.selection(forVM: template.url)+ let fresh = try? self.key(+ device: key.device,+ ios: .init(version: key.iOSVersion, build: key.iOSBuild),+ cloudOS: .init(version: key.cloudOSVersion, build: key.cloudOSBuild),+ preset: key.patchPreset,+ blocked: selection.blockedPatches,+ allowed: selection.allowedPatches,+ diskSizeGB: key.diskSizeGB,+ series: key.bundleSeries,+ slimming: key.slimming,+ )+ var drifted: [String] = []+ if let bundle = try? template.bundle(),+ let wanted = try? plan(+ preset: key.patchPreset,+ iOSVersion: key.iOSVersion,+ cloudOSVersion: key.cloudOSVersion,+ blocked: selection.blockedPatches,+ allowed: selection.allowedPatches,+ )+ {+ let planned = VPhonePatchPresetStore.plan(forVM: template.url).map { Set($0.enabledPatches) }+ drifted = drift(of: bundle, wanted: wanted.enabled, planned: planned)+ }+ return template.staleReasons(currentSeries: currentSeries, freshKey: fresh, driftedPatches: drifted)+ }+}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swiftindex a09d7654..d4c49378 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCommand.swift@@ -25,6 +25,7 @@ struct VPhoneVirtualMachineCommand: ParsableCommand {VPhoneVirtualMachineLaunchCommand.self,VPhoneVirtualMachineStopCommand.self,VPhoneVirtualMachineCreateCommand.self,+ VPhoneVirtualMachineTemplateCommand.self,VPhoneVirtualMachineWriteManifestCommand.self,],)@@ -345,7 +346,7 @@ struct VPhoneVirtualMachineConfigCommand: ParsableCommand {return edit}- private static func parseSwitch(_ value: String, option: String) throws -> Bool {+ static func parseSwitch(_ value: String, option: String) throws -> Bool {switch value.lowercased() {case "on": return truecase "off": return false@@ -353,7 +354,7 @@ struct VPhoneVirtualMachineConfigCommand: ParsableCommand {}}- private static func parseMode(_ s: String)+ static func parseMode(_ s: String)throws -> VPhoneVirtualMachineManifest.NetworkConfig.NetworkMode{switch s.lowercased() {diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swiftindex 69ac09dd..9b62249e 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateCommand.swift@@ -7,7 +7,23 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {static let configuration = CommandConfiguration(commandName: "create",abstract: "Create a VM end-to-end (prepare → patch → restore → CFW → first boot)",- discussion: "Runs the full custom-firmware pipeline for a new VM. Requires an internet connection to download IPSWs, a macOS host that is not itself a VM, and sudo to install custom firmware.",+ discussion: """+ Runs the full custom-firmware pipeline for a new VM. Requires an internet connection \+ to download IPSWs, a macOS host that is not itself a VM, and sudo to install custom \+ firmware.++ By default the pipeline builds a template instead of the VM: a machine in \+ <library>/.templates that never boots, keyed by the guest device, the iOS and cloudOS \+ builds, the preset and the disk size. The VM is then cloned from it with a new identity, \+ and every later create with the same key clones from the same template in a fraction \+ of a second, without root, an IPSW download or a restore, sharing every unchanged block \+ on disk. Such machines share the template's SEP root secret and Data volume keys; \+ --no-template builds the VM on its own, with keys of its own, as before. \+ --template <id> clones from a template listed by vm template list.++ --cpu, --memory, --network and --unlock-at-startup are set on the new VM, whichever way \+ it is made.+ """,)@OptionGroup var lib: VPhoneLibraryOption@@ -23,12 +39,24 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {valueName: "product-type",))var device: String?- @Option(name: .shortAndLong, help: "Disk size (GB)") var diskSize: UInt64 = 64+ @Option(name: .shortAndLong, help: "Disk size (GB, default 64)") var diskSize: UInt64?@Option(name: .customLong("preset"),help: "Patch preset for the new VM. Defaults to standard; run `fw patches` to see what each one applies.",)- var preset: String = VPhonePatchPreset.standardIdentifier+ var preset: String?+ @Option(name: .long, help: "CPU cores (default 8)") var cpu: UInt?+ @Option(name: .long, help: "Memory (MB, default 8192)") var memory: UInt64?+ @Option(name: [.customShort("n"), .long], help: "Network mode: nat (default) | bridged | tunnel | none")+ var network: String?+ @Option(name: .long, help: "Unlock the guest when it starts: on | off (default)")+ var unlockAtStartup: String?+ @Option(help: ArgumentHelp("Clone the VM from this template (vm template list)", valueName: "id"))+ var template: String?+ @Flag(help: "Build the VM on its own, with SEP and Data volume keys of its own, instead of from a template")+ var noTemplate = false+ @Flag(help: "Do not boot the new VM to check that vphoned answers")+ var skipFirstBoot = false@Flag(name: .customLong("keep-artifacts"),help: "Keep the prepared restore tree after installation. Downloaded IPSWs always stay in the IPSW cache.",@@ -37,20 +65,57 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {@Flag(name: .customShort("v"), help: "Increase verbosity: -v tool detail, -vv guest serial, -vvv internal trace")var verboseCount: Int+ func validate() throws {+ if template != nil, noTemplate {+ throw ValidationError("--template and --no-template exclude each other.")+ }+ if template != nil {+ let firmware = [+ ("--iphone-source", iphoneSource != nil),+ ("--cloudos-source", cloudosSource != nil),+ ("--gpu-driver-bundle", gpuDriverBundle != nil),+ ("--ipsw-cache", ipswCache != nil),+ ("--keep-artifacts", keepArtifacts),+ ].filter(\.1).map(\.0)+ if !firmware.isEmpty {+ throw ValidationError("\(firmware.joined(separator: ", ")) cannot be used with --template: the template's firmware is already installed.")+ }+ }+ }+func run() throws {let resources = VPhoneResources.resolve()- // Resolved up front: a create boots the guest four times, and this is- // also where a missing vphone-vm should be reported — before any of the- // long-running download and patch work, not after it.- let launcher = try VPhoneGuestLaunchPlanner()if let device, VPhoneGuestDevice.named(device) == nil {throw ValidationError("vphone runs \(VPhoneGuestDevice.known.map(\.productType).joined(separator: ", ")) guests, not \(device).")}- // Prompt for any firmware component not supplied on the command line,- // from the guest device's builds.- let sources = try VPhoneFirmwareSourceSelection.resolve(iphone: iphoneSource, cloudos: cloudosSource, device: device)- guard sources.iphoneSource != nil, sources.cloudosSource != nil else {- throw ValidationError("Specify both --iphone-source and --cloudos-source when running without a terminal.")+ let networkMode = try network.map(VPhoneVirtualMachineConfigCommand.parseMode)+ let unlocks = try unlockAtStartup.map { try VPhoneVirtualMachineConfigCommand.parseSwitch($0, option: "--unlock-at-startup") }+ let templateUse: VPhoneVirtualMachineCreator.TemplateUse = if let template {+ .identifier(template)+ } else if noTemplate {+ .none+ } else {+ .automatic+ }++ // Resolved up front: a create boots the guest four times, and this is+ // also where a missing vphone-vm should be reported — before any of the+ // long-running download and patch work, not after it. A clone from a+ // named template that skips its first boot starts no guest at all.+ let launcher: VPhoneGuestLaunchPlanner? = if case .identifier = templateUse, skipFirstBoot {+ nil+ } else {+ try VPhoneGuestLaunchPlanner()+ }++ var sources = VPhoneFirmwareSources(iphoneSource: nil, cloudosSource: nil)+ if templateUse == .none || templateUse == .automatic {+ // Prompt for any firmware component not supplied on the command line,+ // from the guest device's builds.+ sources = try VPhoneFirmwareSourceSelection.resolve(iphone: iphoneSource, cloudos: cloudosSource, device: device)+ guard sources.iphoneSource != nil, sources.cloudosSource != nil else {+ throw ValidationError("Specify both --iphone-source and --cloudos-source when running without a terminal.")+ }}let orchestrator = VPhoneVirtualMachineCreator(library: lib.library,@@ -66,10 +131,17 @@ struct VPhoneVirtualMachineCreateCommand: ParsableCommand {URL(fileURLWithPath: ($0 as NSString).expandingTildeInPath, isDirectory: true)} ?? VPhoneResources.ipswCacheDirectory(),device: device,- patchPreset: preset,- diskSizeGB: diskSize,+ patchPreset: preset ?? VPhonePatchPreset.standardIdentifier,+ cpuCount: cpu ?? 8,+ memoryMB: memory ?? 8192,+ diskSizeGB: diskSize ?? 64,+ networkMode: networkMode,+ unlocksAtStartup: unlocks,verbosity: VPhoneVerbosity(count: verboseCount),keepArtifacts: keepArtifacts,+ template: templateUse,+ templateRequest: VPhoneMachineTemplateRequest(device: device, patchPreset: preset, diskSizeGB: diskSize),+ skipsFirstBoot: skipFirstBoot,))}}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateOptions.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateOptions.swiftindex a482c7a3..660fd472 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateOptions.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreateOptions.swift@@ -5,6 +5,17 @@ import VPhonePatchKit// MARK: - Create Optionspublic extension VPhoneVirtualMachineCreator {+ /// Whether the new machine is cloned from a template.+ enum TemplateUse: Equatable, Sendable {+ /// The full pipeline into the machine itself, with keys of its own.+ case none+ /// Clone from the template whose key the options resolve to,+ /// building it first when there is none.+ case automatic+ /// Clone from this template; no IPSW is needed.+ case identifier(String)+ }+struct Options {public var name: Stringpublic var iphoneSource: String?@@ -19,8 +30,18 @@ public extension VPhoneVirtualMachineCreator {public var cpuCount: UIntpublic var memoryMB: UInt64public var diskSizeGB: UInt64+ /// Set on the new machine after it exists; nil keeps the default.+ public var networkMode: VPhoneVirtualMachineManifest.NetworkConfig.NetworkMode?+ public var unlocksAtStartup: Bool?public var verbosity: VPhoneVerbositypublic var keepArtifacts: Bool+ public var template: TemplateUse+ /// The key fields named on the command line, checked against a+ /// template given by identifier. Nil fields were not given.+ public var templateRequest: VPhoneMachineTemplateRequest+ /// Leave the first boot to the caller (Launchpad boots the machine+ /// itself). A template is never booted either way.+ public var skipsFirstBoot: Boolpublic init(name: String,@@ -33,8 +54,13 @@ public extension VPhoneVirtualMachineCreator {cpuCount: UInt = 8,memoryMB: UInt64 = 8192,diskSizeGB: UInt64 = 64,+ networkMode: VPhoneVirtualMachineManifest.NetworkConfig.NetworkMode? = nil,+ unlocksAtStartup: Bool? = nil,verbosity: VPhoneVerbosity = .quiet,keepArtifacts: Bool = false,+ template: TemplateUse = .none,+ templateRequest: VPhoneMachineTemplateRequest = VPhoneMachineTemplateRequest(),+ skipsFirstBoot: Bool = false,) {self.name = nameself.iphoneSource = iphoneSource@@ -46,8 +72,13 @@ public extension VPhoneVirtualMachineCreator {self.cpuCount = cpuCountself.memoryMB = memoryMBself.diskSizeGB = diskSizeGB+ self.networkMode = networkMode+ self.unlocksAtStartup = unlocksAtStartupself.verbosity = verbosityself.keepArtifacts = keepArtifacts+ self.template = template+ self.templateRequest = templateRequest+ self.skipsFirstBoot = skipsFirstBoot}}}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swiftindex 4ee57a74..f4e364a2 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineCreator.swift@@ -1,6 +1,7 @@import ArgumentParserimport FirmwarePatcherimport Foundation+import VPhoneArchiveKitimport VPhoneCoreKitimport VPhoneRestore@@ -72,13 +73,15 @@ public struct VPhoneVirtualMachineCreator {private let library: VPhoneLibraryprivate let resources: VPhoneResources/// How to start the guest. A create boots in DFU and once for verification,- /// so the AMFI probe runs once before the multi-stage create pipeline.- private let launcher: VPhoneGuestLaunchPlanner+ /// so the AMFI probe runs once before the multi-stage create pipeline. Nil+ /// only for a clone from a named template whose first boot is skipped,+ /// which starts no guest.+ private let launcher: VPhoneGuestLaunchPlanner?public init(library: VPhoneLibrary,resources: VPhoneResources,- launcher: VPhoneGuestLaunchPlanner,+ launcher: VPhoneGuestLaunchPlanner?,) {self.library = libraryself.resources = resources@@ -87,48 +90,67 @@ public struct VPhoneVirtualMachineCreator {// MARK: - run+ /// Creates the machine one of three ways (`Options.template`): the full+ /// pipeline into the machine itself (`--no-template`); a clone of the+ /// template the options resolve to, built first into `.templates` when+ /// there is none (the default); or a clone of a template named by its+ /// identifier. A clone takes a fraction of a second and needs neither+ /// root nor an IPSW.public func run(_ options: Options) throws {- let v = options.verbosity- let invokingUser = VPhoneInvokingUser.current// Fail fast on a nested-VM host — PV=3 guest boot can't nest, and the whole// create pipeline (download + patch + restore) is wasted otherwise. Mirrors// the host preflight that precedes VM launch.- if Self.isNestedVMHost() {+ let startsGuest: Bool = switch options.template {+ case .identifier: !options.skipsFirstBoot+ case .none, .automatic: true+ }+ if startsGuest, Self.isNestedVMHost() {throw VPhoneVirtualMachineCreationError.nestedVirtualization}+ try VPhoneBundleOperations.requireValidName(options.name)let bundleURL = library.url(forName: options.name)// Check before the fixup below is armed: an existing directory, possibly// planted by another account, must never be walked as root.if FileManager.default.fileExists(atPath: bundleURL.path) {throw VPhoneLibraryError.alreadyExists(name: options.name)}- let ownedOutputs = [bundleURL]- // Set only once this run has created the bundle directory itself.- var createdBundle = false- var ownershipRestored = false- var permissionsRestored = false- defer {- if let invokingUser, !ownershipRestored {- for output in ownedOutputs where createdBundle {- do { try invokingUser.restoreOwnership(at: output) } catch {- fputs("warning: could not restore ownership of \(output.path): \(error)\n", stderr)- }- }- try? invokingUser.restoreOwnerOfDirectory(at: library.root)- try? invokingUser.restoreOwnerOfDirectory(at: VPhoneResources.userDataRoot())+ let outputs = VPhoneCreatedOutputs(library: library)+ defer { outputs.finishBestEffort() }++ switch options.template {+ case .none:+ try createIndependent(options, outputs: outputs)+ case let .identifier(identifier):+ let template = try VPhoneMachineTemplates.template(identifier, in: library)+ let conflicts = options.templateRequest.conflicts(with: template.key)+ guard conflicts.isEmpty else {+ throw VPhoneMachineTemplateError.conflicts(identifier: template.identifier, options: conflicts)}- if !permissionsRestored {- for output in ownedOutputs where createdBundle {- do { try VPhoneHostFilePermissions.makeAccessible(at: output) } catch {- fputs("warning: could not set permissions on \(output.path): \(error)\n", stderr)- }- }- try? VPhoneHostFilePermissions.makeDirectoryAccessible(at: library.root)- try? VPhoneHostFilePermissions.makeDirectoryAccessible(at: VPhoneResources.userDataRoot())+ // Named on purpose, so used; but not silently.+ for reason in VPhoneMachineTemplateKeys.staleReasons(template) {+ print("warning: template \(template.identifier) is stale: \(reason)")}+ try cloneFromTemplate(template, options: options, outputs: outputs)+ case .automatic:+ let template = try templateForCreate(options, outputs: outputs)+ try cloneFromTemplate(template, options: options, outputs: outputs)}+ try outputs.finish()+ print("\n=== Done ===")+ if options.skipsFirstBoot {+ print("CFW VM created; its first boot was skipped. Guest user environment is untouched.")+ } else {+ print("CFW VM created; vphoned connected. Guest user environment is untouched.")+ }+ }++ // MARK: - Without a template++ /// The full pipeline into the machine itself: `vm new`, firmware, restore,+ /// CFW and the first boot check. What `vm create` always did.+ private func createIndependent(_ options: Options, outputs: VPhoneCreatedOutputs) throws {print("\n=== vm new ===")let spec = VPhoneBundleOperations.NewBundleConfiguration(name: options.name,@@ -139,9 +161,22 @@ public struct VPhoneVirtualMachineCreator {sepromSource: VPhoneBundleOperations.defaultSEPROMSource(),)let bundle = try VPhoneBundleOperations.create(spec, in: library)- createdBundle = true+ outputs.add(bundle.url)print("created \(bundle.url.path)")+ try buildGuest(at: bundle.url, options: options, outputs: outputs)+ try applySettings(options)+ if !options.skipsFirstBoot {+ print("\n=== First boot check ===")+ try runBootAnalysis(bundleURL: bundle.url, verbosity: options.verbosity)+ }+ }++ /// `fw prepare`, `fw patch`, the restore and `cfw install` into the machine+ /// folder at `bundleURL`, which `vm new` made. Removes the restore tree+ /// afterwards unless `--keep-artifacts`. Starts the guest only in DFU.+ private func buildGuest(at bundleURL: URL, options: Options, outputs: VPhoneCreatedOutputs) throws {+ let v = options.verbosityprint("\n=== fw prepare ===")try runFWPrepare(options: options, bundleURL: bundleURL)@@ -157,9 +192,7 @@ public struct VPhoneVirtualMachineCreator {// installer only accepts a VM folder, Disk.img and restore tree owned// by the invoking user. Hand this run's own bundle back first (the// same descriptor-relative walk as the final fixup).- if let invokingUser {- try invokingUser.restoreOwnership(at: bundleURL)- }+ try outputs.handBack(bundleURL)print("\n=== CFW install (host-mount) ===")try runCustomFirmwareInstall(options: options,@@ -173,25 +206,164 @@ public struct VPhoneVirtualMachineCreator {{print("[+] Removed built firmware \(removed)/ to save space (--keep-artifacts to keep)")}+ }- print("\n=== First boot check ===")- try runBootAnalysis(bundleURL: bundleURL, verbosity: v)- if let invokingUser {- for output in ownedOutputs {- try invokingUser.restoreOwnership(at: output)+ /// The settings `vm config` would set, on the new machine.+ private func applySettings(_ options: Options) throws {+ let bundle = try VPhoneBundleOperations.updateConfig(+ bundleNamed: options.name,+ in: library,+ cpuCount: options.cpuCount,+ memoryMB: options.memoryMB,+ networkMode: options.networkMode,+ unlocksAtStartup: options.unlocksAtStartup,+ )+ let manifest = bundle.manifest+ print("[+] \(bundle.name): \(manifest.cpuCount) CPU, \(manifest.memorySize / (1024 * 1024)) MB, "+ + "network \(manifest.networkConfig.mode.rawValue), unlock at startup \(manifest.unlocksScreenAtStartup ? "on" : "off")")+ }++ // MARK: - Templates++ /// The template a create with these options clones from: the one their+ /// key names, or a new one built into `.templates` first. A second create+ /// with the same key waits for a build in progress instead of restoring+ /// a second copy.+ private func templateForCreate(_ options: Options, outputs: VPhoneCreatedOutputs) throws -> VPhoneMachineTemplate {+ guard let phoneSource = options.iphoneSource, let cloudSource = options.cloudosSource else {+ throw ValidationError("Specify both iPhone and cloudOS IPSW sources when running without a terminal.")+ }+ print("\n=== Template ===")+ let sources = try VPhoneFirmwarePreparer.resolveSources(+ iPhoneSource: phoneSource,+ cloudOSSource: cloudSource,+ ipswCacheDirectory: options.ipswCacheDirectory,+ device: options.device,+ )+ let key = try VPhoneMachineTemplateKeys.key(+ device: sources.device.productType,+ ios: .init(version: sources.phone.version, build: sources.phone.build),+ cloudOS: .init(version: sources.cloud.version, build: sources.cloud.build),+ preset: options.patchPreset,+ diskSizeGB: options.diskSizeGB,+ )+ print("[*] Template key \(key.identifier): \(key.summary)")++ if let found = try VPhoneMachineTemplates.template(for: key, in: library) {+ return try requireCurrent(found)+ }+ let lock: VPhoneMachineTemplateLock+ do {+ lock = try VPhoneMachineTemplates.lock(key.identifier, in: library, wait: false)+ } catch VPhoneMachineTemplateError.busy {+ print("[*] Another create is building template \(key.identifier); waiting for it...")+ lock = try VPhoneMachineTemplates.lock(key.identifier, in: library, wait: true)+ }+ defer { lock.release() }+ outputs.addDirectory(VPhoneMachineTemplates.directory(in: library))+ // Built by the create that held the lock before this one.+ if let found = try VPhoneMachineTemplates.template(for: key, in: library) {+ return try requireCurrent(found)+ }+ return try buildTemplate(key, options: options, outputs: outputs)+ }++ private func requireCurrent(_ template: VPhoneMachineTemplate) throws -> VPhoneMachineTemplate {+ let reasons = VPhoneMachineTemplateKeys.staleReasons(template)+ guard reasons.isEmpty else {+ throw VPhoneMachineTemplateError.stale(identifier: template.identifier, reasons: reasons)+ }+ print("[+] Using template \(template.identifier), built \(template.record.created.formatted(.iso8601))")+ return template+ }++ /// Builds the template for `key` in a staging folder in `.templates` and+ /// freezes it into place. The template is never booted. A failed build+ /// is left in its staging folder for inspection; `vm template list`+ /// shows it and `vm template delete` removes it.+ private func buildTemplate(+ _ key: VPhoneMachineTemplateKey,+ options: Options,+ outputs: VPhoneCreatedOutputs,+ ) throws -> VPhoneMachineTemplate {+ print("\n=== Template build \(key.identifier) ===")+ let build = try VPhoneMachineTemplates.beginBuild(key, in: library)+ outputs.add(build.stagingURL)+ do {+ // The template keeps the default hardware; the machine cloned from+ // it gets the requested CPU, memory and network.+ let spec = VPhoneBundleOperations.NewBundleConfiguration(+ name: key.identifier,+ cpuCount: 8,+ memoryMB: 8192,+ diskSizeGB: options.diskSizeGB,+ romSource: VPhoneBundleOperations.defaultROMSource(),+ sepromSource: VPhoneBundleOperations.defaultSEPROMSource(),+ )+ let bundle = try VPhoneBundleOperations.create(spec, in: build.library)+ print("created \(bundle.url.path)")+ let bundleVersion = VPhoneBundleVersion.current()+ try VPhoneMachineTemplates.writeRecord(+ VPhoneMachineTemplateRecord(+ key: key,+ builtWithBundleVersion: bundleVersion,+ bootChainBundleVersion: bundleVersion,+ sourceMachine: options.name,+ ),+ inBundle: bundle.url,+ )++ try buildGuest(at: bundle.url, options: options, outputs: outputs)++ // Offline trimming (after cfw install) and the setup boot record+ // their work with VPhoneMachineTemplates.recordSteps here, before+ // the freeze; freeze refuses steps that do not match the key.++ // The key the template's own records give must be the one it is+ // filed under, or no later create (or adopt) would find it.+ let recorded = try VPhoneMachineTemplateKeys.recorded(VPhoneBundle.load(at: bundle.url), slimming: key.slimming)+ guard recorded.key == key else {+ throw ValidationError(+ "The built template's records give another key than requested (\(key.differences(from: recorded.key).joined(separator: "; "))).",+ )}- try invokingUser.restoreOwnerOfDirectory(at: library.root)- try invokingUser.restoreOwnerOfDirectory(at: VPhoneResources.userDataRoot())+ try outputs.handBack(build.stagingURL)+ let template = try VPhoneMachineTemplates.freeze(build)+ outputs.replace(build.stagingURL, with: template.url)+ print("[+] Template \(template.identifier) frozen at \(template.url.path)")+ return template+ } catch {+ print("[-] Template build failed; left at \(build.stagingURL.path). "+ + "Remove it with: vphone-cli vm template delete \(build.stagingURL.lastPathComponent)")+ throw error}- ownershipRestored = true- for output in ownedOutputs {- try VPhoneHostFilePermissions.makeAccessible(at: output)+ }++ /// The new machine, cloned from `template` with a new identity, given the+ /// requested settings and booted once to check vphoned answers.+ private func cloneFromTemplate(_ template: VPhoneMachineTemplate, options: Options, outputs: VPhoneCreatedOutputs) throws {+ print("\n=== Clone from template \(template.identifier) ===")+ let clone = try VPhoneMachineTemplates.cloneMachine(from: template, to: options.name, in: library)+ outputs.add(clone.url)+ do {+ try applySettings(options)+ } catch {+ try? FileManager.default.removeItem(at: clone.url)+ throw error}- try VPhoneHostFilePermissions.makeDirectoryAccessible(at: library.root)- try VPhoneHostFilePermissions.makeDirectoryAccessible(at: VPhoneResources.userDataRoot())- permissionsRestored = true- print("\n=== Done ===")- print("CFW VM created; vphoned connected. Guest user environment is untouched.")+ print("[+] \(clone.name) cloned from template \(template.identifier) with a new identity "+ + "(it shares SEP and Data volume keys with every machine from this template)")+ if !options.skipsFirstBoot {+ print("\n=== First boot check ===")+ try runBootAnalysis(bundleURL: clone.url, verbosity: options.verbosity)+ }+ }++ private func requireLauncher() throws -> VPhoneGuestLaunchPlanner {+ guard let launcher else {+ throw ValidationError("This create starts the guest, but vphone-vm was not resolved.")+ }+ return launcher}// MARK: - trace@@ -285,7 +457,7 @@ public struct VPhoneVirtualMachineCreator {print("[*] Starting DFU boot in background...")// Guest serial is never teed during `vm create` (echo: false); the// managed process still reads it internally for panic/prompt matching.- let (dfuExe, dfuArgs) = launcher.plan(["--config", configURL.path, "--dfu"])+ let (dfuExe, dfuArgs) = try requireLauncher().plan(["--config", configURL.path, "--dfu"])trace("spawn \(dfuExe.path) \(dfuArgs.joined(separator: " ")) (guest serial: off)", v)let dfu = VPhoneManagedProcess(dfuExe, dfuArgs, cwd: bundleURL, echo: false)try dfu.start()@@ -445,7 +617,7 @@ public struct VPhoneVirtualMachineCreator {// finish setup before vphoned accepts a connection. A headless first// boot timed out on 26.6.2, while the same disk reached vphoned in// GUI mode; later headless boots then connected normally.- let (vmExe, vmArgs) = launcher.plan(["--config", configURL.path])+ let (vmExe, vmArgs) = try requireLauncher().plan(["--config", configURL.path])trace("spawn \(vmExe.path) \(vmArgs.joined(separator: " ")) (guest serial: off)", v)let vm = VPhoneManagedProcess(vmExe, vmArgs, cwd: bundleURL, echo: false)try vm.start()@@ -474,3 +646,88 @@ public struct VPhoneVirtualMachineCreator {throw VPhoneVirtualMachineCreationError.bootAnalysisTimeout}}++// MARK: - VPhoneCreatedOutputs++/// The folders a create made, handed back to the invoking user (under sudo)+/// and made accessible like every other host VM artifact, on every way out.+///+/// Only folders this run created are listed, so an existing directory,+/// possibly planted by another account, is never walked as root. `finish()`+/// is the strict pass at the end; `finishBestEffort()` runs from a `defer`+/// and warns instead, for whatever `finish()` did not get to.+private final class VPhoneCreatedOutputs {+ private let invokingUser = VPhoneInvokingUser.current+ private var outputs: [URL] = []+ private var directories: [URL]+ private var ownershipRestored = false+ private var permissionsRestored = false++ init(library: VPhoneLibrary) {+ directories = [library.root, VPhoneResources.userDataRoot()]+ }++ func add(_ url: URL) {+ outputs.append(url)+ }++ /// A folder that moved: a template build renamed into place.+ func replace(_ old: URL, with new: URL) {+ outputs = outputs.map { $0 == old ? new : $0 }+ }++ /// A shared directory this run may have created, such as `.templates`.+ func addDirectory(_ url: URL) {+ if !directories.contains(url) {+ directories.insert(url, at: directories.count - 1)+ }+ }++ /// Gives one output back to the invoking user now, ahead of the CFW+ /// install, which accepts only a folder its caller owns.+ func handBack(_ url: URL) throws {+ try invokingUser?.restoreOwnership(at: url)+ }++ func finish() throws {+ if let invokingUser {+ for output in outputs {+ try invokingUser.restoreOwnership(at: output)+ }+ for directory in directories {+ try invokingUser.restoreOwnerOfDirectory(at: directory)+ }+ }+ ownershipRestored = true+ for output in outputs {+ try VPhoneHostFilePermissions.makeAccessible(at: output)+ }+ for directory in directories {+ try VPhoneHostFilePermissions.makeDirectoryAccessible(at: directory)+ }+ permissionsRestored = true+ }++ func finishBestEffort() {+ if let invokingUser, !ownershipRestored {+ for output in outputs {+ do { try invokingUser.restoreOwnership(at: output) } catch {+ fputs("warning: could not restore ownership of \(output.path): \(error)\n", stderr)+ }+ }+ for directory in directories {+ try? invokingUser.restoreOwnerOfDirectory(at: directory)+ }+ }+ if !permissionsRestored {+ for output in outputs {+ do { try VPhoneHostFilePermissions.makeAccessible(at: output) } catch {+ fputs("warning: could not set permissions on \(output.path): \(error)\n", stderr)+ }+ }+ for directory in directories {+ try? VPhoneHostFilePermissions.makeDirectoryAccessible(at: directory)+ }+ }+ }+}diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swiftindex 77fd9109..b58c9f72 100644--- a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineLaunchCommand.swift@@ -37,6 +37,7 @@ struct VPhoneVirtualMachineLaunchCommand: ParsableCommand {}let name = try VPhoneVirtualMachineSelection.resolveExisting(name, in: lib.library)let bundle = try lib.library.bundle(named: name)+ try VPhoneMachineTemplates.requireBootable(bundleURL: bundle.url)defer {do { try VPhoneHostFilePermissions.makeAccessible(at: bundle.url) }catch { fputs("warning: could not set VM file permissions: \(error)\n", stderr) }diff --git a/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swiftnew file mode 100644index 00000000..e6597c7f--- /dev/null+++ b/VPhoneExecutable/VPhoneCommand/VPhoneCommand/VirtualMachine/VPhoneVirtualMachineTemplateCommand.swift@@ -0,0 +1,259 @@+import ArgumentParser+import Foundation+import VPhoneCoreKit++// MARK: - Command group++struct VPhoneVirtualMachineTemplateCommand: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "template",+ abstract: "Manage machine templates (vm create clones new machines from them)",+ discussion: """+ A template is a complete machine that never boots, kept in <library>/.templates/<id>. \+ vm create clones a new machine from the template whose key matches what it was asked \+ for, with a new identity, in a fraction of a second and almost no disk space: the clone \+ shares every block it does not change with the template. The key is the guest device, \+ the iOS and cloudOS builds, the patch preset and the boot-chain patches it resolves to, \+ the bundle series, the disk size and what was trimmed. CPU, memory, screen and network \+ are not part of it; they are set on each clone.++ Every machine cloned from one template shares its SEP root secret and the keys of its \+ Data volume. Create a machine with --no-template when it needs keys of its own.++ A template is never listed by vm list and cannot be booted: a boot would write state \+ every later clone inherits.+ """,+ subcommands: [+ VPhoneVirtualMachineTemplateListCommand.self,+ VPhoneVirtualMachineTemplateShowCommand.self,+ VPhoneVirtualMachineTemplateAdoptCommand.self,+ VPhoneVirtualMachineTemplateDeleteCommand.self,+ ],+ )+}++// MARK: - Report++/// One template as `list --json` and `show --json` print it.+struct VPhoneMachineTemplateReport: Encodable {+ var id: String+ var path: String+ var key: VPhoneMachineTemplateKey+ var created: Date+ var builtWithBundleVersion: String?+ var bootChainBundleVersion: String?+ var sourceMachine: String?+ var steps: VPhoneMachineTemplateSteps+ var diskSizeBytes: Int64+ var stale: Bool+ var staleReasons: [String]++ init(_ template: VPhoneMachineTemplate) {+ let record = template.record+ id = record.identifier+ path = template.url.path+ key = record.key+ created = record.created+ builtWithBundleVersion = record.builtWithBundleVersion+ bootChainBundleVersion = record.bootChainBundleVersion+ sourceMachine = record.sourceMachine+ steps = record.steps+ diskSizeBytes = (try? template.bundle().diskSizeBytes) ?? 0+ staleReasons = VPhoneMachineTemplateKeys.staleReasons(template)+ stale = !staleReasons.isEmpty+ }+}++struct VPhoneMachineTemplateStagingReport: Encodable {+ var name: String+ var path: String+ var id: String?+ var active: Bool+}++struct VPhoneMachineTemplateListReport: Encodable {+ var templates: [VPhoneMachineTemplateReport]+ var building: [VPhoneMachineTemplateStagingReport]+ var damaged: [[String: String]]+}++private func encodeJSON(_ value: some Encodable) throws -> String {+ let encoder = JSONEncoder()+ encoder.outputFormatting = [.prettyPrinted, .sortedKeys]+ encoder.dateEncodingStrategy = .iso8601+ return try String(decoding: encoder.encode(value), as: UTF8.self)+}++// MARK: - list++struct VPhoneVirtualMachineTemplateListCommand: ParsableCommand {+ static let configuration = CommandConfiguration(commandName: "list", abstract: "List templates")++ @OptionGroup var lib: VPhoneLibraryOption+ @Flag(name: .shortAndLong, help: "Emit JSON") var json = false++ func run() throws {+ let listing = try VPhoneMachineTemplates.list(in: lib.library)+ let reports = listing.templates.map(VPhoneMachineTemplateReport.init)+ if json {+ try print(encodeJSON(VPhoneMachineTemplateListReport(+ templates: reports,+ building: listing.staging.map {+ VPhoneMachineTemplateStagingReport(name: $0.name, path: $0.url.path, id: $0.identifier, active: $0.isActive)+ },+ damaged: listing.damaged.map { ["name": $0.name, "reason": $0.reason] },+ )))+ return+ }+ if reports.isEmpty, listing.staging.isEmpty, listing.damaged.isEmpty {+ print("No templates in \(VPhoneMachineTemplates.directory(in: lib.library).path).")+ return+ }+ for report in reports {+ let state = report.stale ? " STALE" : ""+ print("\(report.id) \(report.key.summary)\(state)")+ for reason in report.staleReasons {+ print(" stale: \(reason)")+ }+ }+ for staging in listing.staging {+ print("\(staging.name) \(staging.isActive ? "building" : "unfinished; vm template delete \(staging.name) removes it")")+ }+ for skip in listing.damaged {+ print("\(skip.name) damaged: \(skip.reason)")+ }+ }+}++// MARK: - show++struct VPhoneVirtualMachineTemplateShowCommand: ParsableCommand {+ static let configuration = CommandConfiguration(commandName: "show", abstract: "Show one template")++ @OptionGroup var lib: VPhoneLibraryOption+ @Argument(help: "template id (or a unique prefix of at least 4 digits)") var id: String+ @Flag(name: .shortAndLong, help: "Emit JSON") var json = false++ func run() throws {+ let report = try VPhoneMachineTemplateReport(VPhoneMachineTemplates.template(id, in: lib.library))+ if json {+ try print(encodeJSON(report))+ return+ }+ let key = report.key+ print("id: \(report.id)")+ print("path: \(report.path)")+ print("device: \(key.device)")+ print("iOS: \(key.iOSVersion) (\(key.iOSBuild))")+ print("cloudOS: \(key.cloudOSVersion) (\(key.cloudOSBuild))")+ print("preset: \(key.patchPreset) boot chain \(key.bootChainPlanDigest.prefix(12))")+ print("bundle: series \(key.bundleSeries), boot chain \(report.bootChainBundleVersion ?? "unknown"), "+ + "built with \(report.builtWithBundleVersion ?? "unknown")")+ print("disk: \(key.diskSizeGB) GB")+ print("trim: \(key.slimming.trimTier), setup boot \(key.slimming.setupBoot ? "yes" : "no"), "+ + "services \(key.slimming.serviceProfile), removed apps \(key.slimming.removedApps.isEmpty ? "none" : key.slimming.removedApps.joined(separator: ","))")+ print("steps: snapshot deleted \(report.steps.snapshotDeleted ? "yes" : "no"), setup done \(report.steps.setupDone ? "yes" : "no")")+ print("created: \(report.created.formatted(.iso8601))")+ if let source = report.sourceMachine {+ print("source: \(source)")+ }+ print("state: \(report.stale ? "stale" : "current")")+ for reason in report.staleReasons {+ print(" \(reason)")+ }+ }+}++// MARK: - adopt++struct VPhoneVirtualMachineTemplateAdoptCommand: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "adopt",+ abstract: "Freeze a stopped, newly created VM into a template",+ discussion: """+ Moves the VM's folder into <library>/.templates/<id>: it leaves vm list, can no longer \+ boot, and vm create clones new machines from it. Its key is read from its records \+ (restore-info.json, PatchPlan.plist, config.plist and the disk). Adopt a machine straight \+ after creating it: whatever it has done since its first boot, every clone inherits.++ Refused while the VM runs, while it has snapshots, or when a template with its key \+ exists. --force adopts a machine whose boot chain was built by another bundle series \+ than this vphone-cli's, or whose patch receipt differs from its plan; such a template \+ is listed as stale.+ """,+ )++ @OptionGroup var lib: VPhoneLibraryOption+ @Argument(help: "VM name") var name: String+ @Flag(help: "adopt even when the template would be stale") var force = false++ func run() throws {+ let bundle = try lib.library.bundle(named: name)+ try VPhoneBundleActivity.requireStopped(bundle)+ let previous = try VPhoneMachineTemplates.readRecord(inBundle: bundle.url)+ let steps = previous?.steps ?? VPhoneMachineTemplateSteps()+ let recorded = try VPhoneMachineTemplateKeys.recorded(bundle, slimming: steps.slimming)+ var problems: [String] = []+ let series = VPhoneMachineTemplateKeys.currentSeries+ if recorded.key.bundleSeries != series {+ problems.append("its boot chain was built by bundle series \(recorded.key.bundleSeries); this vphone-cli is \(series)")+ }+ if !recorded.drift.isEmpty {+ problems.append("its patch receipt differs from its plan: \(recorded.drift.joined(separator: ", "))")+ }+ if !problems.isEmpty {+ guard force else {+ throw ValidationError("VM '\(name)' would be a stale template: \(problems.joined(separator: "; ")). Pass --force to adopt it anyway.")+ }+ for problem in problems {+ print("warning: \(problem)")+ }+ }+ let record = VPhoneMachineTemplateRecord(+ key: recorded.key,+ created: previous?.created ?? Date(),+ builtWithBundleVersion: VPhoneBundleVersion.current(),+ bootChainBundleVersion: recorded.bootChainBundleVersion,+ sourceMachine: name,+ steps: steps,+ )+ let template = try VPhoneMachineTemplates.adopt(machineNamed: name, in: lib.library, record: record)+ print("adopted \(name) as template \(template.identifier)")+ print(" \(template.key.summary)")+ print("create machines from it with: vphone-cli vm create <name> --template \(template.identifier)")+ }+}++// MARK: - delete++struct VPhoneVirtualMachineTemplateDeleteCommand: ParsableCommand {+ static let configuration = CommandConfiguration(+ commandName: "delete",+ abstract: "Delete a template or an unfinished template build",+ discussion: """+ Machines cloned from the template keep working: they share its blocks but do not refer \+ to it. The space those shared blocks take is freed only when no clone uses them either.+ """,+ )++ @OptionGroup var lib: VPhoneLibraryOption+ @Argument(help: "template id (or unique prefix), or a .building-… name from vm template list") var id: String+ @Flag(name: .shortAndLong, help: "Do not prompt") var force = false++ func run() throws {+ let library = lib.library+ if !force {+ // A damaged template has no summary to show, and is deleted all the same.+ let what = (try? VPhoneMachineTemplates.template(id, in: library)).map { "template \($0.identifier) (\($0.key.summary))" }+ ?? "'\(id)'"+ print("Delete \(what)? [y/N] ", terminator: "")+ guard (readLine() ?? "").lowercased() == "y" else {+ print("Canceled. Nothing was deleted.")+ return+ }+ }+ let removed = try VPhoneMachineTemplates.delete(id, in: library)+ print("deleted \(removed.lastPathComponent)")+ print("note: blocks still shared with machines cloned from it are freed only when those machines change or are deleted")+ }+}diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swiftindex 3efb682e..5991c192 100644--- a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneBundleOperations.swift@@ -202,6 +202,31 @@ public enum VPhoneBundleOperations {) throws -> VPhoneBundle {try requireValidName(newName)let source = try library.bundle(named: name)+ return try clone(source, sourceName: name, to: newName, in: library, newIdentity: newIdentity, afterCopy: afterCopy)+ }++ /// Clones a machine folder that need not be in `library`, such as a+ /// template in `.templates`, into `library` as `newName`. `sourceName` is+ /// the name a derived mDNS name follows from.+ public static func clone(+ _ source: VPhoneBundle,+ sourceName name: String,+ to newName: String,+ in library: VPhoneLibrary,+ newIdentity: Bool,+ ) throws -> VPhoneBundle {+ try clone(source, sourceName: name, to: newName, in: library, newIdentity: newIdentity, afterCopy: {})+ }++ static func clone(+ _ source: VPhoneBundle,+ sourceName name: String,+ to newName: String,+ in library: VPhoneLibrary,+ newIdentity: Bool,+ afterCopy: () throws -> Void,+ ) throws -> VPhoneBundle {+ try requireValidName(newName)let src = source.urllet dst = library.url(forName: newName)let fm = FileManager.default@@ -246,8 +271,13 @@ public enum VPhoneBundleOperations {}/// Left out of every clone: snapshots record the source's history, not- /// the copy's, and the control socket is the stopped source's.- private static let droppedFromClone: Set<String> = [VPhoneMachineSnapshots.directoryName, "vphone.sock"]+ /// the copy's, the control socket is the stopped source's, and a+ /// template's record would make its clone a template that never boots.+ private static let droppedFromClone: Set<String> = [+ VPhoneMachineSnapshots.directoryName,+ "vphone.sock",+ VPhoneMachineTemplates.recordFileName,+ ]/// The network settings a new-identity clone drops, described for display./// Each would collide with the source's when both run: a fixed address,diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swiftnew file mode 100644index 00000000..6f60a932--- /dev/null+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplateKey.swift@@ -0,0 +1,282 @@+import CryptoKit+import Foundation++// MARK: - Slimming++/// What a template's guest was trimmed of before it was frozen. Part of the+/// key: a machine cloned from a trimmed template cannot get the files back,+/// and one cloned from an untrimmed template does not lose them.+///+/// Every field has a "nothing done" value, which is all this version builds.+/// Offline file trimming (`trimTier`) and the setup boot (`setupBoot`,+/// `serviceProfile`, `removedApps`) record their work here once they exist.+public struct VPhoneMachineTemplateSlimming: Codable, Equatable, Hashable, Sendable {+ /// The file-trimming tier applied to the System volume: `none`,+ /// `conservative`, `standard` or `aggressive`.+ public var trimTier: String+ /// Whether the template was booted once to finish Setup and first-boot+ /// work before it was frozen.+ public var setupBoot: Bool+ /// The vphoned service profile applied during the setup boot: `none` or+ /// `trimmed`.+ public var serviceProfile: String+ /// Bundle identifiers of the system apps removed during the setup boot,+ /// sorted.+ public var removedApps: [String]++ public static let none = VPhoneMachineTemplateSlimming()++ public init(trimTier: String = "none", setupBoot: Bool = false, serviceProfile: String = "none", removedApps: [String] = []) {+ self.trimTier = trimTier+ self.setupBoot = setupBoot+ self.serviceProfile = serviceProfile+ self.removedApps = Array(Set(removedApps)).sorted()+ }++ private enum CodingKeys: String, CodingKey {+ case trimTier = "TrimTier"+ case setupBoot = "SetupBoot"+ case serviceProfile = "ServiceProfile"+ case removedApps = "RemovedApps"+ }+}++// MARK: - Key++/// Everything a new machine inherits from its template and could not change+/// afterwards without a restore. Two requests with the same key can share one+/// template; any difference needs another.+///+/// Not part of it: CPU, memory, screen, network and the other `config.plist`+/// settings (`vm config` changes them on the clone), and the guest patch+/// selection, which `cfw update-environment` applies both ways. The boot chain+/// is: `bootChainPlanDigest` covers the preset's boot-chain patches as the+/// plan resolved them, and the preset itself is a field because the presets+/// also differ in what a full `cfw install` writes into Preboot.+///+/// The key is pure data. The caller resolves each field: from the requested+/// options and IPSWs before a create, or from a machine's own records when it+/// is adopted. Both must arrive at the same values for the same machine.+public struct VPhoneMachineTemplateKey: Codable, Equatable, Hashable, Sendable {+ /// Raised whenever a field is added or its meaning changes, so templates+ /// keyed by an older rule are never matched by a newer one.+ public static let currentFormatVersion = 1++ public var formatVersion: Int+ /// The guest device's product type, as `fw prepare` picked it.+ public var device: String+ public var iOSVersion: String+ public var iOSBuild: String+ public var cloudOSVersion: String+ public var cloudOSBuild: String+ public var patchPreset: String+ /// ``planDigest(bootChainPatches:parameters:)`` of the resolved plan.+ public var bootChainPlanDigest: String+ /// The `VPhone.bundle` series (`2.8`) that built the boot chain.+ public var bundleSeries: String+ /// The disk image's size in decimal GB, which the restore fixed.+ public var diskSizeGB: UInt64+ public var slimming: VPhoneMachineTemplateSlimming++ public init(+ formatVersion: Int = Self.currentFormatVersion,+ device: String,+ iOSVersion: String,+ iOSBuild: String,+ cloudOSVersion: String,+ cloudOSBuild: String,+ patchPreset: String,+ bootChainPlanDigest: String,+ bundleSeries: String,+ diskSizeGB: UInt64,+ slimming: VPhoneMachineTemplateSlimming = .none,+ ) {+ self.formatVersion = formatVersion+ self.device = device+ self.iOSVersion = iOSVersion+ self.iOSBuild = iOSBuild+ self.cloudOSVersion = cloudOSVersion+ self.cloudOSBuild = cloudOSBuild+ self.patchPreset = patchPreset+ self.bootChainPlanDigest = bootChainPlanDigest+ self.bundleSeries = bundleSeries+ self.diskSizeGB = diskSizeGB+ self.slimming = slimming+ }++ // MARK: Identifier++ /// One `name=value` line per field, in a fixed order. Lists are joined+ /// with commas after sorting, so the order a caller gathered them in does+ /// not matter.+ public var canonicalDescription: String {+ [+ "format=\(formatVersion)",+ "device=\(device)",+ "ios=\(iOSVersion)/\(iOSBuild)",+ "cloudos=\(cloudOSVersion)/\(cloudOSBuild)",+ "preset=\(patchPreset)",+ "bootchain=\(bootChainPlanDigest)",+ "series=\(bundleSeries)",+ "disk=\(diskSizeGB)",+ "trim=\(slimming.trimTier)",+ "setup=\(slimming.setupBoot ? 1 : 0)",+ "services=\(slimming.serviceProfile)",+ "removed-apps=\(slimming.removedApps.sorted().joined(separator: ","))",+ ].joined(separator: "\n")+ }++ /// The template's folder name: the first 12 hex digits of the SHA-256 of+ /// ``canonicalDescription``.+ public var identifier: String {+ Self.hex(SHA256.hash(data: Data(canonicalDescription.utf8))).prefix(Self.identifierLength).description+ }++ public static let identifierLength = 12++ /// Whether `text` has the shape of an identifier. Only such a name is+ /// ever looked up under `.templates`.+ public static func isIdentifier(_ text: String) -> Bool {+ text.utf8.count == identifierLength && text.utf8.allSatisfy { byte in+ (byte >= 0x30 && byte <= 0x39) || (byte >= 0x61 && byte <= 0x66)+ }+ }++ // MARK: Plan digest++ /// SHA-256 over the sorted boot-chain patch identifiers and the preset's+ /// parameters. The caller decides which patches count as boot chain, and+ /// must decide the same way for a request and for a recorded plan.+ public static func planDigest(bootChainPatches: some Sequence<String>, parameters: [String: String]) -> String {+ let patches = Array(Set(bootChainPatches)).sorted()+ let knobs = parameters.keys.sorted().map { "\($0)=\(parameters[$0] ?? "")" }+ let text = (["patches"] + patches + ["parameters"] + knobs).joined(separator: "\n")+ return hex(SHA256.hash(data: Data(text.utf8)))+ }++ // MARK: Bundle series++ /// The first two numbers of a bundle version: `2.8.1` and+ /// `2.8.0-local.ab12cd34` are both `2.8`. Nil for anything else.+ public static func series(ofBundleVersion version: String) -> String? {+ let numbers = version.split(separator: "-", maxSplits: 1).first.map(String.init) ?? ""+ let parts = numbers.split(separator: ".", omittingEmptySubsequences: false)+ guard parts.count >= 2, parts.prefix(2).allSatisfy({ !$0.isEmpty && Int($0) != nil }) else {+ return nil+ }+ return "\(parts[0]).\(parts[1])"+ }++ // MARK: Comparison++ /// The fields that differ from `other`, as `name: mine → theirs`, for+ /// messages. Empty when the keys are equal.+ public func differences(from other: VPhoneMachineTemplateKey) -> [String] {+ var lines: [String] = []+ func compare(_ name: String, _ mine: String, _ theirs: String) {+ if mine != theirs {+ lines.append("\(name): \(mine) → \(theirs)")+ }+ }+ compare("key format", String(formatVersion), String(other.formatVersion))+ compare("device", device, other.device)+ compare("iOS", "\(iOSVersion) (\(iOSBuild))", "\(other.iOSVersion) (\(other.iOSBuild))")+ compare("cloudOS", "\(cloudOSVersion) (\(cloudOSBuild))", "\(other.cloudOSVersion) (\(other.cloudOSBuild))")+ compare("preset", patchPreset, other.patchPreset)+ compare("boot-chain plan", String(bootChainPlanDigest.prefix(12)), String(other.bootChainPlanDigest.prefix(12)))+ compare("bundle series", bundleSeries, other.bundleSeries)+ compare("disk size", "\(diskSizeGB) GB", "\(other.diskSizeGB) GB")+ compare("trim tier", slimming.trimTier, other.slimming.trimTier)+ compare("setup boot", slimming.setupBoot ? "yes" : "no", other.slimming.setupBoot ? "yes" : "no")+ compare("service profile", slimming.serviceProfile, other.slimming.serviceProfile)+ compare(+ "removed apps",+ slimming.removedApps.joined(separator: ",").ifEmpty("none"),+ other.slimming.removedApps.joined(separator: ",").ifEmpty("none"),+ )+ return lines+ }++ /// One line for listings.+ public var summary: String {+ "\(device) iOS \(iOSVersion) (\(iOSBuild)) / cloudOS \(cloudOSVersion) (\(cloudOSBuild)), "+ + "\(patchPreset), \(diskSizeGB) GB, bundle \(bundleSeries), trim \(slimming.trimTier)"+ }++ // MARK: Coding++ private enum CodingKeys: String, CodingKey {+ case formatVersion = "FormatVersion"+ case device = "Device"+ case iOSVersion = "IOSVersion"+ case iOSBuild = "IOSBuild"+ case cloudOSVersion = "CloudOSVersion"+ case cloudOSBuild = "CloudOSBuild"+ case patchPreset = "PatchPreset"+ case bootChainPlanDigest = "BootChainPlanDigest"+ case bundleSeries = "BundleSeries"+ case diskSizeGB = "DiskSizeGB"+ case slimming = "Slimming"+ }++ private static func hex(_ digest: SHA256.Digest) -> String {+ digest.map { String(format: "%02x", $0) }.joined()+ }+}++// MARK: - Request++/// The key fields a `vm create --template` names explicitly. A nil field was+/// not given and takes the template's value.+public struct VPhoneMachineTemplateRequest: Equatable, Sendable {+ public var device: String?+ public var patchPreset: String?+ public var diskSizeGB: UInt64?++ public init(device: String? = nil, patchPreset: String? = nil, diskSizeGB: UInt64? = nil) {+ self.device = device+ self.patchPreset = patchPreset+ self.diskSizeGB = diskSizeGB+ }++ /// Each option that asks for something the template does not have, as a+ /// sentence. A clone cannot change any of them.+ public func conflicts(with key: VPhoneMachineTemplateKey) -> [String] {+ var lines: [String] = []+ if let device, device != key.device {+ lines.append("--device \(device): the template's guest is \(key.device)")+ }+ if let patchPreset, patchPreset != key.patchPreset {+ lines.append("--preset \(patchPreset): the template was built with \(key.patchPreset)")+ }+ if let diskSizeGB, diskSizeGB != key.diskSizeGB {+ lines.append("--disk-size \(diskSizeGB): the template's disk is \(key.diskSizeGB) GB, fixed by its restore")+ }+ return lines+ }+}++// MARK: - Bundle version++public enum VPhoneBundleVersion {+ /// `CFBundleShortVersionString` of the `VPhone.bundle` the running+ /// executable is in, read from `Contents/Info.plist` beside+ /// `Contents/MacOS`. Nil for an executable outside a bundle.+ public static func current() -> String? {+ let executable = VPhoneResources.runningExecutable().resolvingSymlinksInPath()+ let info = executable+ .deletingLastPathComponent() // Contents/MacOS+ .deletingLastPathComponent() // Contents+ .appendingPathComponent("Info.plist")+ guard let data = try? Data(contentsOf: info),+ let plist = (try? PropertyListSerialization.propertyList(from: data, format: nil)) as? [String: Any]+ else { return nil }+ return plist["CFBundleShortVersionString"] as? String+ }+}++private extension String {+ func ifEmpty(_ replacement: String) -> String {+ isEmpty ? replacement : self+ }+}diff --git a/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swiftnew file mode 100644index 00000000..967eea6d--- /dev/null+++ b/VPhoneKit/VPhoneCoreKit/Bundle/VPhoneMachineTemplates.swift@@ -0,0 +1,761 @@+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:_:)``):+/// offline trimming inside 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 removedApps: [String]+ public var trimTier: String++ public init(+ snapshotDeleted: Bool = false,+ setupDone: Bool = false,+ serviceProfile: String = "none",+ removedApps: [String] = [],+ trimTier: String = "none",+ ) {+ self.snapshotDeleted = snapshotDeleted+ self.setupDone = setupDone+ self.serviceProfile = serviceProfile+ self.removedApps = Array(Set(removedApps)).sorted()+ self.trimTier = trimTier+ }++ /// The slimming these steps produced, as a key states it.+ public var slimming: VPhoneMachineTemplateSlimming {+ VPhoneMachineTemplateSlimming(+ trimTier: trimTier,+ setupBoot: setupDone,+ serviceProfile: serviceProfile,+ removedApps: removedApps,+ )+ }++ private enum CodingKeys: String, CodingKey {+ case snapshotDeleted = "SnapshotDeleted"+ case setupDone = "SetupDone"+ case serviceProfile = "ServiceProfile"+ case removedApps = "RemovedApps"+ case trimTier = "TrimTier"+ }++ 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"+ removedApps = try container.decodeIfPresent([String].self, forKey: .removedApps) ?? []+ trimTier = try container.decodeIfPresent(String.self, forKey: .trimTier) ?? "none"+ }+}++// 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++ 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(),+ ) {+ 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+ }++ 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"+ }++ 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()+ }+}++// 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+ /// 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.+ public static func recordSteps(inBundle url: URL, _ body: (inout VPhoneMachineTemplateSteps) -> Void) throws {+ guard var record = try readRecord(inBundle: url) 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 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 a template with+ /// the identifier appeared meanwhile; the build is then left in place.+ @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),+ )+ }+ let bundle = try VPhoneBundle.load(at: build.bundleURL)+ try VPhoneBundleActivity.requireStopped(bundle)+ record.frozen = true+ record.frozenAt = Self.wholeSeconds(now)+ 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+ 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),+ /// or a template with that key exists. On a failure the machine is left+ /// as it was.+ @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),+ )+ }+ let destination = url(of: record.identifier, in: library)+ if isDirectory(destination) {+ throw VPhoneMachineTemplateError.alreadyExists(record.identifier)+ }+ try ensureDirectory(in: library)+ record.frozen = true+ record.frozenAt = Self.wholeSeconds(now)+ 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()+ return try VPhoneBundleOperations.clone(+ source,+ sourceName: template.record.sourceMachine ?? template.identifier,+ to: newName,+ in: library,+ newIdentity: true,+ )+ }++ // MARK: Delete++ /// 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 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 .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+ }+}diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneBootCommand.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneBootCommand.swiftindex c4169a3d..8d67f736 100644--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneBootCommand.swift+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneBootCommand.swift@@ -106,6 +106,8 @@ public struct VPhoneBootCommand: ParsableCommand {public mutating func validate() throws {let manifest = try VPhoneVirtualMachineManifest.load(from: config)let bundle = VPhoneBundle(url: config.deletingLastPathComponent(), manifest: manifest)+ // In DFU too: a restore would rewrite the disk every clone shares.+ try VPhoneMachineTemplates.requireBootable(bundleURL: bundle.url)if !dfu,let existingVariant = VPhoneRestoreInfo.load(fromBundle: bundle)?.variant,existingVariant != "jb"diff --git a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneLibrary.swift b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneLibrary.swiftindex e6c34179..01ac901d 100644--- a/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneLibrary.swift+++ b/VPhoneKit/VPhoneCoreKit/VirtualMachine/VPhoneLibrary.swift@@ -81,7 +81,12 @@ public struct VPhoneLibrary: Sendable {try scan().bundles}+ /// Only a machine name reaches a folder: one path component that does not+ /// start with `.`. So no command that takes a machine name can reach a+ /// template in `.templates`, a staging folder, or anything outside the+ /// library.public func bundle(named name: String) throws -> VPhoneBundle {+ try VPhoneBundleOperations.requireValidName(name)let url = url(forName: name)guard FileManager.default.fileExists(atPath: url.appendingPathComponent("config.plist").path,diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swiftnew file mode 100644index 00000000..b6757a64--- /dev/null+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplateKeyTests.swift@@ -0,0 +1,159 @@+import Foundation+import Testing+@testable import VPhoneCoreKit++/// The template key: which requests may share one template.+struct MachineTemplateKeyTests {+ static func key(+ device: String = "iPhone17,3",+ bootChain: String = "abc",+ series: String = "2.8",+ disk: UInt64 = 64,+ slimming: VPhoneMachineTemplateSlimming = .none,+ ) -> VPhoneMachineTemplateKey {+ VPhoneMachineTemplateKey(+ device: device,+ iOSVersion: "27.0",+ iOSBuild: "24A435",+ cloudOSVersion: "26.4",+ cloudOSBuild: "23E5207q",+ patchPreset: "standard",+ bootChainPlanDigest: bootChain,+ bundleSeries: series,+ diskSizeGB: disk,+ slimming: slimming,+ )+ }++ // MARK: - Identifier++ @Test func `the identifier is pinned to the canonical description`() {+ // Computed outside Swift: printf '<canonical description>' | shasum -a 256 | cut -c1-12.+ // A change here orphans every template on disk: raise currentFormatVersion instead.+ let key = Self.key()+ #expect(key.canonicalDescription == """+ format=1+ device=iPhone17,3+ ios=27.0/24A435+ cloudos=26.4/23E5207q+ preset=standard+ bootchain=abc+ series=2.8+ disk=64+ trim=none+ setup=0+ services=none+ removed-apps=+ """)+ #expect(key.identifier == "a5f0340ef865")+ #expect(VPhoneMachineTemplateKey.isIdentifier(key.identifier))+ }++ @Test func `equal keys share an identifier whatever order their lists came in`() {+ let a = Self.key(slimming: .init(removedApps: ["com.apple.tv", "com.apple.news"]))+ let b = Self.key(slimming: .init(removedApps: ["com.apple.news", "com.apple.tv", "com.apple.tv"]))+ #expect(a == b)+ #expect(a.identifier == b.identifier)+ }++ @Test func `every field changes the identifier`() {+ let base = Self.key()+ var variants: [VPhoneMachineTemplateKey] = []+ func vary(_ change: (inout VPhoneMachineTemplateKey) -> Void) {+ var copy = base+ change(©)+ variants.append(copy)+ }+ vary { $0.formatVersion = 2 }+ vary { $0.device = "iPad16,1" }+ vary { $0.iOSVersion = "27.0.1" }+ vary { $0.iOSBuild = "24A446" }+ vary { $0.cloudOSVersion = "26.5" }+ vary { $0.cloudOSBuild = "23F1" }+ vary { $0.patchPreset = "experimental" }+ vary { $0.bootChainPlanDigest = "abd" }+ vary { $0.bundleSeries = "2.9" }+ vary { $0.diskSizeGB = 128 }+ vary { $0.slimming.trimTier = "standard" }+ vary { $0.slimming.setupBoot = true }+ vary { $0.slimming.serviceProfile = "trimmed" }+ vary { $0.slimming.removedApps = ["com.apple.tv"] }++ let identifiers = Set(variants.map(\.identifier) + [base.identifier])+ #expect(identifiers.count == variants.count + 1)+ for variant in variants {+ #expect(!base.differences(from: variant).isEmpty, "\(variant.canonicalDescription)")+ }+ #expect(base.differences(from: base).isEmpty)+ }++ @Test func `identifier shape`() {+ #expect(VPhoneMachineTemplateKey.isIdentifier("0123456789ab"))+ for bad in ["", "0123456789a", "0123456789abc", "0123456789AB", "0123456789ag", ".templates/x", "../../etc/x"] {+ #expect(!VPhoneMachineTemplateKey.isIdentifier(bad), "\(bad)")+ }+ }++ // MARK: - Plan digest++ @Test func `plan digest ignores order and duplicates and sees parameters`() {+ let digest = VPhoneMachineTemplateKey.planDigest(bootChainPatches: ["b", "a", "a"], parameters: ["k": "v"])+ #expect(digest == "bacbaaea391f4545d0d261fdeffa3b17a4761a5f4ad244db481c50cbc5b61236")+ #expect(digest == VPhoneMachineTemplateKey.planDigest(bootChainPatches: ["a", "b"], parameters: ["k": "v"]))+ #expect(digest != VPhoneMachineTemplateKey.planDigest(bootChainPatches: ["a", "b"], parameters: ["k": "w"]))+ #expect(digest != VPhoneMachineTemplateKey.planDigest(bootChainPatches: ["a"], parameters: ["k": "v"]))+ #expect(digest != VPhoneMachineTemplateKey.planDigest(bootChainPatches: ["a", "b"], parameters: [:]))+ }++ // MARK: - Series++ @Test func `bundle series is the first two numbers`() {+ #expect(VPhoneMachineTemplateKey.series(ofBundleVersion: "2.8.0") == "2.8")+ #expect(VPhoneMachineTemplateKey.series(ofBundleVersion: "2.8.1") == "2.8")+ #expect(VPhoneMachineTemplateKey.series(ofBundleVersion: "2.8.0-local.ab12cd34") == "2.8")+ #expect(VPhoneMachineTemplateKey.series(ofBundleVersion: "2.10") == "2.10")+ for bad in ["", "2", "2.", "x.y", "-local.2.8"] {+ #expect(VPhoneMachineTemplateKey.series(ofBundleVersion: bad) == nil, "\(bad)")+ }+ }++ // MARK: - Request++ @Test func `a request conflicts only in the key fields it names differently`() {+ let key = Self.key()+ #expect(VPhoneMachineTemplateRequest().conflicts(with: key).isEmpty)+ #expect(VPhoneMachineTemplateRequest(device: "iPhone17,3", patchPreset: "standard", diskSizeGB: 64)+ .conflicts(with: key).isEmpty)++ let conflicts = VPhoneMachineTemplateRequest(device: "iPad16,1", patchPreset: "experimental", diskSizeGB: 128)+ .conflicts(with: key)+ #expect(conflicts.count == 3)+ #expect(conflicts[0].hasPrefix("--device iPad16,1"))+ #expect(conflicts[1].hasPrefix("--preset experimental"))+ #expect(conflicts[2].hasPrefix("--disk-size 128"))+ }++ // MARK: - Coding++ @Test func `a record survives Template plist`() throws {+ let record = VPhoneMachineTemplateRecord(+ key: Self.key(slimming: .init(trimTier: "standard")),+ created: Date(timeIntervalSince1970: 1_800_000_000),+ builtWithBundleVersion: "2.8.0",+ bootChainBundleVersion: "2.8.0-local.ab12cd34",+ sourceMachine: "src",+ frozen: true,+ frozenAt: Date(timeIntervalSince1970: 1_800_000_100),+ steps: .init(snapshotDeleted: true, trimTier: "standard"),+ )+ let encoder = PropertyListEncoder()+ encoder.outputFormat = .xml+ let data = try encoder.encode(record)+ #expect(try PropertyListDecoder().decode(VPhoneMachineTemplateRecord.self, from: data) == record)+ #expect(record.identifier == record.key.identifier)+ let text = String(decoding: data, as: UTF8.self)+ for field in ["Identifier", "Key", "Frozen", "Steps", "SnapshotDeleted", "TrimTier", "BootChainPlanDigest"] {+ #expect(text.contains("<key>\(field)</key>"), "\(field)")+ }+ }+}diff --git a/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swiftnew file mode 100644index 00000000..826ba48b--- /dev/null+++ b/VPhoneKit/VPhoneCoreKitTests/Bundle/MachineTemplatesTests.swift@@ -0,0 +1,429 @@+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)+ }+}