@xenon-device-management/xenon 2.8.3 → 2.9.0

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

@@ -18,7 +18,7 @@ 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;
 /**
@@ -69,6 +69,13 @@ 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');
@@ -118,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,
@@ -161,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)
@@ -180,7 +214,22 @@ let IOSTunnels = class IOSTunnels {
                 ended();
             });
             this.logOutput(udid, tunnel);
-            this.log.info(`[${udid}] iOS ${version}: starting a go-ios tunnel on ${port} (traffic on ${port + 1})`);
+            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)
@@ -206,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);
@@ -253,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;
@@ -400,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-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}`);
@@ -332,6 +338,66 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xenon-device-management/xenon",
-  "version": "2.8.3",
+  "version": "2.9.0",
   "description": "Xenon - Intelligent Mobile Infrastructure. A self-healing device orchestration platform for Appium.",
   "main": "./lib/src/index.js",
   "exports": {