feat: enhance connection settings with manual API port and cache mode options in browser and VS Code extensions

Author: PythonSmall-Q

CHANGELOG.md

@@ -9,7 +9,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Changed
 
-- **Extension connection settings** — the browser extension popup now lets users set a manual API port and choose the discovered-port cache duration. The VS Code extension gained a new `timelens.apiBaseUrlCacheSeconds` setting for the same purpose. Both extensions still scan the fallback range automatically when no manual port is set.
+- **Extension connection settings** — the browser extension popup now lets users set a manual API port, choose between duration-based cache or "until next startup" cache, and configure the cache duration. The VS Code extension gained `timelens.apiBaseUrlCacheMode` (`duration` / `startup`) and `timelens.apiBaseUrlCacheSeconds` settings for the same behavior. If a manually configured localhost port fails repeatedly, both extensions temporarily ignore it and automatically scan the fallback port range.
 - **Settings page UI redesign** — rewrote the Settings page to use a reusable card-based layout consistent with Backup & Restore v2, including `glass-card` containers, icon-header cards, and inner content wells.
 
 ### Fixed

browser-extension/api.js

@@ -1,40 +1,74 @@
 const STORAGE_KEYS = {
   apiPort: "timelens.apiPort",
+  apiCacheMode: "timelens.apiCacheMode",
   apiCacheSeconds: "timelens.apiCacheSeconds",
 };
 
 const DEFAULT_API_PORT = 49152;
 const API_PORT_FALLBACK_COUNT = 1000;
 const DEFAULT_CACHE_SECONDS = 60;
 const FALLBACK_CACHE_MS = 5_000;
+const MANUAL_PORT_FAILURE_THRESHOLD = 5;
 
 let discoveredApiBaseCache = null;
