@xenon-device-management/xenon 2.13.2 → 2.15.0

package/lib/src/services/AIService.js

@@ -45,7 +45,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AI_SERVICE = exports.AIService = void 0;
+exports.AI_SERVICE = exports.AIService = exports.FAILURE_ANALYSIS_TIMEOUT_MS = exports.AI_CALL_TIMEOUT_MS = exports.AITimeoutError = exports.AIProviderPausedError = exports.AIRateLimitedError = void 0;
+exports.parseVisualVerdict = parseVisualVerdict;
 const generative_ai_1 = require("@google/generative-ai");
 const openai_1 = __importDefault(require("openai"));
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
@@ -55,13 +56,128 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const config_1 = require("../config");
 const CircuitBreaker_1 = require("./CircuitBreaker");
+/**
+ * A provider refused a call for its rate limit or quota (HTTP 429), whichever
+ * provider it is. A failed call like any other: its caller gets no answer and
+ * the circuit breaker counts it (`status`). Through 2.14 Gemini's provider
+ * answered a 429 with the text 'CONNECTION_OK_RATE_LIMITED', which was saved
+ * as a failed session's AI analysis and counted by the breaker as a success.
+ */
+class AIRateLimitedError extends Error {
+    constructor(detail) {
+        super('The AI provider is rate-limited or out of quota');
+        this.name = 'AIRateLimitedError';
+        this.status = 429;
+        this.detail = detail;
+    }
+}
+exports.AIRateLimitedError = AIRateLimitedError;
+/** A provider's 429, as its SDK (`status`) or axios (`response.status`) reports it. */
+function isRateLimit(err) {
+    var _a;
+    return err instanceof AIRateLimitedError || (err === null || err === void 0 ? void 0 : err.status) === 429 || ((_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.status) === 429;
+}
+/**
+ * The circuit breaker didn't send the call: the provider's recent calls
+ * failed. Still a CircuitOpenError, in words for testers: the Omni-Scan, Test
+ * locator and visual assertion answers show it, and "Circuit open for
+ * 'ai:gemini:<model>'; retry in 43120ms" isn't.
+ */
+class AIProviderPausedError extends CircuitBreaker_1.CircuitOpenError {
+    constructor(from) {
+        super(from.key, from.retryAfterMs);
+        this.seconds = Math.max(1, Math.ceil(from.retryAfterMs / 1000));
+        this.message = `The AI provider has been failing, so Xenon will call it again in ${this.seconds} s`;
+    }
+}
+exports.AIProviderPausedError = AIProviderPausedError;
+/** A call that outlasted its time limit; its request was cancelled. The circuit breaker counts it (`code`). */
+class AITimeoutError extends Error {
+    constructor(ms) {
+        super(`The AI provider didn't answer within ${Math.round(ms / 1000)} s`);
+        this.name = 'AITimeoutError';
+        this.code = 'ETIMEDOUT';
+    }
+}
+exports.AITimeoutError = AITimeoutError;
+/**
+ * How long an AI call may take, retries included, unless it says otherwise
+ * (failure analysis). Most are made while a test command runs: the LLM and
+ * visual healing tiers inside a failing findElement (both: 2 of these), the
+ * visual assertion and the screen description inside an execute script, an
+ * ai-icon find. The OpenAI and Anthropic SDKs otherwise wait up to 10 minutes
+ * a try, three tries, and Gemini has no limit, which held the command past
+ * the client's own timeout. Ollama's generate call already had 30 s.
+ */
+exports.AI_CALL_TIMEOUT_MS = 30000;
+/**
+ * How long a failed session's AI analysis may take, retries included. The
+ * OpenAI and Anthropic SDKs otherwise wait up to 10 minutes a try, three
+ * tries. The analysis runs after the session has ended (onSessionStopped
+ * doesn't wait for it), so this bounds the work left running, not a client's
+ * wait: an answer with a screenshot usually takes seconds.
+ */
+exports.FAILURE_ANALYSIS_TIMEOUT_MS = 120000;
+/** `call`, given a signal that cancels it after `ms`, when it fails with AITimeoutError. */
+function withTimeLimit(ms, call) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const controller = new AbortController();
+        let timer;
+        const expired = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                // The time-out first, so it, not the cancelled request's error, is the answer.
+                reject(new AITimeoutError(ms));
+                controller.abort();
+            }, ms);
+        });
+        try {
+            return yield Promise.race([call(controller.signal), expired]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    });
+}
+/**
+ * A provider's answer to the assertion prompt, `{ "result": true|false,
+ * "reason": "..." }`, read leniently (code fences, text around the JSON,
+ * `message` for `reason`, "true"/"false" as strings) but never guessed: null
+ * when it holds no true/false `result`.
+ */
+function parseVisualVerdict(answer) {
+    const text = answer.replace(/```(?:json)?/gi, '').trim();
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start)
+        return null;
+    let data;
+    try {
+        data = JSON.parse(text.slice(start, end + 1));
+    }
+    catch (_a) {
+        return null;
+    }
+    const raw = data === null || data === void 0 ? void 0 : data.result;
+    const result = raw === true || raw === 'true' ? true : raw === false || raw === 'false' ? false : null;
+    if (result === null)
+        return null;
+    const reason = typeof data.reason === 'string'
+        ? data.reason
+        : typeof data.message === 'string'
+            ? data.message
+            : '';
+    return {
+        result,
+        message: reason.trim() || (result ? 'The condition holds.' : 'The condition does not hold.'),
+    };
+}
 class GeminiProvider {
     constructor(apiKey, modelName) {
         this.genAI = new generative_ai_1.GoogleGenerativeAI(apiKey.trim());
         this.modelName =
             modelName && modelName.trim() !== '' ? modelName.trim() : 'gemini-3-flash-preview';
     }
-    analyze(prompt, screenshotBase64) {
+    analyze(prompt, screenshotBase64, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             const parts = [prompt];
             if (screenshotBase64) {
@@ -80,17 +196,17 @@ class GeminiProvider {
             for (const version of versions) {
                 try {
                     const model = this.genAI.getGenerativeModel({ model: this.modelName }, { apiVersion: version });
-                    const result = yield model.generateContent(parts);
+                    const result = yield model.generateContent(parts, signal ? { signal } : undefined);
                     const response = yield result.response;
                     return response.text();
                 }
                 catch (err) {
                     lastError = err;
-                    // If we get a 429, the connection IS WORKING, just rate limited.
-                    if (err.message.includes('429') || err.message.includes('Quota exceeded')) {
-                        logger_1.default.info(`[Gemini] Connection verified (Rate Limited) via ${version} endpoint.`);
-                        return 'CONNECTION_OK_RATE_LIMITED';
-                    }
+                    // The other endpoint has the same quota. By status only: the message
+                    // holds the URL and the provider's text, where "429" can be a token
+                    // count or part of the model's name.
+                    if (err.status === 429)
+                        throw new AIRateLimitedError(err.message);
                     if (err.message.includes('404') ||
                         err.message.includes('not found') ||
                         err.message.includes('unsupported')) {
@@ -109,7 +225,7 @@ class OpenAIProvider {
         this.client = new openai_1.default({ apiKey, baseURL });
         this.model = model;
     }
-    analyze(prompt, screenshotBase64) {
+    analyze(prompt, screenshotBase64, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             const messages = [
                 {
@@ -127,7 +243,7 @@ class OpenAIProvider {
                 model: this.model,
                 messages,
                 max_tokens: 500,
-            });
+            }, { signal });
             return response.choices[0].message.content || '';
         });
     }
@@ -137,7 +253,7 @@ class AnthropicProvider {
         this.client = new sdk_1.default({ apiKey });
         this.model = model;
     }
-    analyze(prompt, screenshotBase64) {
+    analyze(prompt, screenshotBase64, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             const content = [{ type: 'text', text: prompt }];
             if (screenshotBase64) {
@@ -154,7 +270,7 @@ class AnthropicProvider {
                 model: this.model,
                 max_tokens: 500,
                 messages: [{ role: 'user', content }],
-            });
+            }, { signal });
             return response.content[0].text || '';
         });
     }
@@ -170,10 +286,11 @@ class OllamaProvider {
     checkAvailability() {
         return __awaiter(this, void 0, void 0, function* () {
             const now = Date.now();
-            // Use cached status if checked recently
-            if (this.isAvailable !== null &&
-                now - this.lastAvailabilityCheck < this.AVAILABILITY_CHECK_INTERVAL) {
-                return this.isAvailable;
+            // An answer is kept for a while; "down" is checked again at the next call
+            // (a refused local connection costs nothing), so Ollama is used as soon as
+            // it is back.
+            if (this.isAvailable && now - this.lastAvailabilityCheck < this.AVAILABILITY_CHECK_INTERVAL) {
+                return true;
             }
             try {
                 // Quick health check - Ollama has a /api/tags endpoint
@@ -189,7 +306,7 @@ class OllamaProvider {
             }
         });
     }
-    analyze(prompt, screenshotBase64) {
+    analyze(prompt, screenshotBase64, signal) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
             // Check if Ollama is available before attempting
@@ -203,7 +320,7 @@ class OllamaProvider {
                     prompt: prompt,
                     images: screenshotBase64 ? [screenshotBase64] : [],
                     stream: false,
-                }, { timeout: 30000 });
+                }, { timeout: 30000, signal });
                 return response.data.response || '';
             }
             catch (err) {
@@ -221,6 +338,8 @@ class AIService {
     constructor() {
         this.provider = null;
         this.isMock = false;
+        /** The settings `provider` was set up from (initializeProvider). */
+        this.setUpFrom = null;
         this.initializeProvider();
     }
     // Key the breaker by provider + resolved model name so a misbehaving model
@@ -240,16 +359,60 @@ class AIService {
         return `ai:${provider}:${model || 'default'}`;
     }
     // Single choke point for every LLM call so circuit-breaker state is shared
-    // across analyzeFailure / visualFind / healLocator.
-    callProvider(prompt, screenshotBase64) {
-        return __awaiter(this, void 0, void 0, function* () {
-            return CircuitBreaker_1.CIRCUIT_BREAKERS.execute(this.breakerKey(), () => this.provider.analyze(prompt, screenshotBase64));
+    // across analyzeFailure / visualFind / healLocator. A rate limit is
+    // AIRateLimitedError whichever provider sent it; a call is cancelled after
+    // `timeoutMs` (AI_CALL_TIMEOUT_MS unless given: AITimeoutError). The breaker
+    // counts both, and a call it holds back is AIProviderPausedError.
+    callProvider(prompt_1, screenshotBase64_1) {
+        return __awaiter(this, arguments, void 0, function* (prompt, screenshotBase64, opts = {}) {
+            var _a;
+            const provider = this.provider;
+            try {
+                return yield CircuitBreaker_1.CIRCUIT_BREAKERS.execute(this.breakerKey(), () => {
+                    var _a;
+                    return withTimeLimit((_a = opts.timeoutMs) !== null && _a !== void 0 ? _a : exports.AI_CALL_TIMEOUT_MS, (signal) => provider.analyze(prompt, screenshotBase64, signal));
+                });
+            }
+            catch (err) {
+                if (isRateLimit(err) && !(err instanceof AIRateLimitedError)) {
+                    throw new AIRateLimitedError((_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : String(err));
+                }
+                if (err instanceof CircuitBreaker_1.CircuitOpenError && !(err instanceof AIProviderPausedError)) {
+                    throw new AIProviderPausedError(err);
+                }
+                throw err;
+            }
         });
     }
+    /**
+     * Sets the provider up from the server's AI settings, which the AI engine
+     * page changes while the server runs (`POST /config`). Again only when they
+     * changed, so a provider's client, and Ollama's availability check, carry
+     * over from one call to the next.
+     */
     initializeProvider() {
         const providerType = config_1.config.aiProvider;
         const genericModel = config_1.config.aiModel;
         const baseUrl = config_1.config.aiBaseUrl;
+        const settings = JSON.stringify([
+            providerType,
+            genericModel,
+            baseUrl,
+            config_1.config.geminiApiKey,
+            config_1.config.openaiApiKey,
+            config_1.config.anthropicApiKey,
+            config_1.config.geminiModel,
+            config_1.config.openaiModel,
+            config_1.config.anthropicModel,
+            config_1.config.ollamaModel,
+            process.env.GEMINI_API_KEY === 'mock',
+        ]);
+        if (settings === this.setUpFrom)
+            return;
+        this.setUpFrom = settings;
+        // A provider chosen without a key is no provider, never the previous one.
+        this.provider = null;
+        this.isMock = false;
         logger_1.default.info(`[AIService] Initializing with provider: ${providerType}`);
         if (process.env.GEMINI_API_KEY === 'mock') {
             this.isMock = true;
@@ -285,7 +448,15 @@ class AIService {
             logger_1.default.error(`[AIService] Initialization error: ${err.message}`);
         }
     }
+    /**
+     * Whether a provider is set up for the settings in force now. Failure
+     * analysis and the LLM and visual healing tiers ask this first; it used to
+     * answer for the provider set up last, so choosing a configured provider on
+     * the AI engine page never turned them on, and choosing one without a key
+     * left the previous provider answering.
+     */
     isEnabled() {
+        this.initializeProvider();
         return this.provider !== null || this.isMock;
     }
     analyzeFailure(context) {
@@ -305,7 +476,9 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
             try {
                 const prompt = this.constructPrompt(context);
                 const screenshotBase64 = this.getScreenshotBase64(context.screenshotPath);
-                const text = yield this.callProvider(prompt, screenshotBase64 || undefined);
+                const text = yield this.callProvider(prompt, screenshotBase64 || undefined, {
+                    timeoutMs: exports.FAILURE_ANALYSIS_TIMEOUT_MS,
+                });
                 logger_1.default.info(`[AIService] Analysis complete for ${context.sessionId}`);
                 return text;
             }
@@ -313,6 +486,12 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
                 if (err instanceof CircuitBreaker_1.CircuitOpenError) {
                     logger_1.default.debug(`[AIService] Analysis skipped: ${err.message}`);
                 }
+                else if (err instanceof AIRateLimitedError) {
+                    logger_1.default.warn(`[AIService] No analysis for ${context.sessionId}: ${err.message}: ${err.detail}`);
+                }
+                else if (err instanceof AITimeoutError) {
+                    logger_1.default.warn(`[AIService] No analysis for ${context.sessionId}: ${err.message}`);
+                }
                 else {
                     logger_1.default.error(`[AIService] Analysis failed: ${err.message}`);
                 }
@@ -365,6 +544,71 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
             }
         });
     }
+    /**
+     * Asks the provider whether `condition` holds on the screenshot
+     * (`xenon: assertVisualState`). Answers only with the provider's own
+     * verdict: with no provider, a failed call, a rate limit or an answer that
+     * isn't true or false it throws, saying the condition was not checked. A
+     * `false` there would pass a test asserting that something is absent.
+     */
+    assertVisual(screenshotBase64, condition) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            this.initializeProvider();
+            const notChecked = 'so the condition was not checked';
+            if (!this.provider) {
+                throw new Error(`No AI provider is configured, ${notChecked}. Set XENON_AI_PROVIDER and the provider's key.`);
+            }
+            const prompt = `
+You are checking a screenshot of a mobile app for an automated test.
+
+Condition: ${JSON.stringify(condition)}
+
+Is the condition true of what the screenshot shows? Judge only what is visible on the screen.
+Answer with JSON only, exactly: {"result": true or false, "reason": "one sentence on what you see"}
+        `.trim();
+            let answer;
+            try {
+                answer = yield this.callProvider(prompt, screenshotBase64);
+            }
+            catch (err) {
+                if (err instanceof AIRateLimitedError || err instanceof AITimeoutError) {
+                    throw new Error(`${err.message}, ${notChecked}. Try again later.`);
+                }
+                if (err instanceof AIProviderPausedError) {
+                    throw new Error(`The AI provider has been failing, ${notChecked}. Xenon will call it again in ${err.seconds} s.`);
+                }
+                throw new Error(`The AI provider failed, ${notChecked}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+            }
+            const verdict = parseVisualVerdict(answer);
+            if (!verdict) {
+                const said = answer.replace(/\s+/g, ' ').trim().slice(0, 200);
+                throw new Error(`Xenon could not read the AI provider's answer as true or false, ${notChecked}. ` +
+                    `It answered: ${JSON.stringify(said)}`);
+            }
+            return verdict;
+        });
+    }
+    /**
+     * A short description of the screen in the screenshot, for
+     * `xenon: analyzeScreen` and device control's Omni-Scan. Throws when there
+     * is no provider or the call fails (AIRateLimitedError for a rate limit,
+     * AITimeoutError after AI_CALL_TIMEOUT_MS), so the caller can say why there
+     * is none.
+     */
+    describeScreen(screenshotBase64) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.initializeProvider();
+            if (!this.provider)
+                throw new Error('No AI provider is configured');
+            const prompt = `
+You are looking at a screenshot of a mobile app, for a software tester.
+Describe the screen in a few short sentences: which screen it is, its main elements and their state (for example filled in, empty, selected or disabled), and anything unexpected, such as an error message, a system dialog, a crash or a loading indicator.
+Describe only what is visible. Answer in plain text.
+        `.trim();
+            return this.callProvider(prompt, screenshotBase64);
+        });
+    }
     /**
      * Heals a broken locator using deep LLM reasoning (Tier 5)
      */
