@xenon-device-management/xenon 1.1.0

package/lib/src/device-utils.js

@@ -0,0 +1,663 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+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.getDeviceTypeFromApp = void 0;
+exports.isAndroid = isAndroid;
+exports.deviceType = deviceType;
+exports.isIOS = isIOS;
+exports.isAndroidAndIOS = isAndroidAndIOS;
+exports.isDeviceConfigPathAbsolute = isDeviceConfigPathAbsolute;
+exports.allocateDeviceForSession = allocateDeviceForSession;
+exports.updateCapabilityForDevice = updateCapabilityForDevice;
+exports.initializeStorage = initializeStorage;
+exports.getUtilizationTime = getUtilizationTime;
+exports.setUtilizationTime = setUtilizationTime;
+exports.getDeviceFiltersFromCapability = getDeviceFiltersFromCapability;
+exports.getBusyDevicesCount = getBusyDevicesCount;
+exports.updateDeviceList = updateDeviceList;
+exports.refreshSimulatorState = refreshSimulatorState;
+exports.setupCronCheckStaleDevices = setupCronCheckStaleDevices;
+exports.removeStaleDevices = removeStaleDevices;
+exports.unblockCandidateDevices = unblockCandidateDevices;
+exports.releaseBlockedDevices = releaseBlockedDevices;
+exports.setupCronReleaseBlockedDevices = setupCronReleaseBlockedDevices;
+exports.setupCronUpdateDeviceList = setupCronUpdateDeviceList;
+exports.cleanPendingSessions = cleanPendingSessions;
+exports.setupCronCleanPendingSessions = setupCronCleanPendingSessions;
+exports.setupCronCleanExpiredReservations = setupCronCleanExpiredReservations;
+exports.setupCronCleanupBuilds = setupCronCleanupBuilds;
+exports.stopAllTimers = stopAllTimers;
+/* eslint-disable no-prototype-builtins */
+const helpers_1 = require("./helpers");
+const XenonCapabilityManager_1 = require("./XenonCapabilityManager");
+const async_wait_until_1 = __importDefault(require("async-wait-until"));
+const typedi_1 = require("typedi");
+const device_managers_1 = require("./device-managers");
+const device_service_1 = require("./data-service/device-service");
+const logger_1 = __importDefault(require("./logger"));
+const Platform_1 = __importDefault(require("./enums/Platform"));
+const lodash_1 = __importDefault(require("lodash"));
+const fs_1 = __importDefault(require("fs"));
+const CapabilityManager_1 = __importDefault(require("./device-managers/cloud/CapabilityManager"));
+const AndroidDeviceManager_1 = __importDefault(require("./device-managers/AndroidDeviceManager"));
+const IOSDeviceManager_1 = __importDefault(require("./device-managers/IOSDeviceManager"));
+const IOSDiscoveryService_1 = require("./device-managers/ios/IOSDiscoveryService");
+const NodeDevices_1 = __importDefault(require("./device-managers/NodeDevices"));
+const device_store_1 = require("./data-service/device-store");
+// 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({}, {
+    get: (target, prop) => {
+        return device_store_1.DeviceStoreFactory.getPendingSessionStore()[prop];
+    },
+});
+const customCapability = {
+    deviceTimeOut: 'appium:deviceAvailabilityTimeout',
+    deviceQueryInterval: 'appium:deviceRetryInterval',
+    iphoneOnly: 'appium:iPhoneOnly',
+    ipadOnly: 'appium:iPadOnly',
+    udids: 'appium:udids',
+    minSDK: 'appium:minSDK',
+    maxSDK: 'appium:maxSDK',
+    filterByHost: 'appium:filterByHost',
+    tags: 'appium:tags',
+};
+let timer;
+let cronTimerToReleaseBlockedDevices;
+let cronTimerToUpdateDevices;
+let cronTimerToCleanPendingSessions;
+let cronTimerToCleanupBuilds;
+const getDeviceTypeFromApp = (app) => {
+    /* If the test is targeting safarim, then app capability will be empty */
+    if (!app) {
+        return;
+    }
+    return app.endsWith('.app') || app.endsWith('.zip') ? 'simulator' : 'real';
+};
+exports.getDeviceTypeFromApp = getDeviceTypeFromApp;
+function isAndroid(cliArgs) {
+    return cliArgs.Platform.toLowerCase() === Platform_1.default.ANDROID;
+}
+function deviceType(pluginArgs, device) {
+    const iosDeviceType = pluginArgs.iosDeviceType;
+    return iosDeviceType === device || iosDeviceType === 'both';
+}
+function isIOS(pluginArgs) {
+    return (0, helpers_1.isMac)() && pluginArgs.platform.toLowerCase() === Platform_1.default.IOS;
+}
+function isAndroidAndIOS(pluginArgs) {
+    return (0, helpers_1.isMac)() && pluginArgs.platform.toLowerCase() === Platform_1.default.BOTH;
+}
+function isDeviceConfigPathAbsolute(path) {
+    if ((0, helpers_1.checkIfPathIsAbsolute)(path)) {
+        return true;
+    }
+    else {
+        throw new Error(`Device Config Path ${path} should be absolute`);
+    }
+}
+/**
+ * For given capability, wait untill a free device is available from the database
+ * and update the capability json with required device informations
+ * @param capability
+ * @returns
+ */
+function allocateDeviceForSession(capability, deviceTimeOutMs, deviceQueryIntervalMs, pluginArgs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const firstMatch = Object.assign({}, capability.firstMatch[0], capability.alwaysMatch);
+        const filters = getDeviceFiltersFromCapability(firstMatch, pluginArgs);
+        const timeout = firstMatch[customCapability.deviceTimeOut] || deviceTimeOutMs;
+        const intervalBetweenAttempts = firstMatch[customCapability.deviceQueryInterval] || deviceQueryIntervalMs;
+        let device = null;
+        const store = device_store_1.DeviceStoreFactory.getStore();
+        try {
+            yield (0, async_wait_until_1.default)(() => __awaiter(this, void 0, void 0, function* () {
+                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) {
+                    // Principal Intelligence: Multi-node consistent locking
+                    // Attempt to atomically claim this specific device
+                    device = yield store.findAndLockDevice(Object.assign(Object.assign({}, filters), { udid: [availableCandidate.udid] }));
+                    return device !== null;
+                }
+                logger_1.default.info(`Waiting for free device. Filter: ${JSON.stringify(filters)}}`);
+                return false;
+            }), { timeout, intervalBetweenAttempts });
+        }
+        catch (err) {
+            // figure out whether the device is simply busy or non-existent
+            const filterCopy = Object.assign({}, filters);
+            delete filterCopy.busy;
+            delete filterCopy.userBlocked;
+            const possibleDevice = yield (0, device_service_1.getDevice)(filterCopy);
+            let failureReason = 'No device matching request.';
+            if ((possibleDevice === null || possibleDevice === void 0 ? void 0 : possibleDevice.busy) || (possibleDevice === null || possibleDevice === void 0 ? void 0 : possibleDevice.userBlocked)) {
+                failureReason = 'Device is busy or blocked.';
+            }
+            else if (possibleDevice && (0, device_service_1.isDeviceReserved)(possibleDevice)) {
+                failureReason = `Device is reserved by ${possibleDevice.reservedBy}.`;
+            }
+            throw new Error(`${failureReason}. Device request: ${JSON.stringify(filterCopy)}`);
+        }
+        // We have a locked device here
+        if (device !== null) {
+            const lockedDevice = device;
+            // Principal Health Check Integration: Ensure device is READY before allocation
+            if (!lockedDevice.cloud) {
+                const platform = lockedDevice.platform.toLowerCase();
+                const managers = yield getDeviceManager().deviceInstances();
+                const manager = managers.find((m) => {
+                    if (platform === Platform_1.default.ANDROID)
+                        return m instanceof AndroidDeviceManager_1.default;
+                    if (platform === Platform_1.default.IOS || platform === 'tvos')
+                        return m instanceof IOSDeviceManager_1.default;
+                    return false;
+                });
+                if (manager && manager.readyForSession) {
+                    const isReady = yield manager.readyForSession(lockedDevice);
+                    if (!isReady) {
+                        logger_1.default.error(`❌ [Allocation] Device ${lockedDevice.udid} failed pre-session health check. Unblocking.`);
+                        yield (0, device_service_1.unblockDevice)(lockedDevice.udid, lockedDevice.host);
+                        throw new Error(`Device ${lockedDevice.udid} is unhealthy and could not be autonomously recovered.`);
+                    }
+                }
+            }
+            // 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 });
+            return lockedDevice;
+        }
+        else {
+            // This should theoretically not be reached if waitUntil succeeded
+            throw new Error(`Device allocation failed unexpectedly for filters: ${JSON.stringify(filters)}`);
+        }
+    });
+}
+/**
+ * Adjust the capability for the device
+ * @param capability
+ * @param device
+ * @returns
+ */
+function updateCapabilityForDevice(capability, device) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!device.cloud) {
+            // Fetch additional info lazily if method exists on manager
+            const platform = device.platform.toLowerCase();
+            const manager = (yield getDeviceManager().deviceInstances()).find((m) => {
+                if (platform === Platform_1.default.ANDROID)
+                    return m instanceof AndroidDeviceManager_1.default;
+                if (platform === Platform_1.default.IOS || platform === 'tvos')
+                    return m instanceof IOSDeviceManager_1.default;
+                return false;
+            });
+            if (manager && manager.getAdditionalDeviceInfo) {
+                const additionalInfo = yield manager.getAdditionalDeviceInfo(device);
+                Object.assign(device, additionalInfo);
+            }
+            if (platform == Platform_1.default.ANDROID) {
+                yield (0, XenonCapabilityManager_1.androidCapabilities)(capability, device);
+            }
+            else {
+                yield (0, XenonCapabilityManager_1.iOSCapabilities)(capability, device);
+            }
+        }
+        else {
+            logger_1.default.info('Updating cloud capability for Device');
+            return new CapabilityManager_1.default(capability, device).getCapability();
+        }
+    });
+}
+/**
+ * Sets up node-persist storage in local cache
+ * @returns storage
+ */
+function initializeStorage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        logger_1.default.info('Initializing storage');
+        const basePath = (0, helpers_1.cachePath)('storage');
+        yield fs_1.default.promises.mkdir(basePath, { recursive: true });
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const storage = require('node-persist');
+        const localStorage = storage.create({ dir: basePath });
+        yield localStorage.init();
+        typedi_1.Container.set('LocalStorage', localStorage);
+    });
+}
+function getStorage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            typedi_1.Container.get('LocalStorage');
+        }
+        catch (err) {
+            logger_1.default.error(`Failed to get LocalStorage: Error ${err}`);
+            yield initializeStorage();
+        }
+        return typedi_1.Container.get('LocalStorage');
+    });
+}
+/**
+ * Gets utlization time for a device from storage
+ * Returns 0 if the device has not been used an thus utilization time has not been saved
+ * @param udid
+ * @returns number
+ */
+function getUtilizationTime(udid) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const value = (yield getStorage()).getItem(udid);
+            if (value !== undefined && value && !isNaN(yield value)) {
+                return value;
+            }
+            else {
+                //log.error(`Custom Exception: Utilizaiton time in cache is corrupted. Value = '${value}'.`);
+            }
+        }
+        catch (err) {
+            logger_1.default.error(`Failed to fetch Utilization Time \n ${err}`);
+        }
+        return 0;
+    });
+}
+/**
+ * Sets utilization time for a device to storage
+ * @param udid
+ * @param utilizationTime
+ */
+function setUtilizationTime(udid, utilizationTime) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield (yield getStorage()).setItem(udid, utilizationTime);
+    });
+}
+/**
+ * Method to get the device filters from the custom session capability
+ * This filter will be used as in the query to find the free device from the databse
+ * @param capability
+ * @returns IDeviceFilterOptions
+ */
+function getDeviceFiltersFromCapability(capability, pluginArgs) {
+    var _a;
+    const platformName = capability['platformName'] || capability['appium:platformName'];
+    const platform = platformName ? platformName.toLowerCase() : undefined;
+    const udids = capability[customCapability.udids]
+        ? capability[customCapability.udids].split(',').map(lodash_1.default.trim)
+        : (_a = process.env.UDIDS) === null || _a === void 0 ? void 0 : _a.split(',').map(lodash_1.default.trim);
+    /* Based on the app file extension, we will decide whether to run the
+     * test on real device or simulator.
+     *
+     * Applicaple only for ios.
+     */
+    const deviceType = platform == Platform_1.default.IOS
+        ? (0, exports.getDeviceTypeFromApp)(capability['appium:app'])
+        : undefined;
+    if ((deviceType === null || deviceType === void 0 ? void 0 : deviceType.startsWith('sim')) && pluginArgs.iosDeviceType === 'real') {
+        throw new Error('iosDeviceType value is set to "real" but app provided is not suitable for real device.');
+    }
+    if ((deviceType === null || deviceType === void 0 ? void 0 : deviceType.startsWith('real')) && pluginArgs.iosDeviceType == 'simulated') {
+        throw new Error('iosDeviceType value is set to "simulated" but app provided is not suitable for simulator device.');
+    }
+    let name = undefined;
+    if (capability[customCapability.ipadOnly]) {
+        name = 'iPad';
+    }
+    else if (capability[customCapability.iphoneOnly]) {
+        name = 'iPhone';
+    }
+    // Ensure udid is always an array of strings for the filter
+    let udidFilter = [];
+    if (udids === null || udids === void 0 ? void 0 : udids.length) {
+        udidFilter = udids;
+    }
+    else if (capability['appium:udid']) {
+        udidFilter = [capability['appium:udid']];
+    }
+    else if (capability['udid']) {
+        udidFilter = [capability['udid']];
+    }
+    let caps = {
+        platform,
+        platformVersion: capability['appium:platformVersion']
+            ? capability['appium:platformVersion']
+            : undefined,
+        name,
+        deviceType,
+        udid: udidFilter,
+        busy: false,
+        userBlocked: false,
+        filterByHost: capability[customCapability.filterByHost],
+        minSDK: capability[customCapability.minSDK] ? capability[customCapability.minSDK] : undefined,
+        maxSDK: capability[customCapability.maxSDK] ? capability[customCapability.maxSDK] : undefined,
+        tags: capability[customCapability.tags]
+            ? capability[customCapability.tags].split(',').map(lodash_1.default.trim)
+            : undefined,
+    };
+    if (name !== undefined) {
+        caps = Object.assign(Object.assign({}, caps), { name });
+    }
+    return caps;
+}
+/**
+ * Helper methods to manage devices
+ */
+function getDeviceManager() {
+    return typedi_1.Container.get(device_managers_1.XenonManager);
+}
+function getBusyDevicesCount() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const allDevices = yield (0, device_service_1.getAllDevices)();
+        return allDevices.filter((device) => {
+            return device.busy;
+        }).length;
+    });
+}
+function updateDeviceList(host, hubArgument, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const allExistingDevices = yield (0, device_service_1.getAllDevices)();
+        const devices = yield getDeviceManager().getDevices(allExistingDevices);
+        if (devices.length === 0) {
+            logger_1.default.warn('No devices found');
+            return [];
+        }
+        // log.debug(`Updating device list with ${JSON.stringify(devices)} devices`);
+        // first thing first. Update device list in local list
+        yield (0, device_service_1.addNewDevice)(devices, host);
+        // Prune any devices that are in our local DB for this host but NO LONGER discovered.
+        // This automatically cleans up disconnected Android devices safely, or filtered
+        // iOS simulators (e.g. when booted-simulators is turned on and a simulator shuts down)
+        const discoveredUdids = new Set(devices.map((d) => d.udid));
+        const staleLocalDevices = allExistingDevices.filter((d) => d.host === host && !discoveredUdids.has(d.udid));
+        if (staleLocalDevices.length > 0) {
+            logger_1.default.info(`Removing ${staleLocalDevices.length} stale devices/simulators no longer discovered on this host.`);
+            yield (0, device_service_1.removeDevice)(staleLocalDevices.map((d) => ({ udid: d.udid, host: d.host })));
+        }
+        if (hubArgument) {
+            if (yield (0, helpers_1.isXenonRunning)(hubArgument, tlsRejectUnauthorized)) {
+                const nodeDevices = new NodeDevices_1.default(hubArgument, tlsRejectUnauthorized);
+                try {
+                    yield nodeDevices.postDevicesToHub(devices, 'add');
+                    if (staleLocalDevices.length > 0) {
+                        yield nodeDevices.postDevicesToHub(staleLocalDevices, 'remove');
+                    }
+                }
+                catch (error) {
+                    logger_1.default.error(`Cannot send device list update. Reason: ${error}`);
+                }
+            }
+            else {
+                logger_1.default.warn(`Not sending device update since hub ${hubArgument} is not running`);
+            }
+        }
+        return devices;
+    });
+}
+function refreshSimulatorState(pluginArgs, hostPort) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (timer) {
+            clearInterval(timer);
+        }
+        timer = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            const iosDiscoveryService = typedi_1.Container.get(IOSDiscoveryService_1.IOSDiscoveryService);
+            const simulators = yield iosDiscoveryService.getSimulators();
+            yield (0, device_service_1.setSimulatorState)(simulators);
+        }), 10000);
+    });
+}
+function setupCronCheckStaleDevices(intervalMs, currentHost, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            yield removeStaleDevices(currentHost, tlsRejectUnauthorized);
+        }), intervalMs);
+    });
+}
+/**
+ * Remove devices where the host is not alive nor defined.
+ * @param currentHost current host ip address
+ */
+function removeStaleDevices(currentHost, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const allDevices = yield (0, device_service_1.getAllDevices)();
+        const nodeDevices = allDevices.filter((device) => {
+            // devices that's not from this node ip address
+            return device.host !== undefined && !device.host.includes(currentHost);
+        });
+        const devicesWithNoHost = nodeDevices.filter((device) => {
+            return device.host === undefined;
+        });
+        const nodeHosts = nodeDevices.filter((device) => !device.cloud).map((device) => device.host);
+        const cloudHosts = nodeDevices.filter((device) => !!device.cloud).map((device) => device.host);
+        const aliveHosts = (yield Promise.allSettled(nodeHosts.map((host) => __awaiter(this, void 0, void 0, function* () {
+            return {
+                host: host,
+                alive: yield (0, helpers_1.isXenonRunning)(host, tlsRejectUnauthorized),
+            };
+        }))));
+        const aliveCloudHosts = (yield Promise.allSettled(cloudHosts.map((host) => __awaiter(this, void 0, void 0, function* () {
+            return {
+                host: host,
+                alive: yield (0, helpers_1.isAppiumRunningAt)(host, tlsRejectUnauthorized),
+            };
+        }))));
+        // summarize alive hosts
+        const allAliveHosts = [...aliveHosts, ...aliveCloudHosts]
+            .filter((item) => item.status === 'fulfilled' && item.value.alive)
+            .map((item) => item.value.host);
+        // stale devices are devices that's not alive
+        const staleDevices = nodeDevices.filter((device) => !allAliveHosts.includes(device.host));
+        yield (0, device_service_1.removeDevice)(staleDevices.map((device) => ({ udid: device.udid, host: device.host })));
+        if (staleDevices.length > 0) {
+            logger_1.default.debug(`Removing device with udid(s): ${staleDevices
+                .map((device) => device.udid)
+                .join(', ')} because the node is not alive`);
+        }
+        // remove devices with no host
+        yield (0, device_service_1.removeDevice)(devicesWithNoHost.map((device) => ({ udid: device.udid, host: device.host })));
+        if (devicesWithNoHost.length > 0) {
+            logger_1.default.debug(`Removing device with udid(s): ${devicesWithNoHost
+                .map((device) => device.udid)
+                .join(', ')} because the device has no host`);
+        }
+    });
+}
+function unblockCandidateDevices() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const allDevices = yield (0, device_service_1.getAllDevices)();
+        return allDevices.filter((device) => {
+            // log.debug(`Checking if device ${device.udid} from ${device.host} is a candidate to be released: ${isCandidate}`);
+            return device.busy && !device.userBlocked && device.lastCmdExecutedAt != undefined;
+        });
+    });
+}
+function releaseBlockedDevices(newCommandTimeout) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const busyDevices = yield unblockCandidateDevices();
+        logger_1.default.debug(`Found ${busyDevices.length} device candidates to be released`);
+        busyDevices.forEach(function (device) {
+            // need to keep this to make typescript happy. good thing tho.
+            if (device.lastCmdExecutedAt == undefined) {
+                return;
+            }
+            const currentEpoch = new Date().getTime();
+            const timeoutSeconds = device.newCommandTimeout != undefined ? device.newCommandTimeout : newCommandTimeout;
+            const timeSinceLastCmdExecuted = (currentEpoch - device.lastCmdExecutedAt) / 1000;
+            if (timeSinceLastCmdExecuted > timeoutSeconds) {
+                // unblock regardless of whether the device has session or not
+                logger_1.default.info(`Unblocking device ${device.udid} at host ${device.host} because it has been idle for ${timeSinceLastCmdExecuted} seconds`);
+                // Principal Protection: If this device has an active dashboard session, stop it properly
+                if (device.session_id) {
+                    const sessionId = device.session_id;
+                    // Mark as stopped/failed in dashboard
+                    Promise.resolve().then(() => __importStar(require('./dashboard/event-manager'))).then((m) => {
+                        m.DASHBORD_EVENT_MANAGER.onSessionStopped(sessionId, 'failed', 'Session timed out due to inactivity');
+                    });
+                    // Important: Remove from in-memory SessionManager so it doesn't leak
+                    Promise.resolve().then(() => __importStar(require('./sessions/SessionManager'))).then((m) => {
+                        m.SESSION_MANAGER.removeSession(sessionId);
+                    });
+                    logger_1.default.warn(`🕒 Session ${sessionId} timed out on device ${device.udid}`);
+                }
+                (0, device_service_1.unblockDevice)(device.udid, device.host);
+            }
+        });
+    });
+}
+function setupCronReleaseBlockedDevices(intervalMs, newCommandTimeoutSec) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (cronTimerToReleaseBlockedDevices) {
+            clearInterval(cronTimerToReleaseBlockedDevices);
+        }
+        yield releaseBlockedDevices(newCommandTimeoutSec);
+        cronTimerToReleaseBlockedDevices = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            yield releaseBlockedDevices(newCommandTimeoutSec);
+        }), intervalMs);
+    });
+}
+function setupCronUpdateDeviceList(host, hubArgument, intervalMs, tlsRejectUnauthorized) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (cronTimerToUpdateDevices) {
+            clearInterval(cronTimerToUpdateDevices);
+        }
+        logger_1.default.info(`This node will send device list update to the hub (${hubArgument}) every ${intervalMs} ms`);
+        cronTimerToUpdateDevices = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            yield updateDeviceList(host, hubArgument, tlsRejectUnauthorized);
+        }), intervalMs);
+    });
+}
+function cleanPendingSessions(timeoutMs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const pendingSessions = yield pendingStore.getAllPendingSessions();
+        const currentEpoch = new Date().getTime();
+        const timedOutSessions = pendingSessions.filter((session) => {
+            const timeSinceSessionCreated = currentEpoch - session.createdAt;
+            logger_1.default.debug(`Session queue ID:${session.capability_id} has been pending for ${timeSinceSessionCreated} ms`);
+            return timeSinceSessionCreated > timeoutMs;
+        });
+        if (timedOutSessions.length === 0) {
+            logger_1.default.debug('No pending sessions to clean');
+        }
+        else {
+            logger_1.default.debug(`Found ${timedOutSessions.length} pending sessions to clean`);
+        }
+        for (const session of timedOutSessions) {
+            logger_1.default.debug(`Removing pending session ${session.capability_id} because it has timed out`);
+            yield pendingStore.remove(session);
+        }
+    });
+}
+function setupCronCleanPendingSessions(intervalMs, timeoutMs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        logger_1.default.info(`Hub will clean pending sessions every ${intervalMs} ms with pending session timeout: ${timeoutMs} ms`);
+        if (cronTimerToCleanPendingSessions) {
+            clearInterval(cronTimerToCleanPendingSessions);
+        }
+        cronTimerToCleanPendingSessions = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            logger_1.default.debug('Cleaning pending sessions...');
+            yield cleanPendingSessions(timeoutMs);
+        }), intervalMs);
+    });
+}
+let cronTimerToCleanExpiredReservations;
+function setupCronCleanExpiredReservations(intervalMs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        logger_1.default.info(`Hub will clean expired reservations every ${intervalMs} ms`);
+        if (cronTimerToCleanExpiredReservations) {
+            clearInterval(cronTimerToCleanExpiredReservations);
+        }
+        cronTimerToCleanExpiredReservations = setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            logger_1.default.debug('Cleaning expired reservations...');
+            yield (0, device_service_1.cleanExpiredReservations)();
+        }), intervalMs);
+    });
+}
+/**
+ * Sets up a cron job to purge older builds and sessions based on configuration
+ */
+function setupCronCleanupBuilds(pluginArgs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { buildCleanupSchedule = '0 0 * * *' } = pluginArgs;
+        const { CleanupService } = yield Promise.resolve().then(() => __importStar(require('./services/CleanupService')));
+        const schedule = yield Promise.resolve().then(() => __importStar(require('node-schedule')));
+        const cleanupService = typedi_1.Container.get(CleanupService);
+        if (cronTimerToCleanupBuilds) {
+            cronTimerToCleanupBuilds.cancel();
+        }
+        logger_1.default.info(`Build cleanup scheduled with expression: ${buildCleanupSchedule}`);
+        cronTimerToCleanupBuilds = schedule.scheduleJob(buildCleanupSchedule, () => __awaiter(this, void 0, void 0, function* () {
+            logger_1.default.info('Running scheduled build cleanup...');
+            yield cleanupService.runCleanup(pluginArgs);
+        }));
+    });
+}
+/**
+ * Principal Shutdown: Clears all background intervals and scheduled jobs
+ * to prevent process hangs and handle leaks.
+ */
+function stopAllTimers() {
+    if (timer)
+        clearInterval(timer);
+    if (cronTimerToReleaseBlockedDevices)
+        clearInterval(cronTimerToReleaseBlockedDevices);
+    if (cronTimerToUpdateDevices)
+        clearInterval(cronTimerToUpdateDevices);
+    if (cronTimerToCleanPendingSessions)
+        clearInterval(cronTimerToCleanPendingSessions);
+    if (cronTimerToCleanExpiredReservations)
+        clearInterval(cronTimerToCleanExpiredReservations);
+    if (cronTimerToCleanupBuilds)
+        cronTimerToCleanupBuilds.cancel();
+}

package/lib/src/enums/Capabilities.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var Capabilities;
+(function (Capabilities) {
+    Capabilities["DEVICE_NAME"] = "appium:deviceName";
+    Capabilities["PLATFORM_VERSION"] = "platformVersion";
+})(Capabilities || (Capabilities = {}));
+exports.default = Capabilities;

package/lib/src/enums/Cloud.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var Cloud;
+(function (Cloud) {
+    Cloud["BROWSERSTACK"] = "browserstack";
+    Cloud["PCLOUDY"] = "pcloudy";
+    Cloud["SAUCELABS"] = "sauce";
+    Cloud["LAMBDATEST"] = "lambdatest";
+    Cloud["HEADSPIN"] = "headspin";
+})(Cloud || (Cloud = {}));
+exports.default = Cloud;