@xenon-device-management/xenon 2.8.2 → 2.9.0

package/lib/src/app/routers/dashboard.js

@@ -129,7 +129,13 @@ function getSessions(request, response) {
         const cursor = readQuery(response, () => (0, sessionInsights_1.cursorWhere)(request.query.before, request.query.beforeId));
         if (cursor === undefined)
             return;
+        const ids = readQuery(response, () => (0, sessionInsights_1.parseIds)(request.query.ids));
+        if (ids === undefined)
+            return;
         const where = {};
+        if (ids) {
+            where.id = { in: ids };
+        }
         if (since) {
             where.createdAt = { gte: since };
         }

package/lib/src/app/routers/sessionInsights.js

@@ -9,10 +9,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_PAGE_MAX = exports.SESSION_PAGE_DEFAULT = exports.InvalidQueryError = void 0;
+exports.SESSION_IDS_MAX = exports.SESSION_PAGE_MAX = exports.SESSION_PAGE_DEFAULT = exports.InvalidQueryError = void 0;
 exports.sessionOutcome = sessionOutcome;
 exports.parseSince = parseSince;
 exports.parseLimit = parseLimit;
+exports.parseIds = parseIds;
 exports.cursorWhere = cursorWhere;
 exports.describeSessions = describeSessions;
 exports.percentile = percentile;
@@ -77,6 +78,27 @@ function parseLimit(raw) {
     }
     return Math.min(n, exports.SESSION_PAGE_MAX);
 }
+/** The most ids one GET /session takes. */
+exports.SESSION_IDS_MAX = 200;
+/**
+ * The `ids` query parameter: null when absent; else the comma-separated
+ * session ids, 1 to SESSION_IDS_MAX of them, or InvalidQueryError. The
+ * Sessions page re-reads older rows still running by id.
+ */
+function parseIds(raw) {
+    if (raw === undefined)
+        return null;
+    const ids = typeof raw === 'string'
+        ? raw
+            .split(',')
+            .map((id) => id.trim())
+            .filter(Boolean)
+        : [];
+    if (ids.length === 0 || ids.length > exports.SESSION_IDS_MAX) {
+        throw new InvalidQueryError('invalid_ids', `ids must list 1 to ${exports.SESSION_IDS_MAX} session ids, separated by commas`);
+    }
+    return ids;
+}
 /**
  * Where the next page starts: after the last row of the page before, given
  * as its `createdAt` (`before`) and `id` (`beforeId`). Pages go newest first

package/lib/src/device-managers/ios/IOSStreamService.js

@@ -283,6 +283,10 @@ let IOSStreamService = class IOSStreamService {
         return __awaiter(this, void 0, void 0, function* () {
             if (yield this.appiumSessionMayUse(udid, 'go-ios tunnels'))
                 return;
+            // A tunnel opened for screenshots is live and tracked, not a leftover:
+            // the start's ensure takes it over (IOSTunnels.borrow).
+            if (this.tunnels().isOnDemand(udid))
+                return;
             logger_1.default.debug(`Cleaning up orphan tunnels for ${udid}...`);
             yield this.tunnels().stop(udid);
             // Reap the tunnel process *group* for this udid so the self-forking go-ios
@@ -853,6 +857,14 @@ let IOSStreamService = class IOSStreamService {
                         session.status = 'error';
                         session.lastError = error.message;
                     }
+                    // A start that got its tunnel up and then failed (WDA didn't launch)
+                    // stops that tunnel, so it doesn't run on, holding its ports, until
+                    // the phone's next start. Not while an Appium session may use it.
+                    if ((session === null || session === void 0 ? void 0 : session.tunnelPort) != null &&
+                        !(yield this.appiumSessionMayUse(udid, "the failed start's go-ios tunnel"))) {
+                        yield this.tunnels().stop(udid);
+                        session.tunnelPort = null;
+                    }
                     // Back off before the next attempt so a polling client can't drive a
                     // restart loop against a device that keeps failing to start.
                     this.markRecoveryAttempt(udid);

package/lib/src/device-managers/ios/IOSTunnels.js

@@ -18,8 +18,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.IOSTunnels = exports.TUNNEL_CHECK_MS = exports.TUNNEL_LEASE_TTL_MS = exports.TUNNEL_READY_POLL_MS = exports.TUNNEL_READY_TIMEOUT_MS = void 0;
+exports.IOSTunnels = exports.TUNNEL_BORROW_IDLE_MS = exports.TUNNEL_CHECK_MS = exports.TUNNEL_LEASE_TTL_MS = exports.TUNNEL_READY_POLL_MS = exports.TUNNEL_READY_TIMEOUT_MS = void 0;
 exports.iosVersionOf = iosVersionOf;
+exports.goIosReason = goIosReason;
 /**
  * One go-ios tunnel per iOS 17+ phone, each on its own leased pair of ports.
  *
@@ -68,12 +69,53 @@ exports.TUNNEL_READY_POLL_MS = 500;
 exports.TUNNEL_LEASE_TTL_MS = 90 * 60 * 1000;
 /** How often running tunnels are checked for a phone that went away. */
 exports.TUNNEL_CHECK_MS = 5000;
