@xenon-device-management/xenon 2.13.1 → 2.13.2

package/lib/src/app/routers/control.js

@@ -88,6 +88,8 @@ const streamLeave_1 = require("./streamLeave");
 const SessionOwnerResolver_1 = require("../../services/device-access/SessionOwnerResolver");
 const actor_1 = require("../../services/device-access/actor");
 const deviceAccessPolicy_1 = require("../../services/device-access/deviceAccessPolicy");
+const leaseHold_1 = require("../../services/device-access/leaseHold");
+const activeLeases_1 = require("../../services/lease/activeLeases");
 /**
  * The answer for an unknown udid, and for another team's phone (see
  * deviceTeamGuard): the same JSON on every route. Most routes used to send
@@ -623,7 +625,7 @@ const MJPEG_PROXY_CACHE = new Map();
  * Start stream endpoint - Initiates WDA and MJPEG streaming for iOS devices
  */
 router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     const { udid } = req.params;
     // Someone is about to watch: a page that just left (a reload, or another tab
     // closing) must not stop the stream this page is starting.
@@ -654,6 +656,18 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
             return res.status(503).json((0, deviceAccessPolicy_1.ownershipUnavailableBody)());
         }
     }
+    // Busy with nothing in session_id is a lease's lock: is it the caller's?
+    let leaseHolder = false;
+    if (device.busy && !device.session_id && !actor.isAdmin) {
+        try {
+            const held = yield (0, leaseHold_1.leaseHoldFor)({ udid, host: device.host }, (u, h) => (0, activeLeases_1.activeLeaseOn)(u, h), (id) => ownerResolver.leaseHolderOf(id));
+            leaseHolder = (0, deviceAccessPolicy_1.isLeaseHolder)(held, actorUserId, actor.apiKeyId);
+        }
+        catch (e) {
+            logger_1.default.error(`stream/start: lease lookup failed for ${udid}: ${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e}`);
+            return res.status(503).json((0, deviceAccessPolicy_1.ownershipUnavailableBody)());
+        }
+    }
     const conflict = (0, streamStartConflict_1.decideStreamStartConflict)({
         udid,
         busy: !!device.busy,
@@ -663,6 +677,7 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
         actorUserId,
         actorApiKeyId: actor.apiKeyId,
         isAdmin: actor.isAdmin,
+        leaseHolder,
     });
     if (conflict.action === 'deny') {
         // holderName lookup is cosmetic — a failure here must still deny (never
@@ -673,7 +688,7 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
                 holderName = yield ownerResolver.displayName(conflict.holderId);
             }
             catch (e) {
-                logger_1.default.warn(`stream/start: holder name lookup failed for ${conflict.holderId}: ${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e}`);
+                logger_1.default.warn(`stream/start: holder name lookup failed for ${conflict.holderId}: ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e}`);
             }
         }
         logger_1.default.warn(`Manual Control refused for ${udid}: ${conflict.code} (holder=${conflict.holderId || 'unknown'})`);
