@xenon-device-management/xenon 2.0.0 → 2.1.0

package/lib/src/app/ws/h264StreamWs.js

@@ -17,6 +17,7 @@ exports.parseH264WsPath = parseH264WsPath;
 exports.attachH264Ws = attachH264Ws;
 const ws_1 = require("ws");
 const logger_1 = __importDefault(require("../../logger"));
+const upgradeRouter_1 = require("./upgradeRouter");
 /**
  * Authenticated H.264 video WebSocket.
  *
@@ -44,18 +45,22 @@ function parseH264WsPath(url) {
 }
 /**
  * Attach the h264 WebSocket upgrade handler to the plugin's HTTP server. Only
- * claims `/xenon/api/control/:udid/stream/h264` — other upgrades (e.g.
- * socket.io) are left for their own listeners. Every connection must redeem a
- * valid stream ticket before any video flows.
+ * claims `/xenon/api/control/:udid/stream/h264` (with a ticket), as a route of
+ * the server's upgrade router, so no other handler sees these sockets and this
+ * one sees no others (upgradeRouter.ts). Every connection must redeem a valid
+ * stream ticket before any video flows.
  */
 function attachH264Ws(server, deps) {
     var _a;
     const wss = new ws_1.WebSocketServer({ noServer: true });
     const maxBuffered = (_a = deps.maxBufferedBytes) !== null && _a !== void 0 ? _a : 4 * 1024 * 1024;
-    server.on('upgrade', (req, socket, head) => {
-        const parsed = req.url ? parseH264WsPath(req.url) : null;
-        if (!parsed)
-            return; // not our path — let other upgrade listeners handle it
+    (0, upgradeRouter_1.upgradeRouterFor)(server).add({
+        name: 'H.264 live preview',
+        matches: (req) => !!req.url && parseH264WsPath(req.url) !== null,
+        handle: upgrade,
+    });
+    function upgrade(req, socket, head) {
+        const parsed = parseH264WsPath(req.url);
         wss.handleUpgrade(req, socket, head, (ws) => __awaiter(this, void 0, void 0, function* () {
             // Register cleanup BEFORE the awaits below. redeem + startStream can take
             // seconds; if the client disconnects during that window we must still
@@ -111,5 +116,5 @@ function attachH264Ws(server, deps) {
             });
             logger_1.default.info(`[${parsed.udid}] H.264 WS client connected`);
         }));
-    });
+    }
 }

package/lib/src/app/ws/logcatWs.js

@@ -16,6 +16,7 @@ exports.parseLogcatWsPath = parseLogcatWsPath;
 exports.attachLogcatWs = attachLogcatWs;
 const ws_1 = require("ws");
 const logger_1 = __importDefault(require("../../logger"));
+const upgradeRouter_1 = require("./upgradeRouter");
 const ostraceParse_1 = require("../../services/logcat/ostraceParse");
 const LOGCAT_PATH_RE = /^\/xenon\/api\/control\/([^/]+)\/logcat$/;
 /** Parse the logcat stream upgrade path; returns null for any non-matching URL. */