+/**
+ * How long a tunnel opened for screenshots stays after the last one: long
+ * enough that a client taking screenshots in a loop pays the start once.
+ */
+exports.TUNNEL_BORROW_IDLE_MS = 2 * 60 * 1000;
+/** How long a phone's iOS version is trusted before `ios info` is asked again. */
+const VERSION_CACHE_MS = 10 * 60 * 1000;
 /** The iOS version `ios info` reports, as a number: 17.2 for "17.2.1" or "iOS 17.2", 0 for none. */
 function iosVersionOf(info) {
     const versionStr = String(info.ProductVersion || info.HumanReadableProductVersionString || '0');
     const match = versionStr.match(/(\d+\.?\d*)/);
     return match ? parseFloat(match[0]) : 0;
 }
+/** The longest go-ios reason kept for an error message. */
+const REASON_MAX = 200;
+/**
+ * The last error or warning in a chunk of go-ios's stderr, for an error
+ * message. go-ios logs JSON lines: an ERROR or WARN line gives its `msg` and
+ * `error`, an INFO line gives nothing, and a line that isn't JSON (a panic)
+ * is kept as it is.
+ */
+function goIosReason(text) {
+    var _a;
+    let reason;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch (_b) {
+            entry = undefined;
+        }
+        if (entry && typeof entry === 'object') {
+            const level = String((_a = entry.level) !== null && _a !== void 0 ? _a : '').toUpperCase();
+            if ((level === 'ERROR' || level === 'WARN') && entry.msg) {
+                reason = entry.error ? `${entry.msg}: ${entry.error}` : String(entry.msg);
+            }
+        }
+        else {
+            reason = line;
+        }
+    }
+    return reason === null || reason === void 0 ? void 0 : reason.slice(0, REASON_MAX);
+}
 /** An answer that puts the phone's traffic anywhere but its leased P + 1. */
 function moved(info, port) {
     return info.state === 'up' && info.userspacePort !== undefined && info.userspacePort !== port + 1;
@@ -83,29 +125,48 @@ let IOSTunnels = class IOSTunnels {
         this.log = logger_1.default.scope('IOSTunnels');
         this.tunnels = new Map();
         this.checking = false;
+        this.versionCache = new Map();
         this.goIOSPath = path_1.default.join((0, helpers_1.cachePath)('goIOS'), 'ios');
     }
     /**
-     * The phone's tunnel-info port, starting its tunnel if it has none. Null
-     * for a phone below iOS 17, or whose version can't be read: it needs no
-     * tunnel. Throws when no pair of ports is left, or when the tunnel exits
-     * before it is ready.
+     * The phone's tunnel-info port for its stream, starting its tunnel if it
+     * has none. A tunnel opened for screenshots is taken over: from then on
+     * only the stream's stop ends it. Null for a phone below iOS 17, or whose
+     * version can't be read: it needs no tunnel. Throws when no pair of ports
+     * is left, or when the tunnel exits before it is ready.
      */
     ensure(udid) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const running = this.portFor(udid);
-            if (running !== undefined)
-                return running;
-            let version;
-            try {
-                version = yield this.iosVersion(udid);
-            }
-            catch (e) {
-                this.log.warn(`[${udid}] Could not read the iOS version, so no go-ios tunnel: ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}`);
-                return null;
+            return this.open(udid, 'stream');
+        });
+    }
+    /**
+     * The phone's tunnel-info port for a screenshot, which on iOS 17+ is
+     * reached only through the tunnel. A phone that isn't streaming has none,
+     * so one is started; it stays while screenshots keep coming and stops
+     * {@link TUNNEL_BORROW_IDLE_MS} after the last one (checkTunnels). Null and
+     * throws as ensure.
+     */
+    borrow(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.open(udid, 'screenshot');
+        });
+    }
+    /** Whether the phone's tunnel was opened for screenshots and no stream has taken it. */
+    isOnDemand(udid) {
+        const tunnel = this.tunnels.get(udid);
+        return !!tunnel && tunnel.process.exitCode === null && !tunnel.streamOwned;
+    }
+    open(udid, use) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const running = this.tunnels.get(udid);
+            if (running && running.process.exitCode === null) {
+                this.claim(running, use);
+                return running.whenReady;
             }