+let manualPortFailureCount = 0;
+let manualPortDisabledUntil = 0;
+
+function log(...args) {
+  console.log("[TimeLens API]", ...args);
+}
+
+function logWarn(...args) {
+  console.warn("[TimeLens API]", ...args);
+}
 
 async function getConnectionSettings() {
-  const { [STORAGE_KEYS.apiPort]: port, [STORAGE_KEYS.apiCacheSeconds]: cacheSeconds } =
-    await chrome.storage.local.get([STORAGE_KEYS.apiPort, STORAGE_KEYS.apiCacheSeconds]);
-  return {
-    manualPort: typeof port === "number" ? port : (parseInt(port, 10) || 0),
-    cacheSeconds: typeof cacheSeconds === "number" ? cacheSeconds : (parseInt(cacheSeconds, 10) || DEFAULT_CACHE_SECONDS),
+  const {
+    [STORAGE_KEYS.apiPort]: port,
+    [STORAGE_KEYS.apiCacheMode]: cacheMode,
+    [STORAGE_KEYS.apiCacheSeconds]: cacheSeconds,
+  } = await chrome.storage.local.get([
+    STORAGE_KEYS.apiPort,
+    STORAGE_KEYS.apiCacheMode,
+    STORAGE_KEYS.apiCacheSeconds,
+  ]);
+
+  const manualPort = parseInt(port, 10) || 0;
+  const settings = {
+    manualPort,
+    cacheMode: cacheMode === "startup" ? "startup" : "duration",
+    cacheSeconds: parseInt(cacheSeconds, 10) || DEFAULT_CACHE_SECONDS,
   };
+  log("Loaded connection settings:", settings);
+  return settings;
 }
 
 /**
  * Discover the actual local API port. The desktop backend may bind to a
  * fallback port when 49152 is unavailable (e.g. blocked by Windows / AV).
  * If the user has set a manual port, that port is tried first.
+ *
+ * If the manual port fails repeatedly, it is temporarily ignored and the
+ * fallback range is scanned automatically. This handles the case where the
+ * user entered a wrong port or the desktop moved to a different port.
  */
 export async function discoverApiBaseUrl() {
   const now = Date.now();
   if (discoveredApiBaseCache && discoveredApiBaseCache.expiresAt > now) {
     return discoveredApiBaseCache.value;
   }
 
-  const { manualPort, cacheSeconds } = await getConnectionSettings();
-  const cacheMs = Math.max(0, cacheSeconds) * 1000;
+  const { manualPort, cacheMode, cacheSeconds } = await getConnectionSettings();
+  const cacheMs = cacheMode === "startup" ? Number.MAX_SAFE_INTEGER : Math.max(0, cacheSeconds) * 1000;
 
   const portsToTry = [];
-  if (manualPort > 0 && manualPort <= 65535) {
+  const manualPortAllowed =
+    manualPort > 0 &&
+    manualPort <= 65535 &&
+    now > manualPortDisabledUntil &&
+    manualPortFailureCount < MANUAL_PORT_FAILURE_THRESHOLD;
+
+  if (manualPortAllowed) {
     portsToTry.push(manualPort);
   }
   for (let offset = 0; offset <= API_PORT_FALLBACK_COUNT; offset += 1) {
@@ -44,7 +78,11 @@ export async function discoverApiBaseUrl() {
     }
   }
 
+  let manualPortTried = false;
   for (const port of portsToTry) {
+    if (port === manualPort) {
+      manualPortTried = true;
+    }
     const baseUrl = `http://127.0.0.1:${port}`;
     try {
       const controller = new AbortController();
@@ -56,6 +94,10 @@ export async function discoverApiBaseUrl() {
       if (response.ok) {
         const data = await response.json();
         if (data && typeof data.version === "string") {
+          if (port === manualPort) {
+            manualPortFailureCount = 0;
+            manualPortDisabledUntil = 0;
+          }
           discoveredApiBaseCache = { value: baseUrl, expiresAt: now + cacheMs };
           return baseUrl;
         }
@@ -65,6 +107,14 @@ export async function discoverApiBaseUrl() {
     }
   }
 
+  if (manualPortTried) {
+    manualPortFailureCount += 1;
+    if (manualPortFailureCount >= MANUAL_PORT_FAILURE_THRESHOLD) {
+      // Temporarily ignore the manual port for 5 minutes so the fallback scan can work.
+      manualPortDisabledUntil = now + 5 * 60 * 1000;
+    }
+  }
+
   discoveredApiBaseCache = { value: "", expiresAt: now + FALLBACK_CACHE_MS };
   return null;
 }
@@ -77,5 +127,11 @@ export function clearApiBaseUrlCache() {
   discoveredApiBaseCache = null;
 }
 
+export function resetManualPortFailureTracking() {
+  manualPortFailureCount = 0;
+  manualPortDisabledUntil = 0;
+}
+
 export const API_STORAGE_KEYS = STORAGE_KEYS;
 export const DEFAULT_CACHE_SECONDS_VALUE = DEFAULT_CACHE_SECONDS;
+export const MANUAL_PORT_FAILURE_THRESHOLD_VALUE = MANUAL_PORT_FAILURE_THRESHOLD;

browser-extension/background.js

@@ -12,7 +12,7 @@
  */
 
 import { getLocale, t } from "./i18n.js";
-import { discoverApiBaseUrl, getApiBaseUrl } from "./api.js";
+import { discoverApiBaseUrl, getApiBaseUrl, clearApiBaseUrlCache, resetManualPortFailureTracking } from "./api.js";
 
 const STORAGE_KEYS = {
   activeSession:   "timelens.activeSession",
@@ -35,13 +35,17 @@ chrome.runtime.onInstalled.addListener(() => {
   chrome.alarms.create("timelens-api-heartbeat", { periodInMinutes: 1 });
   safeConfigureIdleDetection();
   initState();
+  clearApiBaseUrlCache();
+  resetManualPortFailureTracking();
   pingApiStatus();
 });
 
 chrome.runtime.onStartup.addListener(() => {
   chrome.alarms.create("timelens-api-heartbeat", { periodInMinutes: 1 });
   safeConfigureIdleDetection();
   initState();
+  clearApiBaseUrlCache();
+  resetManualPortFailureTracking();
   flushPendingSessions();
 });
 

browser-extension/i18n.js

@@ -31,8 +31,11 @@ const TRANSLATIONS = {
     bridgeKeyCleared: "Extension bridge key cleared.",
     connectionSettings: "Connection settings",
     apiPort: "API Port:",
-    cacheDuration: "Cache (s):",
-    connectionSettingsHint: "Set the port to 0 to scan the fallback range. Cache duration controls how long the discovered port is remembered.",
+    cacheMode: "Cache:",
+    cacheModeDuration: "Duration",
+    cacheModeStartup: "Until next startup",
+    cacheDuration: "Duration (s):",
+    connectionSettingsHint: "Set the port to 0 to scan the fallback range. If the set port fails repeatedly, the extension will automatically scan again.",
   },
   "zh-CN": {
     connection: "桌面端连接",
@@ -66,8 +69,11 @@ const TRANSLATIONS = {
     bridgeKeyCleared: "扩展网桥密钥已清除。",
     connectionSettings: "连接设置",
     apiPort: "API 端口：",
-    cacheDuration: "缓存（秒）：",
-    connectionSettingsHint: "端口设为 0 将扫描回退范围。缓存时长控制记住已发现端口的时长。",
+    cacheMode: "缓存：",
+    cacheModeDuration: "时长",
+    cacheModeStartup: "到下次启动",
+    cacheDuration: "缓存时长（秒）：",
+    connectionSettingsHint: "端口设为 0 将扫描回退范围。若设置的端口持续失败，扩展会自动重新扫描。",
   },
   "zh-TW": {
     connection: "桌面端連線",
@@ -101,8 +107,11 @@ const TRANSLATIONS = {
     bridgeKeyCleared: "擴充功能橋接金鑰已清除。",
     connectionSettings: "連線設定",
     apiPort: "API 連接埠：",
-    cacheDuration: "快取（秒）：",
-    connectionSettingsHint: "連接埠設為 0 將掃描回退範圍。快取時長控制記住已發現連接埠的時間。",
+    cacheMode: "快取：",
+    cacheModeDuration: "時長",
+    cacheModeStartup: "到下次啟動",
+    cacheDuration: "快取時長（秒）：",
+    connectionSettingsHint: "連接埠設為 0 將掃描回退範圍。若設定的連接埠持續失敗，擴充功能會自動重新掃描。",
   },
 };
 

browser-extension/popup.html

@@ -55,7 +55,17 @@ <h2 data-i18n="connectionSettings">Connection settings</h2>
             />
           </div>
           <div style="display: flex; align-items: center; gap: 8px;">
-            <label for="cache-duration-input" class="muted" style="font-size: 12px; width: 80px;" data-i18n="cacheDuration">Cache (s):</label>
+            <label for="cache-mode-select" class="muted" style="font-size: 12px; width: 80px;" data-i18n="cacheMode">Cache:</label>
+            <select
+              id="cache-mode-select"
+              style="flex: 1; padding: 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 12px;"
+            >
+              <option value="duration" data-i18n="cacheModeDuration">Duration</option>
+              <option value="startup" data-i18n="cacheModeStartup">Until next startup</option>
+            </select>
+          </div>
+          <div id="cache-duration-row" style="display: flex; align-items: center; gap: 8px;">
+            <label for="cache-duration-input" class="muted" style="font-size: 12px; width: 80px;" data-i18n="cacheDuration">Duration (s):</label>
             <input
               id="cache-duration-input"
               type="number"
@@ -66,7 +76,7 @@ <h2 data-i18n="connectionSettings">Connection settings</h2>
             />
           </div>
           <button id="save-connection-settings-button" class="ghost-button" type="button" data-i18n="saveOrUpdate">Save / Update</button>
-          <p class="muted" style="font-size: 11px;" data-i18n="connectionSettingsHint">Set the port to 0 to scan the fallback range. Cache duration controls how long the discovered port is remembered.</p>
+          <p class="muted" style="font-size: 11px;" data-i18n="connectionSettingsHint">Set the port to 0 to scan the fallback range. If the set port fails repeatedly, the extension will automatically scan again.</p>
         </div>
       </section>
 

browser-extension/popup.js

@@ -25,6 +25,8 @@ const bridgeKeyPanel = document.querySelector("#bridge-key-panel");
 const bridgeKeyInput = document.querySelector("#bridge-key-input");
 const saveKeyButton = document.querySelector("#save-key-button");
 const apiPortInput = document.querySelector("#api-port-input");
+const cacheModeSelect = document.querySelector("#cache-mode-select");
+const cacheDurationRow = document.querySelector("#cache-duration-row");
 const cacheDurationInput = document.querySelector("#cache-duration-input");
 const saveConnectionSettingsButton = document.querySelector("#save-connection-settings-button");
 const locale = getLocale();
@@ -50,22 +52,45 @@ if (saveKeyButton) {
 
 // Load and save connection settings
 async function loadConnectionSettings() {
-  const { [API_STORAGE_KEYS.apiPort]: port, [API_STORAGE_KEYS.apiCacheSeconds]: cacheSeconds } =
-    await chrome.storage.local.get([API_STORAGE_KEYS.apiPort, API_STORAGE_KEYS.apiCacheSeconds]);
+  const {
+    [API_STORAGE_KEYS.apiPort]: port,
+    [API_STORAGE_KEYS.apiCacheMode]: cacheMode,
+    [API_STORAGE_KEYS.apiCacheSeconds]: cacheSeconds,
+  } = await chrome.storage.local.get([
+    API_STORAGE_KEYS.apiPort,
+    API_STORAGE_KEYS.apiCacheMode,
+    API_STORAGE_KEYS.apiCacheSeconds,
+  ]);
   if (apiPortInput) {
     apiPortInput.value = port === 0 || port === "0" ? "0" : (port ? String(port) : "");
   }
+  if (cacheModeSelect) {
+    cacheModeSelect.value = cacheMode === "startup" ? "startup" : "duration";
+  }
   if (cacheDurationInput) {
     cacheDurationInput.value = String(cacheSeconds ?? DEFAULT_CACHE_SECONDS_VALUE);
   }
+  if (cacheDurationRow) {
+    cacheDurationRow.style.display = cacheMode === "startup" ? "none" : "flex";
+  }
+}
+
+if (cacheModeSelect) {
+  cacheModeSelect.addEventListener("change", () => {
+    if (cacheDurationRow) {
+      cacheDurationRow.style.display = cacheModeSelect.value === "startup" ? "none" : "flex";
+    }
+  });
 }
 
 if (saveConnectionSettingsButton) {
   saveConnectionSettingsButton.addEventListener("click", async () => {
     const port = parseInt(apiPortInput?.value || "0", 10) || 0;
+    const cacheMode = cacheModeSelect?.value === "startup" ? "startup" : "duration";
     const cacheSeconds = parseInt(cacheDurationInput?.value || String(DEFAULT_CACHE_SECONDS_VALUE), 10) || DEFAULT_CACHE_SECONDS_VALUE;
     await chrome.storage.local.set({
       [API_STORAGE_KEYS.apiPort]: port,
+      [API_STORAGE_KEYS.apiCacheMode]: cacheMode,
       [API_STORAGE_KEYS.apiCacheSeconds]: cacheSeconds,
     });
     clearApiBaseUrlCache();

vscode-extension/package.json

@@ -108,6 +108,16 @@
           "maximum": 3600,
           "description": "%timelens.apiBaseUrlCacheSeconds.description%"
         },
+        "timelens.apiBaseUrlCacheMode": {
+          "type": "string",
+          "default": "duration",
+          "enum": ["duration", "startup"],
+          "enumDescriptions": [
+            "%timelens.apiBaseUrlCacheMode.duration%",
+            "%timelens.apiBaseUrlCacheMode.startup%"
+          ],
+          "description": "%timelens.apiBaseUrlCacheMode.description%"
+        },
         "timelens.bridgeKey": {
           "type": "string",
           "default": "",

vscode-extension/package.nls.json

@@ -3,6 +3,9 @@
   "timelens.enabled.description": "Enable local VS Code usage tracking for TimeLens.",
   "timelens.apiBaseUrl.description": "Local TimeLens API base URL.",
   "timelens.apiBaseUrlCacheSeconds.description": "How long to cache the discovered local API port (seconds). Set to 0 to re-discover on every request.",
+  "timelens.apiBaseUrlCacheMode.description": "Cache discovered port until VS Code restarts, or for a fixed duration.",
+  "timelens.apiBaseUrlCacheMode.duration": "Cache for the duration configured below.",
+  "timelens.apiBaseUrlCacheMode.startup": "Cache until VS Code restarts.",
   "timelens.bridgeKey.description": "Extension bridge key for authenticating with TimeLens local API. Get this from Settings > Local API / Extension Bridge.",
   "timelens.apiToken.description": "Local API token for authenticating with TimeLens when token-required mode is enabled. Get this from Settings > Local API / Tokens.",
   "timelens.flushIntervalSeconds.description": "How often to flush queued sessions to TimeLens API.",

vscode-extension/package.nls.zh-CN.json

@@ -3,6 +3,9 @@
   "timelens.enabled.description": "启用 TimeLens 本地 VS Code 使用时长追踪。",
   "timelens.apiBaseUrl.description": "TimeLens 本地 API 基础 URL。",
   "timelens.apiBaseUrlCacheSeconds.description": "缓存已发现本地 API 端口的时长（秒）。设为 0 则每次请求都重新发现。",
+  "timelens.apiBaseUrlCacheMode.description": "缓存已发现端口直到 VS Code 重启，或按下方固定时长缓存。",
+  "timelens.apiBaseUrlCacheMode.duration": "按下方配置时长缓存。",
+  "timelens.apiBaseUrlCacheMode.startup": "缓存到 VS Code 重启。",
   "timelens.bridgeKey.description": "用于向 TimeLens 本地 API 认证的扩展桥接密钥，可在「设置 > 本地 API / 扩展桥接」中获取。",
   "timelens.apiToken.description": "在启用「需要 API Token」模式时，用于向 TimeLens 本地 API 认证的令牌，可在「设置 > 本地 API / 令牌」中获取。",
   "timelens.flushIntervalSeconds.description": "将排队会话刷新到 TimeLens API 的频率（秒）。",