@xenon-device-management/xenon 2.14.0 → 2.15.0

package/lib/src/device-managers/android/AndroidH264StreamService.js

@@ -93,27 +93,34 @@ let AndroidH264StreamService = class AndroidH264StreamService {
     startWatchdog() {
         // unref()ed below: the server's listener keeps the process alive; this only
         // needs to fire while it runs.
-        setInterval(() => {
-            const now = Date.now();
-            for (const [udid, s] of this.sessions.entries()) {
-                if (s.status !== 'running')
-                    continue;
-                if (s.mux.clientCount > 0) {
-                    s.emptyAt = undefined;
-                }
-                else if (s.emptyAt === undefined) {
-                    s.emptyAt = now;
-                }
-                else if (now - s.emptyAt > IDLE_TIMEOUT_MS) {
-                    logger_1.default.info(`[${udid}] Stopping idle H.264 stream (no viewers for ${IDLE_TIMEOUT_MS}ms)`);
-                    // The stream went, but the live-preview hold stayed: with H.264
-                    // preview, a tab closed without releasing kept the device busy for
-                    // good. stop() itself must not release (a recording starting calls
-                    // it); an idle stop does, if nothing else uses the device.
-                    void this.stop(udid).then(() => (0, previewHold_1.releaseIdlePreviewHold)(udid));
-                }
+        setInterval(() => this.sweep(Date.now()), 60000).unref();
+    }
+    /** One look at every capture: ends those nobody has watched for long enough. */
+    sweep(now) {
+        for (const [udid, s] of this.sessions.entries()) {
+            if (s.status !== 'running')
+                continue;
+            if (s.mux.clientCount > 0) {
+                s.emptyAt = undefined;
+            }
+            else if (s.endWhenUnwatched && !this.startPromises.has(udid)) {
+                // A page asked for MJPEG while this capture was starting for a viewer
+                // who then never came (endWhenUnwatched leaves a start alone).
+                logger_1.default.info(`[${udid}] Stopping the unwatched H.264 stream: the phone is shown as MJPEG`);
+                void this.stop(udid);
             }
-        }, 60000).unref();
+            else if (s.emptyAt === undefined) {
+                s.emptyAt = now;
+            }
+            else if (now - s.emptyAt > IDLE_TIMEOUT_MS) {
+                logger_1.default.info(`[${udid}] Stopping idle H.264 stream (no viewers for ${IDLE_TIMEOUT_MS}ms)`);
+                // The stream went, but the live-preview hold stayed: with H.264
+                // preview, a tab closed without releasing kept the device busy for
+                // good. stop() itself must not release (a recording starting calls
+                // it); an idle stop does, if nothing else uses the device.
+                void this.stop(udid).then(() => (0, previewHold_1.releaseIdlePreviewHold)(udid));
+            }
+        }
     }
     getMultiplexer(udid) {
         var _a;
@@ -131,6 +138,7 @@ let AndroidH264StreamService = class AndroidH264StreamService {
                 var _a, _b;
                 const mux = new H264Multiplexer_1.H264Multiplexer();
                 const session = { status: 'running', mux };
+                mux.onEmpty(() => this.endIfUnwatched(udid, session));
                 this.sessions.set(udid, session);
                 try {
                     let resolveConfig = () => undefined;
@@ -178,6 +186,44 @@ let AndroidH264StreamService = class AndroidH264StreamService {
             }
         });
     }
+    /**
+     * A page that showed this phone's H.264 preview now shows MJPEG (its player
+     * failed, or it cannot play H.264), and the MJPEG capture is starting for
+     * it. One capture per phone where possible, but never at the expense of a
+     * viewer still playing H.264: another tile, tab or admin may be. So the
+     * capture ends now if nobody watches it, else the moment its last viewer
+     * leaves, never after the idle wait. A viewer who joins meanwhile is served
+     * and ends it in turn. A capture still starting is left to the viewer it is
+     * starting for, and the watchdog ends it if that viewer never comes.
+     */
+    endWhenUnwatched(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = this.sessions.get(udid);
+            if (!session || session.status !== 'running')
+                return;
+            session.endWhenUnwatched = true;
+            const viewers = session.mux.clientCount;
+            if (viewers > 0) {
+                logger_1.default.info(`[${udid}] H.264 stream kept beside MJPEG for its ${viewers} viewer(s); ` +
+                    'it ends when the last one leaves');
+                return;
+            }
+            if (this.startPromises.has(udid)) {
+                logger_1.default.info(`[${udid}] H.264 stream still starting: kept for the viewer it is starting for`);
+                return;
+            }
+            logger_1.default.info(`[${udid}] Stopping the unwatched H.264 stream: the phone is shown as MJPEG`);
+            yield this.stop(udid);
+        });
+    }
+    /** The last viewer left `session`: end it if a page asked (endWhenUnwatched). */
+    endIfUnwatched(udid, session) {
+        // A capture replaced since (a stop and a new start) is not this one.
+        if (this.sessions.get(udid) !== session || !session.endWhenUnwatched)
+            return;
+        logger_1.default.info(`[${udid}] Stopping the H.264 stream: its last viewer left, the phone is shown as MJPEG`);
+        void this.stop(udid);
+    }
     stop(udid) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -192,6 +238,9 @@ let AndroidH264StreamService = class AndroidH264StreamService {
                 /* best-effort */
             }
             this.sessions.delete(udid);
