serve-sim 0.1.50-beta.145.1 → 0.1.50-beta.149.1

package/README.md

@@ -209,6 +209,8 @@ serve-sim camera --stop-webcam
 
 Multiple booted simulators are supported — pass several device names, or leave it empty to attach to all of them.
 
+Helpers started by `--detach` or `--no-preview` exit after their target simulators remain shut down beyond the grace period. A failed check keeps the helper alive.
+
 ### Remote access (`--auth-token`)
 
 Requests that don't come straight from this machine — LAN clients, tunnels, reverse proxies — are refused unless the server is started with `--auth-token <token>` (or `SERVE_SIM_AUTH_TOKEN`). CLI and scripted clients send `Authorization: Bearer <token>`. To share the preview with a browser, send the link with the token in the URL fragment:

package/Sources/SimNative/HIDInjector.swift

@@ -21,6 +21,12 @@ private func hidLog(_ message: @autoclosure () -> String) {
     fflush(stdout)
 }
 
+/// Carries the `SimDevice` to `SpringBoardLauncher`'s queue. The object is
+/// never mutated from Swift; the launch only sends it one message.
+private struct UncheckedSimDevice: @unchecked Sendable {
+    let device: NSObject
+}
+
 /// Injects touch, button, and orientation HID events into the iOS Simulator.
 ///
 /// Uses IndigoHIDMessageForMouseNSEvent to create touch messages and
