[PATCH] trackInitialHost() is missing a JSDoc comment in background.js

[ormidales]

Category: documentation
Severity: patch
File(s): background.js

Description

The trackInitialHost(requestId, host) function implements non-trivial LRU + TTL eviction logic to bound memory usage, but it has no JSDoc comment. Its eviction strategy (prefer stale entries, fall back to oldest-inserted) is a meaningful behaviour contract that deserves explicit documentation, consistent with the level of detail found in other functions in the same file.

Problematic code example

// No JSDoc above this function
function trackInitialHost(requestId, host) {
  if (initialHostByRequest.size >= MAX_TRACKED_REQUESTS) {
    // eviction logic …
  }
  initialHostByRequest.set(requestId, { host, trackedAt: Date.now() });
}

Suggested fix

/**
 * Records the initial hostname for a given request ID to allow cross-redirect
 * domain comparison in onHeadersReceived.
 *
 * When the map reaches MAX_TRACKED_REQUESTS, eviction prefers the oldest
 * TTL-expired entry so that live (in-flight) requests are not prematurely
 * removed during burst traffic. Falls back to evicting the oldest-inserted
 * entry only when no stale entry exists, bounding memory usage.
 *
 * @param {string} requestId - The WebExtensions request identifier.
 * @param {string} host      - The hostname from the original request URL.
 */
function trackInitialHost(requestId, host) { … }

Acceptance criteria

• trackInitialHost() has a JSDoc block with @param annotations
• The eviction strategy is described in the comment
• Style is consistent with surrounding documentation