diff options
Diffstat (limited to 'browser/components/urlbar/MerinoClient.sys.mjs')
| -rw-r--r-- | browser/components/urlbar/MerinoClient.sys.mjs | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/browser/components/urlbar/MerinoClient.sys.mjs b/browser/components/urlbar/MerinoClient.sys.mjs new file mode 100644 index 0000000000..1e818a78a6 --- /dev/null +++ b/browser/components/urlbar/MerinoClient.sys.mjs @@ -0,0 +1,400 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs"; + +const lazy = {}; + +ChromeUtils.defineESModuleGetters(lazy, { + PromiseUtils: "resource://gre/modules/PromiseUtils.sys.mjs", + SkippableTimer: "resource:///modules/UrlbarUtils.sys.mjs", + UrlbarPrefs: "resource:///modules/UrlbarPrefs.sys.mjs", + UrlbarUtils: "resource:///modules/UrlbarUtils.sys.mjs", +}); + +const SEARCH_PARAMS = { + CLIENT_VARIANTS: "client_variants", + PROVIDERS: "providers", + QUERY: "q", + SEQUENCE_NUMBER: "seq", + SESSION_ID: "sid", +}; + +const SESSION_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes + +const HISTOGRAM_LATENCY = "FX_URLBAR_MERINO_LATENCY_MS"; +const HISTOGRAM_RESPONSE = "FX_URLBAR_MERINO_RESPONSE"; + +/** + * Client class for querying the Merino server. Each instance maintains its own + * session state including a session ID and sequence number that is included in + * its requests to Merino. + */ +export class MerinoClient { + /** + * @returns {object} + * The names of URL search params. + */ + static get SEARCH_PARAMS() { + return { ...SEARCH_PARAMS }; + } + + /** + * @param {string} name + * An optional name for the client. It will be included in log messages. + */ + constructor(name = "anonymous") { + this.#name = name; + XPCOMUtils.defineLazyGetter(this, "logger", () => + lazy.UrlbarUtils.getLogger({ prefix: `MerinoClient [${name}]` }) + ); + } + + /** + * @returns {string} + * The name of the client. + */ + get name() { + return this.#name; + } + + /** + * @returns {number} + * If `resetSession()` is not called within this timeout period after a + * session starts, the session will time out and the next fetch will begin a + * new session. + */ + get sessionTimeoutMs() { + return this.#sessionTimeoutMs; + } + set sessionTimeoutMs(value) { + this.#sessionTimeoutMs = value; + } + + /** + * @returns {number} + * The current session ID. Null when there is no active session. + */ + get sessionID() { + return this.#sessionID; + } + + /** + * @returns {number} + * The current sequence number in the current session. Zero when there is no + * active session. + */ + get sequenceNumber() { + return this.#sequenceNumber; + } + + /** + * @returns {string} + * A string that indicates the status of the last fetch. The values are the + * same as the labels used in the `FX_URLBAR_MERINO_RESPONSE` histogram: + * success, timeout, network_error, http_error + */ + get lastFetchStatus() { + return this.#lastFetchStatus; + } + + /** + * Fetches Merino suggestions. + * + * @param {object} options + * Options object + * @param {string} options.query + * The search string. + * @param {Array} options.providers + * Array of provider names to request from Merino. If this is given it will + * override the `merinoProviders` Nimbus variable and its fallback pref + * `browser.urlbar.merino.providers`. + * @param {number} options.timeoutMs + * Timeout in milliseconds. This method will return once the timeout + * elapses, a response is received, or an error occurs, whichever happens + * first. + * @param {string} options.extraLatencyHistogram + * If specified, the fetch's latency will be recorded in this histogram in + * addition to the usual Merino latency histogram. + * @param {string} options.extraResponseHistogram + * If specified, the fetch's response will be recorded in this histogram in + * addition to the usual Merino response histogram. + * @returns {Array} + * The Merino suggestions or null if there's an error or unexpected + * response. + */ + async fetch({ + query, + providers = null, + timeoutMs = lazy.UrlbarPrefs.get("merinoTimeoutMs"), + extraLatencyHistogram = null, + extraResponseHistogram = null, + }) { + this.logger.info(`Fetch starting with query: "${query}"`); + + // Set up the Merino session ID and related state. The session ID is a UUID + // without leading and trailing braces. + if (!this.#sessionID) { + let uuid = Services.uuid.generateUUID().toString(); + this.#sessionID = uuid.substring(1, uuid.length - 1); + this.#sequenceNumber = 0; + this.#sessionTimer?.cancel(); + + // Per spec, for the user's privacy, the session should time out and a new + // session ID should be used if the engagement does not end soon. + this.#sessionTimer = new lazy.SkippableTimer({ + name: "Merino session timeout", + time: this.#sessionTimeoutMs, + logger: this.logger, + callback: () => this.resetSession(), + }); + } + + // Get the endpoint URL. It's empty by default when running tests so they + // don't hit the network. + let endpointString = lazy.UrlbarPrefs.get("merinoEndpointURL"); + if (!endpointString) { + return []; + } + let url; + try { + url = new URL(endpointString); + } catch (error) { + this.logger.error("Error creating endpoint URL: " + error); + return []; + } + url.searchParams.set(SEARCH_PARAMS.QUERY, query); + url.searchParams.set(SEARCH_PARAMS.SESSION_ID, this.#sessionID); + url.searchParams.set(SEARCH_PARAMS.SEQUENCE_NUMBER, this.#sequenceNumber); + this.#sequenceNumber++; + + let clientVariants = lazy.UrlbarPrefs.get("merinoClientVariants"); + if (clientVariants) { + url.searchParams.set(SEARCH_PARAMS.CLIENT_VARIANTS, clientVariants); + } + + let providersString; + if (providers != null) { + if (!Array.isArray(providers)) { + throw new Error("providers must be an array if given"); + } + providersString = providers.join(","); + } else { + let value = lazy.UrlbarPrefs.get("merinoProviders"); + if (value) { + // The Nimbus variable/pref is used only if it's a non-empty string. + providersString = value; + } + } + + // An empty providers string is a valid value and means Merino should + // receive the request but not return any suggestions, so do not do a simple + // `if (providersString)` here. + if (typeof providersString == "string") { + url.searchParams.set(SEARCH_PARAMS.PROVIDERS, providersString); + } + + let details = { query, providers, timeoutMs, url }; + this.logger.debug("Fetch details: " + JSON.stringify(details)); + + let recordResponse = category => { + this.logger.info("Fetch done with status: " + category); + Services.telemetry.getHistogramById(HISTOGRAM_RESPONSE).add(category); + if (extraResponseHistogram) { + Services.telemetry + .getHistogramById(extraResponseHistogram) + .add(category); + } + this.#lastFetchStatus = category; + recordResponse = null; + }; + + // Set up the timeout timer. + let timer = (this.#timeoutTimer = new lazy.SkippableTimer({ + name: "Merino timeout", + time: timeoutMs, + logger: this.logger, + callback: () => { + // The fetch timed out. + this.logger.info(`Fetch timed out (timeout = ${timeoutMs}ms)`); + recordResponse?.("timeout"); + }, + })); + + // If there's an ongoing fetch, abort it so there's only one at a time. By + // design we do not abort fetches on timeout or when the query is canceled + // so we can record their latency. + try { + this.#fetchController?.abort(); + } catch (error) { + this.logger.error("Error aborting previous fetch: " + error); + } + + // Do the fetch. + let response; + let controller = (this.#fetchController = new AbortController()); + let stopwatchInstance = (this.#latencyStopwatchInstance = {}); + TelemetryStopwatch.start(HISTOGRAM_LATENCY, stopwatchInstance); + if (extraLatencyHistogram) { + TelemetryStopwatch.start(extraLatencyHistogram, stopwatchInstance); + } + await Promise.race([ + timer.promise, + (async () => { + try { + // Canceling the timer below resolves its promise, which can resolve + // the outer promise created by `Promise.race`. This inner async + // function happens not to await anything after canceling the timer, + // but if it did, `timer.promise` could win the race and resolve the + // outer promise without a value. For that reason, we declare + // `response` in the outer scope and set it here instead of returning + // the response from this inner function and assuming it will also be + // returned by `Promise.race`. + response = await fetch(url, { signal: controller.signal }); + TelemetryStopwatch.finish(HISTOGRAM_LATENCY, stopwatchInstance); + if (extraLatencyHistogram) { + TelemetryStopwatch.finish(extraLatencyHistogram, stopwatchInstance); + } + this.logger.debug( + "Got response: " + + JSON.stringify({ "response.status": response.status, ...details }) + ); + if (!response.ok) { + recordResponse?.("http_error"); + } + } catch (error) { + TelemetryStopwatch.cancel(HISTOGRAM_LATENCY, stopwatchInstance); + if (extraLatencyHistogram) { + TelemetryStopwatch.cancel(extraLatencyHistogram, stopwatchInstance); + } + if (error.name != "AbortError") { + this.logger.error("Fetch error: " + error); + recordResponse?.("network_error"); + } + } finally { + // Now that the fetch is done, cancel the timeout timer so it doesn't + // fire and record a timeout. If it already fired, which it would have + // on timeout, or was already canceled, this is a no-op. + timer.cancel(); + if (controller == this.#fetchController) { + this.#fetchController = null; + } + this.#nextResponseDeferred?.resolve(response); + this.#nextResponseDeferred = null; + } + })(), + ]); + if (timer == this.#timeoutTimer) { + this.#timeoutTimer = null; + } + + // Get the response body as an object. + let body; + try { + body = await response?.json(); + } catch (error) { + this.logger.error("Error getting response as JSON: " + error); + } + + if (body) { + this.logger.debug("Response body: " + JSON.stringify(body)); + } + + if (!body?.suggestions?.length) { + recordResponse?.("no_suggestion"); + return []; + } + + let { suggestions, request_id } = body; + if (!Array.isArray(suggestions)) { + this.logger.error("Unexpected response: " + JSON.stringify(body)); + recordResponse?.("no_suggestion"); + return []; + } + + recordResponse?.("success"); + return suggestions.map(suggestion => ({ + ...suggestion, + request_id, + source: "merino", + })); + } + + /** + * Resets the Merino session ID and related state. + */ + resetSession() { + this.#sessionID = null; + this.#sequenceNumber = 0; + this.#sessionTimer?.cancel(); + this.#sessionTimer = null; + this.#nextSessionResetDeferred?.resolve(); + this.#nextSessionResetDeferred = null; + } + + /** + * Cancels the timeout timer. + */ + cancelTimeoutTimer() { + this.#timeoutTimer?.cancel(); + } + + /** + * Returns a promise that's resolved when the next response is received or a + * network error occurs. + * + * @returns {Promise} + * The promise is resolved with the `Response` object or undefined if a + * network error occurred. + */ + waitForNextResponse() { + if (!this.#nextResponseDeferred) { + this.#nextResponseDeferred = lazy.PromiseUtils.defer(); + } + return this.#nextResponseDeferred.promise; + } + + /** + * Returns a promise that's resolved when the session is next reset, including + * on session timeout. + * + * @returns {Promise} + */ + waitForNextSessionReset() { + if (!this.#nextSessionResetDeferred) { + this.#nextSessionResetDeferred = lazy.PromiseUtils.defer(); + } + return this.#nextSessionResetDeferred.promise; + } + + get _test_sessionTimer() { + return this.#sessionTimer; + } + + get _test_timeoutTimer() { + return this.#timeoutTimer; + } + + get _test_fetchController() { + return this.#fetchController; + } + + get _test_latencyStopwatchInstance() { + return this.#latencyStopwatchInstance; + } + + // State related to the current session. + #sessionID = null; + #sequenceNumber = 0; + #sessionTimer = null; + #sessionTimeoutMs = SESSION_TIMEOUT_MS; + + #name; + #timeoutTimer = null; + #fetchController = null; + #latencyStopwatchInstance = null; + #lastFetchStatus = null; + #nextResponseDeferred = null; + #nextSessionResetDeferred = null; +} |