@@ -41,6 +47,7 @@ actor HIDInjector {
     private var hidClient: NSObject?
     private var sendSel: Selector?
     private var simDevice: NSObject?
+    private let springBoardLauncher = SpringBoardLauncher()
     private var deviceHubKeyboardBridge: DeviceHubKeyboardBridge?
 
     // IndigoHIDMessageForMouseNSEvent(CGPoint*, CGPoint*, IndigoHIDTarget, NSEventType, NSSize, IndigoHIDEdge)
@@ -473,7 +480,7 @@ actor HIDInjector {
             // and is functionally identical to a single home press, so use it
             // unconditionally rather than depending on whether the HID symbol
             // resolved.
-            launchSpringBoard(deviceUDID: deviceUDID)
+            await launchSpringBoard(deviceUDID: deviceUDID)
 
         case "swipe_home":
             sendSwipeHome()
@@ -618,11 +625,37 @@ actor HIDInjector {
         rawSendTouch(type: "end", x: xPos, y: yEnd, edge: edge)
     }
 
-    private func launchSpringBoard(deviceUDID: String) {
-        let process = Process()
-        process.executableURL = URL(fileURLWithPath: "/usr/bin/xcrun")
-        process.arguments = DeviceSet.simctlArguments(["launch", deviceUDID, "com.apple.springboard"])
-        try? process.run()
+    /// Launches SpringBoard off the actor, falling back to `simctl`, and returns
+    /// once the attempt finishes.
+    private func launchSpringBoard(deviceUDID: String) async {
+        let device = simDevice.map(UncheckedSimDevice.init)
+        await springBoardLauncher.launch(
+            direct: { Self.launchSpringBoardDirectly(device: device?.device) },
+            fallback: {
+                // Older CoreSimulator versions may not expose the direct launch API.
+                let process = Process()
+                process.executableURL = URL(fileURLWithPath: "/usr/bin/xcrun")
+                process.arguments = DeviceSet.simctlArguments(["launch", deviceUDID, "com.apple.springboard"])
+                // Already on the launcher's queue; waiting keeps repeat presses
+                // coalesced instead of starting overlapping simctl processes.
+                SpringBoardLauncher.runToExit(process, timeout: 30)
+            }
+        )
+    }
+
+    /// Blocks until CoreSimulator answers, so it must stay off the actor's executor.
+    private nonisolated static func launchSpringBoardDirectly(device: NSObject?) -> SpringBoardLauncher.DirectResult {
+        let sel = NSSelectorFromString("launchApplicationWithID:options:pid:error:")
+        guard let device, device.responds(to: sel) else { return .unavailable }
+        typealias Fn = @convention(c) (
+            AnyObject, Selector, NSString, NSDictionary,
+            UnsafeMutablePointer<pid_t>, AutoreleasingUnsafeMutablePointer<NSError?>
+        ) -> ObjCBool
+        let fn = unsafeBitCast(device.method(for: sel), to: Fn.self)
+        var pid: pid_t = 0
+        var error: NSError?
+        if fn(device, sel, "com.apple.springboard", [:], &pid, &error).boolValue { return .launched }
+        return .failed(error?.localizedDescription ?? "unknown error")
     }
 
     // MARK: - Orientation (GSEvent via PurpleWorkspacePort)

package/Sources/SimNativeSupport/SpringBoardLauncher.swift

@@ -0,0 +1,102 @@
+import Foundation
+
+/// Runs the Home button's SpringBoard launch on its own serial queue so a slow
+/// launch never occupies the HID actor's executor, where it would queue later
+/// touches, buttons, and display operations behind it.
+///
+/// The direct CoreSimulator call is tried first; the fallback runs only if that
+/// API is unavailable or the launch fails. Presses that arrive while a launch
+/// is in flight join it rather than queueing another one, and resume with it.
+public final class SpringBoardLauncher: @unchecked Sendable {
+    public enum DirectResult: Sendable {
+        case launched
+        /// The direct launch API doesn't exist on this CoreSimulator version.
+        case unavailable
+        case failed(String)
+    }
+
+    private let queue = DispatchQueue(
+        label: "serve-sim.springboard-launch",
+        qos: .userInteractive,
+        autoreleaseFrequency: .workItem
+    )
+    private let log: @Sendable (String) -> Void
+    private let lock = NSLock()
+    private var waiters: [CheckedContinuation<Void, Never>] = []
+
+    public init(log: @escaping @Sendable (String) -> Void = SpringBoardLauncher.logToStderr) {
+        self.log = log
+    }
+
+    /// Presses currently waiting on the in-flight launch, including its initiator.
+    var waiterCount: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return waiters.count
+    }
+
+    /// Runs `direct`, then `fallback` if it didn't launch, on the launcher's
+    /// queue. Returns when the attempt this press started or joined finishes.
+    public func launch(
+        direct: @escaping @Sendable () -> DirectResult,
+        fallback: @escaping @Sendable () -> Void
+    ) async {
+        await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+            lock.lock()
+            waiters.append(continuation)
+            let isFirst = waiters.count == 1
+            lock.unlock()
+            guard isFirst else { return }
+
+            queue.async { [self] in
+                switch direct() {
+                case .launched:
+                    break
+                case .unavailable:
+                    fallback()
+                case .failed(let message):
+                    log("[hid] Direct SpringBoard launch failed: \(message)")
+                    fallback()
+                }
+
+                lock.lock()
+                let finished = waiters
+                waiters = []
+                lock.unlock()
+                finished.forEach { $0.resume() }
+            }
+        }
+    }
+
+    /// Starts `process` and blocks until it exits, terminating it after `timeout`
+    /// so a hung child can't hold up later launches forever. Call only from a
+    /// thread that may block, such as a `fallback`. Returns whether the process
+    /// started and exited within `timeout`.
+    @discardableResult
+    public static func runToExit(
+        _ process: Process,
+        timeout: TimeInterval,
+        log: @Sendable (String) -> Void = SpringBoardLauncher.logToStderr
+    ) -> Bool {
+        let exited = DispatchSemaphore(value: 0)
+        process.terminationHandler = { _ in exited.signal() }
+        guard (try? process.run()) != nil else { return false }
+        if exited.wait(timeout: .now() + timeout) == .success { return true }
+
+        log("[hid] \(process.executableURL?.path ?? "process") timed out after \(timeout)s; terminating")
+        process.terminate()
+        // Give SIGTERM a short grace period, then SIGKILL (which can't be ignored)
+        // so a timed-out child is gone before the next launch can start.
+        if exited.wait(timeout: .now() + 1) == .timedOut {
+            kill(process.processIdentifier, SIGKILL)
+            _ = exited.wait(timeout: .now() + 5)
+        }
+        return false
+    }
+
+    /// Writes one line to stderr; the default `log` destination.
+    @Sendable
+    public static func logToStderr(_ message: String) {
+        FileHandle.standardError.write(Data((message + "\n").utf8))
+    }
+}

package/Tests/SimNativeSupportTests/SpringBoardLauncherTests.swift

@@ -0,0 +1,294 @@
+import Foundation
+import XCTest
+@testable import SimNativeSupport
+
+/// Thread-safe call log; the launcher runs its closures on its own queue.
+private final class Recorder: @unchecked Sendable {
+    private let lock = NSLock()
+    private var entries: [String] = []
+
+    func record(_ entry: String) {
+        lock.lock()
+        entries.append(entry)
+        lock.unlock()
+    }
+
+    var all: [String] {
+        lock.lock()
+        defer { lock.unlock() }
+        return entries
+    }
+}
+
+/// Stands in for `HIDInjector`: if the launcher blocked its caller, `ping()`
+/// could not run on this actor until the slow launch finished.
+private actor FakeInjector {
+    let launcher: SpringBoardLauncher
+
+    init(launcher: SpringBoardLauncher) {
+        self.launcher = launcher
+    }
+
+    func pressHome(
+        direct: @escaping @Sendable () -> SpringBoardLauncher.DirectResult,
+        fallback: @escaping @Sendable () -> Void
+    ) async {
+        await launcher.launch(direct: direct, fallback: fallback)
+    }
+
+    func ping() -> Bool { true }
+}
+
+final class SpringBoardLauncherTests: XCTestCase {
+    func testDirectSuccessSkipsFallback() async {
+        let recorder = Recorder()
+        let launcher = SpringBoardLauncher()
+
+        await launcher.launch(
+            direct: { recorder.record("direct"); return .launched },
+            fallback: { recorder.record("fallback") }
+        )
+
+        XCTAssertEqual(recorder.all, ["direct"])
+    }
+
+    func testMissingSelectorFallsBack() async {
+        let recorder = Recorder()
+        let launcher = SpringBoardLauncher()
+
+        await launcher.launch(
+            direct: { recorder.record("direct"); return .unavailable },
+            fallback: { recorder.record("fallback") }
+        )
+
+        XCTAssertEqual(recorder.all, ["direct", "fallback"])
+    }
+
+    func testDirectFailureFallsBackAndLogs() async {
+        let recorder = Recorder()
+        let launcher = SpringBoardLauncher(log: { recorder.record("log: \($0)") })
+
+        await launcher.launch(
+            direct: { recorder.record("direct"); return .failed("boom") },
+            fallback: { recorder.record("fallback") }
+        )
+
+        XCTAssertEqual(recorder.all.first, "direct")
+        XCTAssertEqual(recorder.all.last, "fallback")
+        XCTAssertEqual(recorder.all.count, 3)
+        XCTAssertTrue(recorder.all[1].contains("boom"), "unexpected log: \(recorder.all[1])")
+    }
+
+    func testActorStaysResponsiveDuringSlowDirectLaunch() async {
+        let started = DispatchSemaphore(value: 0)
+        let release = DispatchSemaphore(value: 0)
+        let injector = FakeInjector(launcher: SpringBoardLauncher())
+
+        let press = Task {
+            await injector.pressHome(
+                direct: {
+                    started.signal()
+                    release.wait()
+                    return .launched
+                },
+                fallback: {}
+            )
+        }
+
+        // Wait off the cooperative pool so a blocked launcher can't starve it.
+        let didStart = await Self.wait(for: started, timeout: 5)
+        XCTAssertTrue(didStart, "direct launch never started")
+
+        // Safety release so a launcher that blocks the actor fails this test
+        // rather than deadlocking it.
+        let recorder = Recorder()
+        DispatchQueue.global().asyncAfter(deadline: .now() + 2) {
+            recorder.record("released")
+            release.signal()
+        }
+
+        // The direct launch is still blocked here; the actor must serve this.
+        let responded = await injector.ping()
+        recorder.record("pinged")
+        XCTAssertTrue(responded)
+        XCTAssertEqual(recorder.all.first, "pinged", "actor was blocked by the direct launch")
+
+        release.signal()
+        await press.value
+    }
+
+    func testLaunchRunsOnDedicatedQueueNotTheCooperativePool() async {
+        let recorder = Recorder()
+        let launcher = SpringBoardLauncher()
+
+        await launcher.launch(
+            direct: {
+                recorder.record(String(cString: __dispatch_queue_get_label(nil)))
+                return .unavailable
+            },
+            fallback: { recorder.record(String(cString: __dispatch_queue_get_label(nil))) }
+        )
+
+        XCTAssertEqual(recorder.all, Array(repeating: "serve-sim.springboard-launch", count: 2))
+    }
+
+    func testConcurrentPressesCoalesceWhileLaunchIsInFlight() async {
+        let recorder = Recorder()
+        let started = DispatchSemaphore(value: 0)
+        let release = DispatchSemaphore(value: 0)
+        let launcher = SpringBoardLauncher()
+
+        let first = Task {
+            await launcher.launch(
+                direct: {
+                    recorder.record("direct")
+                    started.signal()
+                    release.wait()
+                    return .launched
+                },
+                fallback: { recorder.record("fallback") }
+            )
+        }
+        let didStart = await Self.wait(for: started, timeout: 5)
+        XCTAssertTrue(didStart, "direct launch never started")
+
+        let extras = (0..<8).map { _ in
+            Task {
+                await launcher.launch(
+                    direct: { recorder.record("extra-direct"); return .launched },
+                    fallback: { recorder.record("extra-fallback") }
+                )
+            }
+        }
+
+        // Release only once every extra has joined; release even on failure so
+        // the launcher's queue can't stay blocked past the end of the test.
+        let didJoin = await Self.waitForWaiters(on: launcher, count: 9, timeout: 5)
+        release.signal()
+        XCTAssertTrue(didJoin, "extra presses never joined the in-flight launch")
+
+        await first.value
+        for extra in extras { await extra.value }
+        XCTAssertEqual(recorder.all, ["direct"])
+    }
+
+    func testLaunchesAgainAfterPreviousCompletes() async {
+        let recorder = Recorder()
+        let launcher = SpringBoardLauncher()
+
+        for _ in 0..<3 {
+            await launcher.launch(
+                direct: { recorder.record("direct"); return .launched },
+                fallback: { recorder.record("fallback") }
+            )
+        }
+
+        XCTAssertEqual(recorder.all, ["direct", "direct", "direct"])
+    }
+
+    func testRunToExitWaitsForProcessToFinish() throws {
+        let marker = FileManager.default.temporaryDirectory
+            .appendingPathComponent("springboard-launcher-\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(at: marker) }
+        let process = Self.shell("sleep 0.2; touch '\(marker.path)'")
+
+        XCTAssertTrue(SpringBoardLauncher.runToExit(process, timeout: 10))
+
+        XCTAssertFalse(process.isRunning)
+        XCTAssertTrue(FileManager.default.fileExists(atPath: marker.path), "returned before the process finished")
+    }
+
+    func testRunToExitTerminatesHungProcessAtTimeout() {
+        let recorder = Recorder()
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/bin/sleep")
+        process.arguments = ["30"]
+
+        XCTAssertFalse(SpringBoardLauncher.runToExit(process, timeout: 0.1, log: { recorder.record($0) }))
+
+        XCTAssertFalse(process.isRunning, "hung process was left running")
+        XCTAssertEqual(recorder.all.count, 1, "unexpected log: \(recorder.all)")
+    }
+
+    func testRunToExitKillsProcessThatIgnoresSIGTERM() {
+        // `Process` resets signal dispositions and the signal mask in the child,
+        // so the shell can't ignore SIGTERM from its first instruction, and
+        // `runToExit` starts its timeout as soon as `run()` returns. The shell
+        // creates `trapped` only after installing its trap. If it died without
+        // `trapped`, the timeout won the startup race (no fault of runToExit),
+        // so retry. Once `trapped` exists, the SIGKILL assertions must hold.
+        let trapped = FileManager.default.temporaryDirectory
+            .appendingPathComponent("springboard-launcher-trap-\(UUID().uuidString)")
+        defer { try? FileManager.default.removeItem(at: trapped) }
+
+        for _ in 0..<5 {
+            let recorder = Recorder()
+            // The loop is bounded (~30s) so the shell can't outlive a crashed test run.
+            let process = Self.shell(
+                "trap '' TERM; : > '\(trapped.path)'; i=0; while [ $i -lt 600 ]; do sleep 0.05; i=$((i+1)); done"
+            )
+            // Only reached with a live child if the escalation regresses.
+            defer { if process.isRunning { kill(process.processIdentifier, SIGKILL) } }
+
+            XCTAssertFalse(SpringBoardLauncher.runToExit(process, timeout: 1, log: { recorder.record($0) }))
+
+            if !process.isRunning, !FileManager.default.fileExists(atPath: trapped.path) {
+                continue
+            }
+            return Self.assertKilledDespiteSIGTERMTrap(process, log: recorder.all)
+        }
+        XCTFail("shell never installed its SIGTERM trap before the timeout")
+    }
+
+    private static func assertKilledDespiteSIGTERMTrap(_ process: Process, log: [String]) {
+        // `terminationStatus` raises if read while the process is still running.
+        guard !process.isRunning else {
+            return XCTFail("process that ignored SIGTERM was left running")
+        }
+        // SIGTERM would report 15, so this proves the trap held and SIGKILL landed.
+        XCTAssertEqual(process.terminationReason, .uncaughtSignal)
+        XCTAssertEqual(process.terminationStatus, SIGKILL)
+        // Capture errno immediately; XCTest calls in between could overwrite it.
+        let probe = kill(process.processIdentifier, 0)
+        let probeErrno = errno
+        XCTAssertEqual(probe, -1, "process still exists")
+        XCTAssertEqual(probeErrno, ESRCH)
+        XCTAssertEqual(log.count, 1, "unexpected log: \(log)")
+    }
+
+    func testRunToExitReturnsWhenProcessCannotStart() {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/nonexistent/serve-sim-test-binary")
+
+        XCTAssertFalse(SpringBoardLauncher.runToExit(process, timeout: 10))
+    }
+
+    private static func shell(_ command: String) -> Process {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/bin/sh")
+        process.arguments = ["-c", command]
+        return process
+    }
+
+    /// Polls until `count` presses are waiting on the in-flight launch.
+    private static func waitForWaiters(
+        on launcher: SpringBoardLauncher,
+        count: Int,
+        timeout: TimeInterval
+    ) async -> Bool {
+        let deadline = Date().addingTimeInterval(timeout)
+        while launcher.waiterCount < count {
+            guard Date() < deadline else { return false }
+            try? await Task.sleep(for: .milliseconds(1))
+        }
+        return true
+    }
+
+    private static func wait(for semaphore: DispatchSemaphore, timeout: TimeInterval) async -> Bool {
+        await withCheckedContinuation { continuation in
+            DispatchQueue.global().async {
+                continuation.resume(returning: semaphore.wait(timeout: .now() + timeout) == .success)
+            }
+        }
+    }
+}