@@ -685,11 +700,11 @@ router.post('/:udid/stream/start', (req, res) => __awaiter(void 0, void 0, void
             yield (0, device_service_1.unblockDevice)(udid, device.host);
         }
         catch (e) {
-            logger_1.default.warn(`Failed to clear orphaned lock on ${udid}: ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e}`);
+            logger_1.default.warn(`Failed to clear orphaned lock on ${udid}: ${(_d = e === null || e === void 0 ? void 0 : e.message) !== null && _d !== void 0 ? _d : e}`);
         }
     }
     try {
-        const h264Cfg = (0, androidH264Config_1.resolveAndroidH264)((_d = typedi_1.Container.get(PluginContext_1.PluginContext).pluginArgs.streaming) === null || _d === void 0 ? void 0 : _d.androidH264);
+        const h264Cfg = (0, androidH264Config_1.resolveAndroidH264)((_e = typedi_1.Container.get(PluginContext_1.PluginContext).pluginArgs.streaming) === null || _e === void 0 ? void 0 : _e.androidH264);
         const flagOn = h264Cfg.enabled;
         // A recording device keeps MJPEG preview so we never run screenrecord and
         // the recording's screencap pipeline against the same device at once.

package/lib/src/app/routers/streamStartConflict.js

@@ -21,6 +21,9 @@ function decideStreamStartConflict(i) {
     var _a, _b;
     if (!i.busy)
         return PROCEED;
+    // Busy only by the caller's own lease: their phone to preview.
+    if (i.leaseHolder && !i.sessionId)
+        return PROCEED;
     if ((0, manualLock_1.isManualLock)(i.sessionId)) {
         // Orphan: lock persisted but nothing is serving (server restart, crashed
         // stop, H.264 stop that skipped unlock). Any caller may reclaim it.

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

@@ -53,6 +53,7 @@ const prisma_1 = require("../prisma");
 const manualLock_1 = require("../services/recording/manualLock");
 const deviceVisibility_1 = require("../services/device-access/deviceVisibility");
 const DeviceTeamResolver_1 = require("../services/device-access/DeviceTeamResolver");
+const activeLeases_1 = require("../services/lease/activeLeases");
 // Use a Proxy to ensure we're always using the latest store from the factory,
 // which is critical for test isolation when the factory cache is cleared.
 const store = new Proxy({}, {
@@ -434,10 +435,49 @@ function releaseClaimOn(device, ref) {
         }
         yield (0, device_utils_1.setUtilizationTime)(device.udid, totalUtilization);
         logger_1.default.debug(`Released ${JSON.stringify(ref)} on ${device.udid}`);
+        if (yield keepLeaseLock(device))
+            return true;
         emitUnblocked(device);
         return true;
     });
 }
+/**
+ * A session's phone that an SDK lease still holds goes back to the lease,
+ * not to the pool: the release above cleared `busy`, which is the lease's
+ * only lock (deviceClaims.ts). Allocation would skip the phone anyway, but
+ * the device list, the ownership guard and the dashboard read `busy`. The
+ * lease's own end (release, or LeaseOrphanSweeper) clears it. True when the
+ * phone was kept for its lease.
+ */
+function keepLeaseLock(device) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            if (!(yield (0, activeLeases_1.activeLeaseOn)(device.udid, device.host)))
+                return false;
+            // lastCmdExecutedAt, so that if this lock outlives its lease (the undo
+            // below fails) the idle sweeper still frees it: it skips the phone only
+            // while a live lease holds it.
+            yield store.updateDevice(device.udid, device.host, {
+                busy: true,
+                lastCmdExecutedAt: Date.now(),
+            });
+            // The lease may have ended between the check and the write; its own
+            // release ran before ours and cleared nothing. Then undo, by the same
+            // conditional clear it uses. A release after this check runs after the
+            // write, and clears it itself.
+            if (!(yield (0, activeLeases_1.activeLeaseOn)(device.udid, device.host))) {
+                yield store.releaseLeaseLock(device.udid, device.host);
+                return false;
+            }
+            logger_1.default.debug(`Kept ${device.udid} at ${device.host} busy for its lease`);
+            return true;
+        }
+        catch (error) {
+            logger_1.default.warn(`Could not check ${device.udid} for a lease after its session: ${error}`);
+            return false;
+        }
+    });
+}
 /** The phone's total use once the session on it now ends. */
 function utilizationAfter(device) {
     var _a;

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

@@ -246,7 +246,10 @@ class LokiDeviceStore {
             });
             const blockedKeys = new Set(activeLeases.map((l) => `${l.deviceUdid}@${l.deviceHost}`));
             const devices = yield this.getDevices(filterOptions);
