feat: add Test Connection diagnostic button (#63)

* feat: add Test Connection diagnostic button (#61)

Add a "Test Connection" button to the Dashboard that runs 4 sequential
checks (Server, Accounts, Transport, Upstream) and displays pass/fail/skip
results with latency — helps Electron users diagnose connectivity issues
without access to console logs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use socket address for localhost check, static import for buildHeaders

- Replace spoofable x-forwarded-for/x-real-ip with getConnInfo() socket address
for /debug/fingerprint and /debug/diagnostics endpoints
- Add ::ffff:127.0.0.1 match for IPv4-mapped IPv6 addresses
- Change dynamic import() of buildHeaders to static import

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

shared/hooks/use-test-connection.ts

@@ -0,0 +1,29 @@
+import { useState, useCallback } from "preact/hooks";
+import type { TestConnectionResult } from "../types.js";
+
+export function useTestConnection() {
+  const [testing, setTesting] = useState(false);
+  const [result, setResult] = useState<TestConnectionResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const runTest = useCallback(async () => {
+    setTesting(true);
+    setError(null);
+    setResult(null);
+    try {
+      const resp = await fetch("/admin/test-connection", { method: "POST" });
+      if (!resp.ok) {
+        setError(`HTTP ${resp.status}`);
+        return;
+      }
+      const data = (await resp.json()) as TestConnectionResult;
+      setResult(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Network error");
+    } finally {
+      setTesting(false);
+    }
+  }, []);
+
+  return { testing, result, error, runTest };
+}

shared/i18n/translations.ts

@@ -157,6 +157,17 @@ export const translations = {
     apiKeyLabel: "API Key",
     apiKeySaved: "Saved",
     apiKeyClear: "Clear key (disable auth)",
+    testConnection: "Test Connection",
+    testing: "Testing...",
+    testPassed: "All checks passed",
+    testFailed: "Some checks failed",
+    checkServer: "Server",
+    checkAccounts: "Accounts",
+    checkTransport: "Transport",
+    checkUpstream: "Upstream",
+    statusPass: "Pass",
+    statusFail: "Fail",
+    statusSkip: "Skip",
   },
   zh: {
     serverOnline: "\u670d\u52a1\u8fd0\u884c\u4e2d",
@@ -319,6 +330,17 @@ export const translations = {
     apiKeyLabel: "API \u5bc6\u94a5",
     apiKeySaved: "\u5df2\u4fdd\u5b58",
     apiKeyClear: "\u6e05\u9664\u5bc6\u94a5\uff08\u5173\u95ed\u9274\u6743\uff09",
+    testConnection: "\u8fde\u63a5\u6d4b\u8bd5",
+    testing: "\u6d4b\u8bd5\u4e2d...",
+    testPassed: "\u6240\u6709\u68c0\u67e5\u5747\u901a\u8fc7",
+    testFailed: "\u90e8\u5206\u68c0\u67e5\u672a\u901a\u8fc7",
+    checkServer: "\u670d\u52a1\u5668",
+    checkAccounts: "\u8d26\u6237",
+    checkTransport: "\u4f20\u8f93\u5c42",
+    checkUpstream: "\u4e0a\u6e38\u670d\u52a1",
+    statusPass: "\u901a\u8fc7",
+    statusFail: "\u5931\u8d25",
+    statusSkip: "\u8df3\u8fc7",
   },
 } as const;
 

shared/types.ts

@@ -45,3 +45,19 @@ export interface ProxyAssignment {
   accountId: string;
   proxyId: string;
 }
+
+export type DiagnosticStatus = "pass" | "fail" | "skip";
+
+export interface DiagnosticCheck {
+  name: string;
+  status: DiagnosticStatus;
+  latencyMs: number;
+  detail: string | null;
+  error: string | null;
+}
+
+export interface TestConnectionResult {
+  checks: DiagnosticCheck[];
+  overall: DiagnosticStatus;
+  timestamp: string;
+}

src/auth/account-pool.ts

@@ -210,6 +210,13 @@ export class AccountPool {
     this.schedulePersist();
   }
 
+  /**
+   * Release an account without counting usage (for diagnostics).
+   */
+  releaseWithoutCounting(entryId: string): void {
+    this.acquireLocks.delete(entryId);
+  }
+
   /**
    * Mark an account as rate-limited after a 429.
    * P1-6: countRequest option to track 429s as usage without exposing entry internals.

src/routes/web.ts

@@ -1,10 +1,14 @@
 import { Hono } from "hono";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { getConnInfo } from "@hono/node-server/conninfo";
 import { readFileSync, existsSync } from "fs";
 import { resolve } from "path";
 import type { AccountPool } from "../auth/account-pool.js";
 import { getConfig, getFingerprint, reloadAllConfigs } from "../config.js";
-import { getPublicDir, getDesktopPublicDir, getConfigDir, getDataDir, isEmbedded } from "../paths.js";
+import { getPublicDir, getDesktopPublicDir, getConfigDir, getDataDir, getBinDir, isEmbedded } from "../paths.js";
+import { getTransport, getTransportInfo } from "../tls/transport.js";
+import { getCurlDiagnostics } from "../tls/curl-binary.js";
+import { buildHeaders } from "../fingerprint/manager.js";
 import { getUpdateState, checkForUpdate, isUpdateInProgress } from "../update-checker.js";
 import { getProxyInfo, canSelfUpdate, checkProxySelfUpdate, applyProxySelfUpdate, isProxyUpdateInProgress, getCachedProxyUpdateResult, getDeployMode } from "../self-update.js";
 import { mutateYaml } from "../utils/yaml-mutate.js";
@@ -62,8 +66,8 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
   app.get("/debug/fingerprint", (c) => {
     // Only allow in development or from localhost
     const isProduction = process.env.NODE_ENV === "production";
-    const remoteAddr = c.req.header("x-forwarded-for") ?? c.req.header("x-real-ip") ?? "";
-    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1";
+    const remoteAddr = getConnInfo(c).remote.address ?? "";
+    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
     if (isProduction && !isLocalhost) {
       c.status(404);
       return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
@@ -123,6 +127,52 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
     });
   });
 
+  app.get("/debug/diagnostics", (c) => {
+    const remoteAddr = getConnInfo(c).remote.address ?? "";
+    const isLocalhost = remoteAddr === "" || remoteAddr === "127.0.0.1" || remoteAddr === "::1" || remoteAddr === "::ffff:127.0.0.1";
+    if (process.env.NODE_ENV === "production" && !isLocalhost) {
+      c.status(404);
+      return c.json({ error: { message: "Not found", type: "invalid_request_error" } });
+    }
+
+    const transport = getTransportInfo();
+    const curl = getCurlDiagnostics();
+    const poolSummary = accountPool.getPoolSummary();
+    const caCertPath = resolve(getBinDir(), "cacert.pem");
+
+    return c.json({
+      transport: {
+        type: transport.type,
+        initialized: transport.initialized,
+        impersonate: transport.impersonate,
+        ffi_error: transport.ffi_error,
+      },
+      curl: {
+        binary: curl.binary,
+        is_impersonate: curl.is_impersonate,
+        profile: curl.profile,
+      },
+      proxy: { url: curl.proxy_url },
+      ca_cert: { found: existsSync(caCertPath), path: caCertPath },
+      accounts: {
+        total: poolSummary.total,
+        active: poolSummary.active,
+        authenticated: accountPool.isAuthenticated(),
+      },
+      paths: {
+        bin: getBinDir(),
+        config: getConfigDir(),
+        data: getDataDir(),
+      },
+      runtime: {
+        platform: process.platform,
+        arch: process.arch,
+        node_version: process.version,
+        embedded: isEmbedded(),
+      },
+    });
+  });
+
   // --- Update management endpoints ---
 
   app.get("/admin/update-status", (c) => {
@@ -231,6 +281,129 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
     return c.json(result);
   });
 
+  // --- Test connection endpoint ---
+
+  app.post("/admin/test-connection", async (c) => {
+    type DiagStatus = "pass" | "fail" | "skip";
+    interface DiagCheck { name: string; status: DiagStatus; latencyMs: number; detail: string | null; error: string | null; }
+    const checks: DiagCheck[] = [];
+    let overallFailed = false;
+
+    // 1. Server check — if we're responding, it's a pass
+    const serverStart = Date.now();
+    checks.push({
+      name: "server",
+      status: "pass",
+      latencyMs: Date.now() - serverStart,
+      detail: `PID ${process.pid}`,
+      error: null,
+    });
+
+    // 2. Accounts check — any authenticated accounts?
+    const accountsStart = Date.now();
+    const poolSummary = accountPool.getPoolSummary();
+    const hasActive = poolSummary.active > 0;
+    checks.push({
+      name: "accounts",
+      status: hasActive ? "pass" : "fail",
+      latencyMs: Date.now() - accountsStart,
+      detail: hasActive
+        ? `${poolSummary.active} active / ${poolSummary.total} total`
+        : `0 active / ${poolSummary.total} total`,
+      error: hasActive ? null : "No active accounts",
+    });
+    if (!hasActive) overallFailed = true;
+
+    // 3. Transport check — TLS transport initialized?
+    const transportStart = Date.now();
+    const transportInfo = getTransportInfo();
+    const caCertPath = resolve(getBinDir(), "cacert.pem");
+    const caCertExists = existsSync(caCertPath);
+    const transportOk = transportInfo.initialized;
+    checks.push({
+      name: "transport",
+      status: transportOk ? "pass" : "fail",
+      latencyMs: Date.now() - transportStart,
+      detail: transportOk
+        ? `${transportInfo.type}, impersonate=${transportInfo.impersonate}, ca_cert=${caCertExists}`
+        : null,
+      error: transportOk
+        ? (transportInfo.ffi_error ? `FFI fallback: ${transportInfo.ffi_error}` : null)
+        : (transportInfo.ffi_error ?? "Transport not initialized"),
+    });
+    if (!transportOk) overallFailed = true;
+
+    // 4. Upstream check — can we reach chatgpt.com?
+    if (!hasActive) {
+      // Skip upstream if no accounts
+      checks.push({
+        name: "upstream",
+        status: "skip",
+        latencyMs: 0,
+        detail: "Skipped (no active accounts)",
+        error: null,
+      });
+    } else {
+      const upstreamStart = Date.now();
+      const acquired = accountPool.acquire();
+      if (!acquired) {
+        checks.push({
+          name: "upstream",
+          status: "fail",
+          latencyMs: Date.now() - upstreamStart,
+          detail: null,
+          error: "Could not acquire account for test",
+        });
+        overallFailed = true;
+      } else {
+        try {
+          const transport = getTransport();
+          const config = getConfig();
+          const url = `${config.api.base_url}/codex/usage`;
+          const headers = buildHeaders(acquired.token, acquired.accountId);
+          const resp = await transport.get(url, headers, 15);
+          const latency = Date.now() - upstreamStart;
+          if (resp.status >= 200 && resp.status < 400) {
+            checks.push({
+              name: "upstream",
+              status: "pass",
+              latencyMs: latency,
+              detail: `HTTP ${resp.status} (${latency}ms)`,
+              error: null,
+            });
+          } else {
+            checks.push({
+              name: "upstream",
+              status: "fail",
+              latencyMs: latency,
+              detail: `HTTP ${resp.status}`,
+              error: `Upstream returned ${resp.status}`,
+            });
+            overallFailed = true;
+          }
+        } catch (err) {
+          const latency = Date.now() - upstreamStart;
+          checks.push({
+            name: "upstream",
+            status: "fail",
+            latencyMs: latency,
+            detail: null,
+            error: err instanceof Error ? err.message : String(err),
+          });
+          overallFailed = true;
+        } finally {
+          accountPool.releaseWithoutCounting(acquired.entryId);
+        }
+      }
+    }
+
+    return c.json({
+      checks,
+      overall: overallFailed ? "fail" as const : "pass" as const,
+      timestamp: new Date().toISOString(),
+    });
+  });
+
   // --- Settings endpoints ---
 
   app.get("/admin/settings", (c) => {

src/tls/curl-binary.ts

@@ -287,6 +287,23 @@ export function getProxyUrl(): string | null {
   return _proxyUrl ?? null;
 }
 
+/**
+ * Get curl diagnostic info for /debug/diagnostics endpoint.
+ */
+export function getCurlDiagnostics(): {
+  binary: string | null;
+  is_impersonate: boolean;
+  profile: string;
+  proxy_url: string | null;
+} {
+  return {
+    binary: _resolved,
+    is_impersonate: _isImpersonate,
+    profile: _resolvedProfile,
+    proxy_url: _proxyUrl ?? null,
+  };
+}
+
 /**
  * Reset the cached binary path (useful for testing).
  */

src/tls/transport.ts

@@ -58,6 +58,8 @@ export interface TlsTransport {
 }
 
 let _transport: TlsTransport | null = null;
+let _transportType: "libcurl-ffi" | "curl-cli" | "none" = "none";
+let _ffiError: string | null = null;
 
 /**
  * Initialize the transport singleton. Must be called once at startup
@@ -74,6 +76,7 @@ export async function initTransport(): Promise<TlsTransport> {
     try {
       const { createLibcurlFfiTransport } = await import("./libcurl-ffi-transport.js");
       _transport = await createLibcurlFfiTransport();
+      _transportType = "libcurl-ffi";
       console.log("[TLS] Using libcurl-impersonate FFI transport");
       return _transport;
     } catch (err) {
@@ -81,12 +84,14 @@ export async function initTransport(): Promise<TlsTransport> {
       if (setting === "libcurl-ffi") {
         throw new Error(`Failed to initialize libcurl FFI transport: ${msg}`);
       }
+      _ffiError = msg;
       console.warn(`[TLS] FFI transport unavailable (${msg}), falling back to curl CLI`);
     }
   }
 
   const { CurlCliTransport } = await import("./curl-cli-transport.js");
   _transport = new CurlCliTransport();
+  _transportType = "curl-cli";
   console.log("[TLS] Using curl CLI transport");
   return _transport;
 }
@@ -111,7 +116,24 @@ function shouldUseFfi(): boolean {
   return existsSync(dllPath);
 }
 
+/** Get transport diagnostic info. */
+export function getTransportInfo(): {
+  type: "libcurl-ffi" | "curl-cli" | "none";
+  initialized: boolean;
+  impersonate: boolean;
+  ffi_error: string | null;
+} {
+  return {
+    type: _transportType,
+    initialized: _transport !== null,
+    impersonate: _transport?.isImpersonate() ?? false,
+    ffi_error: _ffiError,
+  };
+}
+
 /** Reset transport singleton (for testing). */
 export function resetTransport(): void {
   _transport = null;
+  _transportType = "none";
+  _ffiError = null;
 }

web/src/App.tsx

@@ -10,6 +10,7 @@ import { ApiConfig } from "./components/ApiConfig";
 import { AnthropicSetup } from "./components/AnthropicSetup";
 import { CodeExamples } from "./components/CodeExamples";
 import { SettingsPanel } from "./components/SettingsPanel";
+import { TestConnection } from "./components/TestConnection";
 import { Footer } from "./components/Footer";
 import { ProxySettings } from "./pages/ProxySettings";
 import { useAccounts } from "../../shared/hooks/use-accounts";
@@ -144,6 +145,7 @@ function Dashboard() {
             serviceTier={status.selectedSpeed}
           />
           <SettingsPanel />
+          <TestConnection />
         </div>
       </main>
       <Footer updateStatus={update.status} />

web/src/components/TestConnection.tsx

@@ -0,0 +1,145 @@
+import { useState } from "preact/hooks";
+import { useT } from "../../../shared/i18n/context";
+import { useTestConnection } from "../../../shared/hooks/use-test-connection";
+import type { DiagnosticCheck, DiagnosticStatus } from "../../../shared/types";
+
+const STATUS_COLORS: Record<DiagnosticStatus, string> = {
+  pass: "text-green-600 dark:text-green-400",
+  fail: "text-red-500 dark:text-red-400",
+  skip: "text-slate-400 dark:text-text-dim",
+};
+
+const STATUS_BG: Record<DiagnosticStatus, string> = {
+  pass: "bg-green-50 dark:bg-green-900/20 border-green-200 dark:border-green-800",
+  fail: "bg-red-50 dark:bg-red-900/20 border-red-200 dark:border-red-800",
+  skip: "bg-slate-50 dark:bg-[#161b22] border-slate-200 dark:border-border-dark",
+};
+
+const CHECK_NAME_KEYS: Record<string, string> = {
+  server: "checkServer",
+  accounts: "checkAccounts",
+  transport: "checkTransport",
+  upstream: "checkUpstream",
+};
+
+const STATUS_KEYS: Record<DiagnosticStatus, string> = {
+  pass: "statusPass",
+  fail: "statusFail",
+  skip: "statusSkip",
+};
+
+function StatusIcon({ status }: { status: DiagnosticStatus }) {
+  if (status === "pass") {
+    return (
+      <svg class="size-5 text-green-600 dark:text-green-400 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+    );
+  }
+  if (status === "fail") {
+    return (
+      <svg class="size-5 text-red-500 dark:text-red-400 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M9.75 9.75l4.5 4.5m0-4.5l-4.5 4.5M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+    );
+  }
+  return (
+    <svg class="size-5 text-slate-400 dark:text-text-dim shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M15 12H9m12 0a9 9 0 11-18 0 9 9 0 0118 0z" />
+    </svg>
+  );
+}
+
+function CheckRow({ check }: { check: DiagnosticCheck }) {
+  const t = useT();
+  const nameKey = CHECK_NAME_KEYS[check.name] ?? check.name;
+  const statusKey = STATUS_KEYS[check.status];
+
+  return (
+    <div class={`flex items-start gap-3 p-3 rounded-lg border ${STATUS_BG[check.status]}`}>
+      <StatusIcon status={check.status} />
+      <div class="flex-1 min-w-0">
+        <div class="flex items-center gap-2">
+          <span class="text-sm font-semibold text-slate-700 dark:text-text-main">
+            {t(nameKey as Parameters<typeof t>[0])}
+          </span>
+          <span class={`text-xs font-medium ${STATUS_COLORS[check.status]}`}>
+            {t(statusKey as Parameters<typeof t>[0])}
+          </span>
+          {check.latencyMs > 0 && (
+            <span class="text-xs text-slate-400 dark:text-text-dim">{check.latencyMs}ms</span>
+          )}
+        </div>
+        {check.detail && (
+          <p class="text-xs text-slate-500 dark:text-text-dim mt-0.5 break-all">{check.detail}</p>
+        )}
+        {check.error && (
+          <p class="text-xs text-red-500 dark:text-red-400 mt-0.5 break-all">{check.error}</p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export function TestConnection() {
+  const t = useT();
+  const { testing, result, error, runTest } = useTestConnection();
+  const [collapsed, setCollapsed] = useState(true);
+
+  return (
+    <section class="bg-white dark:bg-card-dark border border-gray-200 dark:border-border-dark rounded-xl shadow-sm transition-colors">
+      {/* Header */}
+      <button
+        onClick={() => setCollapsed(!collapsed)}
+        class="w-full flex items-center justify-between p-5 cursor-pointer select-none"
+      >
+        <div class="flex items-center gap-2">
+          <svg class="size-5 text-primary" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M9.75 3.104v5.714a2.25 2.25 0 01-.659 1.591L5 14.5M9.75 3.104c-.251.023-.501.05-.75.082m.75-.082a24.301 24.301 0 014.5 0m0 0v5.714c0 .597.237 1.17.659 1.591L19.8 15.3M14.25 3.104c.251.023.501.05.75.082M19.8 15.3l-1.57.393A9.065 9.065 0 0112 15a9.065 9.065 0 00-6.23.693L5 14.5m14.8.8l1.402 1.402c1.232 1.232.65 3.318-1.067 3.611A48.309 48.309 0 0112 21c-2.773 0-5.491-.235-8.135-.687-1.718-.293-2.3-2.379-1.067-3.61L5 14.5" />
+          </svg>
+          <h2 class="text-[0.95rem] font-bold">{t("testConnection")}</h2>
+          {result && !collapsed && (
+            <span class={`text-xs font-medium ml-1 ${result.overall === "pass" ? "text-green-600 dark:text-green-400" : "text-red-500 dark:text-red-400"}`}>
+              {result.overall === "pass" ? t("testPassed") : t("testFailed")}
+            </span>
+          )}
+        </div>
+        <svg class={`size-5 text-slate-400 dark:text-text-dim transition-transform ${collapsed ? "" : "rotate-180"}`} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 8.25l-7.5 7.5-7.5-7.5" />
+        </svg>
+      </button>
+
+      {/* Content */}
+      {!collapsed && (
+        <div class="px-5 pb-5 border-t border-slate-100 dark:border-border-dark pt-4">
+          {/* Run test button */}
+          <button
+            onClick={runTest}
+            disabled={testing}
+            class={`w-full py-2.5 text-sm font-medium rounded-lg transition-colors ${
+              testing
+                ? "bg-slate-100 dark:bg-[#21262d] text-slate-400 dark:text-text-dim cursor-not-allowed"
+                : "bg-primary text-white hover:bg-primary/90 cursor-pointer"
+            }`}
+          >
+            {testing ? t("testing") : t("testConnection")}
+          </button>
+
+          {/* Error */}
+          {error && (
+            <p class="mt-3 text-sm text-red-500">{error}</p>
+          )}
+
+          {/* Results */}
+          {result && (
+            <div class="mt-4 space-y-2">
+              {result.checks.map((check) => (
+                <CheckRow key={check.name} check={check} />
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+    </section>
+  );
+}