@@ -413,9 +657,10 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
     }
     testConnection(testConfig) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const providerType = testConfig.aiProvider || config_1.config.aiProvider;
             try {
                 let testProvider = null;
-                const providerType = testConfig.aiProvider || config_1.config.aiProvider;
                 const model = testConfig.aiModel || config_1.config.aiModel;
                 const baseUrl = testConfig.aiBaseUrl || config_1.config.aiBaseUrl;
                 logger_1.default.info(`[AIService] Testing connection for provider: ${providerType}`);
@@ -448,17 +693,21 @@ Fix: Add a pre-emptive check for the location permission dialog or use the \`aut
                 }
                 if (!testProvider)
                     throw new Error('Failed to initialize provider for testing');
-                // Send a minimal ping command
-                const responseText = yield testProvider.analyze('Hello. Response: OK');
-                if (responseText === 'CONNECTION_OK_RATE_LIMITED') {
-                    return {
-                        success: true,
-                        message: `Successfully connected to ${providerType}! (Note: You are currently out of quota/rate-limited, but the setup is correct)`,
-                    };
-                }
+                // Send a minimal ping command. Not through the circuit breaker (a test
+                // shouldn't pause the provider for everyone), but with the time limit.
+                const pinged = testProvider;
+                yield withTimeLimit(exports.AI_CALL_TIMEOUT_MS, (signal) => pinged.analyze('Hello. Response: OK', undefined, signal));
                 return { success: true, message: `Successfully connected to ${providerType}!` };
             }
             catch (err) {
+                // Not a success: every AI call fails the same way until it has quota again.
+                if (isRateLimit(err)) {
+                    logger_1.default.warn(`[AIService] Connection test: ${providerType} is rate-limited: ${(_a = err.detail) !== null && _a !== void 0 ? _a : err.message}`);
+                    return {
+                        success: false,
+                        message: `${providerType} answered, but it is rate-limited or out of quota. AI features won't work with it until it has quota again.`,
+                    };
+                }
                 logger_1.default.error(`[AIService] Connection test failed: ${err.message}`);
                 return { success: false, message: `Connection failed: ${err.message}` };
             }