-            const available = devices.find((d) => !d.busy && !d.userBlocked && !blockedKeys.has(`${d.udid}@${d.host}`));
+            const available = devices.find((d) => !d.busy &&
+                !d.userBlocked &&
+                !blockedKeys.has(`${d.udid}@${d.host}`) &&
+                (!options.only || options.only.has(`${d.udid}@${d.host}`)));
             if (available) {
                 yield this.updateDevice(available.udid, available.host, Object.assign({ busy: true }, (options.claim ? { claimedAt: Date.now(), claimSessionId: null } : {})));
                 return available;

package/lib/src/data-service/prisma-store.js

@@ -323,7 +323,8 @@ class PrismaDeviceStore {
             const candidates = yield this.getDevices(Object.assign(Object.assign({}, filterOptions), { busy: false }));
             // 2. Attempt to atomically lock them one by one, skipping lease-blocked devices
             for (const device of candidates) {
-                if (blockedKeys.has(`${device.udid}@${device.host}`)) {
+                const key = `${device.udid}@${device.host}`;
+                if (blockedKeys.has(key) || (options.only && !options.only.has(key))) {
                     continue;
                 }
                 const now = Date.now();

package/lib/src/device-utils.js

@@ -99,6 +99,7 @@ const config_1 = require("./config");
 const device_store_1 = require("./data-service/device-store");
 const leaseSessionCaps_1 = require("./services/lease/leaseSessionCaps");
 const deviceVisibility_1 = require("./services/device-access/deviceVisibility");
+const activeLeases_1 = require("./services/lease/activeLeases");
 // Use a Proxy to ensure we're always using the latest store from the factory,
 // which is critical for test isolation when the factory cache is cleared.
 const pendingStore = new Proxy({}, {
@@ -182,6 +183,14 @@ function allocateDeviceForSession(capability_1, deviceTimeOutMs_1, deviceQueryIn
             // text or its stack tells them apart.
             if (!leasedDevice)
                 throw new Error((0, leaseSessionCaps_1.leaseRefusalMessage)(leaseIdCap));
+            // As for an allocated phone below: the idle sweeper reads this session's
+            // own timeout from the row, and its idle time from now, not from when the
+            // lease was taken. Without it a leased session was ended after the
+            // server-wide newCommandTimeoutSec, whatever the session asked for.
+            yield (0, device_service_1.updatedAllocatedDevice)(leasedDevice, {
+                newCommandTimeout: sessionNewCommandTimeout(firstMatch, pluginArgs),
+                lastCmdExecutedAt: Date.now(),
+            });
             return leasedDevice;
         }
         const filters = getDeviceFiltersFromCapability(firstMatch, pluginArgs);
@@ -195,29 +204,45 @@ function allocateDeviceForSession(capability_1, deviceTimeOutMs_1, deviceQueryIn
         const intervalBetweenAttempts = firstMatch[customCapability.deviceQueryInterval] || deviceQueryIntervalMs;
         let device = null;
         const store = device_store_1.DeviceStoreFactory.getStore();
+        // Set once the wait has given up. waitUntil rejects on its timeout but
+        // doesn't stop an attempt already running, which could then claim a phone
+        // for a create that has failed: a pending claim nobody would ever use.
+        let abandoned = false;
         try {
             yield (0, async_wait_until_1.default)(() => __awaiter(this, void 0, void 0, function* () {
+                if (abandoned)
+                    return false;
                 const maxSessions = getDeviceManager().getMaxSessionCount();
                 const busyDevicesCount = yield getBusyDevicesCount();
                 if (maxSessions !== undefined && busyDevicesCount === maxSessions) {
                     logger_1.default.info(`Waiting for session available, already at max session count of: ${maxSessions}`);
                     return false;
                 }
-                // Get matching devices and find one that is not reserved
-                const matchingDevices = yield (0, device_service_1.getDevices)(filters);
-                const availableCandidate = matchingDevices.find((d) => !(0, device_service_1.isDeviceReserved)(d));
-                if (availableCandidate) {
+                // Get matching devices that are not reserved
+                const candidates = (yield (0, device_service_1.getDevices)(filters)).filter((d) => !(0, device_service_1.isDeviceReserved)(d));
+                if (candidates.length > 0) {
                     // Principal Intelligence: Multi-node consistent locking
-                    // Attempt to atomically claim this specific device: busy, with a
-                    // pending claim for the session being created (deviceClaims.ts).
-                    device = yield store.findAndLockDevice(Object.assign(Object.assign({}, filters), { udid: [availableCandidate.udid] }), { claim: true });
-                    return device !== null;
+                    // Atomically claim one of them: busy, with a pending claim for the
+                    // session being created (deviceClaims.ts). Every candidate, not just
+                    // the first: the lock skips a phone an SDK lease holds, and offering
+                    // it alone stalled the create while other phones were free. Exact
+                    // (udid, host) pairs: a udid repeats across hosts, and a reserved
+                    // twin of a candidate must not be locked in its place.
+                    const locked = yield store.findAndLockDevice(Object.assign(Object.assign({}, filters), { udid: [...new Set(candidates.map((d) => d.udid))] }), { claim: true, only: new Set(candidates.map((d) => `${d.udid}@${d.host}`)) });
+                    if (locked && abandoned) {
+                        yield (0, device_service_1.releasePendingClaim)(locked);
+                        return false;
+                    }
+                    device = locked;
+                    if (device !== null)
+                        return true;
                 }
                 logger_1.default.info(`Waiting for free device. Filter: ${JSON.stringify(filters)}}`);
                 return false;
             }), { timeout, intervalBetweenAttempts });
         }
         catch (err) {
+            abandoned = true;
             // figure out whether the device is simply busy or non-existent
             const filterCopy = Object.assign({}, filters);
             delete filterCopy.busy;
@@ -258,11 +283,9 @@ function allocateDeviceForSession(capability_1, deviceTimeOutMs_1, deviceQueryIn
             // Since findAndLockDevice already sets busy: true, we don't need blockDevice(device.udid, device.host);
             logger_1.default.info(`📱 Locked device ${lockedDevice.udid} at host ${lockedDevice.host} for new session`);
             yield updateCapabilityForDevice(capability, lockedDevice);
-            let newCommandTimeout = firstMatch['appium:newCommandTimeout'];
-            if (!newCommandTimeout) {
-                newCommandTimeout = pluginArgs.newCommandTimeoutSec;
-            }
-            yield (0, device_service_1.updatedAllocatedDevice)(lockedDevice, { newCommandTimeout });
+            yield (0, device_service_1.updatedAllocatedDevice)(lockedDevice, {
+                newCommandTimeout: sessionNewCommandTimeout(firstMatch, pluginArgs),
+            });
             return lockedDevice;
         }
         else {
@@ -271,6 +294,10 @@ function allocateDeviceForSession(capability_1, deviceTimeOutMs_1, deviceQueryIn
         }
     });
 }
+/** The session's own `appium:newCommandTimeout` (seconds), else the server's. */
+function sessionNewCommandTimeout(firstMatch, pluginArgs) {
+    return firstMatch['appium:newCommandTimeout'] || pluginArgs.newCommandTimeoutSec;
+}
 /**
  * The device a lease-bound session may use, or null when it may not: the lease
  * is missing, inactive or expired, the session did not prove it holds it, or
@@ -604,6 +631,23 @@ function releaseBlockedDevices(newCommandTimeout) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
         const busyDevices = yield unblockCandidateDevices();
+        // A phone an SDK lease holds is the lease's to time out (its heartbeats and
+        // expiry, LeaseOrphanSweeper), not idle until a session runs on it. A lease
+        // sets lastCmdExecutedAt when taken, so without this the sweeper freed a
+        // leased phone the new-command timeout later, before a slow first session
+        // had even started on it.
+        let leases = new Map();
+        if (busyDevices.length) {
+            try {
+                leases = yield (0, activeLeases_1.activeLeasesByDevice)();
+            }
+            catch (err) {
+                // Not knowing which phones are leased, sweeping would free all of them:
+                // their lastCmdExecutedAt is when the lease was taken. Next tick.
+                logger_1.default.warn(`Idle sweep skipped: could not read active leases: ${err}`);
+                return;
+            }
+        }
         logger_1.default.debug(`Found ${busyDevices.length} device candidates to be released`);
         for (const device of busyDevices) {
             // need to keep this to make typescript happy. good thing tho.
@@ -622,6 +666,12 @@ function releaseBlockedDevices(newCommandTimeout) {
                 }
                 continue;
             }
+            // Leased, with no session or hold on it: not idle.
+            if (leases.has((0, activeLeases_1.leaseKey)(device.udid, device.host)) &&
+                !device.claimSessionId &&
+                !device.session_id) {
+                continue;
+            }
             const timeoutSeconds = device.newCommandTimeout != undefined ? device.newCommandTimeout : newCommandTimeout;
             const timeSinceLastCmdExecuted = (currentEpoch - device.lastCmdExecutedAt) / 1000;
             if (timeSinceLastCmdExecuted > timeoutSeconds) {

package/lib/src/middleware/deviceAccessGuard.js

@@ -12,7 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OWNERSHIP_CHECKED_READS = exports.UNGUARDED_CONTROL_MUTATIONS = void 0;
+exports.LEASE_CHECKED_MUTATIONS = exports.OWNERSHIP_CHECKED_READS = exports.UNGUARDED_CONTROL_MUTATIONS = void 0;
 exports.deviceAccessGuard = deviceAccessGuard;
 const typedi_1 = require("typedi");
 const logger_1 = __importDefault(require("../logger"));
@@ -20,8 +20,10 @@ const manualLock_1 = require("../services/recording/manualLock");
 const controlDevice_1 = require("./controlDevice");
 const SessionOwnerResolver_1 = require("../services/device-access/SessionOwnerResolver");
 const deviceAccessPolicy_1 = require("../services/device-access/deviceAccessPolicy");
+const leaseHold_1 = require("../services/device-access/leaseHold");
 const actor_1 = require("../services/device-access/actor");
 const deviceClaims_1 = require("../data-service/deviceClaims");
+const activeLeases_1 = require("../services/lease/activeLeases");
 const STATE_CHANGING = new Set(['POST', 'PUT', 'DELETE', 'PATCH']);
 /**
  * Mutations under /control that this guard must NOT handle.
@@ -56,6 +58,14 @@ exports.UNGUARDED_CONTROL_MUTATIONS = [
  * "reads are cheap" assumption the mosaic depends on.
  */
 exports.OWNERSHIP_CHECKED_READS = ['clipboard', 'logs'];
+/**
+ * Unguarded mutations that still take the lease rule: starting a preview
+ * takes a hold on the phone. stream/start's own conflict handling knows
+ * holds and sessions, not leases, and on a hub the call goes on to the
+ * node, which knows nothing of the hub's leases. So a stranger is refused a
+ * leased phone here, before either, and the lease holder passes on to it.
+ */
+exports.LEASE_CHECKED_MUTATIONS = ['stream/start'];
 /**
  * Refuse /control mutations against a device somebody else holds.
  *
@@ -65,14 +75,16 @@ exports.OWNERSHIP_CHECKED_READS = ['clipboard', 'logs'];
  * handlers and was remembered in none of them.
  */
 function deviceAccessGuard(deps = {}) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const findDevice = (_a = deps.findDevice) !== null && _a !== void 0 ? _a : controlDevice_1.findControlDeviceInStore;
     const resolveSessionOwner = (_b = deps.resolveSessionOwner) !== null && _b !== void 0 ? _b : ((sid) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).ownerOf(sid));
     const describeHolder = (_c = deps.describeHolder) !== null && _c !== void 0 ? _c : ((id) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).displayName(id));
+    const findActiveLease = (_d = deps.findActiveLease) !== null && _d !== void 0 ? _d : ((udid, host) => (0, activeLeases_1.activeLeaseOn)(udid, host));
+    const resolveLeaseHolder = (_e = deps.resolveLeaseHolder) !== null && _e !== void 0 ? _e : ((id) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).leaseHolderOf(id));
     const unavailable = (res) => res.status(503).json((0, deviceAccessPolicy_1.ownershipUnavailableBody)());
     return function (req, res, next) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c;
+            var _a, _b, _c, _d, _e;
             // Router-level middleware has no req.params; controlAction reads the path.
             // It lowercases, as Express routes case-insensitively: `Stream/Start`
             // still reaches stream/start's own richer handling, and `Clipboard`
@@ -81,8 +93,9 @@ function deviceAccessGuard(deps = {}) {
             // Decide whether this request is in scope BEFORE touching the udid, so an
             // ordinary read (screenshot, stream, logs, page source) short-circuits here
             // exactly as it did when this guard was mutations-only.
+            const leaseOnly = req.method === 'POST' && exports.LEASE_CHECKED_MUTATIONS.includes(action);
             const inScope = STATE_CHANGING.has(req.method)
-                ? !exports.UNGUARDED_CONTROL_MUTATIONS.includes(action)
+                ? !exports.UNGUARDED_CONTROL_MUTATIONS.includes(action) || leaseOnly
                 : req.method === 'GET' && exports.OWNERSHIP_CHECKED_READS.includes(action);
             if (!action || !inScope)
                 return next();
@@ -116,6 +129,26 @@ function deviceAccessGuard(deps = {}) {
             // resolved device to reason about ownership at all.
             if (!device)
                 return next();
+            if (leaseOnly) {
+                if (actor.isAdmin)
+                    return next();
+                let held;
+                try {
+                    held = yield (0, leaseHold_1.leaseHoldFor)({ udid, host: device.host }, findActiveLease, resolveLeaseHolder);
+                }
+                catch (e) {
+                    logger_1.default.error(`deviceAccessGuard: lease lookup failed for ${udid}: ${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e}`);
+                    return unavailable(res);
+                }
+                if (!held || (0, deviceAccessPolicy_1.isLeaseHolder)(held, actor.userId, actor.apiKeyId))
+                    return next();
+                return deny(req, res, udid, actor.userId, {
+                    allow: false,
+                    code: 'device_held_by_another_user',
+                    holderId: (_c = held.holderUserId) !== null && _c !== void 0 ? _c : '',
+                    heldBy: 'lease',
+                });
+            }
             let sessionOwnerUserId = null;
             if (device.busy && device.session_id && !(0, manualLock_1.isManualLock)(device.session_id)) {
                 try {
@@ -124,7 +157,19 @@ function deviceAccessGuard(deps = {}) {
                 catch (e) {
                     // Same reasoning as the device lookup above: not knowing who owns a
                     // live session is exactly the case where we must not guess allow.
-                    logger_1.default.error(`deviceAccessGuard: session owner lookup failed for ${device.session_id}: ${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e}`);
+                    logger_1.default.error(`deviceAccessGuard: session owner lookup failed for ${device.session_id}: ${(_d = e === null || e === void 0 ? void 0 : e.message) !== null && _d !== void 0 ? _d : e}`);
+                    return unavailable(res);
+                }
+            }
+            let lease = null;
+            if (!actor.isAdmin) {
+                try {
+                    lease = yield (0, leaseHold_1.leaseHoldFor)({ udid, host: device.host }, findActiveLease, resolveLeaseHolder);
+                }
+                catch (e) {
+                    // A leased phone is held whatever `busy` says: not knowing whether a
+                    // lease holds it is not knowing who owns it.
+                    logger_1.default.error(`deviceAccessGuard: lease lookup failed for ${udid}: ${(_e = e === null || e === void 0 ? void 0 : e.message) !== null && _e !== void 0 ? _e : e}`);
                     return unavailable(res);
                 }
             }
@@ -138,9 +183,16 @@ function deviceAccessGuard(deps = {}) {
                 actorUserId: actor.userId,
                 actorApiKeyId: actor.apiKeyId,
                 isAdmin: actor.isAdmin,
+                lease,
             });
             if (decision.allow)
                 return next();
+            return deny(req, res, udid, actor.userId, decision);
+        });
+    };
+    function deny(req, res, udid, actorUserId, decision) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             // describeHolder is cosmetic — it only resolves a display name for the
             // deny message. A failure here must still deny (never flip to allow) but
             // must not hang the request either; fall back to no holder name.
@@ -150,12 +202,14 @@ function deviceAccessGuard(deps = {}) {
                     holderName = yield describeHolder(decision.holderId);
                 }
                 catch (e) {
-                    logger_1.default.warn(`deviceAccessGuard: holder name lookup failed for ${decision.holderId}: ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e}`);
+                    logger_1.default.warn(`deviceAccessGuard: holder name lookup failed for ${decision.holderId}: ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}`);
                 }
             }
-            logger_1.default.warn(`Device access denied: ${actor.userId} -> ${req.method} ${req.originalUrl} ` +
+            logger_1.default.warn(`Device access denied: ${actorUserId} -> ${req.method} ${req.originalUrl} ` +
                 `on ${udid} (${decision.code}, holder=${decision.holderId || 'unknown'})`);
-            return res.status(409).json((0, deviceAccessPolicy_1.denyBody)(decision.code, decision.holderId, holderName));
+            return res
+                .status(409)
+                .json((0, deviceAccessPolicy_1.denyBody)(decision.code, decision.holderId, holderName, decision.heldBy));
         });
-    };
+    }
 }

