@xenon-device-management/xenon 2.0.0 → 2.2.0

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

@@ -17,6 +17,8 @@ exports.parseH264WsPath = parseH264WsPath;
 exports.attachH264Ws = attachH264Ws;
 const ws_1 = require("ws");
 const logger_1 = __importDefault(require("../../logger"));
+const upgradeRouter_1 = require("./upgradeRouter");
+const nodeSocketRelay_1 = require("./nodeSocketRelay");
 /**
  * Authenticated H.264 video WebSocket.
  *
@@ -44,19 +46,24 @@ 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* () {
+            var _a, _b, _c;
             // Register cleanup BEFORE the awaits below. redeem + startStream can take
             // seconds; if the client disconnects during that window we must still
             // remove it from the multiplexer — otherwise clientCount stays inflated
@@ -69,20 +76,44 @@ function attachH264Ws(server, deps) {
             };
             ws.on('close', onClose);
             ws.on('error', onClose);
+            let actor;
             try {
-                yield deps.redeem(parsed.ticket, parsed.udid);
+                actor = yield deps.redeem(parsed.ticket, parsed.udid);
             }
-            catch (_a) {
+            catch (_d) {
                 try {
                     ws.close(1008, 'unauthorized');
                 }
-                catch (_b) {
+                catch (_e) {
                     /* noop */
                 }
                 return;
             }
             if (closed)
                 return; // disconnected during redeem