package/lib/src/services/CleanupService.js

@@ -25,6 +25,7 @@ const logger_1 = __importDefault(require("../logger"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../config");
+const labSettings_1 = require("./settings/labSettings");
 const recordingCleanup_1 = require("./recording/recordingCleanup");
 /** Subdirectory holding composite (multi-device) outputs, keyed by group id. */
 const GROUPS_DIR = '_groups';
@@ -34,6 +35,8 @@ let CleanupService = class CleanupService {
     }
     /**
      * Orchestrates build + session + recording cleanup based on retention policy.
+     * The build retention window, the build cap and the asset purge are the ones
+     * saved on the dashboard's Maintenance page, else `pluginArgs`'.
      *
      * Phases:
      *  1. Purge old builds (by age AND count cap) together with their sessions.
@@ -44,7 +47,9 @@ let CleanupService = class CleanupService {
      */
     runCleanup(pluginArgs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { buildCleanupDays = 30, buildCleanupMaxCount = 100, deleteBuildAssets = true, } = pluginArgs;
+            // What the Maintenance page saved wins over the startup options, and is
+            // read here, at each run, so a change needs no restart. See labSettings.ts.
+            const { buildCleanupDays, buildCleanupMaxCount, deleteBuildAssets } = yield (0, labSettings_1.loadEffectiveSettings)(pluginArgs);
             this.log.info(`Starting cleanup: Retention = ${buildCleanupDays} days, Max Builds = ${buildCleanupMaxCount}, Purge Assets = ${deleteBuildAssets}`);
             const expirationDate = new Date();
             expirationDate.setDate(expirationDate.getDate() - buildCleanupDays);

package/lib/src/services/EmailService.js

@@ -23,6 +23,7 @@ const typedi_1 = require("typedi");
 const nodemailer_1 = __importDefault(require("nodemailer"));
 const config_1 = require("../config");
 const logger_1 = __importDefault(require("../logger"));
+const passwordResetLink_1 = require("./passwordResetLink");
 let EmailService = class EmailService {
     constructor() {
         this.log = logger_1.default.scope('Email');
@@ -55,6 +56,34 @@ let EmailService = class EmailService {
             'over the account for the link lifetime. Configure XENON_SMTP_URL, or unset this and ' +
             'issue links from the dashboard Users page.');
     }
+    /**
+     * Startup notice about XENON_PUBLIC_URL, the address links Xenon hands out
+     * are built from (never the request's Host, which the asker chooses):
+     *
+     * - set but refused (not an http(s) server address): whatever the mail
+     *   setup, since it also decides each device's dashboard_link. The value is
+     *   not logged: a user name and password in it is one reason to refuse it.
+     * - unset while Xenon could send reset links: the sign-in page's "forgot
+     *   password" then sends people to an administrator, and an administrator's
+     *   reset link is handed back to them rather than emailed.
+     */
+    warnAboutPublicUrl() {
+        var _a;
+        if (((_a = config_1.config.publicUrl) === null || _a === void 0 ? void 0 : _a.trim()) && (0, passwordResetLink_1.resetLinkBase)() === null) {
+            this.warnLog('XENON_PUBLIC_URL is set but is not an http(s) server address such as ' +
+                'https://xenon.example.com or http://lab-mac:4723 (a trailing /xenon is fine; any ' +
+                'other path, a query, a fragment or a user name is not), so Xenon ignores it: it ' +
+                'emails no password-reset links, and device dashboard links are paths on this server.');
+            return;
+        }
+        if (!this.canDeliver() || (0, passwordResetLink_1.resetLinkBase)() !== null)
+            return;
+        this.warnLog("XENON_PUBLIC_URL is not set to this server's address, so Xenon sends no password-reset " +
+            'links: "Forgot password" asks people to contact an administrator, and the Users ' +
+            'page hands an administrator the link instead of emailing it. Set XENON_PUBLIC_URL to ' +
+            'the http(s) address people reach this server at, such as https://xenon.example.com ' +
+            'or http://lab-mac:4723 (a trailing /xenon is fine; any other path is not).');
+    }
     send(mail) {
         return __awaiter(this, void 0, void 0, function* () {
             const smtpUrl = config_1.config.smtpUrl;

package/lib/src/services/InterceptorService.js

@@ -72,6 +72,10 @@ const SessionArchive_1 = require("./interceptor/SessionArchive");
 const PortAllocator_1 = require("./PortAllocator");
 const SocketServer_1 = require("./SocketServer");
 const SocketEvents_1 = require("../enums/SocketEvents");
+const adbForPhone_1 = require("./network/adbForPhone");
+const PhoneNetworkLedger_1 = require("./network/PhoneNetworkLedger");
+const phoneNetworkLock_1 = require("./network/phoneNetworkLock");
+const xenonProxy_1 = require("./network/xenonProxy");
 const DEFAULT_BUFFER_CAP = 1000;
 const BODY_SPILL_THRESHOLD = 1024 * 1024;
 let InterceptorService = class InterceptorService {
@@ -88,6 +92,10 @@ let InterceptorService = class InterceptorService {
     isActive(sessionId) {
         return this.states.has(sessionId);
     }
+    /** The sessions whose traffic is captured on this server. */
+    sessionIds() {
+        return [...this.states.keys()];
+    }
     start(sessionId, device, opts) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d;
@@ -143,7 +151,7 @@ let InterceptorService = class InterceptorService {
             catch (err) {
                 this.logger.warn(`Cert install (${installMode}) failed for ${device.udid}: ${err.message}. HTTPS interception may not work.`);
             }
-            yield adapter.setProxy(device.udid, host, port);
+            const previousProxy = yield this.pointPhoneAtProxy(sessionId, device.udid, host, port, routing.reverseEstablished);
             const state = {
                 sessionId,
                 device,
@@ -155,6 +163,7 @@ let InterceptorService = class InterceptorService {
                 certInstalledFilename: certFilename,
                 startedAt: Date.now(),
                 reverseEstablished: routing.reverseEstablished,
+                previousProxy,
             };
             this.states.set(sessionId, state);
             this.emit({ type: 'session_started', sessionId, port, host }, device.udid);
@@ -167,12 +176,7 @@ let InterceptorService = class InterceptorService {
             if (!state)
                 return;
             this.states.delete(sessionId);
-            try {
-                yield this.getAndroidAdapter().clearProxy(state.device.udid);
-            }
-            catch (err) {
-                this.logger.warn(`Clear proxy failed for ${state.device.udid}: ${err.message}`);
-            }
+            yield this.putPhoneProxyBack(state);
             if (state.reverseEstablished) {
                 try {
                     yield this.getAndroidAdapter().removeReverse(state.device.udid, state.port);
@@ -284,15 +288,68 @@ let InterceptorService = class InterceptorService {
             requests: state.buffer.list(),
         };
     }
+    /**
+     * Points the whole phone at the session's proxy, and returns the proxy the
+     * phone had (null: none) for stop() to put back. The change is written down
+     * before it is made, so a restart after a crash can undo it
+     * (PhoneNetworkLedger, PhoneNetworkRestore).
+     *
+     * A previous proxy that is a capture an earlier run left behind (this
+     * machine, a capture port, nothing answering) is not the phone's own: it
+     * counts as none, so the end of this session doesn't put a dead proxy back.
+     */
+    pointPhoneAtProxy(sessionId, udid, host, port, reverseEstablished) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const adapter = this.getAndroidAdapter();
+            const setting = `${host}:${port}`;
+            return yield (0, phoneNetworkLock_1.withPhoneNetworkLock)(udid, () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                let previous = null;
+                try {
+                    const read = yield adapter.readProxy(udid);
+                    const leftover = read === setting ||
+                        (yield (0, xenonProxy_1.isDeadCaptureProxy)(read, typedi_1.Container.get(PortAllocator_1.PortAllocator).rangeOf('proxy')));
+                    if (leftover) {
+                        this.logger.info(`[${sessionId}] ${udid} had a proxy left by an earlier capture (${read})`);
+                    }
+                    previous = (0, xenonProxy_1.isUnsetProxy)(read) || leftover ? null : read;
+                }
+                catch (err) {
+                    this.logger.warn(`Could not read the proxy of ${udid}: ${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}`);
+                }
+                yield typedi_1.Container.get(PhoneNetworkLedger_1.PhoneNetworkLedger).note(sessionId, udid, {
+                    proxy: Object.assign({ set: setting, previous }, (reverseEstablished ? { reversePort: port } : {})),
+                });
+                yield adapter.setProxy(udid, host, port);
+                return previous;
+            }));
+        });
+    }
+    /**
+     * Puts back the proxy the phone had before the session. A phone that can't
+     * be reached keeps the change written down, and is put back at its next
+     * session or at this server's next start.
+     */
+    putPhoneProxyBack(state) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const udid = state.device.udid;
+            yield (0, phoneNetworkLock_1.withPhoneNetworkLock)(udid, () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                try {
+                    yield this.getAndroidAdapter().restoreProxy(udid, state.previousProxy);
+                    yield typedi_1.Container.get(PhoneNetworkLedger_1.PhoneNetworkLedger).settle(state.sessionId, 'proxy');
+                }
+                catch (err) {
+                    this.logger.warn(`Could not put back the proxy of ${udid} after session ${state.sessionId}: ` +
+                        `${(_a = err === null || err === void 0 ? void 0 : err.message) !== null && _a !== void 0 ? _a : err}. Xenon tries again at the phone's next session and when it restarts.`);
+                }
+            }));
+        });
+    }
     getAndroidAdapter() {
         if (this.androidAdapter)
             return this.androidAdapter;
-        const provider = (udid) => __awaiter(this, void 0, void 0, function* () {
-            const { default: AndroidDeviceManager } = yield Promise.resolve().then(() => __importStar(require('../device-managers/AndroidDeviceManager')));
-            const mgr = typedi_1.Container.get(AndroidDeviceManager);
-            return yield mgr.getAdbForDevice(udid);
-        });
-        this.androidAdapter = new AndroidProxyAdapter_1.AndroidProxyAdapter(provider);
+        this.androidAdapter = new AndroidProxyAdapter_1.AndroidProxyAdapter(adbForPhone_1.adbForPhone);
         return this.androidAdapter;
     }
     // Establishes how the device will reach the host-side MITM proxy.