@xenon-device-management/xenon 2.0.0 → 2.2.0

package/lib/src/services/SessionLifecycleService.js

@@ -51,7 +51,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionLifecycleService = void 0;
+exports.SessionLifecycleService = exports.REMOTE_CREATE_TIMEOUT_MS = void 0;
 const typedi_1 = require("typedi");
 const uuid_1 = require("uuid");
 const lodash_1 = __importDefault(require("lodash"));
@@ -73,24 +73,40 @@ const JwtKeyService_1 = require("./token/JwtKeyService");
 const sessionIdentity_1 = require("./session/sessionIdentity");
 const leaseSessionCaps_1 = require("./lease/leaseSessionCaps");
 const sessionCredentials_1 = require("./session/sessionCredentials");
+const nodeCreateCaps_1 = require("./session/nodeCreateCaps");
+const xenonOptions_1 = require("./session/xenonOptions");
 const leaseOverride_1 = require("./device-access/leaseOverride");
 const callerTeamIds_1 = require("./device-access/callerTeamIds");
 const queueVisibility_1 = require("./device-access/queueVisibility");
 const appVisibility_1 = require("./device-access/appVisibility");
+const LiveSessionOwners_1 = require("./device-access/LiveSessionOwners");
 const appCapability_1 = require("./session/appCapability");
 const CircuitBreaker_1 = require("../data-service/CircuitBreaker");
-const wd_command_proxy_1 = require("../proxy/wd-command-proxy");
+const nodeWebDriverUrl_1 = require("../gateway/nodeWebDriverUrl");
+const hubSessionToken_1 = require("../gateway/hubSessionToken");
 const device_store_1 = require("../data-service/device-store");
+const deviceClaims_1 = require("../data-service/deviceClaims");
 const LocalSession_1 = require("../sessions/LocalSession");
 const CloudSession_1 = require("../sessions/CloudSession");
 const RemoteSession_1 = require("../sessions/RemoteSession");
 const SessionManager_1 = require("../sessions/SessionManager");
 const event_manager_1 = require("../dashboard/event-manager");
+const prisma_1 = require("../prisma");
 const session_service_1 = require("../dashboard/services/session-service");
 const SessionStatus_1 = require("../types/SessionStatus");
 const SessionType_1 = __importDefault(require("../enums/SessionType"));
 const async_lock_1 = __importDefault(require("async-lock"));
 const base_driver_1 = require("@appium/base-driver");
+/**
+ * How long the hub waits for a node (or cloud provider) to create a session.
+ * A create is sent once (InternalRequestConfig `retry: false`): the node may
+ * still be creating when an ordinary request would give up, and a second
+ * create starts a second session holding the phone. A first UiAutomator2 or
+ * WebDriverAgent install takes minutes. It ends before the phone's pending
+ * claim can expire (PENDING_CLAIM_TIMEOUT_MS), so the idle sweeper never frees
+ * a phone whose create the hub is still waiting for.
+ */
+exports.REMOTE_CREATE_TIMEOUT_MS = deviceClaims_1.PENDING_CLAIM_TIMEOUT_MS - 2 * 60000;
 const commandsQueueGuard = new async_lock_1.default();
 // Serializes concurrent deleteSession cleanup for the same sessionId so
 // that onSessionStopped events don't fire twice if two clients race.