-            if (version < 17)
+            // A screenshot also asks on a simulator, which has no version to read.
+            const version = yield this.versionOf(udid, use === 'screenshot');
+            if (version === null || version < 17)
                 return null;
             const port = yield this.allocator().acquirePair('tunnel', udid, {
                 ttlMs: exports.TUNNEL_LEASE_TTL_MS,
@@ -126,7 +187,15 @@ let IOSTunnels = class IOSTunnels {
                 yield this.releasePair(port, udid);
                 throw e;
             }
-            const tunnel = { port, process: proc, ready: false };
+            const tunnel = {
+                port,
+                process: proc,
+                ready: false,
+                whenReady: Promise.resolve(port),
+                streamOwned: false,
+                borrowedUntil: 0,
+            };
+            this.claim(tunnel, use);
             this.tunnels.set(udid, tunnel);
             this.watch();
             // A tunnel whose process ends (go-ios crashed, or something killed it)
@@ -144,14 +213,30 @@ let IOSTunnels = class IOSTunnels {
                 this.log.warn(`[${udid}] go-ios tunnel failed: ${err.message}`);
                 ended();
             });
-            this.logOutput(udid, proc);
-            this.log.info(`[${udid}] iOS ${version}: starting a go-ios tunnel on ${port} (traffic on ${port + 1})`);
+            this.logOutput(udid, tunnel);
+            this.log.info(`[${udid}] iOS ${version}: starting a go-ios tunnel on ${port} (traffic on ${port + 1})` +
+                (use === 'screenshot' ? ' for screenshots' : ''));
+            // Whoever asks while it starts waits for the same start.
+            tunnel.whenReady = this.waitUntilReady(udid, tunnel);
+            return tunnel.whenReady;
+        });
+    }
+    claim(tunnel, use) {
+        if (use === 'stream')
+            tunnel.streamOwned = true;
+        else
+            tunnel.borrowedUntil = this.now() + exports.TUNNEL_BORROW_IDLE_MS;
+    }
+    waitUntilReady(udid, tunnel) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { port, process: proc } = tunnel;
             const polls = exports.TUNNEL_READY_TIMEOUT_MS / exports.TUNNEL_READY_POLL_MS;
             for (let poll = 0; poll <= polls; poll++) {
                 if (poll > 0)
                     yield this.sleep(exports.TUNNEL_READY_POLL_MS);
                 if (this.tunnels.get(udid) !== tunnel) {
-                    throw new Error(`The go-ios tunnel for ${udid} exited before it was ready (exit code ${proc.exitCode})`);
+                    throw new Error(`The go-ios tunnel for ${udid} exited before it was ready (exit code ${proc.exitCode})` +
+                        (tunnel.reason ? `: ${tunnel.reason}` : ''));
                 }
                 const info = yield this.tunnelInfo(port, udid);
                 if (moved(info, port)) {
@@ -170,6 +255,33 @@ let IOSTunnels = class IOSTunnels {
             return port;
         });
     }
