@xenon-device-management/xenon 1.1.0

package/lib/src/device-managers/ios/IOSStreamService.js

@@ -0,0 +1,893 @@
+"use strict";
+/**
+ * iOS Stream Service
+ *
+ * This service manages independent MJPEG streaming for iOS devices without requiring
+ * an active Appium session. It uses go-ios to start WDA and forwards the MJPEG stream.
+ *
+ * Based on GADS implementation approach.
+ */
+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 __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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 __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+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 });
+const typedi_1 = require("typedi");
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const http_1 = __importDefault(require("http"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const tcp_port_used_1 = __importDefault(require("tcp-port-used"));
+const InternalHttpClient_1 = require("../../InternalHttpClient");
+const logger_1 = __importDefault(require("../../logger"));
+const helpers_1 = require("../../helpers");
+const device_store_1 = require("../../data-service/device-store");
+const device_service_1 = require("../../data-service/device-service");
+const execPromise = (0, util_1.promisify)(child_process_1.exec);
+const typedi_2 = require("typedi");
+const ResourceIsolationService_1 = require("../../services/ResourceIsolationService");
+let IOSStreamService = class IOSStreamService {
+    constructor() {
+        this.sessions = new Map();
+        this.startPromises = new Map();
+        this.recoveryCooldowns = new Map(); // Track last recovery attempt time
+        this.RECOVERY_COOLDOWN_MS = 30000; // 30s cooldown between recovery attempts
+        this.goIOSPath = this.getGoIOSPath();
+        this.startWatchdog();
+    }
+    /**
+     * Watchdog: Periodically monitors running streams and cleans up idle ones
+     */
+    startWatchdog() {
+        setInterval(() => __awaiter(this, void 0, void 0, function* () {
+            for (const [udid, session] of this.sessions.entries()) {
+                const now = Date.now();
+                if (session.status === 'running') {
+                    // Check for inactivity
+                    if (now - session.lastViewerAt > 600000 && session.viewerCount === 0) {
+                        // Principal Protection: Never stop a stream if the device is busy with an active session.
+                        // This prevents the watchdog from killing WDA while a test is running.
+                        const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                        if (device && device.busy) {
+                            logger_1.default.debug(`🛡️ [${udid}] [Watchdog] Stream is idle but device is BUSY. Keeping alive.`);
+                            session.lastViewerAt = Date.now(); // Refresh timer to avoid constant DB checks
+                            continue;
+                        }
+                        logger_1.default.info(`[${udid}] [Watchdog] Stopping idle iOS stream (No viewers for 30s)`);
+                        this.stopStream(udid);
+                        continue;
+                    }
+                    // 2. Health check & Self-Healing
+                    // We use elased autonomous methodology to ensure devices are always warm
+                    const isAlive = yield this.isStreamResponsive(udid);
+                    if (!isAlive) {
+                        // Check cooldown before attempting recovery
+                        if (!this.canAttemptRecovery(udid)) {
+                            const lastAttempt = this.recoveryCooldowns.get(udid);
+                            const waitMs = this.RECOVERY_COOLDOWN_MS - (Date.now() - (lastAttempt || 0));
+                            logger_1.default.debug(`[Watchdog] ${udid} stream unhealthy but recovery cooldown active (${Math.ceil(waitMs / 1000)}s remaining). Skipping recovery attempt.`);
+                            continue;
+                        }
+                        logger_1.default.warn(`Stream watchdog detected failure for ${udid}. Attempting autonomous healing...`);
+                        try {
+                            // Get device state to check for Session Shield
+                            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                            if (device && device.busy) {
+                                logger_1.default.info(`🛡️ [Watchdog] Skipping heal for ${udid} as it has an active session.`);
+                                continue;
+                            }
+                            this.markRecoveryAttempt(udid);
+                            yield this.startStream(udid);
+                            // Increment healed count for visual feedback
+                            if (device) {
+                                yield device_store_1.DeviceStoreFactory.getStore().updateDevice(udid, device.host, {
+                                    totalHealedCount: (device.totalHealedCount || 0) + 1,
+                                });
+                            }
+                        }
+                        catch (e) {
+                            logger_1.default.error(`Watchdog healing failed for ${udid}: ${e}`);
+                        }
+                    }
+                }
+            }
+        }), 3600000); // 1hr interval for background stability
+    }
+    getGoIOSPath() {
+        const goIOSDir = (0, helpers_1.cachePath)('goIOS');
+        return path_1.default.join(goIOSDir, 'ios');
+    }
+    /**
+     * Check if go-ios binary exists
+     */
+    isGoIOSAvailable() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (!fs_extra_1.default.existsSync(this.goIOSPath)) {
+                    logger_1.default.warn(`go-ios binary not found at ${this.goIOSPath}`);
+                    return false;
+                }
+                return true;
+            }
+            catch (error) {
+                return false;
+            }
+        });
+    }
+    /**
+     * Detect the WDA bundle ID installed on the device
+     */
+    detectWDABundleId(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const { stdout } = yield execPromise(`"${this.goIOSPath}" apps --udid ${udid}`, {
+                    env: Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }),
+                });
+                const apps = JSON.parse(stdout);
+                const wda = apps.find((a) => (a.CFBundleIdentifier && a.CFBundleIdentifier.includes('WebDriverAgentRunner')) ||
+                    (a.CFBundleName && a.CFBundleName.includes('WebDriverAgentRunner')));
+                return wda ? wda.CFBundleIdentifier : null;
+            }
+            catch (error) {
+                logger_1.default.warn(`Failed to detect WDA bundle ID for ${udid}: ${error}`);
+                return null;
+            }
+        });
+    }
+    /**
+     * Check if tunnel is needed (iOS 17+) and ensure it's running
+     */
+    ensureTunnel(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            try {
+                const { stdout } = yield execPromise(`"${this.goIOSPath}" info --udid ${udid}`, {
+                    env: Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }),
+                });
+                const info = JSON.parse(stdout);
+                const versionStr = String(info.ProductVersion || info.HumanReadableProductVersionString || '0');
+                // Extract the first numeric sequence (e.g., "15.8.6" or "iOS 17.2")
+                const versionMatch = versionStr.match(/(\d+\.?\d*)/);
+                const version = versionMatch ? parseFloat(versionMatch[0]) : 0;
+                if (version >= 17) {
+                    logger_1.default.info(`iOS ${version} detected for ${udid} (Raw: "${versionStr}"). Starting tunnel...`);
+                    // Check if already running in our session tracker
+                    const existing = [...this.sessions.values()].find((s) => s.udid === udid && s.tunnelProcess && s.tunnelProcess.exitCode === null);
+                    if (existing && existing.tunnelProcess)
+                        return existing.tunnelProcess;
+                    // CRITICAL: Kill any orphan tunnel processes before starting new one
+                    // This prevents 'address already in use' errors from stale processes
+                    yield this.cleanupOrphanTunnels(udid);
+                    const isolationService = typedi_2.Container.get(ResourceIsolationService_1.ResourceIsolationService);
+                    const { command, args } = isolationService.wrapSpawn(this.goIOSPath, ['tunnel', 'start', '--udid', udid, '--userspace'], 'Performance');
+                    const tunnelProcess = (0, child_process_1.spawn)(command, args, {
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                        env: Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }),
+                    });
+                    (_a = tunnelProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (data) => logger_1.default.debug(`Tunnel [${udid}]: ${data}`));
+                    (_b = tunnelProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (data) => logger_1.default.debug(`Tunnel Err [${udid}]: ${data}`));
+                    // Wait for tunnel to establish by checking the go-ios agent port
+                    logger_1.default.info('Waiting for tunnel agent on port 60105 to be ready...');
+                    let tunnelReady = false;
+                    const tunnelTimeout = 15000;
+                    const subStartTime = Date.now();
+                    while (Date.now() - subStartTime < tunnelTimeout) {
+                        try {
+                            tunnelReady = yield tcp_port_used_1.default.check(60105, '127.0.0.1');
+                            if (tunnelReady)
+                                break;
+                        }
+                        catch (e) {
+                            /* ignore */
+                        }
+                        yield new Promise((resolve) => setTimeout(resolve, 1000));
+                    }
+                    if (!tunnelReady) {
+                        logger_1.default.warn(`Tunnel agent port 60105 not ready after ${tunnelTimeout / 1000}s, proceeding anyway...`);
+                    }
+                    else {
+                        logger_1.default.info('Tunnel agent is ready. Settling for 2s...');
+                        yield new Promise((resolve) => setTimeout(resolve, 2000));
+                        logger_1.default.info('Tunnel agent settled.');
+                    }
+                    return tunnelProcess;
+                }
+            }
+            catch (error) {
+                logger_1.default.warn(`Failed to check version or start tunnel for ${udid}: ${error}`);
+            }
+            return null;
+        });
+    }
+    /**
+     * Kill any orphan tunnel processes that might be left from previous runs
+     * This is critical for preventing 'address already in use' errors
+     */
+    cleanupOrphanTunnels(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            logger_1.default.debug(`Cleaning up orphan tunnels for ${udid}...`);
+            const pkillCmds = [
+                // Kill any existing tunnel for this specific device
+                `pkill -9 -f "ios tunnel.*${udid}"`,
+                `pkill -9 -f "go-ios.*tunnel.*${udid}"`,
+            ];
+            for (const cmd of pkillCmds) {
+                try {
+                    yield execPromise(cmd);
+                }
+                catch (err) {
+                    /* ignore - process might not exist */
+                }
+            }
+            // Check common go-ios agent ports (60105, 60106) and kill if bound
+            const agentPorts = [60105, 60106];
+            for (const port of agentPorts) {
+                try {
+                    const { stdout } = yield execPromise(`lsof -ti :${port}`);
+                    const pids = stdout.trim().split('\n');
+                    for (const pid of pids) {
+                        if (pid) {
+                            logger_1.default.debug(`Killing orphan process ${pid} on go-ios agent port ${port}`);
+                            yield execPromise(`kill -9 ${pid}`);
+                        }
+                    }
+                }
+                catch (err) {
+                    /* ignore - lsof returns 1 if no port found */
+                }
+            }
+            // Small delay to ensure OS releases sockets
+            yield new Promise((resolve) => setTimeout(resolve, 500));
+        });
+    }
+    /**
+     * Check if WDA is already running and responding
+     * Principal Resilience: Retries transient connection errors (ECONNRESET) up to 2 times
+     * with exponential backoff, as these often indicate WDA is restarting or tunnel is reconnecting.
+     */
+    isWDARunning(wdaPort_1) {
+        return __awaiter(this, arguments, void 0, function* (wdaPort, retries = 2) {
+            var _a, _b, _c, _d;
+            const axios = (yield Promise.resolve().then(() => __importStar(require('axios')))).default;
+            const host = '127.0.0.1'; // Force IPv4 for local tunnels
+            const maxRetries = retries;
+            let lastError;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    const response = yield axios.get(`http://${host}:${wdaPort}/status`, {
+                        timeout: 2500, // 2.5s for consistency
+                        httpAgent: new http_1.default.Agent({ keepAlive: false }),
+                        validateStatus: (status) => status === 200,
+                    });
+                    const isReady = ((_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.ready) === true;
+                    if (!isReady) {
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} active but not ready. Status: ${JSON.stringify((_c = response.data) === null || _c === void 0 ? void 0 : _c.value)}`);
+                    }
+                    return isReady;
+                }
+                catch (error) {
+                    lastError = error;
+                    const isTransientError = error.code === 'ECONNRESET' ||
+                        error.code === 'ETIMEDOUT' ||
+                        error.code === 'ECONNABORTED' ||
+                        (error.response && error.response.status >= 500);
+                    if (isTransientError && attempt < maxRetries) {
+                        const backoffMs = Math.min(500 * Math.pow(2, attempt), 2000); // 500ms, 1000ms, 2000ms max
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} transient error (${error.code || ((_d = error.response) === null || _d === void 0 ? void 0 : _d.status)}), retrying in ${backoffMs}ms (attempt ${attempt + 1}/${maxRetries + 1})`);
+                        yield new Promise((resolve) => setTimeout(resolve, backoffMs));
+                        continue;
+                    }
+                    // Permanent error or max retries reached
+                    if (error.code === 'ECONNREFUSED') {
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} connection refused (Tunnel likely down)`);
+                    }
+                    else if (error.code === 'ECONNABORTED') {
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} health check timed out (WDA hanging)`);
+                    }
+                    else if (error.code === 'ECONNRESET') {
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} connection reset after ${attempt + 1} attempts (WDA may be restarting or tunnel unstable)`);
+                    }
+                    else {
+                        logger_1.default.debug(`[WDA] Port ${wdaPort} health check failed: ${error.message}`);
+                    }
+                    return false;
+                }
+            }
+            return false;
+        });
+    }
+    /**
+     * Comprehensive process-level and endpoint-level health check.
+     * Principal Intelligence: Differentiates between 'Process dead' and 'Network unreachable'.
+     * If only the tunnel is dead but WDA is alive via IP, it will trigger a tunnel restart.
+     */
+    isStreamResponsive(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = this.sessions.get(udid);
+            if (!session || session.status !== 'running')
+                return false;
+            // 1. Process Check: verify child processes haven't exited
+            const isWdaAlive = session.wdaProcess && session.wdaProcess.exitCode === null;
+            const isWdaIproxyAlive = session.forwardWDAProcess && session.forwardWDAProcess.exitCode === null;
+            const isMjpegIproxyAlive = session.forwardMJPEGProcess && session.forwardMJPEGProcess.exitCode === null;
+            if (!isWdaAlive) {
+                logger_1.default.warn(`🛡️ [${udid}] [Watchdog] WDA process is dead. Full restart required.`);
+                return false;
+            }
+            if (!isWdaIproxyAlive || !isMjpegIproxyAlive) {
+                logger_1.default.warn(`🛡️ [${udid}] [Watchdog] Tunnel processes are dead. Attempting tunnel-only recovery...`);
+                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                if (device && device.ip) {
+                    // Double check if WDA is alive via network IP
+                    const isWdaAccessibleViaNetwork = yield this.isWDARunningOnHost(device.ip, 8100);
+                    if (isWdaAccessibleViaNetwork) {
+                        logger_1.default.info(`🛡️ [${udid}] [Watchdog] WDA is alive on network ${device.ip}. Restarting tunnels...`);
+                        yield this.restartTunnelsOnly(session);
+                        return true; // We healed it!
+                    }
+                }
+                return false; // Cannot heal without network access or if WDA is also dead
+            }
+            // 2. Network Check: verify endpoint is responding via tunnel
+            const isRespondingViaTunnel = yield this.isWDARunning(session.wdaPort);
+            if (!isRespondingViaTunnel) {
+                logger_1.default.warn(`🛡️ [${udid}] [Watchdog] WDA tunnel on port ${session.wdaPort} is unresponsive. checking network...`);
+                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                if (device && device.ip) {
+                    const isWdaAccessibleViaNetwork = yield this.isWDARunningOnHost(device.ip, 8100);
+                    if (isWdaAccessibleViaNetwork) {
+                        logger_1.default.info(`🛡️ [${udid}] [Watchdog] WDA is alive on network but tunnel is hung. Restarting tunnels...`);
+                        yield this.restartTunnelsOnly(session);
+                        return true;
+                    }
+                }
+                return false;
+            }
+            return true;
+        });
+    }
+    /**
+     * Check if WDA is running on a specific host/port
+     */
+    isWDARunningOnHost(host, port) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const axios = (yield Promise.resolve().then(() => __importStar(require('axios')))).default;
+            try {
+                const response = yield axios.get(`http://${host}:${port}/status`, {
+                    timeout: 3000,
+                    validateStatus: (status) => status === 200,
+                });
+                return ((_b = (_a = response.data) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.ready) === true;
+            }
+            catch (e) {
+                return false;
+            }
+        });
+    }
+    /**
+     * Restarts only the iproxy tunnels without stopping WDA
+     */
+    restartTunnelsOnly(session) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const udid = session.udid;
+            const isolationService = typedi_2.Container.get(ResourceIsolationService_1.ResourceIsolationService);
+            // 1. Kill old tunnels
+            if (session.forwardWDAProcess)
+                session.forwardWDAProcess.kill('SIGKILL');
+            if (session.forwardMJPEGProcess)
+                session.forwardMJPEGProcess.kill('SIGKILL');
+            // 2. Start new tunnels
+            const wdaIproxy = isolationService.wrapSpawn('iproxy', ['-u', udid, `${session.wdaPort}:8100`], 'Performance');
+            const mjpegIproxy = isolationService.wrapSpawn('iproxy', ['-u', udid, `${session.mjpegPort}:9100`], 'Performance');
+            session.forwardWDAProcess = (0, child_process_1.spawn)(wdaIproxy.command, wdaIproxy.args);
+            session.forwardMJPEGProcess = (0, child_process_1.spawn)(mjpegIproxy.command, mjpegIproxy.args);
+            logger_1.default.info(`🛡️ [${udid}] [Watchdog] Tunnels restarted successfully.`);
+        });
+    }
+    /**
+     * Start streaming for a device
+     */
+    /**
+     * Check if recovery is allowed (cooldown period has passed)
+     */
+    canAttemptRecovery(udid) {
+        const lastAttempt = this.recoveryCooldowns.get(udid);
+        if (!lastAttempt)
+            return true;
+        const elapsed = Date.now() - lastAttempt;
+        return elapsed >= this.RECOVERY_COOLDOWN_MS;
+    }
+    /**
+     * Mark recovery attempt timestamp
+     */
+    markRecoveryAttempt(udid) {
+        this.recoveryCooldowns.set(udid, Date.now());
+    }
+    startStream(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Return existing promise if already starting
+            if (this.startPromises.has(udid)) {
+                const existingPromise = this.startPromises.get(udid);
+                if (existingPromise)
+                    return existingPromise;
+            }
+            // Check if stream is already running - avoid unnecessary restarts
+            const existingSession = this.sessions.get(udid);
+            if (existingSession && existingSession.status === 'running') {
+                const isHealthy = yield this.isWDARunning(existingSession.wdaPort);
+                if (isHealthy) {
+                    logger_1.default.debug(`[${udid}] Stream already running and healthy, reusing existing session`);
+                    return { wdaPort: existingSession.wdaPort, mjpegPort: existingSession.mjpegPort };
+                }
+                // Stream exists but unhealthy - check cooldown before recovery
+                if (!this.canAttemptRecovery(udid)) {
+                    const lastAttempt = this.recoveryCooldowns.get(udid);
+                    const waitMs = this.RECOVERY_COOLDOWN_MS - (Date.now() - (lastAttempt || 0));
+                    logger_1.default.debug(`[${udid}] Recovery cooldown active (${Math.ceil(waitMs / 1000)}s remaining). Skipping recovery attempt.`);
+                    throw new Error(`Stream recovery is in cooldown. Last attempt was ${Math.ceil(waitMs / 1000)}s ago.`);
+                }
+                // Stop unhealthy stream before restarting
+                logger_1.default.info(`[${udid}] Stream exists but unhealthy, stopping before restart...`);
+                yield this.stopStream(udid);
+            }
+            // Define the core logic as an internal async function
+            const performStartup = () => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c, _d;
+                try {
+                    const existingSession = this.sessions.get(udid);
+                    if (existingSession && existingSession.status === 'running') {
+                        const isHealthy = yield this.isWDARunning(existingSession.wdaPort);
+                        if (isHealthy) {
+                            logger_1.default.debug(`[${udid}] Stream already running and healthy, reusing existing session`);
+                            return { wdaPort: existingSession.wdaPort, mjpegPort: existingSession.mjpegPort };
+                        }
+                        // Stream exists but unhealthy - check cooldown before recovery
+                        if (!this.canAttemptRecovery(udid)) {
+                            const lastAttempt = this.recoveryCooldowns.get(udid);
+                            const waitMs = this.RECOVERY_COOLDOWN_MS - (Date.now() - (lastAttempt || 0));
+                            logger_1.default.debug(`[${udid}] Recovery cooldown active (${Math.ceil(waitMs / 1000)}s remaining). Skipping recovery attempt.`);
+                            throw new Error(`Stream recovery is in cooldown. Last attempt was ${Math.ceil(waitMs / 1000)}s ago.`);
+                        }
+                        logger_1.default.info(`Existing session for ${udid} not responding, restarting...`);
+                        this.markRecoveryAttempt(udid);
+                    }
+                    const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                    if (!device)
+                        throw new Error(`Device ${udid} not found`);
+                    const wdaPort = device.wdaLocalPort || (yield (0, helpers_1.getFreePort)());
+                    const mjpegPort = device.mjpegServerPort || (yield (0, helpers_1.getFreePort)());
+                    // Perform aggressive cleanup of any existing processes for THIS device/ports
+                    yield this.stopStream(udid);
+                    yield this.killStaleProcesses(udid, wdaPort, mjpegPort);
+                    const session = {
+                        udid,
+                        wdaProcess: null,
+                        forwardWDAProcess: null,
+                        forwardMJPEGProcess: null,
+                        tunnelProcess: null,
+                        wdaPort,
+                        mjpegPort,
+                        status: 'starting',
+                        startedAt: new Date(),
+                        lastViewerAt: Date.now(),
+                        viewerCount: 0,
+                    };
+                    this.sessions.set(udid, session);
+                    const goIOSAvailable = yield this.isGoIOSAvailable();
+                    if (!goIOSAvailable)
+                        throw new Error('go-ios not available');
+                    // 1. Technical Optimization: If real iOS device and WDA IPA exists in repository, use it as priority
+                    const { APP_SERVICE } = yield Promise.resolve().then(() => __importStar(require('../../dashboard/services/app-service')));
+                    const wdaApp = yield APP_SERVICE.getWDAApp();
+                    if (wdaApp && fs_extra_1.default.existsSync(wdaApp.filepath)) {
+                        logger_1.default.info(`📱 Artisan WDA: Found pre-signed artifact "${wdaApp.name}". Provisioning ${udid} for stream...`);
+                        try {
+                            const { Container } = yield Promise.resolve().then(() => __importStar(require('typedi')));
+                            const { XenonManager } = yield Promise.resolve().then(() => __importStar(require('../index')));
+                            const IOSDeviceManager = (yield Promise.resolve().then(() => __importStar(require('../IOSDeviceManager')))).default;
+                            const deviceManager = Container.get(XenonManager);
+                            const manager = (yield deviceManager.deviceInstances()).find((m) => m instanceof IOSDeviceManager);
+                            if (manager) {
+                                yield manager.installApp(udid, wdaApp.filepath);
+                                logger_1.default.info(`📱 Artisan WDA: Artifact provisioned successfully to ${udid}`);
+                            }
+                        }
+                        catch (e) {
+                            logger_1.default.warn(`📱 Artisan WDA: Failed to provision WDA to ${udid}: ${e}`);
+                        }
+                    }
+                    // 2. Ensure tunnel for iOS 17+
+                    session.tunnelProcess = yield this.ensureTunnel(udid);
+                    // 2. Start Port Forwarding using iproxy (more reliable on Mac)
+                    logger_1.default.info(`Forwarding ${udid}: ${wdaPort}->8100, ${mjpegPort}->9100 using iproxy`);
+                    const isolationService = typedi_2.Container.get(ResourceIsolationService_1.ResourceIsolationService);
+                    const wdaIproxy = isolationService.wrapSpawn('iproxy', ['-u', udid, `${wdaPort}:8100`], 'Performance');
+                    const mjpegIproxy = isolationService.wrapSpawn('iproxy', ['-u', udid, `${mjpegPort}:9100`], 'Performance');
+                    session.forwardWDAProcess = (0, child_process_1.spawn)(wdaIproxy.command, wdaIproxy.args);
+                    session.forwardMJPEGProcess = (0, child_process_1.spawn)(mjpegIproxy.command, mjpegIproxy.args);
+                    const handleIproxyProcess = (p, name) => {
+                        p.on('error', (err) => logger_1.default.error(`${name} [${udid}] error: ${err.message}`));
+                        p.on('exit', (code) => {
+                            if (code !== 0 && code !== null) {
+                                logger_1.default.warn(`${name} [${udid}] exited with code ${code}`);
+                            }
+                        });
+                    };
+                    handleIproxyProcess(session.forwardWDAProcess, 'iproxy-wda');
+                    handleIproxyProcess(session.forwardMJPEGProcess, 'iproxy-mjpeg');
+                    // 3. Detect and Start WDA
+                    const bundleId = (yield this.detectWDABundleId(udid)) || 'com.qasecret.WebDriverAgentRunner.xctrunner';
+                    logger_1.default.info(`Starting WDA ${bundleId} on ${udid}`);
+                    const wdaSpawn = isolationService.wrapSpawn(this.goIOSPath, [
+                        'runwda',
+                        '--bundleid',
+                        bundleId,
+                        '--testrunnerbundleid',
+                        bundleId,
+                        '--xctestconfig',
+                        'WebDriverAgentRunner.xctest',
+                        '--udid',
+                        udid,
+                    ], 'Performance'); // WDA deserves Performance mode
+                    session.wdaProcess = (0, child_process_1.spawn)(wdaSpawn.command, wdaSpawn.args, {
+                        env: Object.assign(Object.assign({}, process.env), { ENABLE_GO_IOS_AGENT: 'yes' }),
+                    });
+                    const logDir = path_1.default.join(os_1.default.tmpdir(), 'xenon-logs');
+                    if (!fs_extra_1.default.existsSync(logDir))
+                        fs_extra_1.default.mkdirSync(logDir);
+                    const wdaRunLog = path_1.default.join(logDir, `runwda-${udid}.log`);
+                    (_a = session.wdaProcess.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (d) => fs_extra_1.default.appendFileSync(wdaRunLog, d));
+                    (_b = session.wdaProcess.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (d) => fs_extra_1.default.appendFileSync(wdaRunLog, d));
+                    // 4. Wait for WDA to be ready
+                    const startTime = Date.now();
+                    const timeout = 120000; // Senior Resiliency: 120s for WDA startup consistency
+                    while (Date.now() - startTime < timeout) {
+                        if (yield this.isWDARunning(wdaPort)) {
+                            session.status = 'running';
+                            session.startedAt = new Date(); // Reset settlement timer for strict readiness phase
+                            // Ensure MJPEG server is started by updating WDA settings
+                            yield this.updateWDASettings(wdaPort);
+                            // Wait up to 5 seconds for MJPEG server to be ready on the local port
+                            logger_1.default.info(`Waiting for MJPEG server to be ready on port ${mjpegPort}...`);
+                            let mjpegReady = false;
+                            for (let i = 0; i < 5; i++) {
+                                // Try 5 times with 1-second delay = 5 seconds total
+                                // Perform a real HTTP check to see if the MJPEG server is actually serving
+                                try {
+                                    mjpegReady = yield tcp_port_used_1.default.check(mjpegPort, '127.0.0.1');
+                                    if (mjpegReady)
+                                        break;
+                                }
+                                catch (e) {
+                                    // Not ready yet
+                                }
+                                yield new Promise((resolve) => setTimeout(resolve, 1000));
+                            }
+                            if (mjpegReady) {
+                                logger_1.default.info(`MJPEG server is ready on port ${mjpegPort} for ${udid}`);
+                            }
+                            else {
+                                logger_1.default.warn(`MJPEG server not detected on port ${mjpegPort} for ${udid} after 5s timeout. It might be starting slowly or WDA might be struggling.`);
+                            }
+                            // Fetch screen size from WDA
+                            let screenWidth = 0, screenHeight = 0;
+                            try {
+                                const winSize = yield InternalHttpClient_1.InternalHttpClient.get(`http://127.0.0.1:${wdaPort}/window/size`);
+                                screenWidth = winSize.value.width;
+                                screenHeight = winSize.value.height;
+                                session.screenWidth = screenWidth;
+                                session.screenHeight = screenHeight;
+                                logger_1.default.info(`Detected screen size for ${udid}: ${screenWidth}x${screenHeight}`);
+                            }
+                            catch (e) {
+                                logger_1.default.warn(`Failed to get screen size for ${udid}: ${e}`);
+                            }
+                            // Update device info in store
+                            const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                            if (device) {
+                                const updateData = {
+                                    wdaLocalPort: wdaPort,
+                                    mjpegServerPort: mjpegPort,
+                                };
+                                if (screenWidth > 0) {
+                                    updateData.screenWidth = screenWidth.toString();
+                                    updateData.screenHeight = screenHeight.toString();
+                                }
+                                yield device_store_1.DeviceStoreFactory.getStore().updateDevice(udid, device.host, updateData);
+                            }
+                            logger_1.default.info(`WDA is ready for ${udid} at port ${wdaPort}`);
+                            // Create a WDA session for keyboard/interaction operations
+                            try {
+                                const sessionId = yield this.createWDASession(wdaPort);
+                                if (sessionId) {
+                                    session.sessionId = sessionId;
+                                    logger_1.default.info(`Created WDA session ${sessionId} for ${udid} during stream startup`);
+                                }
+                            }
+                            catch (e) {
+                                logger_1.default.warn(`Failed to create WDA session during stream startup for ${udid}: ${e.message}`);
+                            }
+                            session.lastViewerAt = Date.now(); // Initialize activity
+                            // Clear recovery cooldown on successful start
+                            this.recoveryCooldowns.delete(udid);
+                            return { wdaPort, mjpegPort };
+                        }
+                        if (((_c = session.wdaProcess) === null || _c === void 0 ? void 0 : _c.exitCode) !== null) {
+                            const logContent = fs_extra_1.default.existsSync(wdaRunLog) ? fs_extra_1.default.readFileSync(wdaRunLog, 'utf8') : '';
+                            throw new Error(`WDA process exited with code ${(_d = session.wdaProcess) === null || _d === void 0 ? void 0 : _d.exitCode}. Log: ${logContent.slice(-200)}`);
+                        }
+                        yield new Promise((resolve) => setTimeout(resolve, 1000));
+                    }
+                    throw new Error(`WDA failed to start within ${timeout / 1000}s. Check logs.`);
+                }
+                catch (error) {
+                    const session = this.sessions.get(udid);
+                    if (session) {
+                        session.status = 'error';
+                        session.lastError = error.message;
+                    }
+                    logger_1.default.error(`Stream start failed for ${udid}: ${error.message}`);
+                    throw error;
+                }
+                finally {
+                    this.startPromises.delete(udid);
+                }
+            });
+            // Set the promise in the map IMMEDIATELY before awaiting anything
+            const startPromise = performStartup();
+            this.startPromises.set(udid, startPromise);
+            return startPromise;
+        });
+    }
+    killStaleProcesses(udid, wdaPort, mjpegPort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            logger_1.default.info(`Cleaning up stale processes for ${udid} (Ports: ${wdaPort}, ${mjpegPort})`);
+            // Senior Resiliency: Use centralized tunnel cleanup
+            yield this.cleanupOrphanTunnels(udid);
+            const pkillCmds = [`pkill -9 -f "iproxy.*${udid}"`, `pkill -9 -f "ios runwda.*${udid}"`];
+            for (const cmd of pkillCmds) {
+                try {
+                    yield execPromise(cmd);
+                }
+                catch (err) {
+                    /* ignore */
+                }
+            }
+            // Port-based cleanup (more surgical)
+            const ports = [wdaPort, mjpegPort];
+            for (const port of ports) {
+                try {
+                    const { stdout } = yield execPromise(`lsof -ti :${port}`);
+                    const pids = stdout.trim().split('\n');
+                    for (const pid of pids) {
+                        if (pid) {
+                            logger_1.default.debug(`Killing stale process ${pid} on port ${port}`);
+                            yield execPromise(`kill -9 ${pid}`);
+                        }
+                    }
+                }
+                catch (err) {
+                    /* ignore - lsof returns 1 if no port found */
+                }
+            }
+            // Small delay to ensure OS releases sockets
+            yield new Promise((resolve) => setTimeout(resolve, 500));
+        });
+    }
+    stopStream(udid) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const session = this.sessions.get(udid);
+            if (!session)
+                return;
+            // Kill all processes including tunnel (CRITICAL: tunnel was missing from cleanup!)
+            [
+                session.wdaProcess,
+                session.forwardWDAProcess,
+                session.forwardMJPEGProcess,
+                session.tunnelProcess,
+            ].forEach((p) => {
+                if (p)
+                    try {
+                        p.kill('SIGKILL');
+                    }
+                    catch (e) {
+                        // ignore
+                    }
+            });
+            // Principal Fix: Only release the device lock if THIS STREAM SERVICE owns it.
+            // The lock could belong to an Appium automation session (session_id is a real UUID).
+            // We should only unblock if it's a manual control lock (session_id starts with 'manual_').
+            try {
+                const device = yield device_store_1.DeviceStoreFactory.getStore().findDevice({ udid });
+                if (device && ((_a = device.session_id) === null || _a === void 0 ? void 0 : _a.startsWith('manual_'))) {
+                    logger_1.default.info(`Stream Stop: Releasing manual control lock for ${udid}`);
+                    yield (0, device_service_1.unblockDevice)(udid, device.host);
+                }
+                else if (device && device.busy) {
+                    logger_1.default.info(`Stream Stop: Device ${udid} is busy with session ${device.session_id}. NOT releasing lock.`);
+                }
+            }
+            catch (e) {
+                logger_1.default.error(`Failed to check/release lock during stream stop for ${udid}: ${e}`);
+            }
+            // Also clean up any orphan processes (belt and suspenders)
+            yield this.cleanupOrphanTunnels(udid);
+            this.sessions.delete(udid);
+        });
+    }
+    updateWDASettings(wdaPort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const urls = [`http://127.0.0.1:${wdaPort}/appium/settings`];
+            const data = {
+                settings: {
+                    mjpegServerPort: 9100,
+                    mjpegServerFramerate: 15, // Optimal for tunnel stability
+                    mjpegServerScreenshotQuality: 50, // Reduced quality to avoid ECONNRESETS during swipes
+                    mjpegScalingFactor: 100,
+                },
+            };
+            for (const url of urls) {
+                try {
+                    logger_1.default.info(`Broadcasting WDA settings to ${url} (15fps/50%)`);
+                    yield InternalHttpClient_1.InternalHttpClient.post(url, data, { timeout: 10000 });
+                    return;
+                }
+                catch (error) {
+                    logger_1.default.warn(`Failed to broadcast WDA settings via ${url}: ${error.code || error.message}`);
+                }
+            }
+        });
+    }
+    /**
+     * Create a WDA session for keyboard/interaction operations
+     * Uses minimal capabilities to avoid disrupting the current app
+     * IMPORTANT: First checks if a session already exists (e.g., from active Appium automation)
+     * and reuses it to avoid disrupting active automation runs.
+     */
+    createWDASession(wdaPort) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            const axios = (yield Promise.resolve().then(() => __importStar(require('axios')))).default;
+            // SAFETY: First check if a session already exists (e.g., from active Appium session)
+            // If yes, reuse it instead of creating a new one that could displace the automation
+            try {
+                const existingResponse = yield axios.get(`http://127.0.0.1:${wdaPort}/sessions`, {
+                    timeout: 5000,
+                });
+                const sessions = ((_a = existingResponse.data) === null || _a === void 0 ? void 0 : _a.value) || [];
+                if (sessions.length > 0) {
+                    const existingSid = sessions[0].id || sessions[0].sessionId;
+                    if (existingSid) {
+                        logger_1.default.info(`Reusing existing WDA session ${existingSid} (likely from active automation)`);
+                        return existingSid;
+                    }
+                }
+            }
+            catch (err) {
+                logger_1.default.debug(`No existing WDA sessions found: ${err.message}`);
+            }
+            // No existing session - create a new one with minimal capabilities
+            const sessionConfigs = [
+                // Minimal session - doesn't specify bundleId, uses current app
+                { capabilities: { alwaysMatch: {} } },
+                // Springboard fallback
+                { capabilities: { alwaysMatch: { bundleId: 'com.apple.springboard' } } },
+            ];
+            for (const config of sessionConfigs) {
+                try {
+                    const response = yield axios.post(`http://127.0.0.1:${wdaPort}/session`, config, {
+                        timeout: 15000,
+                        headers: { 'Content-Type': 'application/json' },
+                    });
+                    const sid = ((_b = response.data) === null || _b === void 0 ? void 0 : _b.sessionId) || ((_d = (_c = response.data) === null || _c === void 0 ? void 0 : _c.value) === null || _d === void 0 ? void 0 : _d.sessionId);
+                    if (sid) {
+                        return sid;
+                    }
+                }
+                catch (err) {
+                    logger_1.default.debug(`WDA session creation attempt failed: ${err.message}`);
+                }
+            }
+            return null;
+        });
+    }
+    getStreamStatus(udid) {
+        return this.sessions.get(udid);
+    }
+    updateViewerCount(udid, delta) {
+        const session = this.sessions.get(udid);
+        if (session) {
+            session.viewerCount = Math.max(0, session.viewerCount + delta);
+            session.lastViewerAt = Date.now();
+            logger_1.default.debug(`[${udid}] iOS Stream viewer update: delta=${delta}, total=${session.viewerCount}`);
+        }
+    }
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const udid of this.sessions.keys())
+                yield this.stopStream(udid);
+        });
+    }
+    /**
+     * Get the cached WDA session ID for a device
+     */
+    getWDASessionId(udid) {
+        var _a;
+        return (_a = this.sessions.get(udid)) === null || _a === void 0 ? void 0 : _a.sessionId;
+    }
+    /**
+     * Set/update the WDA session ID for a device.
+     * Passing undefined will clear the cached session.
+     */
+    setWDASessionId(udid, sessionId) {
+        const session = this.sessions.get(udid);
+        if (session) {
+            session.sessionId = sessionId;
+            if (sessionId) {
+                logger_1.default.info(`Cached WDA Session ID for ${udid}: ${sessionId}`);
+            }
+            else {
+                logger_1.default.debug(`Cleared cached WDA Session ID for ${udid}`);
+            }
+        }
+    }
+};
+IOSStreamService = __decorate([
+    (0, typedi_1.Service)({ name: 'IOSStreamService' }),
+    __metadata("design:paramtypes", [])
+], IOSStreamService);
+exports.default = IOSStreamService;