@@ -99,9 +115,52 @@ let SessionLifecycleService = class SessionLifecycleService {
     constructor() {
         this.logger = logger_1.default.scope('SessionLifecycleService');
     }
-    createSession(next, driver, caps) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+    /**
+     * Create a session in one call: prepare it (allocate a phone), then
+     * complete it here through `next` (a phone this server drives) or on the
+     * phone's node (one another server drives).
+     *
+     * The session gateway runs the same steps with Appium's route between them
+     * (gateway/sessionCreate.ts): it prepares, answers a remote phone itself,
+     * and hands a local phone's allocation to XenonPlugin.createSession, which
+     * completes it. The plugin calls this only for a create that did not come
+     * through the gateway, with `localOnly`: a phone on another server is then
+     * given back and refused, since answering for Appium without its driver is
+     * what made Appium's umbrella fail (a 500 while the node kept the session).
+     */
+    createSession(next_1, driver_1, caps_1) {
+        return __awaiter(this, arguments, void 0, function* (next, driver, caps, opts = {}) {
+            const allocation = yield this.prepareSession(caps);
+            if (!allocation.remote)
+                return this.completeLocalSession(allocation, next, driver, caps);
+            if (opts.localOnly) {
+                yield this.releaseAllocation(allocation);
+                throw new base_driver_1.errors.SessionNotCreatedError(`Device ${allocation.device.udid} is driven by another server ` +
+                    `(${allocation.device.host}). Xenon creates sessions there in its session gateway, ` +
+                    'which did not handle this request; the device was released.');
+            }
+            return this.completeRemoteSession(allocation);
+        });
+    }
+    /**
+     * The first half of a create: everything up to and including allocating a
+     * phone. It takes the credentials out of `caps` (in place) before anything
+     * reads them, checks them (or the hub's grant), validates the capabilities,
+     * resolves an uploaded app, writes the pending-session row and allocates.
+     * Throws to refuse, leaving no pending row and no busy phone.
+     *
+     * `hubGrant` is the verified grant of a create the hub forwarded (a node
+     * only; gateway/sessionCreate.ts). Each instance has its own database, so a
+     * node can't check the client's key: the hub checked it, applied the team
+     * rule and the session-token gate, and resolved any lease. The grant is
+     * then the session's credential: it names the owner, and the one phone on
+     * this node the create may have.
+     *
+     * What it returns must be completed (completeLocalSession /
+     * completeRemoteSession) or released (releaseAllocation).
+     */
+    prepareSession(caps_1) {
+        return __awaiter(this, arguments, void 0, function* (caps, opts = {}) {
             // Fail fast during graceful shutdown so clients get a clear error instead
             // of their request hanging until the process dies. Lazy import to avoid
             // a cycle (ShutdownCoordinator -> SessionLifecycleService -> this file).
@@ -116,7 +175,13 @@ let SessionLifecycleService = class SessionLifecycleService {
             // driver, the Session row, the dashboard, the logs — and hand them only to
             // the checks that need them.
             const credentials = (0, sessionCredentials_1.takeSessionCredentials)(caps);
-            const authResult = yield this.authorizeSessionRequest(caps, credentials);
+            const { hubGrant } = opts;
+            yield this.assertCreateCameFromHub(hubGrant);
+            if (hubGrant)
+                this.assertGrantNamesCapsPhone(caps, hubGrant);
+            const authResult = hubGrant
+                ? this.authorizeHubGrant(hubGrant)
+                : yield this.authorizeSessionRequest(caps, credentials);
             const context = typedi_1.Container.get(PluginContext_1.PluginContext);
             const pluginArgs = context.pluginArgs;
             this.logger.debug(`📱 pluginArgs: ${JSON.stringify(pluginArgs)}`);
@@ -174,76 +239,207 @@ let SessionLifecycleService = class SessionLifecycleService {
                 }
             }));
             yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Allocating node resources...');
-            let session;
-            const isRemoteOrCloudSession = !device.nodeId || device.nodeId !== context.nodeId;
             this.logger.debug(`device.host: ${device.host} and pluginArgs.bindHostOrIp: ${pluginArgs.bindHostOrIp}`);
+            const allocation = {
+                caps,
+                device,
+                remote: !device.nodeId || device.nodeId !== context.nodeId,
+                pendingSessionId,
+                apiKeyId: authResult.apiKeyId,
+                userId: authResult.userId,
+                appDownload,
+            };
+            // The grant opens one phone, on this node. A token taken to another node
+            // (an emulator's udid repeats across machines), or naming a phone this
+            // node does not drive, is refused, and the phone given back.
+            if (hubGrant &&
+                (allocation.remote || device.udid !== hubGrant.udid || device.host !== hubGrant.host)) {
+                yield this.releaseAllocation(allocation);
+                this.logger.error(`❌ Rejecting session: the hub's token is for ${hubGrant.udid} at ${hubGrant.host}, ` +
+                    `and this node allocated ${device.udid} at ${device.host}`);
+                throw new base_driver_1.errors.InvalidArgumentError("session rejected: the hub's token for this session names another device");
+            }
+            return allocation;
+        });
+    }
+    /**
+     * Complete a create on the phone's node (or cloud provider), and record the
+     * session here. On failure the phone is released and the error thrown.
+     */
+    completeRemoteSession(allocation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { device, caps, appDownload } = allocation;
+            let session;
             try {
-                if (isRemoteOrCloudSession) {
-                    this.logger.debug(`📱 Forwarding session request to ${device.host}`);
-                    yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Forwarding to remote node...');
-                    // A peer Xenon node re-runs createSession — authentication,
-                    // attribution, the session-token gate and the lease check — so it
-                    // needs the credentials this hub read; it strips them itself. A cloud
-                    // provider is not a Xenon node and never sees them.
-                    const isPeerNode = !device.cloud && !!device.nodeId;
-                    const forwardCaps = isPeerNode ? (0, sessionCredentials_1.capsWithCredentials)(caps, credentials) : caps;
-                    // The node's driver downloads the app from this hub, so the copy it
-                    // is sent carries the ticket; `caps` keeps the plain URL.
-                    session = yield this.forwardSessionRequest(device, appDownload
-                        ? (0, appCapability_1.withAppCapability)(forwardCaps, yield this.driverAppUrl(appDownload))
-                        : forwardCaps);
-                }
-                else {
-                    this.logger.debug('📱 Creating session on the same node');
-                    yield this.handleLocalWDAProvisioning(device, caps);
-                    yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Finalizing session bootstrap...');
-                    // The driver reads these same caps and downloads the app while it
-                    // starts, so the ticket is in them for this call only.
-                    if (appDownload)
-                        (0, appCapability_1.setAppCapability)(caps, yield this.driverAppUrl(appDownload));
-                    try {
-                        session = yield next();
-                    }
-                    finally {
-                        if (appDownload)
-                            (0, appCapability_1.setAppCapability)(caps, appDownload.url);
-                    }
-                }
+                this.logger.debug(`📱 Forwarding session request to ${device.host}`);
+                yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Forwarding to remote node...');
+                // A peer Xenon node gets a create that stands on its own (capsForNode:
+                // no credentials, no lease id, the phone pinned), with the hub's token
+                // naming the owner this hub verified, since it can't check the client's
+                // key in its own database. A cloud provider is not a Xenon node: it
+                // gets the caps without the credentials, and no token.
+                const isPeerNode = !device.cloud && !!device.nodeId;
+                const forwardCaps = isPeerNode ? (0, nodeCreateCaps_1.capsForNode)(caps, device.udid) : caps;
+                const hubToken = isPeerNode
+                    ? yield typedi_1.Container.get(hubSessionToken_1.HubSessionTokenIssuer).createTokenFor({
+                        userId: allocation.userId,
+                        udid: device.udid,
+                        host: device.host,
+                    })
+                    : null;
+                // The node's driver downloads the app from this hub, so the copy it
+                // is sent carries the ticket; `caps` keeps the plain URL.
+                session = yield this.forwardSessionRequest(device, appDownload
+                    ? (0, appCapability_1.withAppCapability)(forwardCaps, yield this.driverAppUrl(appDownload))
+                    : forwardCaps, hubToken);
             }
             catch (err) {
-                // A THROWN error from the driver's createSession (next()) or the remote
-                // forward leaves the device locked: allocateDeviceForSession already set
-                // busy=true, and on the throw path neither finalizeSession nor
-                // handleSessionFailure runs — so without this the device gets stuck busy
-                // with no session. Release it, then rethrow the original error.
-                // (handleSessionFailure below covers the separate case where next()
-                // RETURNS a W3C error object rather than throwing.)
-                this.logger.error(`❌ Session creation failed for device ${device.udid}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}. Unblocking device.`);
+                yield this.failedCreate(allocation, err);
+                throw err;
+            }
+            return this.finishCreate(allocation, session, undefined);
+        });
+    }
+    /**
+     * Complete a create on a phone this server drives: `next` is Appium's own
+     * createSession, and `caps` the capabilities its driver reads. On failure
+     * the phone is released and the error thrown.
+     */
+    completeLocalSession(allocation, next, driver, caps) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { device, appDownload } = allocation;
+            let session;
+            try {
+                this.logger.debug('📱 Creating session on the same node');
+                yield this.handleLocalWDAProvisioning(device, caps);
+                yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Finalizing session bootstrap...');
+                // The driver reads these same caps and downloads the app while it
+                // starts, so the ticket is in them for this call only.
+                if (appDownload)
+                    (0, appCapability_1.setAppCapability)(caps, yield this.driverAppUrl(appDownload));
                 try {
-                    yield (0, pending_sessions_service_1.removePendingSession)(pendingSessionId);
-                    yield (0, device_service_1.unblockDevice)(device.udid, device.host);
-                    yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, '');
-                    if (isRemoteOrCloudSession) {
-                        typedi_1.Container.get(CircuitBreaker_1.CircuitBreaker).recordFailure(device.host);
-                    }
+                    session = yield next();
                 }