+    /**
+     * The phone's iOS version, from `ios info`, kept for VERSION_CACHE_MS: a
+     * screenshot on a phone below iOS 17 would otherwise ask every time. Null
+     * when it can't be read (not cached, so a phone still pairing is asked
+     * again); logged at debug when `quiet`.
+     */
+    versionOf(udid_1) {
+        return __awaiter(this, arguments, void 0, function* (udid, quiet = false) {
+            var _a;
+            const cached = this.versionCache.get(udid);
+            if (cached && this.now() - cached.at < VERSION_CACHE_MS)
+                return cached.version;
+            try {
+                const version = yield this.iosVersion(udid);
+                this.versionCache.set(udid, { version, at: this.now() });
+                return version;
+            }
+            catch (e) {
+                const message = `[${udid}] Could not read the iOS version, so no go-ios tunnel: ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}`;
+                if (quiet)
+                    this.log.debug(message);
+                else
+                    this.log.warn(message);
+                return null;
+            }
+        });
+    }
     /** The phone's tunnel-info port, while its tunnel runs. */
     portFor(udid) {
         const tunnel = this.tunnels.get(udid);
@@ -217,6 +329,11 @@ let IOSTunnels = class IOSTunnels {
             this.checking = true;
             try {
                 for (const [udid, tunnel] of [...this.tunnels]) {
+                    if (!tunnel.streamOwned && tunnel.borrowedUntil <= this.now()) {
+                        this.log.info(`[${udid}] go-ios tunnel on ${tunnel.port}, opened for screenshots, is idle; stopping it`);
+                        yield this.stop(udid);
+                        continue;
+                    }
                     const info = yield this.tunnelInfo(tunnel.port, udid);
                     if (this.tunnels.get(udid) !== tunnel)
                         continue;
@@ -278,13 +395,16 @@ let IOSTunnels = class IOSTunnels {
     }
     /**
      * go-ios's output, at debug. Its repeated warning about a connected
-     * pre-iOS 17 phone (which needs no tunnel) is logged once per phone.
+     * pre-iOS 17 phone (which needs no tunnel) is logged once per phone. Its
+     * last error or warning is kept, for the error if the tunnel fails.
      */
-    logOutput(udid, proc) {
+    logOutput(udid, tunnel) {
         var _a, _b;
+        const proc = tunnel.process;
         (_a = proc.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (data) => this.log.debug(`Tunnel [${udid}]: ${data}`));
         const loggedUnsupported = new Set();
         (_b = proc.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (data) => {
+            var _a;
             const text = String(data);
             const { unsupported, udid: targetUdid } = (0, iosStreamDiagnostics_1.classifyTunnelStderr)(text);
             if (unsupported) {
@@ -295,6 +415,7 @@ let IOSTunnels = class IOSTunnels {
                 }
                 return;
             }
+            tunnel.reason = (_a = goIosReason(text)) !== null && _a !== void 0 ? _a : tunnel.reason;
             this.log.debug(`Tunnel Err [${udid}]: ${text}`);
         });
     }
@@ -360,6 +481,9 @@ let IOSTunnels = class IOSTunnels {
             req.on('error', () => resolve({ state: 'unknown' }));
         });
     }
+    now() {
+        return Date.now();
+    }
     sleep(ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     }

package/lib/src/device-managers/ios/WDAClient.js

@@ -395,12 +395,20 @@ let WDAClient = WDAClient_1 = class WDAClient {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             const s = typedi_1.Container.get(IOSStreamService_1.default);
+            let tunnelError;
             if (yield s.isGoIOSAvailable()) {
                 try {
+                    // On iOS 17+ go-ios reaches the screenshot service only through the
+                    // phone's own tunnel, and a phone that isn't streaming has none: open
+                    // one, kept while screenshots keep coming (see IOSTunnels.borrow).
+                    const tunnels = typedi_1.Container.get(IOSTunnels_1.IOSTunnels);
+                    yield tunnels.borrow(udid).catch((e) => {
+                        tunnelError = e;
+                        throw e;
+                    });
                     const p = path_1.default.join(os_1.default.tmpdir(), `screenshot-${udid}.png`);
                     yield execFilePromise(s.goIOSPath, ['screenshot', '--udid', udid, '--output', p], {
-                        // This phone's own go-ios tunnel on iOS 17+ (see IOSTunnels).
-                        env: typedi_1.Container.get(IOSTunnels_1.IOSTunnels).envFor(udid),
+                        env: tunnels.envFor(udid),
                     });
                     const b = yield fs_extra_1.default.readFile(p);
                     yield fs_extra_1.default.remove(p);
@@ -410,8 +418,14 @@ let WDAClient = WDAClient_1 = class WDAClient {
                     this.log.debug(`go-ios screenshot failed for ${udid}: ${e.message}\n${e.stack}`);
                 }
             }
-            const res = yield this.sendWDACommand(udid, 'get', '/screenshot');
-            return ((_b = (_a = res.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.screenshot) || ((_c = res.data) === null || _c === void 0 ? void 0 : _c.value) || '';
+            try {
+                const res = yield this.sendWDACommand(udid, 'get', '/screenshot');
+                return ((_b = (_a = res.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.screenshot) || ((_c = res.data) === null || _c === void 0 ? void 0 : _c.value) || '';
+            }
+            catch (e) {
+                // WebDriverAgent couldn't answer either; the tunnel's reason says more.
+                throw tunnelError !== null && tunnelError !== void 0 ? tunnelError : e;
+            }
         });
     }
     getClipboard(udid) {

package/lib/test/unit/ios-go-ios-tunnel-env.spec.js

@@ -43,13 +43,33 @@ case "$1" in
   syslog) printf '{"msg":"port=%s"}\\n' "$GO_IOS_AGENT_PORT"; exec sleep 5 ;;
 esac
 `;
-/** IOSTunnels as if WITH_TUNNEL's tunnel ran on 12100 and NO_TUNNEL had none. */
+/** iOS 17+, not streaming: it has a tunnel only once one is opened for it. */
+const NEEDS_TUNNEL = 'test-iphone-idle-00008120';
+/**
+ * IOSTunnels as if WITH_TUNNEL's tunnel ran on 12100, NO_TUNNEL needed none
+ * (below iOS 17), and NEEDS_TUNNEL got one on 12102 once borrowed.
+ */
 const tunnels = {
+    borrowed: new Set(),
+    borrowCalls: [],
+    borrowError: undefined,
+    borrow(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.borrowCalls.push(udid);
+            if (this.borrowError)
+                throw this.borrowError;
+            if (udid === NEEDS_TUNNEL)
+                this.borrowed.add(udid);
+            return udid === WITH_TUNNEL ? 12100 : udid === NEEDS_TUNNEL ? 12102 : null;
+        });
+    },
     envFor(udid) {
         const env = Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' });
         delete env.GO_IOS_AGENT_PORT;
         if (udid === WITH_TUNNEL)
             env.GO_IOS_AGENT_PORT = '12100';
+        if (this.borrowed.has(udid))
+            env.GO_IOS_AGENT_PORT = '12102';
         return env;
     },
 };
@@ -63,6 +83,9 @@ describe("go-ios commands find their own phone's tunnel (GO_IOS_AGENT_PORT)", ()
     });
     after(() => fs_1.default.rmSync(dir, { recursive: true, force: true }));
     beforeEach(() => {
+        tunnels.borrowed.clear();
+        tunnels.borrowCalls = [];
+        tunnels.borrowError = undefined;
         const real = typedi_1.Container.get.bind(typedi_1.Container);
         sinon_1.default.stub(typedi_1.Container, 'get').callsFake((token) => {
             if (token === IOSTunnels_1.IOSTunnels)
@@ -88,6 +111,20 @@ describe("go-ios commands find their own phone's tunnel (GO_IOS_AGENT_PORT)", ()
             const png = yield new WDAClient_1.WDAClient().getScreenshot(NO_TUNNEL);
             (0, chai_1.expect)(Buffer.from(png, 'base64').toString()).to.equal('port=');
         }));
+        // On iOS 17+ the screenshot service is reached only through the tunnel,
+        // and a phone that isn't streaming has none.
+        it("opens the phone's tunnel for a screenshot when it has none", () => __awaiter(void 0, void 0, void 0, function* () {
+            const png = yield new WDAClient_1.WDAClient().getScreenshot(NEEDS_TUNNEL);
+            (0, chai_1.expect)(tunnels.borrowCalls).to.deep.equal([NEEDS_TUNNEL]);
+            (0, chai_1.expect)(Buffer.from(png, 'base64').toString()).to.equal('port=12102');
+        }));
+        it("says why, when the tunnel can't start and WebDriverAgent can't answer either", () => __awaiter(void 0, void 0, void 0, function* () {
+            tunnels.borrowError = new Error('The go-ios tunnel for X exited before it was ready (exit code 1): failed to start tunnel: EOF');
+            const client = new WDAClient_1.WDAClient();
+            sinon_1.default.stub(client, 'sendWDACommand').rejects(new Error('connect ECONNREFUSED'));
+            const err = yield client.getScreenshot(NEEDS_TUNNEL).then(() => null, (e) => e);
+            (0, chai_1.expect)(err === null || err === void 0 ? void 0 : err.message).to.match(/exited before it was ready .*failed to start tunnel: EOF/);
+        }));
     });
     describe('the logs read (WDAClient syslog)', () => {
         let client;

package/lib/test/unit/ios-stream-appium-tunnel.spec.js

@@ -198,6 +198,7 @@ describe('go-ios tunnels under a live Appium session (fake exec, fake processes)
             envFor: sinon_1.default.stub().callsFake(() => (Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }))),
             stop: sinon_1.default.stub().resolves(),
             touch: sinon_1.default.stub().resolves(),
+            isOnDemand: sinon_1.default.stub().returns(false),
         };
         svc = iosService();
         const real = typedi_1.Container.get.bind(typedi_1.Container);
@@ -363,6 +364,15 @@ describe('go-ios tunnels under a live Appium session (fake exec, fake processes)
             (0, chai_1.expect)(defaultPorts()).to.deep.equal([]);
         }));
     });
+    describe('a start on a phone whose tunnel was opened for screenshots', () => {
+        it('takes that tunnel over, neither stopping nor reaping it', () => __awaiter(void 0, void 0, void 0, function* () {
+            Object.assign(device, { busy: false, session_id: null });
+            tunnels.isOnDemand.withArgs(IPHONE).returns(true);
+            yield svc.cleanupOrphanTunnels(IPHONE);
+            (0, chai_1.expect)(tunnels.stop.called, 'the tracked tunnel').to.equal(false);
+            (0, chai_1.expect)(swept(), 'no pgrep reap of its process').to.deep.equal([]);
+        }));
+    });
     describe('boot', () => {
         it('reaps every go-ios process, then drops every tunnel port lease', () => __awaiter(void 0, void 0, void 0, function* () {
             yield svc.reapOrphanTunnels();

package/lib/test/unit/ios-stream-port-leases.spec.js

@@ -108,6 +108,8 @@ describe('iOS stream port leases (fake processes, real sockets, scratch DB)', ()
     let appiumWdaPorts;
     let ios;
     let android;
+    /** The stream's runwda exits at once, as when WebDriverAgent fails to launch. */
+    let runwdaExits;
     let tunnels;
     beforeEach(() => {
         allocator = new PortAllocator_1.PortAllocator();
@@ -123,6 +125,7 @@ describe('iOS stream port leases (fake processes, real sockets, scratch DB)', ()
         spawned = [];
         extraServers = [];
         appiumWdaPorts = new Set();
+        runwdaExits = false;
         tunnels = {
             ensure: sinon_1.default.stub().resolves(null),
             envFor: sinon_1.default.stub().callsFake(() => (Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }))),
@@ -150,6 +153,8 @@ describe('iOS stream port leases (fake processes, real sockets, scratch DB)', ()
                 server = listenNow(Number(args[args.length - 1].split(':')[0]));
             }
             const proc = new FakeProcess(command, args, server, opts);
+            if (runwdaExits && args[0] === 'runwda')
+                proc.exitCode = 1;
             spawned.push(proc);
             return proc;
         }));
@@ -236,6 +241,27 @@ describe('iOS stream port leases (fake processes, real sockets, scratch DB)', ()
         const runwda = spawned.find((p) => p.command === ios.goIOSPath && p.args[0] === 'runwda');
         (0, chai_1.expect)((_c = (_b = runwda === null || runwda === void 0 ? void 0 : runwda.opts) === null || _b === void 0 ? void 0 : _b.env) === null || _c === void 0 ? void 0 : _c.GO_IOS_AGENT_PORT, "runwda finds this phone's tunnel").to.equal('12100');
     }));
+    describe("a start whose WebDriverAgent fails after the iPhone's tunnel came up", () => {
+        beforeEach(() => {
+            tunnels.ensure.resolves(12100);
+            runwdaExits = true;
+            sinon_1.default.stub(ios, 'isGoIOSAvailable').resolves(true);
+        });
+        it('stops that tunnel, so it neither lingers nor holds its ports', () => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b;
+            const err = yield ios.startStream(IPHONE).then(() => null, (e) => e);
+            (0, chai_1.expect)(err === null || err === void 0 ? void 0 : err.message).to.match(/WDA process exited/);
+            (0, chai_1.expect)(tunnels.stop.calledWith(IPHONE)).to.equal(true);
+            (0, chai_1.expect)((_a = ios.getStreamStatus(IPHONE)) === null || _a === void 0 ? void 0 : _a.status).to.equal('error');
+            (0, chai_1.expect)((_b = ios.getStreamStatus(IPHONE)) === null || _b === void 0 ? void 0 : _b.tunnelPort).to.equal(null);
+        }));
+        it('leaves it running while an Appium session holds the iPhone', () => __awaiter(void 0, void 0, void 0, function* () {
+            Object.assign(devices.get(IPHONE), { busy: true, session_id: '7f0c5a52-appium-session' });
+            const err = yield ios.startStream(IPHONE).then(() => null, (e) => e);
+            (0, chai_1.expect)(err === null || err === void 0 ? void 0 : err.message).to.match(/WDA process exited/);
+            (0, chai_1.expect)(tunnels.stop.called).to.equal(false);
+        }));
+    });
     it('stopping a stale iOS session never deletes a lease another device holds', () => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
         // The S9+ has since been leased the port the stale iPhone session names.

package/lib/test/unit/ios-tunnels.spec.js

@@ -80,10 +80,16 @@ class TestTunnels extends IOSTunnels_1.IOSTunnels {
         /** Each tunnel-info poll: true is the phone's tunnel on P + 1, false a 404. */
         this.answers = () => true;
         this.ports = fakeAllocator();
+        this.clock = 1000000;
+        this.versionReads = 0;
         this.nextPid = 7000;
     }
+    now() {
+        return this.clock;
+    }
     iosVersion(udid) {
         return __awaiter(this, void 0, void 0, function* () {
+            this.versionReads += 1;
             const version = this.versions.get(udid);
             if (version === undefined)
                 throw new Error(`no such phone: ${udid}`);
@@ -181,6 +187,18 @@ describe('IOSTunnels: a go-ios tunnel per iPhone', () => {
         (0, chai_1.expect)(t.portFor(PHONE_A)).to.equal(undefined);
         (0, chai_1.expect)([...t.ports.leased.keys()]).to.deep.equal([]);
     }));
+    it("says why the tunnel exited before it was ready, in go-ios's words", () => __awaiter(void 0, void 0, void 0, function* () {
+        t.answers = () => {
+            const proc = t.spawned[0].proc;
+            proc.stderr.emit('data', Buffer.from('{"level":"INFO","msg":"Using userspace networking"}\n' +
+                '{"level":"ERROR","msg":"failed to start tunnel","error":"listen tcp 127.0.0.1:12101: bind: address already in use"}\n'));
+            proc.exit(1);
+            return false;
+        };
+        const err = yield t.ensure(PHONE_A).then(() => null, (e) => e);
+        (0, chai_1.expect)(err === null || err === void 0 ? void 0 : err.message).to.equal(`The go-ios tunnel for ${PHONE_A} exited before it was ready (exit code 1): ` +
+            'failed to start tunnel: listen tcp 127.0.0.1:12101: bind: address already in use');
+    }));
     it('fails the start when the tunnel comes up on another traffic port, and stops it', () => __awaiter(void 0, void 0, void 0, function* () {
         t.answers = () => ({ state: 'up', userspacePort: 12102 });
         const err = yield t.ensure(PHONE_A).then(() => null, (e) => e);
@@ -320,6 +338,78 @@ describe('IOSTunnels: a phone that goes away (go-ios keeps its agent running)',
         }
     }));
 });
+// A screenshot on iOS 17+ goes through the phone's tunnel, and a phone that
+// isn't streaming has none: one is opened for screenshots and kept while they
+// keep coming.
+describe('IOSTunnels: a tunnel opened for screenshots', () => {
+    let t;
+    beforeEach(() => {
+        sinon_1.default.stub(process, 'kill');
+        t = new TestTunnels();
+        t.versions.set(PHONE_A, 17.4);
+    });
+    afterEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        yield t.stop(PHONE_A);
+        sinon_1.default.restore();
+    }));
+    it('opens one when the phone has none, and the next screenshot reuses it', () => __awaiter(void 0, void 0, void 0, function* () {
+        (0, chai_1.expect)(yield t.borrow(PHONE_A)).to.equal(12100);
+        (0, chai_1.expect)(yield t.borrow(PHONE_A)).to.equal(12100);
+        (0, chai_1.expect)(t.spawned.length).to.equal(1);
+        (0, chai_1.expect)(t.envFor(PHONE_A).GO_IOS_AGENT_PORT).to.equal('12100');
+    }));
+    it('stops it 2 minutes after the last screenshot, and gives its ports back', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield t.borrow(PHONE_A);
+        t.clock += IOSTunnels_1.TUNNEL_BORROW_IDLE_MS - 1000;
+        yield t.borrow(PHONE_A); // another screenshot: the 2 minutes start again
+        t.clock += IOSTunnels_1.TUNNEL_BORROW_IDLE_MS - 1000;
+        yield t.checkTunnels();
+        (0, chai_1.expect)(t.portFor(PHONE_A), 'last used 119 s ago').to.equal(12100);
+        t.clock += 2000;
+        yield t.checkTunnels();
+        yield settle();
+        (0, chai_1.expect)(t.portFor(PHONE_A)).to.equal(undefined);
+        (0, chai_1.expect)(t.killed).to.deep.equal([t.spawned[0].proc.pid]);
+        (0, chai_1.expect)([...t.ports.leased.keys()]).to.deep.equal([]);
+    }));
+    it('never stops one a stream took over', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield t.borrow(PHONE_A);
+        (0, chai_1.expect)(t.isOnDemand(PHONE_A)).to.equal(true);
+        (0, chai_1.expect)(yield t.ensure(PHONE_A), 'the stream takes it').to.equal(12100);
+        (0, chai_1.expect)(t.isOnDemand(PHONE_A)).to.equal(false);
+        t.clock += 10 * IOSTunnels_1.TUNNEL_BORROW_IDLE_MS;
+        yield t.checkTunnels();
+        (0, chai_1.expect)(t.portFor(PHONE_A)).to.equal(12100);
+        (0, chai_1.expect)(t.spawned.length).to.equal(1);
+    }));
+    it("never stops a stream's own tunnel for being idle", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield t.ensure(PHONE_A);
+        yield t.borrow(PHONE_A); // a screenshot while the stream runs
+        t.clock += 10 * IOSTunnels_1.TUNNEL_BORROW_IDLE_MS;
+        yield t.checkTunnels();
+        (0, chai_1.expect)(t.portFor(PHONE_A)).to.equal(12100);
+        (0, chai_1.expect)(t.isOnDemand(PHONE_A)).to.equal(false);
+    }));
+    it('opens none for a phone below iOS 17, and reads its version once', () => __awaiter(void 0, void 0, void 0, function* () {
+        t.versions.set('old-iphone', 16.7);
+        (0, chai_1.expect)(yield t.borrow('old-iphone')).to.equal(null);
+        (0, chai_1.expect)(yield t.borrow('old-iphone')).to.equal(null);
+        (0, chai_1.expect)(t.versionReads).to.equal(1);
+        (0, chai_1.expect)(t.spawned).to.deep.equal([]);
+    }));
+});
+describe('goIosReason', () => {
+    it("reads go-ios's last error or warning", () => {
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('{"level":"INFO","msg":"Tunnel server started"}\n')).to.equal(undefined);
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('{"level":"WARN","msg":"failed to get tunnel info","udid":"X"}')).to.equal('failed to get tunnel info');
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('{"level":"ERROR","msg":"first"}\n{"level":"ERROR","msg":"failed to start tunnel","error":"EOF"}\n')).to.equal('failed to start tunnel: EOF');
+    });
+    it('keeps a line that is not JSON, trimmed and at most 200 characters', () => {
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('  panic: runtime error  \n')).to.equal('panic: runtime error');
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('x'.repeat(500))).to.have.length(200);
+        (0, chai_1.expect)((0, IOSTunnels_1.goIosReason)('\n  \n')).to.equal(undefined);
+    });
+});
 describe('iosVersionOf', () => {
     it('reads the version ios info reports', () => {
         (0, chai_1.expect)((0, IOSTunnels_1.iosVersionOf)({ ProductVersion: '17.2.1' })).to.equal(17.2);