+            // Viewers still on it (a recording starting, a stream/stop) are told, so
+            // their players fall back to MJPEG instead of freezing on the last frame.
+            session.mux.close();
             logger_1.default.info(`[${udid}] H.264 stream terminated.`);
         });
     }

package/lib/src/device-managers/android/H264Multiplexer.js

@@ -9,6 +9,7 @@ class H264Multiplexer {
     constructor() {
         this.clients = new Set();
         this.gop = []; // current GOP: [keyframe, ...deltas-since]
+        this.closed = false;
     }
     setConfig(p) {
         this.config = p;
@@ -16,9 +17,21 @@ class H264Multiplexer {
     get clientCount() {
         return this.clients.size;
     }
-    /** Register a client sink. Returns a remover. */
-    addClient(send) {
-        const c = { send, started: false };
+    /** Called each time the last client leaves. */
+    onEmpty(listener) {
+        this.emptyListener = listener;
+    }
+    /**
+     * Register a client sink, and how to end it when the stream does (see
+     * `close`). Returns a remover (safe to call twice).
+     */
+    addClient(send, end) {
+        const c = { send, started: false, end };
+        if (this.closed) {
+            // Joined a stream already stopped: end it now rather than starve it.
+            end === null || end === void 0 ? void 0 : end();
+            return () => undefined;
+        }
         this.clients.add(c);
         if (this.config)
             send(this.config);
@@ -29,9 +42,30 @@ class H264Multiplexer {
             c.started = true;
         }
         return () => {
-            this.clients.delete(c);
+            var _a;
+            if (this.clients.delete(c) && this.clients.size === 0)
+                (_a = this.emptyListener) === null || _a === void 0 ? void 0 : _a.call(this);
         };
     }
+    /**
+     * The capture stopped: end every client (its socket closes, so its player
+     * falls back to MJPEG instead of freezing on its last frame). Not an
+     * `onEmpty`: nobody left, the stream did.
+     */
+    close() {
+        var _a;
+        this.closed = true;
+        const ending = [...this.clients];
+        this.clients.clear();
+        for (const c of ending) {
+            try {
+                (_a = c.end) === null || _a === void 0 ? void 0 : _a.call(c);
+            }
+            catch (_b) {
+                /* one client's end must not keep the others open */
+            }
+        }
+    }
     /** Feed one upstream packet; fans out per the join semantics above. */
     push(p) {
         if (p.type === 'config') {

package/lib/src/device-utils.js

@@ -648,7 +648,7 @@ function unblockCandidateDevices() {
 }
 function releaseBlockedDevices(newCommandTimeout) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b;
+        var _a, _b, _c;
         const busyDevices = yield unblockCandidateDevices();
         // A phone an SDK lease holds is the lease's to time out (its heartbeats and
         // expiry, LeaseOrphanSweeper), not idle until a session runs on it. A lease
@@ -698,6 +698,7 @@ function releaseBlockedDevices(newCommandTimeout) {
                 logger_1.default.info(`Unblocking device ${device.udid} at host ${device.host} because it has been idle for ${timeSinceLastCmdExecuted} seconds`);
                 // Before anything below can release the phone (onSessionStopped too).
                 yield restoreIdleSessionNetwork((_a = device.claimSessionId) !== null && _a !== void 0 ? _a : device.session_id);
+                yield forgetIdleSessionMemory((_b = device.claimSessionId) !== null && _b !== void 0 ? _b : device.session_id);
                 // Principal Protection: If this device has an active dashboard session, stop it properly
                 if (device.session_id) {
                     const sessionId = device.session_id;
@@ -713,7 +714,7 @@ function releaseBlockedDevices(newCommandTimeout) {
                 }
                 // Keyed on the session read here, so a release that loses the race to
                 // the session's own end (and the phone's next claim) frees nothing.
-                const claimant = (_b = device.claimSessionId) !== null && _b !== void 0 ? _b : device.session_id;
+                const claimant = (_c = device.claimSessionId) !== null && _c !== void 0 ? _c : device.session_id;
                 yield (claimant
                     ? (0, device_service_1.releaseSessionDevice)(device.udid, device.host, claimant)
                     : (0, device_service_1.unblockDevice)(device.udid, device.host)).catch((err) => logger_1.default.error(`Unable to release ${device.udid}: ${err}`));
@@ -739,6 +740,23 @@ function restoreIdleSessionNetwork(sessionId) {
         }
     });
 }
+/**
+ * The idle session's virtual elements and autowait settings
+ * (sessionMemory.ts). Imported lazily, as above. Never throws.
+ */
+function forgetIdleSessionMemory(sessionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!sessionId)
+            return;
+        try {
+            const { forgetSessionMemory } = yield Promise.resolve().then(() => __importStar(require('./sessions/sessionMemory')));
+            forgetSessionMemory(sessionId);
+        }
+        catch (err) {
+            logger_1.default.warn(`Could not forget idle session ${sessionId}'s elements: ${err}`);
+        }
+    });
+}
 function setupCronReleaseBlockedDevices(intervalMs, newCommandTimeoutSec) {
     return __awaiter(this, void 0, void 0, function* () {
         if (cronTimerToReleaseBlockedDevices) {

package/lib/src/gateway/defaultGateway.js

@@ -34,7 +34,7 @@ const createWith = (hubGrants) => ({
 });
 const dashboardHooks = {
     before: (sessionId, command, req, res) => event_manager_1.DASHBORD_EVENT_MANAGER.beforeSessionCommand(sessionId, command, req, res),
-    after: (sessionId, command, req, res, body) => event_manager_1.DASHBORD_EVENT_MANAGER.afterSessionCommand(sessionId, command, null, req, res, body),
+    after: (sessionId, command, req, res, body, heal) => event_manager_1.DASHBORD_EVENT_MANAGER.afterSessionCommand(sessionId, command, null, req, res, body, heal),
 };
 /** A hub: sessions other servers run are forwarded to them. */
 function hubGatewayOptions(config) {

package/lib/src/gateway/forwardToNode.js

@@ -15,6 +15,7 @@ const https_proxy_agent_1 = require("https-proxy-agent");
 const http_proxy_agent_1 = require("http-proxy-agent");
 const internalCall_1 = require("./internalCall");
 const hubSessionToken_1 = require("./hubSessionToken");
+const healReport_1 = require("./healReport");
 /**
  * Sending a session command on to the node that runs the session, and handing
  * the node's answer back to the client unchanged.
@@ -44,6 +45,7 @@ const NEVER_FORWARDED = new Set([
     'x-xenon-token',
     internalCall_1.INTERNAL_CALL_HEADER,
     hubSessionToken_1.HUB_TOKEN_HEADER,
+    healReport_1.HEAL_REPORT_HEADER,
 ]);
 function forwardedRequestHeaders(incoming) {
     const out = {};

package/lib/src/gateway/healReport.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HEAL_REPORT_HEADER = void 0;
+exports.runReportingHeals = runReportingHeals;
+exports.reportHeal = reportHeal;
+exports.takeHealReport = takeHealReport;
+const async_hooks_1 = require("async_hooks");
+/**
+ * A heal on a node's phone, on its way back to the hub.
+ *
+ * A session the hub created runs its commands on the node, so the node's
+ * CommandInterceptor heals its finds. The node keeps no record of such a
+ * session; the hub does. So the node puts the heal on its answer to the
+ * forwarded command, as the `x-xenon-heal` header, and the hub takes it off
+ * before relaying the answer and records it with the command, as it records a
+ * local session's heal.
+ *
+ * The node's session gateway runs a command that came from a hub inside
+ * `runReportingHeals`, so the interceptor, deep inside Appium's route, finds
+ * the answer to put it on. Anywhere else `reportHeal` does nothing, and the
+ * server records the heal itself.
+ */
+exports.HEAL_REPORT_HEADER = 'x-xenon-heal';
+/**
+ * A header longer than this isn't sent: the hub's HTTP parser refuses an
+ * answer whose headers pass 16 KB, and a refused answer would fail the
+ * command. A heal of selectors that long goes unrecorded instead.
+ */
+const MAX_HEADER_LENGTH = 8 * 1024;
+const answers = new async_hooks_1.AsyncLocalStorage();
+/** Run the rest of a command that came from a hub with its answer at hand. */
+function runReportingHeals(res, fn) {
+    const answer = { res };
+    const forget = () => {
+        answer.res = null;
+    };
+    res.once('finish', forget);
+    res.once('close', forget);
+    return answers.run(answer, fn);
+}
+/**
+ * Put `heal` on the answer to the hub's command this code runs for.
+ * `not-from-hub` when the command didn't come from a hub (or the answer has
+ * gone): the caller records the heal itself.
+ */
+function reportHeal(heal) {
+    var _a;
+    const res = (_a = answers.getStore()) === null || _a === void 0 ? void 0 : _a.res;
+    if (!res || res.headersSent)
+        return 'not-from-hub';
+    const encoded = Buffer.from(JSON.stringify(heal), 'utf8').toString('base64url');
+    if (encoded.length > MAX_HEADER_LENGTH)
+        return 'too-long';
+    res.setHeader(exports.HEAL_REPORT_HEADER, encoded);
+    return 'reported';
+}
+/**
+ * The heal a node put on its answer, taken off the headers so it isn't
+ * relayed to the client. Undefined when there is none, or it isn't one.
+ */
+function takeHealReport(headers) {
+    const raw = headers[exports.HEAL_REPORT_HEADER];
+    delete headers[exports.HEAL_REPORT_HEADER];
+    if (typeof raw !== 'string' || !raw)
+        return undefined;
+    try {
+        const heal = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+        if (!heal ||
+            typeof heal.originalSelector !== 'string' ||
+            typeof heal.healedSelector !== 'string' ||
+            typeof heal.confidence !== 'number') {
+            return undefined;
+        }
+        const optional = (v) => (typeof v === 'string' ? v : undefined);
+        return {
+            originalSelector: heal.originalSelector,
+            originalStrategy: optional(heal.originalStrategy),
+            healedSelector: heal.healedSelector,
+            healedStrategy: optional(heal.healedStrategy),
+            confidence: heal.confidence,
+            tier: typeof heal.tier === 'number' ? heal.tier : undefined,
+        };
+    }
+    catch (_a) {
+        return undefined;
+    }
+}

package/lib/src/gateway/sessionGateway.js

@@ -15,6 +15,7 @@ exports.createHubRouting = createHubRouting;
 const commandAuth_1 = require("../middleware/commandAuth");
 const internalCall_1 = require("./internalCall");
 const hubSessionToken_1 = require("./hubSessionToken");
+const healReport_1 = require("./healReport");
 const forwardToNode_1 = require("./forwardToNode");
 /** Where a session runs could not be determined (a database error). */
 exports.ROUTING_UNAVAILABLE_STATUS = 503;
@@ -62,7 +63,14 @@ function createSessionGatewayLayer(deps) {
             const latency = (_b = (_a = deps.latencyOf) === null || _a === void 0 ? void 0 : _a.call(deps, sessionId)) !== null && _b !== void 0 ? _b : 0;
             if (latency > 0)
                 yield new Promise((resolve) => setTimeout(resolve, latency));
-            next();
+            // On a node, a heal of the hub's command goes back to the hub on the answer
+            // (healReport.ts). The header proves nothing elsewhere: a hub or a
+            // standalone server checks no hub token, so a client could send one there
+            // to keep its heals out of the record.
+            if (fromHub && deps.hubTokens)
+                (0, healReport_1.runReportingHeals)(res, next);
+            else
+                next();
         });
     }
     return function xenonSessionGateway(req, res, next) {
@@ -176,8 +184,10 @@ function createHubRouting(deps) {
                         abort.abort();
                 });
                 let captured;
+                let heal;
                 try {
                     const upstream = yield (0, forwardToNode_1.sendToNode)(yield nodeRequest(req, sessionId, location, abort.signal));
+                    heal = (0, healReport_1.takeHealReport)(upstream.headers);
                     captured = yield (0, forwardToNode_1.relayAnswer)(upstream, res, !!hooks);
                 }
                 catch (error) {
@@ -192,7 +202,7 @@ function createHubRouting(deps) {
                 }
                 if (hooks && captured !== undefined) {
                     yield hooks
-                        .after(sessionId, command, req, res, captured)
+                        .after(sessionId, command, req, res, captured, heal)
                         .catch((error) => logger.warn(`Dashboard log failed for session ${sessionId}: ${(0, commandAuth_1.summarize)(error)}`));
                 }
             });