package/lib/src/services/ServerManager.js

@@ -71,6 +71,7 @@ const LogcatStreamService_1 = require("../device-managers/android/LogcatStreamSe
 const IOSLogStreamService_1 = require("../device-managers/ios/IOSLogStreamService");
 const logSource_1 = require("./logcat/logSource");
 const SessionOwnerResolver_1 = require("./device-access/SessionOwnerResolver");
+const activeLeases_1 = require("./lease/activeLeases");
 const ticketActorAccess_1 = require("./device-access/ticketActorAccess");
 // enable resolveJsonModule in tsconfig must be true for this to work
 const package_json_1 = __importDefault(require("../../package.json"));
@@ -169,6 +170,8 @@ let ServerManager = ServerManager_1 = class ServerManager {
                     authorize: (0, ticketActorAccess_1.makeTicketActorAuthorizer)({
                         findDevice: (udid) => device_store_1.DeviceStoreFactory.getStore().findDevice({ udid }),
                         resolveSessionOwner: (sessionId) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).ownerOf(sessionId),
+                        findActiveLease: (udid, host) => (0, activeLeases_1.activeLeaseOn)(udid, host),
+                        resolveLeaseHolder: (actorId) => typedi_1.Container.get(SessionOwnerResolver_1.SessionOwnerResolver).leaseHolderOf(actorId),
                     }),
                     // One WebSocket, two transports. The device's platform picks which —
                     // see resolveLogSource. The filter is only meaningful for ostrace,

package/lib/src/services/SessionLifecycleService.js

@@ -222,9 +222,7 @@ let SessionLifecycleService = class SessionLifecycleService {
                 // Who asked, for the queue's team scoping (queueVisibility). On this row
                 // only, never in `caps`, and last so a client can't supply its own.
                 [queueVisibility_1.REQUESTER_KEY]: authResult.requester }));