@@ -42,8 +43,9 @@ function parseLogcatWsPath(url) {
 }
 /**
  * Attach the logcat WebSocket upgrade handler to the plugin's HTTP server.
- * Only claims `/xenon/api/control/:udid/logcat` — other upgrades (socket.io,
- * the h264 stream) are left for their own listeners.
+ * Only claims `/xenon/api/control/:udid/logcat` (with a ticket), as a route of
+ * the server's upgrade router, so no other handler sees these sockets and this
+ * one sees no others (upgradeRouter.ts).
  *
  * Authentication mirrors `attachH264Ws`: a single-use, udid-bound stream
  * ticket. Authorization does not — device logs routinely carry auth tokens,
@@ -58,10 +60,13 @@ function attachLogcatWs(server, deps) {
     var _a;
     const wss = new ws_1.WebSocketServer({ noServer: true });
     const maxBuffered = (_a = deps.maxBufferedBytes) !== null && _a !== void 0 ? _a : 4 * 1024 * 1024;
-    server.on('upgrade', (req, socket, head) => {
-        const parsed = req.url ? parseLogcatWsPath(req.url) : null;
-        if (!parsed)
-            return; // not our path — let other upgrade listeners handle it
+    (0, upgradeRouter_1.upgradeRouterFor)(server).add({
+        name: 'logcat',
+        matches: (req) => !!req.url && parseLogcatWsPath(req.url) !== null,
+        handle: upgrade,
+    });
+    function upgrade(req, socket, head) {
+        const parsed = parseLogcatWsPath(req.url);
         wss.handleUpgrade(req, socket, head, (ws) => __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             // Register cleanup BEFORE the awaits below. redeem + authorize +
@@ -282,5 +287,5 @@ function attachLogcatWs(server, deps) {
             };
             logger_1.default.info(`[${parsed.udid}] logcat WS client connected`);
         }));
-    });
+    }
 }

package/lib/src/app/ws/upgradeRouter.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpgradeRouter = void 0;
+exports.appiumPatternMatcher = appiumPatternMatcher;
+exports.dispatchToAppiumHandlers = dispatchToAppiumHandlers;
+exports.appiumUpgradeListener = appiumUpgradeListener;
+exports.upgradeRouterFor = upgradeRouterFor;
+const logger_1 = __importDefault(require("../../logger"));
+const appiumBasePath_1 = require("../appiumBasePath");
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The path-to-regexp v8 syntax Appium's patterns use: literal segments and
+ * `:name` parameters. Anything else (groups, wildcards, escapes) is not
+ * compiled, and such a pattern matches nothing here; see appiumPatternMatcher.
+ */
+const UNSUPPORTED_PATTERN_SYNTAX = /[{}()[\]*+?!\\"]/;
+/** Splits a pattern into literal text (even indexes) and `:name` parameters (odd). */
+const PARAM = /(:[A-Za-z_$][\w$]*)/;
+const compiled = new Map();
+const warnedPatterns = new Set();
+/**
+ * base-driver matches an upgrade's pathname against each registered pattern
+ * with path-to-regexp's `match(pattern)` (v8, defaults): case-insensitive, an
+ * optional trailing slash, the whole pathname, each parameter one or more
+ * characters other than `/`, and each matched parameter decoded with
+ * decodeURIComponent, which throws on a malformed escape. This is that, for
+ * the patterns Appium and drivers register. It returns null for a pattern it
+ * does not speak.
+ */
+function appiumPatternMatcher(pattern) {
+    const cached = compiled.get(pattern);
+    if (cached !== undefined)
+        return cached;
+    let matcher = null;
+    if (!UNSUPPORTED_PATTERN_SYNTAX.test(pattern)) {
+        const source = pattern
+            .split(PARAM)
+            .map((part, i) => (i % 2 === 1 ? '([^/]+)' : escapeRegExp(part)))
+            .join('');
+        const regex = new RegExp(`^${source}(?:/)?$`, 'i');
+        matcher = (pathname) => {
+            const m = regex.exec(pathname);
+            if (!m)
+                return false;
+            // path-to-regexp decodes every matched parameter, and a malformed
+            // escape throws out of Appium's dispatch. Do the same, so this behaves
+            // as Appium's own listener does.
+            for (const value of m.slice(1))
+                decodeURIComponent(value);
+            return true;
+        };
+    }
+    compiled.set(pattern, matcher);
+    return matcher;
+}
+/**
+ * base-driver's `tryHandleWebSocketUpgrade`, over the server's public
+ * `webSocketsMapping`: hand a WebSocket upgrade to the first registered
+ * handler whose pattern matches its pathname. False when none does.
+ */
+function dispatchToAppiumHandlers(req, socket, head, mapping, logger) {
+    var _a, _b;
+    const upgrade = (_a = req.headers) === null || _a === void 0 ? void 0 : _a.upgrade;
+    if (typeof upgrade !== 'string' || upgrade.toLowerCase() !== 'websocket')
+        return false;
+    const pathname = (0, appiumBasePath_1.appiumPathname)((_b = req.url) !== null && _b !== void 0 ? _b : '');
+    for (const [pattern, wsServer] of Object.entries(mapping !== null && mapping !== void 0 ? mapping : {})) {
+        const matches = appiumPatternMatcher(pattern);
+        if (!matches) {
+            if (!warnedPatterns.has(pattern)) {
+                warnedPatterns.add(pattern);
+                logger.warn(`Appium WebSocket handler ${pattern} uses path syntax Xenon's copy of Appium's ` +
+                    'upgrade listener does not match; it is skipped on this Node (< 22.21).');
+            }
+            continue;
+        }
+        if (matches(pathname)) {
+            wsServer.handleUpgrade(req, socket, head, (ws) => wsServer.emit('connection', ws, req));
+            return true;
+        }
+    }
+    logger.info(`Did not match the websocket upgrade request at ${pathname} to any known route`);
+    return false;
+}
+/**
+ * The `upgrade` listener base-driver's configureHttp adds on Node >= 22.21:
+ * Appium's handlers take what they match, and every other socket is destroyed.
+ * `webSocketsMapping` is read per upgrade, since drivers add and remove
+ * handlers as sessions come and go.
+ */
+function appiumUpgradeListener(server, logger) {
+    return function appiumUpgradeThroughXenon(req, socket, head) {
+        if (!dispatchToAppiumHandlers(req, socket, head, server.webSocketsMapping, logger)) {
+            socket.destroy();
+        }
+    };
+}
+/** The upgrade's path without the query, which carries tickets. */
+function pathOf(req) {
+    var _a;
+    return String((_a = req.url) !== null && _a !== void 0 ? _a : '').split('?')[0];
+}
+class UpgradeRouter {
+    constructor(server, logger = logger_1.default.scope('UpgradeRouter')) {
+        this.server = server;
+        this.logger = logger;
+        this.routes = [];
+        // base-driver's own test (`hasShouldUpgradeCallback`): without the
+        // callback it took upgrades in Express and added no listener. A server
+        // with no listener at all (not Appium's) needs one too, or neither Node
+        // emits `upgrade` and Xenon's routes are never reached.
+        const appiumListens = typeof server.shouldUpgradeCallback !== 'undefined' && server.listenerCount('upgrade') > 0;
+        if (appiumListens) {
+            this.appiumPath = 'appium-listener';
+        }
+        else {
+            server.on('upgrade', appiumUpgradeListener(server, logger));
+            this.appiumPath = 'router-listener';
+        }
+        this.routeEmit();
+    }
+    /** Give every upgrade `route.matches` to `route.handle`, and to nothing else. */
+    add(route) {
+        this.routes.push(route);
+    }
+    /**
+     * Run `attach`, which attaches something that takes upgrades by adding an
+     * `upgrade` listener (socket.io). The listeners it added are taken off the
+     * server and become the route's handler, so they see only what `matches`.
+     */
+    adopt(name, matches, attach) {
+        const before = new Set(this.server.listeners('upgrade'));
+        const attached = attach();
+        const added = this.server.listeners('upgrade').filter((l) => !before.has(l));
+        for (const listener of added)
+            this.server.removeListener('upgrade', listener);
+        if (added.length > 0) {
+            const server = this.server;
+            this.add({
+                name,
+                matches,
+                handle: (req, socket, head) => {
+                    for (const listener of added)
+                        listener.call(server, req, socket, head);
+                },
+            });
+        }
+        return attached;
+    }
+    /** The route that owns an upgrade to `req`, or undefined when it is Appium's. */
+    routeFor(req) {
+        return this.routes.find((route) => route.matches(req));
+    }
+    /** Where the upgrades that are not Xenon's go, for the boot log. */
+    describeAppiumPath() {
+        return this.appiumPath === 'appium-listener'
+            ? "Appium's own upgrade listener"
+            : "Appium's WebSocket handlers, through Xenon's copy of Appium's upgrade listener " +
+                '(this Node has no http.Server shouldUpgradeCallback, so Appium took upgrades in ' +
+                'Express, which no upgrade reaches once any upgrade listener exists)';
+    }
+    /** Close a socket whose upgrade could not be handed on, and say why. */
+    refuse(req, socket, what, error) {
+        var _a;
+        this.logger.error(`WebSocket upgrade ${pathOf(req)} ${what}: ${(_a = error === null || error === void 0 ? void 0 : error.message) !== null && _a !== void 0 ? _a : error}. Closing the socket.`);
+        socket.destroy();
+        return true;
+    }
+    routeEmit() {
+        const server = this.server;
+        const emit = server.emit;
+        const routeFor = (req) => this.routeFor(req);
+        const refuse = (req, socket, what, error) => this.refuse(req, socket, what, error);
+        server.emit = function emitThroughUpgradeRouter(event, ...args) {
+            if (event !== 'upgrade')
+                return emit.call(this, event, ...args);
+            const [req, socket, head] = args;
+            let route;
+            try {
+                route = routeFor(req);
+            }
+            catch (error) {
+                return refuse(req, socket, 'could not be routed', error);
+            }
+            try {
+                if (!route)
+                    return emit.call(this, event, ...args);
+                route.handle(req, socket, head);
+                return true;
+            }
+            catch (error) {
+                return refuse(req, socket, `failed in the ${route ? route.name : 'Appium'} handler`, error);
+            }
+        };
+    }
+}
+exports.UpgradeRouter = UpgradeRouter;
+const routers = new WeakMap();
+/**
+ * The server's router, installed on first use. ServerManager installs it in
+ * registerRoutes; attaching a WebSocket installs it on a server that has none.
+ */
+function upgradeRouterFor(server) {
+    let router = routers.get(server);
+    if (!router) {
+        router = new UpgradeRouter(server);
+        routers.set(server, router);
+    }
+    return router;
+}

package/lib/src/dashboard/event-manager.js

@@ -225,9 +225,10 @@ let DashboardEventManager = class DashboardEventManager {
                     // Principal Resource Management: Unblock device immediately
                     const device = this.sessionToDevice.get(sessionId);
                     if (device) {
-                        const { unblockDevice } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
+                        const { releaseSessionDevice } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
                         try {
-                            yield unblockDevice(device.udid, device.host);
+                            // This session's claim only: the phone may have gone on to another.
+                            yield releaseSessionDevice(device.udid, device.host, sessionId);
                             logger_1.default.info(`🔓 [${sessionId}] Device ${device.udid} released.`);
                         }
                         catch (unblockErr) {
@@ -239,9 +240,9 @@ let DashboardEventManager = class DashboardEventManager {
                         yield this.stopIdleStreamForDevice(device);
                     }
                     else {
-                        const { unblockDeviceMatchingFilter } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
+                        const { releaseSessionDevices } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
                         try {
-                            yield unblockDeviceMatchingFilter({ session_id: sessionId });
+                            yield releaseSessionDevices(sessionId);
                             logger_1.default.info(`🔓 [${sessionId}] Device released via session_id fallback.`);
                         }
                         catch (unblockErr) {
@@ -261,9 +262,9 @@ let DashboardEventManager = class DashboardEventManager {
                 else {
                     logger_1.default.warn(`⚠️ Session ${sessionId} not found in SESSION_MANAGER`);
                     // Fallback: If session not in manager, attempt to unblock by session_id in store
-                    const { unblockDeviceMatchingFilter } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
+                    const { releaseSessionDevices } = yield Promise.resolve().then(() => __importStar(require('../data-service/device-service')));
                     try {
-                        yield unblockDeviceMatchingFilter({ session_id: sessionId });
+                        yield releaseSessionDevices(sessionId);
                         logger_1.default.info(`🔓 [${sessionId}] Orphaned device released via session_id fallback.`);
                     }
                     catch (unblockErr) {

package/lib/src/data-service/device-service.js

@@ -13,7 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeDevice = removeDevice;
-exports.removeDevicesByHost = removeDevicesByHost;
+exports.removeNodeDevices = removeNodeDevices;
 exports.addNewDevice = addNewDevice;
 exports.syncDiscoveredDevices = syncDiscoveredDevices;
 exports.setSimulatorState = setSimulatorState;
@@ -23,6 +23,7 @@ exports.filterRowsByVisibleDevice = filterRowsByVisibleDevice;
 exports.getDevices = getDevices;
 exports.getDevice = getDevice;
 exports.updatedAllocatedDevice = updatedAllocatedDevice;
+exports.claimDeviceForSession = claimDeviceForSession;
 exports.updateDeviceProgress = updateDeviceProgress;
 exports.updateCmdExecutedTime = updateCmdExecutedTime;
 exports.userBlockDevice = userBlockDevice;
@@ -30,6 +31,9 @@ exports.userUnblockDevice = userUnblockDevice;
 exports.blockDevice = blockDevice;
 exports.unblockDevice = unblockDevice;
 exports.unblockDeviceMatchingFilter = unblockDeviceMatchingFilter;
+exports.releaseSessionDevices = releaseSessionDevices;
+exports.releaseSessionDevice = releaseSessionDevice;
+exports.releasePendingClaim = releasePendingClaim;
 exports.reserveDevice = reserveDevice;
 exports.releaseReservation = releaseReservation;
 exports.isDeviceReserved = isDeviceReserved;
@@ -43,6 +47,7 @@ const typedi_1 = require("typedi");
 const CircuitBreaker_1 = require("./CircuitBreaker");
 const NotificationService_1 = require("../services/NotificationService");
 const deviceFieldOwners_1 = require("./deviceFieldOwners");
+const deviceClaims_1 = require("./deviceClaims");
 const SocketServer_1 = require("../services/SocketServer");
 const prisma_1 = require("../prisma");
 const manualLock_1 = require("../services/recording/manualLock");
@@ -63,8 +68,8 @@ const store = new Proxy({}, {
 function deviceScope(udid, teamId) {
     return teamId === undefined ? { udid } : { udid, teamId };
 }
-function removeDevice(devices) {
-    return __awaiter(this, void 0, void 0, function* () {
+function removeDevice(devices_1) {
+    return __awaiter(this, arguments, void 0, function* (devices, options = {}) {
         for (const device of devices) {
             logger_1.default.info(`Removing device ${device.udid} from host ${device.host}`);
             const socket = typedi_1.Container.get(SocketServer_1.SocketServer);
@@ -75,18 +80,44 @@ function removeDevice(devices) {
             const team = socket.hasScopedDashboard()
                 ? yield typedi_1.Container.get(DeviceTeamResolver_1.DeviceTeamResolver).resolve(device.udid)
                 : undefined;
-            yield store.removeDevices({ udid: device.udid, host: device.host });
+            yield store.removeDevices({ udid: device.udid, host: device.host }, options);
             typedi_1.Container.get(NotificationService_1.NotificationService).dispatchEvent('device_offline', device);
             void socket.emitToDashboardForDevices('device_removed', device, deviceScope(device.udid, (team === null || team === void 0 ? void 0 : team.known) ? team.teamId : undefined));
         }
     });
 }
-function removeDevicesByHost(host) {
+/**
+ * The phones a node asks the hub to forget (`POST /register`, `type=remove`
+ * for one phone, `type=unregister` when it shuts down). Only that node's: the
+ * rows its `nodeId` names when it sends one, else those filed under exactly
+ * its `host`, and never one of this server's own (`isOwn`). A udid-less
+ * `remove` names no phone and takes nothing.
+ *
+ * The store matched a host that isn't a URL as a substring, and a remove with
+ * no host by udid alone, so a node (an older one sends a bare IP) could delete
+ * the hub's own phones, or another node's. Returns how many rows went.
+ */
+function removeNodeDevices(removals, isOwn) {
     return __awaiter(this, void 0, void 0, function* () {
-        logger_1.default.info(`Removing all devices from host ${host}`);
-        // We can't easily dispatch events here without fetching first,
-        // but for now we'll stick to single device removal alerting
-        yield store.removeDevices({ host });
+        const all = yield store.getAllDevices();
+        const gone = new Map();
+        for (const removal of removals) {
+            if (!removal.nodeId && !removal.host)
+                continue;
+            for (const device of all) {
+                if (isOwn(device))
+                    continue;
+                if (removal.udid !== undefined && device.udid !== removal.udid)
+                    continue;
+                const theirs = removal.nodeId
+                    ? device.nodeId === removal.nodeId
+                    : device.host === removal.host;
+                if (theirs)
+                    gone.set(`${device.udid}\u0000${device.host}`, device);
+            }
+        }
+        yield removeDevice([...gone.values()].map((d) => ({ udid: d.udid, host: d.host })), { exactHost: true });
+        return gone.size;
     });
 }
 function addNewDevice(devices_1, host_1) {
@@ -237,6 +268,22 @@ function updatedAllocatedDevice(device, updateData) {
         yield store.updateDevice(device.udid, device.host, updateData);
     });
 }
+/**
+ * Put a created session on the claim its phone was allocated with
+ * (`device.claimedAt`), writing `updateData` with it. False, and nothing
+ * written, when another session holds the phone now: its claim is not
+ * overwritten.
+ */
+function claimDeviceForSession(device, sessionId, updateData) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const claimed = yield store.claimForSession(device.udid, device.host, device.claimedAt, sessionId, updateData);
+        if (!claimed) {
+            logger_1.default.error(`Session ${sessionId} was created on ${device.udid} at ${device.host}, but another ` +
+                'session has claimed the device since. Leaving that claim in place.');
+        }
+        return claimed;
+    });
+}
 function updateDeviceProgress(udid_1, host_1, progress_1) {
     return __awaiter(this, arguments, void 0, function* (udid, host, progress, extra = {}) {
         logger_1.default.debug(`[${udid}] progress: ${progress}`);
@@ -249,9 +296,9 @@ function updateDeviceProgress(udid_1, host_1, progress_1) {
 }
 function updateCmdExecutedTime(sessionId) {
     return __awaiter(this, void 0, void 0, function* () {
-        yield store.updateDevices({ session_id: sessionId }, (device) => {
-            device.lastCmdExecutedAt = new Date().getTime();
-        });
+        // One conditional write. Reading the row and writing all of it back would
+        // put back a claim released, or a node's report taken, in between.
+        yield store.touchSession(sessionId, new Date().getTime());
     });
 }
 /**
@@ -297,53 +344,109 @@ function blockDevice(udid, host, sessionId) {
         }, { udid });
     });
 }
+/**
+ * Free a phone whatever holds it: a manual hold (a preview, a recording) or
+ * an admin's release. A session's phone is released with
+ * releaseSessionDevices / releaseSessionDevice / releasePendingClaim instead,
+ * keyed on its claim.
+ *
+ * With a host, only that row. A hub also stores its nodes' phones, and a node
+ * on the same machine lists the same udid under its own host: matching the
+ * udid alone freed that row too, with a session on it.
+ */
 function unblockDevice(udid, host) {
     return __awaiter(this, void 0, void 0, function* () {
-        // Prefer udid-only: device.host can be `http://IP:port` while callers pass
-        // `127.0.0.1` / bindHostOrIp, and a host mismatch silently no-ops (0 rows).
-        // UDID uniquely identifies a device in this store.
-        const byUdid = yield store.getDevices({ udid });
-        if (byUdid.length > 0) {
-            yield unblockDeviceMatchingFilter({ udid });
-            return;
+        const devices = yield store.findDevices(host === undefined ? { udid } : { udid, host });
+        yield forceRelease(devices);
+    });
+}
+/** unblockDevice for every phone matching `filter` (getDevices' filter). */
+function unblockDeviceMatchingFilter(filter) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield forceRelease(yield store.getDevices(filter));
+    });
+}
+function forceRelease(devices) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield Promise.all(devices.map((device) => __awaiter(this, void 0, void 0, function* () {
+            const totalUtilization = utilizationAfter(device);
+            yield (0, device_utils_1.setUtilizationTime)(device.udid, totalUtilization);
+            yield store.updateDevice(device.udid, device.host, Object.assign(Object.assign({}, deviceClaims_1.CLAIM_RESET), { busy: false, totalUtilizationTimeMilliSec: totalUtilization }));
+            logger_1.default.debug(`Unblocked device ${device.udid}`);
+            emitUnblocked(device);
+        }))).catch((error) => {
+            logger_1.default.error(`Unable to unblock device: ${error}`);
+        });
+    });
+}
+/**
+ * End a session's claim on its phone, keyed on the session's id: a release
+ * for a session that has ended, arriving after its phone went to another one,
+ * matches nothing. The phone stays busy while its node still reports it busy
+ * (deviceClaims.ts). Never throws.
+ */
+function releaseSessionDevices(sessionId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const rows = new Map();
+            for (const device of [
+                ...(yield store.findDevices({ claimSessionId: sessionId })),
+                ...(yield store.findDevices({ session_id: sessionId })),
+            ]) {
+                rows.set(`${device.udid}@${device.host}`, device);
+            }
+            yield Promise.all([...rows.values()].map((device) => releaseClaimOn(device, { sessionId })));
         }
-        if (host) {
-            yield unblockDeviceMatchingFilter({ udid, host });
+        catch (error) {
+            logger_1.default.error(`Unable to release the device of session ${sessionId}: ${error}`);
         }
     });
 }
-function unblockDeviceMatchingFilter(filter) {
+/** releaseSessionDevices for one phone. */
+function releaseSessionDevice(udid, host, sessionId) {
     return __awaiter(this, void 0, void 0, function* () {
-        const devices = yield store.getDevices(filter);
-        if (devices.length > 0) {
-            yield Promise.all(devices.map((device) => __awaiter(this, void 0, void 0, function* () {
-                const sessionStart = device.sessionStartTime;
-                const currentTime = new Date().getTime();
-                let utilization = currentTime - sessionStart;
-                if (sessionStart === 0)
-                    utilization = 0;
-                const totalUtilization = device.totalUtilizationTimeMilliSec + utilization;
-                yield (0, device_utils_1.setUtilizationTime)(device.udid, totalUtilization);
-                yield store.updateDevice(device.udid, device.host, {
-                    session_id: null,
-                    busy: false,
-                    lastCmdExecutedAt: null,
-                    sessionStartTime: 0,
-                    totalUtilizationTimeMilliSec: totalUtilization,
-                    newCommandTimeout: null,
-                    sessionProgress: '',
-                });
-                logger_1.default.debug(`Unblocked device ${device.udid}`);
-                void typedi_1.Container.get(SocketServer_1.SocketServer).emitToDashboardForDevices('device_unblocked', {
-                    udid: device.udid,
-                    host: device.host,
-                }, deviceScope(device.udid, device.teamId));
-            }))).catch((error) => {
-                logger_1.default.error(`Unable to unblock device: ${error}`);
-            });
+        const device = yield store.findDevice({ udid, host });
+        return device ? releaseClaimOn(device, { sessionId }) : false;
+    });
+}
+/**
+ * Give back a phone allocated for a session that was never created: the
+ * pending claim it was allocated with (`claimedAt`, as the allocation read
+ * it). If that claim has gone (timed out, and the phone taken since) nothing
+ * is written.
+ */
+function releasePendingClaim(allocated) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const device = yield store.findDevice({ udid: allocated.udid, host: allocated.host });
+        return device ? releaseClaimOn(device, { claimedAt: (_a = allocated.claimedAt) !== null && _a !== void 0 ? _a : null }) : false;
+    });
+}
+function releaseClaimOn(device, ref) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const totalUtilization = utilizationAfter(device);
+        const released = yield store.releaseClaim(device.udid, device.host, ref, {
+            totalUtilizationTimeMilliSec: totalUtilization,
+        });
+        if (!released) {
+            logger_1.default.info(`Not releasing ${device.udid} at ${device.host}: it no longer holds ${JSON.stringify(ref)}`);
+            return false;
         }
+        yield (0, device_utils_1.setUtilizationTime)(device.udid, totalUtilization);
+        logger_1.default.debug(`Released ${JSON.stringify(ref)} on ${device.udid}`);
+        emitUnblocked(device);
+        return true;
     });
 }
+/** The phone's total use once the session on it now ends. */
+function utilizationAfter(device) {
+    var _a;
+    const started = device.sessionStartTime;
+    return ((_a = device.totalUtilizationTimeMilliSec) !== null && _a !== void 0 ? _a : 0) + (started ? Date.now() - started : 0);
+}
+function emitUnblocked(device) {
+    void typedi_1.Container.get(SocketServer_1.SocketServer).emitToDashboardForDevices('device_unblocked', { udid: device.udid, host: device.host }, deviceScope(device.udid, device.teamId));
+}
 /**
  * Reserve a device for exclusive manual use
  * @param udid Device UDID