-                catch (cleanupErr) {
-                    this.logger.warn(`Cleanup after failed session creation had issues: ${(_b = cleanupErr === null || cleanupErr === void 0 ? void 0 : cleanupErr.message) !== null && _b !== void 0 ? _b : cleanupErr}`);
+                finally {
+                    if (appDownload)
+                        (0, appCapability_1.setAppCapability)(caps, appDownload.url);
                 }
+            }
+            catch (err) {
+                yield this.failedCreate(allocation, err);
                 throw err;
             }
+            return this.finishCreate(Object.assign(Object.assign({}, allocation), { caps }), session, driver);
+        });
+    }
+    /**
+     * Give back a phone allocated for a session that was never created: its
+     * pending-session row goes and the phone is free again. Only the claim this
+     * allocation took is released: if it timed out and the phone went on to
+     * another session, that session keeps it. Never throws.
+     */
+    releaseAllocation(allocation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { device } = allocation;
+            try {
+                yield (0, pending_sessions_service_1.removePendingSession)(allocation.pendingSessionId);
+                yield (0, device_service_1.releasePendingClaim)(device);
+                yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, '');
+            }
+            catch (cleanupErr) {
+                this.logger.warn(`Cleanup after failed session creation had issues: ${(_a = cleanupErr === null || cleanupErr === void 0 ? void 0 : cleanupErr.message) !== null && _a !== void 0 ? _a : cleanupErr}`);
+            }
+        });
+    }
+    // A THROWN error from the driver's createSession (next()) or the remote
+    // forward leaves the device locked: allocation already set busy=true, and
+    // on the throw path neither finalizeSession nor handleSessionFailure runs,
+    // so without this the device gets stuck busy with no session. (finishCreate
+    // covers the separate case where next() RETURNS a W3C error object rather
+    // than throwing.)
+    failedCreate(allocation, err) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { device } = allocation;
+            this.logger.error(`❌ Session creation failed for device ${device.udid}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}. Unblocking device.`);
+            yield this.releaseAllocation(allocation);
+            if (allocation.remote) {
+                typedi_1.Container.get(CircuitBreaker_1.CircuitBreaker).recordFailure(device.host);
+            }
+        });
+    }
+    finishCreate(allocation, session, driver) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { device, caps, remote } = allocation;
             this.logger.debug('📱 Session response: ', JSON.stringify(session));