+            // Another server's phone: its node streams it, relayed from here.
+            let upstream = null;
+            try {
+                upstream = (_b = (yield ((_a = deps.nodeSocket) === null || _a === void 0 ? void 0 : _a.call(deps, parsed.udid, actor)))) !== null && _b !== void 0 ? _b : null;
+            }
+            catch (e) {
+                const refused = e instanceof nodeSocketRelay_1.NodeSocketRefused;
+                logger_1.default.warn(`[${parsed.udid}] H.264 WS from its node failed: ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e}`);
+                try {
+                    ws.close(refused ? 1008 : 1011, refused ? 'refused by the node' : 'node unreachable');
+                }
+                catch (_f) {
+                    /* noop */
+                }
+                return;
+            }
+            if (upstream) {
+                if (closed)
+                    return void upstream.terminate();
+                (0, nodeSocketRelay_1.relaySocket)(ws, upstream, maxBuffered);
+                logger_1.default.info(`[${parsed.udid}] H.264 WS client connected, relayed from its node`);
+                return;
+            }
             let mux;
             try {
                 mux = yield deps.startStream(parsed.udid);
@@ -92,7 +123,7 @@ function attachH264Ws(server, deps) {
                 try {
                     ws.close(1011, 'stream failed');
                 }
-                catch (_c) {
+                catch (_g) {
                     /* noop */
                 }
                 return;
@@ -111,5 +142,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,8 @@ exports.parseLogcatWsPath = parseLogcatWsPath;
 exports.attachLogcatWs = attachLogcatWs;
 const ws_1 = require("ws");
 const logger_1 = __importDefault(require("../../logger"));
+const upgradeRouter_1 = require("./upgradeRouter");
+const nodeSocketRelay_1 = require("./nodeSocketRelay");
 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 +44,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,12 +61,15 @@ 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;
+            var _a, _b, _c, _d, _e;
             // Register cleanup BEFORE the awaits below. redeem + authorize +
             // startStream can together take seconds; a client that disconnects in
             // that window must still be removed from the multiplexer once it's
@@ -81,11 +87,11 @@ function attachLogcatWs(server, deps) {
             try {
                 actor = yield deps.redeem(parsed.ticket, parsed.udid);
             }
-            catch (_c) {
+            catch (_f) {
                 try {
                     ws.close(1008, 'unauthorized');
                 }
-                catch (_d) {
+                catch (_g) {
                     /* noop */
                 }
                 return;
@@ -105,7 +111,7 @@ function attachLogcatWs(server, deps) {
                 try {
                     ws.close(1011, 'ownership unavailable');
                 }
-                catch (_e) {
+                catch (_h) {
                     /* noop */
                 }
                 return;
@@ -130,13 +136,41 @@ function attachLogcatWs(server, deps) {
                 try {
                     ws.close(1008, unresolvable ? 'device not found' : 'device held by another user');
                 }
-                catch (_f) {
+                catch (_j) {
                     /* noop */
                 }
                 return;
             }
             if (closed)
                 return; // disconnected during authorize
+            // Another server's phone: its node streams the log, relayed from here.
+            // The node keeps the replay, the drop markers and the close codes.
+            let upstream = null;
+            try {
+                upstream =
+                    (_c = (yield ((_b = deps.nodeSocket) === null || _b === void 0 ? void 0 : _b.call(deps, parsed.udid, actor, {
+                        levels: parsed.levels,
+                        process: parsed.process,
+                    })))) !== null && _c !== void 0 ? _c : null;
+            }
+            catch (e) {
+                const refused = e instanceof nodeSocketRelay_1.NodeSocketRefused;
+                logger_1.default.warn(`[${parsed.udid}] logcat WS from its node failed: ${(_d = e === null || e === void 0 ? void 0 : e.message) !== null && _d !== void 0 ? _d : e}`);
+                try {
+                    ws.close(refused ? 1008 : 1011, refused ? 'refused by the node' : 'node unreachable');
+                }
+                catch (_k) {
+                    /* noop */
+                }
+                return;
+            }
+            if (upstream) {
+                if (closed)
+                    return void upstream.terminate();
+                (0, nodeSocketRelay_1.relaySocket)(ws, upstream, maxBuffered);
+                logger_1.default.info(`[${parsed.udid}] logcat WS client connected, relayed from its node`);
+                return;
+            }
             let mux;
             let effectiveLevels;
             try {
@@ -148,11 +182,11 @@ function attachLogcatWs(server, deps) {
                 effectiveLevels = started.levels;
             }
             catch (e) {
-                logger_1.default.warn(`[${parsed.udid}] logcat WS start failed: ${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e}`);
+                logger_1.default.warn(`[${parsed.udid}] logcat WS start failed: ${(_e = e === null || e === void 0 ? void 0 : e.message) !== null && _e !== void 0 ? _e : e}`);
                 try {
                     ws.close(1011, 'stream failed');
                 }
-                catch (_g) {
+                catch (_l) {
                     /* noop */
                 }
                 return;
@@ -282,5 +316,5 @@ function attachLogcatWs(server, deps) {
             };
             logger_1.default.info(`[${parsed.udid}] logcat WS client connected`);
         }));
-    });
+    }
 }

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

@@ -0,0 +1,167 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELAY_HIGH_WATER_BYTES = exports.NODE_SOCKET_TIMEOUT_MS = exports.NodeSocketRefused = void 0;
+exports.openNodeSocket = openNodeSocket;
+exports.relaySocket = relaySocket;
+const typedi_1 = require("typedi");
+const ws_1 = require("ws");
+const logger_1 = __importDefault(require("../../logger"));
+const hubSessionToken_1 = require("../../gateway/hubSessionToken");
+const forwardToNode_1 = require("../../gateway/forwardToNode");
+const controlDevice_1 = require("../../middleware/controlDevice");
+const nodePhoneControl_1 = require("../routers/nodePhoneControl");
+/**
+ * The live preview's H.264 socket and the logcat socket, for another server's
+ * phone. The viewer's ticket is this server's (stream/ticket is answered
+ * here, after the team check) and is redeemed here; the socket itself is the
+ * node's, opened with a ticket the node mints for the same user, and relayed.
+ * The node keeps doing what it does for its own viewers: the multiplexer,
+ * the replay, the slow-viewer drops and the idle release.
+ */
+/** The node, or this server's own rule, refused: the viewer gets 1008. */
+class NodeSocketRefused extends Error {
+}
+exports.NodeSocketRefused = NodeSocketRefused;
+/** How long the node has to mint its ticket and open its socket. */
+exports.NODE_SOCKET_TIMEOUT_MS = 15000;
+/** Unwritten bytes to the viewer beyond which reading from the node pauses. */
+exports.RELAY_HIGH_WATER_BYTES = 4 * 1024 * 1024;
+/**
+ * The node's socket for another server's phone, open and paused until
+ * relaySocket reads it; null for this server's own phone, which the caller
+ * serves itself. Throws NodeSocketRefused when the phone is a cloud
+ * provider's or the node refuses the user, and any other error when the node
+ * can't be reached.
+ */
+function openNodeSocket(request_1) {
+    return __awaiter(this, arguments, void 0, function* (request, deps = {}) {
+        var _a, _b, _c, _d;
+        const findDevice = (_a = deps.findDevice) !== null && _a !== void 0 ? _a : controlDevice_1.findControlDeviceInStore;
+        const controlToken = (_b = deps.controlToken) !== null && _b !== void 0 ? _b : ((grant) => typedi_1.Container.get(hubSessionToken_1.HubSessionTokenIssuer).controlTokenFor(grant));
+        const timeoutMs = (_c = deps.timeoutMs) !== null && _c !== void 0 ? _c : exports.NODE_SOCKET_TIMEOUT_MS;
+        const { udid, actor, path } = request;
+        const device = yield findDevice(udid);
+        if (!device || !(0, nodePhoneControl_1.isOtherServersPhone)(device))
+            return null;
+        if (device.cloud)
+            throw new NodeSocketRefused("a cloud provider's phone");
+        const origin = (0, nodePhoneControl_1.safeNodeOrigin)(device.host);
+        if (!origin)
+            throw new NodeSocketRefused('unsafe device host');
+        const token = yield controlToken({
+            userId: actor.actorId,
+            isAdmin: !!actor.isAdmin,
+            udid,
+            host: device.host,
+        });
+        const base = `/xenon/api/control/${encodeURIComponent(udid)}`;
+        const answer = yield (0, forwardToNode_1.readAnswer)(yield (0, forwardToNode_1.sendToNode)({
+            url: `${origin}${base}/stream/ticket`,
+            method: 'POST',
+            headers: Object.assign({ accept: 'application/json', 'content-type': 'application/json' }, (token ? { [hubSessionToken_1.HUB_TOKEN_HEADER]: token } : {})),
+            body: Buffer.from('{}'),
+            signal: AbortSignal.timeout(timeoutMs),
+        }));
+        if (answer.status >= 400 && answer.status < 500) {
+            throw new NodeSocketRefused(`the node answered ${answer.status} for a ticket`);
+        }
+        if (answer.status >= 300)
+            throw new Error(`the node answered ${answer.status} for a ticket`);
+        const ticket = (_d = JSON.parse(answer.body.toString('utf8'))) === null || _d === void 0 ? void 0 : _d.ticket;
+        if (typeof ticket !== 'string')
+            throw new Error('the node sent no ticket');
+        const query = new URLSearchParams(request.query);
+        query.set('ticket', ticket);
+        const url = `${origin.replace(/^http/, 'ws')}${base}/${path}?${query}`;
+        const socket = new ws_1.WebSocket(url, { handshakeTimeout: timeoutMs, perMessageDeflate: false });
+        yield new Promise((resolve, reject) => {
+            socket.once('open', () => {
+                // Paused until something reads it: the node sends H.264's config
+                // packet and logcat's replay as soon as it opens, and a message with
+                // no listener yet is lost. relaySocket resumes it.
+                socket.pause();
+                resolve();
+            });
+            socket.once('error', reject);
+        });
+        logger_1.default.info(`[${udid}] ${path} socket opened on node ${origin}`);
+        return socket;
+    });
+}
+/** A close code a server may send. 1005, 1006 and 1015 only describe a close. */
+function isSendable(code) {
+    return ((code >= 1000 && code <= 1014 && ![1004, 1005, 1006].includes(code)) ||
+        (code >= 3000 && code <= 4999));
+}
+function closeWith(ws, code, reason) {
+    if (ws.readyState === ws_1.WebSocket.CLOSING || ws.readyState === ws_1.WebSocket.CLOSED)
+        return;
+    try {
+        if (code === 1005)
+            ws.close();
+        // The node's connection dropped with no close: the viewer retries.
+        else if (!isSendable(code))
+            ws.close(1011, 'node connection lost');
+        else
+            ws.close(code, reason.toString());
+    }
+    catch (_a) {
+        ws.terminate();
+    }
+}
+/**
+ * Relay `viewer` to and from `node` until either closes. Messages pass
+ * unchanged, binary or text as they came, and the node's close code and
+ * reason reach the viewer. While more than `highWaterBytes` sent to the
+ * viewer are still unwritten, reading from the node pauses: the node then
+ * sees a slow viewer and applies its own rule, rather than this server
+ * buffering without bound.
+ */
+function relaySocket(viewer, node, highWaterBytes = exports.RELAY_HIGH_WATER_BYTES) {
+    let unwritten = 0;
+    let paused = false;
+    node.on('message', (data, isBinary) => {
+        if (viewer.readyState !== ws_1.WebSocket.OPEN)
+            return;
+        const size = data.length;
+        unwritten += size;
+        viewer.send(data, { binary: isBinary }, () => {
+            unwritten -= size;
+            if (paused && unwritten <= highWaterBytes / 2) {
+                paused = false;
+                node.resume();
+            }
+        });
+        if (!paused && unwritten > highWaterBytes) {
+            paused = true;
+            node.pause();
+        }
+    });
+    viewer.on('message', (data, isBinary) => {
+        if (node.readyState === ws_1.WebSocket.OPEN)
+            node.send(data, { binary: isBinary });
+    });
+    node.on('close', (code, reason) => closeWith(viewer, code, reason));
+    viewer.on('close', () => {
+        if (node.readyState === ws_1.WebSocket.OPEN || node.readyState === ws_1.WebSocket.CONNECTING) {
+            node.close(1000);
+        }
+    });
+    // A 'close' follows each; nothing more to do here.
+    node.on('error', () => undefined);
+    viewer.on('error', () => undefined);
+    // openNodeSocket hands the node's socket over paused; read it now.
+    node.resume();
+}

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) {