-            const lockName = this.getLockName(caps);
-            this.logger.debug(`📱 Acquiring lock: ${lockName}`);
-            const device = yield commandsQueueGuard.acquire(lockName, () => __awaiter(this, void 0, void 0, function* () {
+            const allocate = () => __awaiter(this, void 0, void 0, function* () {
                 var _a;
                 try {
                     return yield (0, device_utils_1.allocateDeviceForSession)(caps, pluginArgs.deviceAvailabilityTimeoutMs, pluginArgs.deviceAvailabilityQueryIntervalMs, pluginArgs, sessionTeamIds, {
@@ -238,7 +236,21 @@ let SessionLifecycleService = class SessionLifecycleService {
                     yield (0, pending_sessions_service_1.removePendingSession)(pendingSessionId);
                     throw err;
                 }
-            }));
+            });
+            // Creates for a platform queue on one lock, first come first served, and
+            // each has its full deviceAvailabilityTimeoutMs from the head of the
+            // queue. A lease-bound session allocates nothing (its phone is the
+            // lease's) and doesn't queue: behind the lock it waited for every create
+            // ahead of it, each of which may wait minutes for a busy phone.
+            let device;
+            if ((0, leaseSessionCaps_1.leaseIdOf)(caps)) {
+                device = yield allocate();
+            }
+            else {
+                const lockName = this.getLockName(caps);
+                this.logger.debug(`📱 Acquiring lock: ${lockName}`);
+                device = yield commandsQueueGuard.acquire(lockName, allocate);
+            }
             yield (0, device_service_1.updateDeviceProgress)(device.udid, device.host, 'Allocating node resources...');
             this.logger.debug(`device.host: ${device.host} and pluginArgs.bindHostOrIp: ${pluginArgs.bindHostOrIp}`);
             const allocation = {

package/lib/src/services/device-access/SessionOwnerResolver.js

@@ -46,9 +46,34 @@ let SessionOwnerResolver = class SessionOwnerResolver {
         this.db = db;
         this.ownerCache = new Map();
         this.nameCache = new Map();
+        this.leaseHolderCache = new Map();
         /** The owners of this server's live sessions. A field, not a constructor parameter: TypeDI. */
         this.liveOwners = () => typedi_1.Container.get(LiveSessionOwners_1.LiveSessionOwners);
     }
+    /**
+     * The user behind a lease's `actorId`: the owner of the API key that
+     * created it, or, for a lease made with a bearer token, the user id itself.
+     * Positive results are cached, as for sessions: a lease's creator never
+     * changes.
+     */
+    leaseHolderOf(actorId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!actorId)
+                return null;
+            const cached = this.leaseHolderCache.get(actorId);
+            if (cached)
+                return cached;
+            const key = yield this.db.apiKey.findUnique({
+                where: { id: actorId },
+                select: { userId: true },
+            });
+            const holder = key ? ((_a = key.userId) !== null && _a !== void 0 ? _a : null) : actorId;
+            if (holder)
+                this.remember(this.leaseHolderCache, actorId, holder);
+            return holder;
+        });
+    }
     ownerOf(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
@@ -165,6 +190,7 @@ let SessionOwnerResolver = class SessionOwnerResolver {
     clear() {
         this.ownerCache.clear();
         this.nameCache.clear();
+        this.leaseHolderCache.clear();
     }
     remember(cache, key, value) {
         if (cache.size >= MAX_CACHE_ENTRIES)

package/lib/src/services/device-access/deviceAccessPolicy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSelfManualLock = isSelfManualLock;
 exports.isOwnSession = isOwnSession;
+exports.isLeaseHolder = isLeaseHolder;
 exports.evaluateDeviceAccess = evaluateDeviceAccess;
 exports.ownershipUnavailableBody = ownershipUnavailableBody;
 exports.denyBody = denyBody;
@@ -23,10 +24,39 @@ function isOwnSession(sessionOwnerUserId, actorUserId) {
     const owner = sessionOwnerUserId !== null && sessionOwnerUserId !== void 0 ? sessionOwnerUserId : '';
     return !!(owner && actorUserId && owner === actorUserId);
 }
+/**
+ * True when the caller holds the lease: by the key that created it, or as
+ * the user behind it (any credential of theirs, the dashboard included), as
+ * ownership is keyed on the user everywhere else.
+ */
+function isLeaseHolder(lease, actorUserId, actorApiKeyId) {
+    if (!lease)
+        return false;
+    if (actorApiKeyId && lease.actorId === actorApiKeyId)
+        return true;
+    return !!actorUserId && (lease.actorId === actorUserId || lease.holderUserId === actorUserId);
+}
 function evaluateDeviceAccess(input) {
-    var _a;
+    var _a, _b;
     if (input.isAdmin)
         return ALLOW;
+    if (input.lease) {
+        if (isLeaseHolder(input.lease, input.actorUserId, input.actorApiKeyId))
+            return ALLOW;
+        // A session on a leased phone proved it may use the lease; its owner
+        // keeps driving it, as with any session of their own.
+        if (input.sessionId &&
+            !(0, manualLock_1.isManualLock)(input.sessionId) &&
+            isOwnSession(input.sessionOwnerUserId, input.actorUserId)) {
+            return ALLOW;
+        }
+        return {
+            allow: false,
+            code: 'device_held_by_another_user',
+            holderId: (_a = input.lease.holderUserId) !== null && _a !== void 0 ? _a : '',
+            heldBy: 'lease',
+        };
+    }
     if (!input.busy)
         return ALLOW;
     const asUser = (0, manualLock_1.inspectManualLock)(input.sessionId, input.actorUserId, input.udid);
@@ -42,7 +72,7 @@ function evaluateDeviceAccess(input) {
     }
     // Not a manual lock: a real Appium session holds the device (or the row is
     // busy with no id at all, which is an inconsistent state we fail closed on).
-    const owner = (_a = input.sessionOwnerUserId) !== null && _a !== void 0 ? _a : '';
+    const owner = (_b = input.sessionOwnerUserId) !== null && _b !== void 0 ? _b : '';
     if (isOwnSession(input.sessionOwnerUserId, input.actorUserId))
         return ALLOW;
     return { allow: false, code: 'device_in_use_by_session', holderId: owner };
@@ -62,11 +92,13 @@ function ownershipUnavailableBody() {
         message: 'Could not verify device ownership. Try again.',
     };
 }
-function denyBody(code, holderId, holderName) {
+function denyBody(code, holderId, holderName, heldBy) {
     const who = holderName || 'another user';
-    const message = code === 'device_held_by_another_user'
-        ? `Device is being controlled by ${who}. Ask them to release it, or use an admin key to force-release.`
-        : `Device is in use by an Appium session owned by ${who}.`;
+    const message = heldBy === 'lease'
+        ? `Device is leased by ${who} through the SDK. It is free again when their lease ends.`
+        : code === 'device_held_by_another_user'
+            ? `Device is being controlled by ${who}. Ask them to release it, or use an admin key to force-release.`
+            : `Device is in use by an Appium session owned by ${who}.`;
     return {
         success: false,
         error: code,

package/lib/src/services/device-access/leaseHold.js

@@ -0,0 +1,26 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.leaseHoldFor = leaseHoldFor;
+/**
+ * The lease hold on a device row for an ownership decision, or null. Throws
+ * when either lookup does: the caller fails closed.
+ */
+function leaseHoldFor(device, findActiveLease, resolveLeaseHolder) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!(device === null || device === void 0 ? void 0 : device.udid) || !device.host)
+            return null;
+        const lease = yield findActiveLease(device.udid, device.host);
+        if (!lease)
+            return null;
+        return { actorId: lease.actorId, holderUserId: yield resolveLeaseHolder(lease.actorId) };
+    });
+}