-            this.logger.debug(`📱 Removing pending session with capability_id: ${pendingSessionId}`);
-            yield (0, pending_sessions_service_1.removePendingSession)(pendingSessionId);
+            this.logger.debug(`📱 Removing pending session with capability_id: ${allocation.pendingSessionId}`);
+            yield (0, pending_sessions_service_1.removePendingSession)(allocation.pendingSessionId);
             if (this.isCreateSessionResponseInternal(session)) {
-                yield this.finalizeSession(session, device, caps, driver, isRemoteOrCloudSession, authResult.apiKeyId, authResult.userId);
+                yield this.finalizeSession(session, device, caps, driver, remote, allocation.apiKeyId, allocation.userId);
             }
             else {
-                yield this.handleSessionFailure(session, device, isRemoteOrCloudSession);
+                yield this.handleSessionFailure(session, device, remote);
             }
             return session;
         });
     }
+    /**
+     * Sessions on a node's phones go through its hub, which owns their team
+     * rules, reservations and blocks and is where auth is enforced. So a node
+     * (a server with `hub`) refuses a create that doesn't carry the hub's
+     * verified grant: one sent to the node directly, or one that reached the
+     * plugin without the session gateway, which is where the grant is checked.
+     *
+     * Only with auth enabled. With auth disabled a node checks no credential,
+     * the hub's token included (sessionCreate.ts), so a create from the hub and
+     * one sent directly look alike, and refusing would protect nothing while
+     * breaking what such a node is used for: running a driver on it directly
+     * during local development. It works there as it always has.
+     */
+    assertCreateCameFromHub(hubGrant) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { hub } = typedi_1.Container.get(PluginContext_1.PluginContext).pluginArgs;
+            if (hub === undefined || hubGrant)
+                return;
+            const { config: xenonConfig } = yield Promise.resolve().then(() => __importStar(require('../config')));
+            if (xenonConfig.authDisabled === true)
+                return;
+            this.logger.warn(`Refusing a session created directly on this node: it carries no grant from the hub (${hub}).`);
+            throw new base_driver_1.errors.SessionNotCreatedError(`This server is a node of the Xenon hub at ${hub}. Create sessions through the hub: ` +
+                'it applies the team rules, reservations and blocks for this node’s devices, and a ' +
+                'node refuses a session that does not come from it.');
+        });
+    }
+    /**
+     * A grant is for the phone the hub pinned in the caps it forwarded
+     * (capsForNode). Caps that name another one, or a list to pick from, are
+     * not a create the hub sent: refused before anything is allocated.
+     */
+    assertGrantNamesCapsPhone(caps, grant) {
+        var _a, _b;
+        const merged = (0, xenonOptions_1.mergedFirstMatch)(caps);
+        if (merged['appium:udid'] === grant.udid && merged['appium:udids'] === undefined)
+            return;
+        this.logger.error(`❌ Rejecting session: the hub's token is for ${grant.udid}, and the capabilities name ` +
+            `${(_b = (_a = merged['appium:udids']) !== null && _a !== void 0 ? _a : merged['appium:udid']) !== null && _b !== void 0 ? _b : 'no device'}`);
+        throw new base_driver_1.errors.InvalidArgumentError("session rejected: the hub's token for this session names another device");
+    }
+    /**
+     * The session's identity when the hub forwarded the create with its grant:
+     * the owner the hub verified, unscoped (the hub applied the team rule), and
+     * no lease override (the hub resolved the lease).
+     */
+    authorizeHubGrant(grant) {
+        return {
+            apiKeyId: null,
+            userId: grant.userId,
+            callerTeamIds: undefined,
+            scoped: false,
+            leaseAccess: () => __awaiter(this, void 0, void 0, function* () { return ({ canOverride: false, teamIds: undefined }); }),
+            requester: { userId: grant.userId, teamId: null },
+        };
+    }
     /**
      * Resolves an uploaded-app id the session names to its plain download URL,
      * written into `caps` in place, when the session may see the app (by
@@ -406,8 +602,8 @@ let SessionLifecycleService = class SessionLifecycleService {
             const requestedTeam = (0, XenonCapabilityManager_1.extractTeamCap)(caps);
             if (requestedTeam) {
                 if (callerTeamIds !== undefined && !callerTeamIds.includes(requestedTeam)) {
-                    this.logger.error(`Rejecting session: xenon:team=${requestedTeam} is not one of the caller's teams (${callerTeamIds.join(', ') || 'shared pool only'})`);
-                    throw new base_driver_1.errors.InvalidArgumentError(`xenon:team '${requestedTeam}' is not allowed for this API key`);
+                    this.logger.error(`Rejecting session: xe:options.team=${requestedTeam} is not one of the caller's teams (${callerTeamIds.join(', ') || 'shared pool only'})`);
+                    throw new base_driver_1.errors.InvalidArgumentError(`xe:options.team '${requestedTeam}' is not allowed for this API key`);
                 }
                 return {
                     apiKeyId: row.id,
@@ -597,21 +793,29 @@ let SessionLifecycleService = class SessionLifecycleService {
                     'xenon.udid': device.udid,
                 });
             }
-            yield (0, device_service_1.updatedAllocatedDevice)(device, {
-                busy: true,
+            // The session takes over the pending claim its phone was allocated with.
+            yield (0, device_service_1.claimDeviceForSession)(device, sessionId, {
                 session_id: sessionId,
                 lastCmdExecutedAt: new Date().getTime(),
                 sessionStartTime: new Date().getTime(),
                 sessionProgress: 'Session Active',
             });
+            // Where the session gateway sends this session's commands: the node's own
+            // base path, which need not be this hub's.
+            let webDriverUrl;
             if (isRemote) {
                 typedi_1.Container.get(CircuitBreaker_1.CircuitBreaker).recordSuccess(device.host);
-                (0, wd_command_proxy_1.addProxyHandler)(sessionId, device.host);
+                webDriverUrl = yield (0, nodeWebDriverUrl_1.nodeWebDriverUrl)(device, context.nodeBasePath);
             }
             const freshDevice = yield this.getFreshDevice(device);
-            const sessionInstance = this.createSessionInstance(sessionId, freshDevice, sessionResponse, xenonCapabilities, driver);
+            const sessionInstance = this.createSessionInstance(sessionId, freshDevice, sessionResponse, xenonCapabilities, driver, webDriverUrl);
             sessionInstance.apiKeyId = apiKeyId;
             sessionInstance.userId = userId;
+            // A session this server drives: its owner is known while it runs, row or
+            // not (a node writes none for the hub's sessions; LiveSessionOwners).
+            if (sessionInstance instanceof LocalSession_1.LocalSession) {
+                typedi_1.Container.get(LiveSessionOwners_1.LiveSessionOwners).record(sessionId, userId);
+            }
             yield this.applyPostSessionLogic(sessionInstance, xenonCapabilities, freshDevice);
         });
     }
@@ -628,7 +832,7 @@ let SessionLifecycleService = class SessionLifecycleService {
             }
         });
     }
-    createSessionInstance(sessionId, device, response, caps, driver) {
+    createSessionInstance(sessionId, device, response, caps, driver, webDriverUrl) {
         const context = typedi_1.Container.get(PluginContext_1.PluginContext);
         const sessionOptions = {
             sessionId,
@@ -636,7 +840,7 @@ let SessionLifecycleService = class SessionLifecycleService {
             sessionResponse: response,
             xenonOption: caps,
         };
-        const nodeWebdriverUrl = (0, helpers_1.nodeUrl)(device, context.nodeBasePath);
+        const nodeWebdriverUrl = webDriverUrl !== null && webDriverUrl !== void 0 ? webDriverUrl : (0, helpers_1.nodeUrl)(device, context.nodeBasePath);
         if (device.nodeId === context.nodeId) {
             return new LocalSession_1.LocalSession(Object.assign(Object.assign({}, sessionOptions), { driver }));
         }
@@ -686,17 +890,53 @@ let SessionLifecycleService = class SessionLifecycleService {
                     this.logger.warn(`⚠️ Failed to start video recording for ${session.getId()}: ${err.message}`);
                 }
             }
-            if ((isDashboardEnabled && shouldSaveLogs) || (isVideoRecordingEnabled && shouldSaveLogs)) {
+            // A session another server runs is always registered, whatever the
+            // dashboard and video settings: SESSION_MANAGER is where the session
+            // gateway finds it to forward its commands.
+            const routedElsewhere = session.getType() !== SessionType_1.default.LOCAL;
+            if (routedElsewhere ||
+                (isDashboardEnabled && shouldSaveLogs) ||
+                (isVideoRecordingEnabled && shouldSaveLogs)) {
                 SessionManager_1.SESSION_MANAGER.addSession(session.getId(), session);
-                if (this.isHub(context.pluginArgs) && isDashboardEnabled) {
+                if (this.isHub(context.pluginArgs) && isDashboardEnabled && shouldSaveLogs) {
                     yield event_manager_1.DASHBORD_EVENT_MANAGER.onSessionStarted(caps, session, device);
                 }
+                else if (routedElsewhere) {
+                    yield this.recordRoutedSession(caps, session, device);
+                }
+            }
+        });
+    }
+    /**
+     * The row a hub keeps for a session it routes to a node or a cloud when the
+     * dashboard's own (onSessionStarted) isn't written: with the dashboard off,
+     * and for every cloud session. After a restart the hub finds where the
+     * session runs, and who owns it, only from this row (SessionLocator,
+     * recoverActiveSessions, SessionOwnerResolver): without it every node
+     * session was sent to the hub's own Appium, which had no such session.
+     *
+     * Only what routing and ownership need: no profiling, logs or dashboard
+     * event. onSessionStopped closes it like any other row. A local session's
+     * row is still the dashboard's alone. A failed write is logged, not
+     * thrown: the session exists, and is routed from memory until a restart.
+     */
+    recordRoutedSession(caps, session, device) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            try {
+                yield prisma_1.prisma.session.create({
+                    data: Object.assign(Object.assign({ id: session.getId(), name: caps[XenonCapabilityManager_1.XENON_CAPABILITIES.SESSION_NAME] || undefined }, (0, event_manager_1.storedSessionCapabilities)(lodash_1.default.assign({}, session.getCapabilities()))), { node_id: device.nodeId || '', has_live_video: false, video_recording_enabled: caps[XenonCapabilityManager_1.XENON_CAPABILITIES.VIDEO_RECORDING] === true, device_udid: device.udid || '', device_platform: device.platform || '', device_version: device.sdk || '', device_name: device.name, status: 'running', api_key_id: (_a = session.apiKeyId) !== null && _a !== void 0 ? _a : null, user_id: (_b = session.userId) !== null && _b !== void 0 ? _b : null }),
+                });
+            }
+            catch (err) {
+                this.logger.warn(`Could not record session ${session.getId()} on ${device.udid}: ${(_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : err}. ` +
+                    'It is routed from memory, and a restart of this hub loses it.');
             }
         });
     }
     handleSessionFailure(session, device, isRemote) {
         return __awaiter(this, void 0, void 0, function* () {
-            yield (0, device_service_1.unblockDevice)(device.udid, device.host);
+            yield (0, device_service_1.releasePendingClaim)(device);
             yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, '');
             if (isRemote) {
                 typedi_1.Container.get(CircuitBreaker_1.CircuitBreaker).recordFailure(device.host);
@@ -704,15 +944,26 @@ let SessionLifecycleService = class SessionLifecycleService {
             this.throwProperError(session, device.host);
         });
     }
-    forwardSessionRequest(device, caps) {
-        return __awaiter(this, void 0, void 0, function* () {
+    /**
+     * POST the create to the phone's node (or cloud provider). `hubToken` is
+     * this hub's create token for a peer Xenon node (HubSessionTokenIssuer),
+     * sent as `x-xenon-hub-token`; nothing else of the client's goes with it.
+     */
+    forwardSessionRequest(device_1, caps_1) {
+        return __awaiter(this, arguments, void 0, function* (device, caps, hubToken = null) {
             const context = typedi_1.Container.get(PluginContext_1.PluginContext);
-            const remoteUrl = `${(0, helpers_1.nodeUrl)(device, context.nodeBasePath)}/session`;
+            const remoteUrl = `${yield (0, nodeWebDriverUrl_1.nodeWebDriverUrl)(device, context.nodeBasePath)}/session`;
+            const headers = { 'Content-Type': 'application/json' };
+            if (hubToken)
+                headers[hubSessionToken_1.HUB_TOKEN_HEADER] = hubToken;
+            // Sent once, with a create's timeout (REMOTE_CREATE_TIMEOUT_MS).
             const config = {
                 method: 'post',
                 url: remoteUrl,
-                headers: { 'Content-Type': 'application/json' },
+                headers,
                 data: { capabilities: caps },
+                timeout: exports.REMOTE_CREATE_TIMEOUT_MS,
+                retry: false,
             };
             if (context.pluginArgs.proxy) {
                 this.logger.info(`Added proxy to axios config: ${JSON.stringify(context.pluginArgs.proxy)}`);
@@ -793,6 +1044,11 @@ let SessionLifecycleService = class SessionLifecycleService {
             typeof session === 'object' &&
             Object.prototype.hasOwnProperty.call(session, 'error')) {
             let errorMessage = session.error;
+            // Appium answers a refused create as `{ error: <Error> }`. Rethrow it, so
+            // the client gets Appium's reason and status; JSON.stringify of an Error
+            // is `{}`.
+            if (errorMessage instanceof Error)
+                throw errorMessage;
             if (typeof errorMessage === 'object') {
                 errorMessage = JSON.stringify(errorMessage);
             }
@@ -818,7 +1074,7 @@ let SessionLifecycleService = class SessionLifecycleService {
             // which releases ports and archives video twice.
             if (sessionId) {
                 yield sessionCleanupLock.acquire(sessionId, () => __awaiter(this, void 0, void 0, function* () {
-                    yield (0, device_service_1.unblockDeviceMatchingFilter)({ session_id: sessionId });
+                    yield (0, device_service_1.releaseSessionDevices)(sessionId);
                     this.logger.info(`📱 Unblocking the device that is blocked for session ${sessionId}`);
                     const session = SessionManager_1.SESSION_MANAGER.getSession(sessionId);
                     if (session && !session.isStopping) {
@@ -847,6 +1103,7 @@ let SessionLifecycleService = class SessionLifecycleService {
             }
             finally {
                 if (sessionId) {
+                    typedi_1.Container.get(LiveSessionOwners_1.LiveSessionOwners).forget(sessionId);
                     yield sessionCleanupLock.acquire(sessionId, () => __awaiter(this, void 0, void 0, function* () {
                         const session = SessionManager_1.SESSION_MANAGER.getSession(sessionId);
                         if (!session) {
@@ -872,6 +1129,7 @@ let SessionLifecycleService = class SessionLifecycleService {
                         }
                         yield event_manager_1.DASHBORD_EVENT_MANAGER.onSessionStopped(sessionId, status, reason);
                         SessionManager_1.SESSION_MANAGER.removeSession(sessionId);
+                        typedi_1.Container.get(hubSessionToken_1.HubSessionTokenIssuer).forget(sessionId);
                         try {
                             const { getSessionById } = yield Promise.resolve().then(() => __importStar(require('../dashboard/services/session-service')));
                             const sessionData = yield getSessionById(sessionId);
@@ -956,7 +1214,7 @@ let SessionLifecycleService = class SessionLifecycleService {
         return __awaiter(this, void 0, void 0, function* () {
             yield sessionCleanupLock.acquire(sessionId, () => __awaiter(this, void 0, void 0, function* () {
                 try {
-                    yield (0, device_service_1.unblockDeviceMatchingFilter)({ session_id: sessionId });
+                    yield (0, device_service_1.releaseSessionDevices)(sessionId);
                 }
                 catch (err) {
                     this.logger.warn(`[shutdown] unblock failed for ${sessionId}: ${err.message}`);
@@ -979,6 +1237,7 @@ let SessionLifecycleService = class SessionLifecycleService {
                     this.logger.warn(`[shutdown] onSessionStopped failed for ${sessionId}: ${err.message}`);
                 }
                 SessionManager_1.SESSION_MANAGER.removeSession(sessionId);
+                typedi_1.Container.get(LiveSessionOwners_1.LiveSessionOwners).forget(sessionId);
             }));
         });
     }

package/lib/src/services/ShutdownCoordinator.js

@@ -23,6 +23,7 @@ const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../logger"));
 const SessionManager_1 = require("../sessions/SessionManager");
 const SessionLifecycleService_1 = require("./SessionLifecycleService");
+const SessionType_1 = __importDefault(require("../enums/SessionType"));
 // Graceful shutdown phase that runs BEFORE the existing infrastructure
 // teardown in index.ts:cleanup(). Active sessions get a bounded chance to
 // archive their video + release ports + mark themselves failed, so we don't
@@ -48,7 +49,12 @@ let ShutdownCoordinator = class ShutdownCoordinator {
                 return { attempted: 0, completed: 0 };
             }
             this.draining = true;
-            const sessions = SessionManager_1.SESSION_MANAGER.getAllSessions();
+            // Only this server's own sessions: they die with the process. A node's or
+            // a cloud provider's session keeps running there, and the restarted hub
+            // routes it again from its database (SessionManager.recoverActiveSessions).
+            // Finalizing it here released the phone and closed the row, so recovery
+            // found nothing, and the node held a session no client could reach.
+            const sessions = SessionManager_1.SESSION_MANAGER.getAllSessions().filter((session) => session.getType() === SessionType_1.default.LOCAL);
             if (sessions.length === 0) {
                 this.logger.info('No active sessions to drain');
                 return { attempted: 0, completed: 0 };

package/lib/src/services/SocketServer.js

@@ -32,6 +32,9 @@ const EventLogService_1 = require("./EventLogService");
 const SocketEvents_1 = require("../enums/SocketEvents");
 const callerTeamIds_1 = require("./device-access/callerTeamIds");
 const DeviceTeamResolver_1 = require("./device-access/DeviceTeamResolver");
+const upgradeRouter_1 = require("../app/ws/upgradeRouter");
+/** socket.io's default path, which the dashboard and nodes connect to. */
+const SOCKET_IO_PATH = '/socket.io';
 const SESSION_COOKIE = 'xenon_dashboard_session';
 function readCookie(cookieHeader, name) {
     if (!cookieHeader)
@@ -54,7 +57,13 @@ let SocketServer = SocketServer_1 = class SocketServer {
         this.deliveries = new Map();
     }
     initialize(server) {
-        this.io = new socket_io_1.Server(server, {
+        // socket.io (engine.io) takes its websocket transport by adding its own
+        // `upgrade` listener, which would also see every other upgrade and end
+        // the ones it doesn't own after 1 s. The upgrade router moves that
+        // listener behind socket.io's path, engine.io's own test (a prefix match
+        // on the raw URL), so it sees only its own upgrades (upgradeRouter.ts).
+        this.io = (0, upgradeRouter_1.upgradeRouterFor)(server).adopt('socket.io', (req) => { var _a; return String((_a = req.url) !== null && _a !== void 0 ? _a : '').startsWith(`${SOCKET_IO_PATH}/`); }, () => new socket_io_1.Server(server, {
+            path: SOCKET_IO_PATH,
             // Same-origin only. Browsers on a different origin are blocked at the
             // handshake; server-to-server node connections send no Origin header
             // and are unaffected. Matches the apiRouter cors({origin:false}) policy.
@@ -62,7 +71,7 @@ let SocketServer = SocketServer_1 = class SocketServer {
                 origin: false,
                 methods: ['GET', 'POST'],
             },
-        });
+        }));
         this.io.use((socket, next) => __awaiter(this, void 0, void 0, function* () {
             try {
                 const identity = yield this.authenticate(socket);