Run a virtual iPhone on an Apple Silicon Mac.
Swift
Stream files to and from a guest without the RPC size limit
Jackyca2586130018
diff --git a/Documents/Guides/launchpad-cli.md b/Documents/Guides/launchpad-cli.mdindex 125e3269..a09c984b 100644--- a/Documents/Guides/launchpad-cli.md+++ b/Documents/Guides/launchpad-cli.md@@ -121,6 +121,8 @@ version while a machine is bound to it; rebind or delete those machines first.| `cfw update-kernel <name>` | Re-patch the kernelcache from the machine's current selection and swap it into Preboot, keeping the data (VM off); the data-preserving way to change a kernel patch on an installed VM, no restore tree needed || `guest send <name> <json>` | One raw `vphone.sock` request (tap, swipe, key, screenshot) || `guest rpc <name> <method> [params]` | Any vphoned method, see `Research/vphoned_http_api.md`. When vphoned refuses it, the last stderr line is its error object as JSON (`code`, `message`, `results`, `reason` …) |+| `guest push <name> <local> <guest-path> [--mode <octal>]` | Copy a Mac file into the guest. It streams through vphoned, so size is not limited by `guest rpc`'s 1 MiB JSON line; use it for binaries and IPAs. A guest path ending in `/` keeps the file's name; the mode defaults to the Mac file's permissions |+| `guest pull <name> <guest-path> <local>` | Copy a guest file to the Mac, streamed; `local` may be a folder. The file replaces `local` only once complete || `guest unlock <name> [--passcode <code>] [--timeout <seconds>]` | Turn the screen on and unlock the guest, whatever state it was in (vphoned `screen.unlock`). `--passcode` is needed only when the guest has one || `exec [--bundle <version>] <vphone-cli arguments>` | Run the default bundle's `vphone-cli`, or that version's, streaming its output. `--bundle` must come first |diff --git a/Skills/vphone-guest-control/references/guest-layout.md b/Skills/vphone-guest-control/references/guest-layout.mdindex 963ec89e..59914ef6 100644--- a/Skills/vphone-guest-control/references/guest-layout.md+++ b/Skills/vphone-guest-control/references/guest-layout.md@@ -153,18 +153,22 @@ difference is the `/rootfs` prefix.## Handing a file to vphoned-To let an RPC (for example `apps.install`) read a file you put in through ssh:+`guest push` copies a Mac file to a real-root guest path, streamed, any size,+with no ssh and no `--api-listen`. `guest pull` brings one back:```sh-scp -P 2222 App.ipa [email protected]:/tmp/App.ipa # lands in the jbroot's /tmp-ssh -p 2222 [email protected] 'mv /tmp/App.ipa /rootfs/private/var/tmp/App.ipa'+vphone-launchpad-cli guest push myphone App.ipa /private/var/tmp/vphone-launchpad-cli guest rpc myphone apps.install '{"path":"/private/var/tmp/App.ipa"}'+vphone-launchpad-cli guest pull myphone /private/var/mobile/Library/Logs/x.log .```-Without ssh, use RPC only: `files.write` for small text. Binaries need the-HTTP route `PUT /v1/files/content?path=<abs path>`, which exists only when the-VM was launched with `vphone-cli vm launch --api-listen` outside `vm start`; ask-the user rather than relaunching a running machine.+The mode follows the Mac file (`--mode 755` to set it), so an executable+stays executable. Paths are real-root paths, so a roothide file goes under the+absolute `.jbroot-<hex>` path from `bootstrap.inspect`, not `/var/jb`. It needs+a Core Bundle that has `push` on `vphone.sock`; an older one says it cannot+copy files. There, `files.write` takes only small files (one 1 MiB JSON line,+no append), and larger ones go through ssh: `scp -P 2222` into the jbroot's+`/tmp`, then `mv` to `/rootfs/private/var/tmp/`.## Installing a `.deb`diff --git a/Skills/vphone-guest-control/references/guest-socket.md b/Skills/vphone-guest-control/references/guest-socket.mdindex a77e5c83..2241698b 100644--- a/Skills/vphone-guest-control/references/guest-socket.md+++ b/Skills/vphone-guest-control/references/guest-socket.md@@ -32,6 +32,8 @@ not there yet.| `{"t":"key","name":"home"}` | `home`, `power`, `volup`, `voldown` are hardware HID keys. Any other name (`return`, `cmd+v`) goes to vphoned `input.key` || `{"t":"type","text":"Hello"}` | Sets the **guest clipboard**; it does not type || `{"t":"rpc","method":"<vphoned method>","params":{…}}` | Calls any vphoned method; see [rpc-methods](rpc-methods.md) |+| `{"t":"push","local":"/abs/host/file","path":"/abs/guest/file","mode":"755"}` | Streams a Mac file into the guest, any size. A `path` ending in `/` keeps the file's name; `mode` defaults to the Mac file's permissions. `result` has `path`, `local`, `size` |+| `{"t":"pull","path":"/abs/guest/file","local":"/abs/host/file"}` | Streams a guest file to the Mac; `local` may be a folder. Written beside `local` and renamed when complete |Unknown `t`, or missing fields, give `{"ok":false,"error":"…"}`.diff --git a/Skills/vphone-guest-control/references/rpc-methods.md b/Skills/vphone-guest-control/references/rpc-methods.mdindex 65516125..fc2a4295 100644--- a/Skills/vphone-guest-control/references/rpc-methods.md+++ b/Skills/vphone-guest-control/references/rpc-methods.md@@ -153,9 +153,12 @@ Paths are real-root paths. All take `path` unless noted.| `files.plist` | `path` || `files.plist_set` | `path`, `key`, and `value` or `remove:true` |-Use `files.read` with `binary:true` to pull guest binaries and crash reports-without ssh. Keep `limit` small; large reads are the usual way to hit the reply-size problem.+`files.write` replaces the whole file and takes one JSON line of at most+1 MiB, so a binary over about 700 KiB does not fit. Copy files of any size with+`vphone-launchpad-cli guest push` and `guest pull`, which stream+([guest-layout](guest-layout.md), "Handing a file to vphoned"). `files.read`+with `binary:true` is for small reads; keep `limit` small, since large reads+are the usual way to hit the reply size problem.## Processes, logs, servicesdiff --git a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swiftindex 22421db1..f86fd7d2 100644--- a/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift+++ b/VPhoneExecutable/VPhoneVirtualization/UI/GuestCommunication/VPhoneGuestControl.swift@@ -584,6 +584,54 @@ final class VPhoneGuestControl {guard response.status == 200 else { throw try httpError(response) }}+ /// Streams the host file at `localURL` to `path` in the guest, a chunk at+ /// a time, so its size is not limited by memory or by a JSON body.+ /// vphoned writes it beside `path` and renames it once every byte is in.+ /// Returns the size written.+ func pushFile(from localURL: URL, to path: String, permissions: String) async throws -> Int64 {+ let response = try await http(+ method: "PUT",+ path: filePath(path, mode: permissions),+ contentType: "application/octet-stream",+ limits: .fileTransfer,+ upload: localURL,+ )+ guard response.status == 200 else { throw try httpError(response) }+ let reply = try? JSONSerialization.jsonObject(with: response.body) as? [String: Any]+ let result = reply?["result"] as? [String: Any]+ return (result?["size"] as? NSNumber)?.int64Value ?? 0+ }++ /// Streams the guest file at `path` to `localURL` on the host. The bytes+ /// go to a hidden file beside `localURL`, which replaces it only once the+ /// whole file has arrived. Returns the size written.+ func pullFile(_ path: String, to localURL: URL) async throws -> Int64 {+ let temporary = localURL.deletingLastPathComponent()+ .appendingPathComponent(".\(localURL.lastPathComponent).vphone-\(UUID().uuidString).part")+ guard FileManager.default.createFile(atPath: temporary.path, contents: nil) else {+ throw ControlError.guestError("Could not create \(temporary.path)")+ }+ do {+ let handle = try FileHandle(forWritingTo: temporary)+ let response: VPhoneHTTPResponse+ do {+ response = try await http(method: "GET", path: filePath(path), limits: .fileTransfer, download: handle)+ try handle.close()+ } catch {+ try? handle.close()+ throw error+ }+ guard response.status == 200 else { throw try httpError(response) }+ guard rename(temporary.path, localURL.path) == 0 else {+ throw ControlError.guestError("Could not replace \(localURL.path): \(String(cString: strerror(errno)))")+ }+ return response.streamedLength+ } catch {+ unlink(temporary.path)+ throw error+ }+ }+func createDirectory(path: String) async throws {_ = try await call("files.mkdir", params: ["path": path])}@@ -834,6 +882,8 @@ final class VPhoneGuestControl {body: Data = Data(),contentType: String = "application/json",limits: VPhoneHTTPLimits = .rpc,+ upload: URL? = nil,+ download: FileHandle? = nil,) async throws -> VPhoneHTTPResponse {guard let device else { throw ControlError.notConnected }let socket = await withCheckedContinuation {@@ -848,6 +898,8 @@ final class VPhoneGuestControl {body: body,contentType: contentType,limits: limits,+ upload: upload,+ download: download,)return try await withCheckedThrowingContinuation { continuation inDispatchQueue.global(qos: .userInitiated).async {@@ -862,6 +914,8 @@ final class VPhoneGuestControl {private struct VPhoneHTTPResponse: Sendable {let status: Intlet body: Data+ /// The bytes written to the transaction's `download` handle instead of `body`.+ var streamedLength: Int64 = 0}// MARK: - Limits@@ -880,6 +934,11 @@ private struct VPhoneHTTPLimits: Sendable {static let download = VPhoneHTTPLimits(maxBodyLength: 2_147_483_647, deadline: .seconds(30 * 60))/// Uploads: the request body is large, the response is a small JSON reply.static let upload = VPhoneHTTPLimits(maxBodyLength: 64 * 1024 * 1024, deadline: .seconds(30 * 60))+ /// `push` and `pull` on vphone.sock: the file streams between the guest+ /// and a host file, so only an error reply is held in memory. The+ /// deadline allows a few GiB over a slow guest; a stall still ends at the+ /// per-read timeout.+ static let fileTransfer = VPhoneHTTPLimits(maxBodyLength: 64 * 1024 * 1024, deadline: .seconds(2 * 60 * 60))}private struct VPhoneSocketResult: @unchecked Sendable {@@ -898,6 +957,10 @@ private final class VPhoneHTTPTransaction: @unchecked Sendable {let body: Datalet contentType: Stringlet limits: VPhoneHTTPLimits+ /// A file sent as the request body in place of `body`.+ let upload: URL?+ /// Where a 200 response body goes in place of memory.+ let download: FileHandle?private let deadline: ContinuousClock.Instant/// Per-read and per-write socket timeout.@@ -910,8 +973,12 @@ private final class VPhoneHTTPTransaction: @unchecked Sendable {body: Data,contentType: String,limits: VPhoneHTTPLimits,+ upload: URL? = nil,+ download: FileHandle? = nil,) {self.connection = connection+ self.upload = upload+ self.download = downloadself.method = methodself.path = pathself.body = body@@ -941,10 +1008,22 @@ private final class VPhoneHTTPTransaction: @unchecked Sendable {else {throw VPhoneGuestControl.ControlError.notConnected}+ let source = try upload.map { try FileHandle(forReadingFrom: $0) }+ defer { try? source?.close() }+ let bodyLength: Int64 = if let source { Int64(try source.seekToEnd()) } else { Int64(body.count) }+ try source?.seek(toOffset: 0)let headers =- "\(method) \(path) HTTP/1.1\r\nHost: vphoned\r\nConnection: close\r\nContent-Type: \(contentType)\r\nContent-Length: \(body.count)\r\n\r\n"+ "\(method) \(path) HTTP/1.1\r\nHost: vphoned\r\nConnection: close\r\nContent-Type: \(contentType)\r\nContent-Length: \(bodyLength)\r\n\r\n"try write(fd, data: Data(headers.utf8))- if !body.isEmpty {+ if let source {+ var sent: Int64 = 0+ while sent < bodyLength {+ guard let chunk = try source.read(upToCount: Int(min(1 << 20, bodyLength - sent))), !chunk.isEmpty+ else { throw VPhoneGuestControl.ControlError.protocolError("the file shrank while it was sent") }+ try write(fd, data: chunk)+ sent += Int64(chunk.count)+ }+ } else if !body.isEmpty {try write(fd, data: body)}@@ -963,6 +1042,19 @@ private final class VPhoneHTTPTransaction: @unchecked Sendable {throw VPhoneGuestControl.ControlError.protocolError("invalid HTTP status")}let length = try Self.contentLength(lines.dropFirst())+ if let download, status == 200 {+ var payload = Data(received[boundary.upperBound...])+ var written: Int64 = 0+ while true {+ let part = payload.prefix(Int(min(Int64(payload.count), Int64(length) - written)))+ try download.write(contentsOf: part)+ written += Int64(part.count)+ guard written < Int64(length) else { break }+ payload.removeAll(keepingCapacity: true)+ try readMore(fd, into: &payload)+ }+ return VPhoneHTTPResponse(status: status, body: Data(), streamedLength: written)+ }guard length <= limits.maxBodyLength else {throw VPhoneGuestControl.ControlError.protocolError("HTTP body of \(length) bytes exceeds the \(limits.maxBodyLength)-byte limit")}diff --git a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swiftindex 478320a4..0ea6056a 100644--- a/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift+++ b/VPhoneExecutable/VPhoneVirtualization/UI/VPhoneHostAutomationServer.swift@@ -38,11 +38,20 @@ import VPhoneCoreKit/// When vphoned refuses it, `"error"` is the message/// and `"guest_error"` vphoned's whole error object/// (`code`, `message`, `results`, `reason`, `errno` …)+/// {"t":"push","local":"/abs/host/file","path":"/abs/guest/file","mode":"755"}+/// → streams a host file into the guest through vphoned's+/// `PUT /v1/files/content`, any size. A `path` ending in `/`+/// takes the host file's name; `mode` defaults to the host+/// file's permissions. `"result"` has `path`, `local`, `size`+/// {"t":"pull","path":"/abs/guest/file","local":"/abs/host/file"}+/// → streams a guest file to the host; `local` may be a+/// directory. The file replaces `local` only once complete/// {"t":"network"} → the NIC's state, in `"result"`/// {"t":"network","link":"down"} → unplug (`up` replugs); not saved///-/// All commands except "screenshot" and "rpc" wait briefly then capture a-/// compact screen image returned as `"image":"<base64>"` in the response.+/// All commands except "screenshot", "rpc", "push", "pull" and "network" wait+/// briefly then capture a compact screen image returned as+/// `"image":"<base64>"` in the response./// Pass `"screen":false` to skip the capture; "rpc" captures only when sent/// `"screen":true`.@MainActor@@ -260,6 +269,41 @@ class VPhoneHostAutomationServer {let image = wantRPCScreen ? await settledCompactScreenshot(delayMs: screenDelay) : nilreturn Self.reply(ok: true, image: image, result: result)+ case "push":+ guard let local = json["local"] as? String, local.hasPrefix("/"),+ var path = json["path"] as? String, path.hasPrefix("/")+ else {+ return Self.reply(ok: false, error: "push requires local (an absolute host path) and path (an absolute guest path)")+ }+ var status = stat()+ guard stat(local, &status) == 0, status.st_mode & S_IFMT == S_IFREG else {+ return Self.reply(ok: false, error: "push: \(local) is not a readable regular file")+ }+ if path.hasSuffix("/") {+ path += (local as NSString).lastPathComponent+ }+ // The host file's permissions unless the request names others,+ // so a pushed executable stays executable.+ let mode = json["mode"] as? String ?? String(status.st_mode & 0o777, radix: 8)+ let size = try await connectedControl().pushFile(+ from: URL(fileURLWithPath: local), to: path, permissions: mode,+ )+ return Self.reply(ok: true, result: ["path": path, "local": local, "size": size])++ case "pull":+ guard let path = json["path"] as? String, path.hasPrefix("/"),+ let local = json["local"] as? String, local.hasPrefix("/")+ else {+ return Self.reply(ok: false, error: "pull requires path (an absolute guest path) and local (an absolute host path)")+ }+ var destination = URL(fileURLWithPath: local)+ var isDirectory: ObjCBool = false+ if FileManager.default.fileExists(atPath: local, isDirectory: &isDirectory), isDirectory.boolValue {+ destination.appendPathComponent((path as NSString).lastPathComponent)+ }+ let size = try await connectedControl().pullFile(path, to: destination)+ return Self.reply(ok: true, result: ["path": path, "local": destination.path, "size": size])+case "network":guard let virtualMachine else {return Self.reply(ok: false, error: "the VM is not running")diff --git a/VPhoneLaunchpad/Tests/ControlTests.swift b/VPhoneLaunchpad/Tests/ControlTests.swiftindex 32528a16..37a29446 100644--- a/VPhoneLaunchpad/Tests/ControlTests.swift+++ b/VPhoneLaunchpad/Tests/ControlTests.swift@@ -40,6 +40,16 @@ struct ControlTests {let (root, _) = try parse(["vm", "stop", "lab-01", "--root", "/tmp/a/../b"])precondition(root.option("root") == "/tmp/b", "Root standardized: \(String(describing: root.option("root")))")+ // The host side of a copy is resolved here; the guest side stays as typed.+ let cwd = FileManager.default.currentDirectoryPath+ let (push, _) = try parse(["guest", "push", "lab-01", "build/./tool", "/var/jb/usr/bin/", "--mode", "755"])+ precondition(push.command == "guest.push" && push.option("mode") == "755", "Push: \(push)")+ precondition(push.arguments == ["lab-01", URL(fileURLWithPath: cwd).appendingPathComponent("build/tool").path, "/var/jb/usr/bin/"], "Push paths: \(push.arguments)")+ let (pull, _) = try parse(["guest", "pull", "lab-01", "/var/mobile/a.log", "/tmp/x/../out"])+ precondition(pull.command == "guest.pull" && pull.arguments == ["lab-01", "/var/mobile/a.log", "/tmp/out"], "Pull paths: \(pull.arguments)")+ precondition(failure(["guest", "pull", "lab-01", "/a"])?.message == "wrong number of arguments.", "Pull needs a local path")+ precondition(failure(["guest", "pull", "lab-01", "/a", "/b", "--mode", "644"])?.message == "unknown option --mode.", "Pull has no mode")+precondition(failure(["vm"])?.message == "vm needs a command.", "A group alone")precondition(failure(["vm", "start"])?.message == "wrong number of arguments.", "Missing name")precondition(failure(["vm", "start", "a", "--nope"])?.message == "unknown option --nope.", "Unknown option")diff --git a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swiftindex a3cf4fa6..7df20d1e 100644--- a/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpad/Control/VPhoneLaunchpadControlCommands.swift@@ -63,6 +63,8 @@ struct VPhoneLaunchpadControlCommands {case "cfw.update-kernel": return try await updateKernelControl(request, emit: emit)case "guest.send": return try await sendToGuest(request)case "guest.rpc": return try await callGuest(request)+ case "guest.push": return try await transferFile(request, push: true)+ case "guest.pull": return try await transferFile(request, push: false)case "guest.unlock": return try await unlockGuest(request)case "exec": return try await exec(request, emit: emit)default: throw VPhoneLaunchpadError("\(command.name) is not handled by this Launchpad.")@@ -972,6 +974,28 @@ struct VPhoneLaunchpadControlCommands {return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine))}+ /// `guest push` and `guest pull`: vphone-vm streams the file between the+ /// Mac and vphoned's `/v1/files/content`, so neither the 1 MiB limit on a+ /// vphone.sock line nor one on a JSON body applies.+ private func transferFile(_ request: VPhoneLaunchpadControlRequest, push: Bool) async throws -> Any {+ let machine = try await machine(request)+ var object: [String: Any] = push+ ? ["t": "push", "local": request.arguments[1], "path": request.arguments[2]]+ : ["t": "pull", "path": request.arguments[1], "local": request.arguments[2]]+ if let mode = request.option("mode") {+ object["mode"] = mode+ }+ do {+ // As long as vphone-vm's own limit on one transfer.+ return try await VPhoneLaunchpadGuestSocket.send(object, socketPath: Self.controlSocket(machine), timeout: 2 * 60 * 60)+ } catch let error as VPhoneLaunchpadError where error.detail?.hasPrefix("unknown command: p") == true {+ throw VPhoneLaunchpadError(+ "The Core Bundle \(machine.name) runs cannot copy files.",+ detail: "guest push and guest pull need a newer VPhone.bundle. Bind the machine to one with vm set-bundle and start it again.",+ )+ }+ }+/// vphoned's `screen.unlock`: the display on and the Lock Screen passed,/// whatever state the guest was in.private func unlockGuest(_ request: VPhoneLaunchpadControlRequest) async throws -> Any {diff --git a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swiftindex 9eb7d82c..1a356c87 100644--- a/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift+++ b/VPhoneLaunchpad/VPhoneLaunchpadShared/VPhoneLaunchpadControl.swift@@ -198,6 +198,10 @@ nonisolated struct VPhoneLaunchpadControlCommand: Sendable {summary: "Send one raw vphone.sock request, such as {\"t\":\"tap\",\"x\":645,\"y\":1398}."),Self(name: "guest.rpc", arguments: ["name", "method", "params..."], options: ["root"], flags: ["screen"],summary: "Call a vphoned method; params is one JSON object."),+ Self(name: "guest.push", arguments: ["name", "local", "path"], options: ["root", "mode"], flags: [],+ summary: "Copy a file from this Mac into the guest, streamed, any size. A path ending in / keeps the file's name; --mode is octal, the Mac file's permissions by default."),+ Self(name: "guest.pull", arguments: ["name", "path", "local"], options: ["root"], flags: [],+ summary: "Copy a file from the guest to this Mac, streamed, any size. local may be a folder; the file replaces it only once complete."),Self(name: "guest.unlock", arguments: ["name"], options: ["root", "passcode", "timeout"], flags: [],summary: "Turn the screen on and unlock the guest (vphoned screen.unlock). --passcode enters the passcode of a guest that has one; --timeout is in seconds, 10 by default."),@@ -311,8 +315,8 @@ extension VPhoneLaunchpadControlRequest {throw Failure(message: "wrong number of arguments.", detail: "usage: vphone-launchpad-cli \(command.usage)")}// The app runs elsewhere; a relative path means nothing to it.- if command.name == "bundle.install-local" {- positional[0] = URL(fileURLWithPath: positional[0]).standardizedFileURL.path+ if let index = ["bundle.install-local": 0, "guest.push": 1, "guest.pull": 2][command.name] {+ positional[index] = URL(fileURLWithPath: positional[index]).standardizedFileURL.path}if let root = request.options["root"] {request.options["root"] = URL(fileURLWithPath: root).standardizedFileURL.path