Skip to content

Commit f4a53c0

Browse files
committed
feat(admin): HTML dashboard for /admin/state + security hardening (#8 phase 1.5)
Dashboard (GET /admin — no auth on HTML shell, data via authed fetch): - per-account totals table (status, requests, success, 1005, 429, 401, tokens) with busyGlobal - per-model distribution table with share % (40-60% green per the 50/50 check) - poll-history drain-rate table (per bucket: latest remaining/used, samples, units/hour) - state-transition log (newest first, color-coded) - auto-refresh selector (5/10/30s/off); ?key= query param passes the proxy API key for browser access Security: - /admin/state compares keys with timingSafeEqual (constant-time, padded) - supports ?key= for browser flows; 401 never echoes header values - metrics models map capped at 50 keys per account (model strings are external input — a hostile client could invent thousands) Counting semantics documented in code: 'requests' counts DISPATCHES (a failover request counts once per serving account) — the right unit for distribution analysis.
1 parent 11eae25 commit f4a53c0

4 files changed

Lines changed: 172 additions & 4 deletions

File tree

‎src/server/admin-html.ts‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
/** Self-contained HTML dashboard for /admin/state (no build step, no deps). */
2+
export const ADMIN_DASHBOARD_HTML = `<!DOCTYPE html>
3+
<html lang="vi">
4+
<head>
5+
<meta charset="utf-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1">
7+
<title>zcode-proxy — pool dashboard</title>
8+
<style>
9+
:root { color-scheme: dark; }
10+
body { font-family: ui-monospace, Menlo, Consolas, monospace; background: #0d1117; color: #e6edf3; margin: 20px; }
11+
h1 { font-size: 18px; } h2 { font-size: 14px; color: #8b949e; margin-top: 24px; }
12+
.meta { color: #8b949e; font-size: 12px; }
13+
table { border-collapse: collapse; width: 100%; margin-top: 8px; font-size: 13px; }
14+
th, td { border: 1px solid #30363d; padding: 6px 10px; text-align: right; }
15+
th:first-child, td:first-child { text-align: left; }
16+
th { background: #161b22; color: #8b949e; }
17+
.ok { color: #3fb950; } .warn { color: #d29922; } .bad { color: #f85149; }
18+
.refresh { font-size: 12px; color: #8b949e; margin-top: 4px; }
19+
select { background: #161b22; color: #e6edf3; border: 1px solid #30363d; padding: 4px; font-family: inherit; }
20+
#transitions { font-size: 12px; max-height: 260px; overflow-y: auto; }
21+
#transitions div { padding: 2px 0; border-bottom: 1px solid #21262d; }
22+
</style>
23+
</head>
24+
<body>
25+
<h1>zcode-proxy — pool dashboard</h1>
26+
<div class="meta">Đếm trong RAM — reset khi restart proxy. Tokens = usage từ response (nếu có).</div>
27+
<div class="refresh">Auto-refresh:
28+
<select id="interval" onchange="setInterval_()">
29+
<option value="5">5s</option>
30+
<option value="10" selected>10s</option>
31+
<option value="30">30s</option>
32+
<option value="0">off</option>
33+
</select>
34+
<span id="updated"></span>
35+
</div>
36+
37+
<h2>Tài khoản — tổng theo acc</h2>
38+
<table id="accounts"></table>
39+
40+
<h2>Phân phối theo model (per acc)</h2>
41+
<table id="models"></table>
42+
43+
<h2>Tốc độ trừ quota (poll history — gần nhất first)</h2>
44+
<table id="polls"></table>
45+
46+
<h2>Chuyển trạng thái (50 dòng gần nhất)</h2>
47+
<div id="transitions"></div>
48+
49+
<script>
50+
let timer = null;
51+
function setInterval_() {
52+
const v = Number(document.getElementById("interval").value);
53+
if (timer) clearInterval(timer);
54+
if (v > 0) { timer = setInterval(load, v * 1000); load(); }
55+
}
56+
async function load() {
57+
try {
58+
const resp = await fetch("/admin/state" + (urlKey ? "?key=" + encodeURIComponent(urlKey) : ""));
59+
if (resp.status === 401) { document.body.innerHTML = "<h1>401 — cần proxy API key</h1><div>Cấu hình auth trong browser không hỗ trợ header tùy chỉnh — dùng curl hoặc thêm ?key=</div>"; return; }
60+
const d = await resp.json();
61+
render(d);
62+
document.getElementById("updated").textContent = " · cập nhật " + new Date().toLocaleTimeString();
63+
} catch (e) {
64+
document.getElementById("updated").textContent = " · lỗi: " + e.message;
65+
}
66+
}
67+
function fmt(n) { return n === undefined ? "—" : Number(n).toLocaleString("vi-VN"); }
68+
function esc(s) { const d = document.createElement("div"); d.textContent = String(s); return d.innerHTML; }
69+
70+
function render(d) {
71+
// Accounts table
72+
let h = "<tr><th>acc</th><th>status</th><th>requests</th><th>success</th><th>1005</th><th>429</th><th>401</th><th>tokens</th></tr>";
73+
for (const a of d.accounts) {
74+
const t = a.totals;
75+
const cls = t.quota1005 > 0 ? "warn" : "ok";
76+
h += "<tr><td>" + esc(a.label || a.id.slice(0, 8)) + "</td><td class='" + cls + "'>" + esc(a.status) + "</td><td>" + fmt(t.requests) + "</td><td>" + fmt(t.success) + "</td><td>" + fmt(t.quota1005) + "</td><td>" + fmt(t.rate429) + "</td><td>" + fmt(t.auth401) + "</td><td>" + fmt(t.tokensUsed) + "</td></tr>";
77+
}
78+
h += "<tr><td><b>busyGlobal</b></td><td colspan='7'>" + fmt(d.busyGlobal) + " (429 từ chính proxy — queue/cap)</td></tr>";
79+
document.getElementById("accounts").innerHTML = h;
80+
81+
// Per-model distribution + share %
82+
h = "<tr><th>acc</th><th>model</th><th>requests</th><th>% phân phối</th><th>success</th><th>1005</th><th>429</th><th>Retry-After cuối</th><th>tokens</th></tr>";
83+
const totalsByModel = {};
84+
for (const a of d.accounts) for (const [k, c] of Object.entries(a.models)) totalsByModel[k] = (totalsByModel[k] ?? 0) + c.requests;
85+
for (const a of d.accounts) {
86+
for (const [k, c] of Object.entries(a.models)) {
87+
const share = totalsByModel[k] > 0 ? Math.round(c.requests / totalsByModel[k] * 100) : 0;
88+
const shareCls = share >= 40 && share <= 60 ? "ok" : share >= 25 ? "warn" : "bad";
89+
h += "<tr><td>" + esc(a.label || a.id.slice(0, 8)) + "</td><td>" + esc(k) + "</td><td>" + fmt(c.requests) + "</td><td class='" + shareCls + "'>" + share + "%</td><td>" + fmt(c.success) + "</td><td>" + fmt(c.quota1005) + "</td><td>" + fmt(c.rate429) + "</td><td>" + fmt(c.lastRetryAfterSec) + "s</td><td>" + fmt(c.tokensUsed) + "</td></tr>";
90+
}
91+
}
92+
document.getElementById("models").innerHTML = h || "<tr><td>chưa có data</td></tr>";
93+
94+
// Poll history: drain rate per bucket (latest vs oldest in window)
95+
h = "<tr><th>acc</th><th>bucket</th><th>remaining (mới nhất)</th><th>used (mới nhất)</th><th>điểm</th><th>tốc độ trừ</th></tr>";
96+
for (const [acc, samples] of Object.entries(d.pollHistory)) {
97+
const byModel = {};
98+
for (const s of samples) (byModel[s.model] ??= []).push(s);
99+
for (const [model, list] of Object.entries(byModel)) {
100+
if (list.length < 2) { h += "<tr><td>" + esc(acc.slice(0, 8)) + "</td><td>" + esc(model) + "</td><td>" + fmt(list[0].remainingUnits) + "</td><td>" + fmt(list[0].usedUnits) + "</td><td>" + list.length + "</td><td>— (cần ≥2 điểm)</td></tr>"; continue; }
101+
const newest = list[list.length - 1], oldest = list[0];
102+
const dtH = (newest.at - oldest.at) / 3600000;
103+
const dUsed = (newest.usedUnits ?? 0) - (oldest.usedUnits ?? 0);
104+
const rate = dtH > 0 ? Math.round(dUsed / dtH).toLocaleString("vi-VN") + "/h" : "—";
105+
h += "<tr><td>" + esc(acc.slice(0, 8)) + "</td><td>" + esc(model) + "</td><td>" + fmt(newest.remainingUnits) + "</td><td>" + fmt(newest.usedUnits) + "</td><td>" + list.length + "</td><td>" + rate + "</td></tr>";
106+
}
107+
}
108+
document.getElementById("polls").innerHTML = h || "<tr><td>chưa có data</td></tr>";
109+
110+
// Transitions
111+
let t = "";
112+
for (const tr of [...d.transitions].reverse()) {
113+
const cls = tr.to === "healthy" ? "ok" : tr.to === "exhausted" || tr.to === "expired" ? "bad" : "warn";
114+
t += "<div><span class='meta'>" + new Date(tr.at).toLocaleTimeString() + "</span> " + esc(tr.accountId.slice(0, 8)) + " <span class='" + cls + "'>" + esc(tr.from) + " → " + esc(tr.to) + "</span> <span class='meta'>" + esc(tr.reason) + "</span></div>";
115+
}
116+
document.getElementById("transitions").innerHTML = t || "<div>chưa có</div>";
117+
}
118+
119+
// Optional key via query param (?key=...) for browser access without header support:
120+
const urlKey = new URLSearchParams(location.search).get("key");
121+
setInterval_();
122+
load();
123+
</script>
124+
</body>
125+
</html>`;

‎src/server/metrics.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,24 @@ export class MetricsRegistry {
7171
return m;
7272
}
7373

74+
/** Bounded model-key set — model comes from requests (external input);
75+
* a hostile client could invent thousands of distinct model strings. */
76+
private static MAX_MODEL_KEYS = 50;
77+
7478
/** Record one proxied request for (account, requested model). */
7579
recordRequest(accountId: string, model: string, label?: string): void {
7680
const m = this.account(accountId, label);
7781
m.totals.requests++;
7882
const key = model || "unknown";
83+
if (!m.models[key] && Object.keys(m.models).length >= MetricsRegistry.MAX_MODEL_KEYS) {
84+
// Over cap: attribute to "unknown" instead of growing unbounded.
85+
m.models.unknown ??= emptyCounters();
86+
m.models.unknown.requests++;
87+
const hour = new Date().toISOString().slice(0, 13);
88+
m.hourly[hour] = (m.hourly[hour] ?? 0) + 1;
89+
this.pruneHourly(m);
90+
return;
91+
}
7992
m.models[key] ??= emptyCounters();
8093
m.models[key].requests++;
8194
const hour = new Date().toISOString().slice(0, 13);

‎src/server/routes-admin.ts‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,37 @@
55
*/
66
import { metricsRegistry } from "./metrics.js";
77
import { errorResponse } from "../proxy/handler.js";
8+
import { timingSafeEqual } from "node:crypto";
89

910
export interface AdminRouteOptions {
1011
proxyApiKey?: string;
1112
}
1213

14+
/** Constant-time string compare (padded to equal length to avoid length leaks). */
15+
function keyMatches(provided: string, expected: string): boolean {
16+
const a = Buffer.from(provided);
17+
const b = Buffer.from(expected);
18+
if (a.length !== b.length) {
19+
// Still burn a compare to keep timing uniform, then fail.
20+
timingSafeEqual(b, b);
21+
return false;
22+
}
23+
return timingSafeEqual(a, b);
24+
}
25+
1326
export function handleAdminState(req: Request, opts: AdminRouteOptions): Response {
14-
// Same auth model as /v1/* — the proxy API key. Accept either header.
27+
// Same auth model as /v1/* — the proxy API key. Accept either header, or
28+
// ?key= (the HTML dashboard's fetch passes it — browsers can't set custom
29+
// headers on cross-page navigation). Constant-time compare; the 401
30+
// response NEVER echoes the header values.
31+
const queryKey = new URL(req.url).searchParams.get("key");
1532
if (opts.proxyApiKey) {
16-
const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
17-
const xKey = req.headers.get("x-api-key");
18-
if (bearer !== opts.proxyApiKey && xKey !== opts.proxyApiKey) {
33+
const bearer = req.headers.get("authorization")?.replace(/^Bearer\s+/i, "") ?? null;
34+
const xKey = req.headers.get("x-api-key") ?? null;
35+
const ok = (bearer !== null && keyMatches(bearer, opts.proxyApiKey))
36+
|| (xKey !== null && keyMatches(xKey, opts.proxyApiKey))
37+
|| (queryKey !== null && keyMatches(queryKey, opts.proxyApiKey));
38+
if (!ok) {
1939
return errorResponse(401, "authentication_error", "Invalid or missing proxy API key");
2040
}
2141
}

‎src/server/server.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ import { handleAsyncMessagesRoute, handleAsyncChatRoute, handleAsyncHealthRoute
1919
import { handleMcpRoute, type McpRouteOptions } from "./routes-mcp.js";
2020
import { handleQuota } from "./routes-quota.js";
2121
import { handleAdminState } from "./routes-admin.js";
22+
import { ADMIN_DASHBOARD_HTML } from "./admin-html.js";
2223
import { errorResponse } from "../proxy/handler.js";
2324
import type { ResponseStore } from "../responses/store.js";
2425

@@ -118,6 +119,15 @@ export function createFetchHandler(opts: ServerOptions): (req: Request) => Promi
118119
return handleAdminState(req, { proxyApiKey: config.auth.proxyApiKey });
119120
}
120121

122+
if (path === "/admin" && method === "GET") {
123+
// HTML dashboard. Read-only; the fetch inside passes ?key= as x-api-key
124+
// when the browser cannot set headers. Binds loopback by default.
125+
return new Response(ADMIN_DASHBOARD_HTML, {
126+
status: 200,
127+
headers: { "content-type": "text/html; charset=utf-8" },
128+
});
129+
}
130+
121131
if (path === "/v1/messages" && method === "POST") {
122132
return handleMessages(req, proxyOpts);
123133
}

0 commit comments

Comments
 (0)