omp-opencode-bridge 0.0.0-stage → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/proxy.ts ADDED
@@ -0,0 +1,1508 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * proxy.ts: runtime-configurable egress, single proxy or pool.
4
+ *
5
+ * Every outbound request this bridge makes (inference, model discovery, identity
6
+ * sync, self-update) can be routed through an HTTP/HTTPS proxy so upstream sees
7
+ * that proxy's IP instead of this host's. Two shapes are supported:
8
+ *
9
+ * - one proxy (`url`), the original behaviour, edited from the panel at `/`;
10
+ * - a pool of proxies, each with its own health state, so a single bridge can
11
+ * spread requests across many egress IPs and move off one that upstream has
12
+ * throttled.
13
+ *
14
+ * Why a pool matters here: the free-tier allowance is per egress IP, not per
15
+ * account. Running one bridge per host therefore multiplies the number of
16
+ * processes, service units and tunnels without adding anything a pool does not
17
+ * already give — the pool rotates the IP while the process, the identity and the
18
+ * model catalog stay in one place.
19
+ *
20
+ * Protocol: HTTP/HTTPS only. Bun's `fetch` accepts `proxy:` for those schemes and
21
+ * tunnels TLS through CONNECT, so the ClientHello still comes from Bun, and the
22
+ * transport-fingerprint baseline is unchanged. SOCKS5 is rejected by Bun with
23
+ * `UnsupportedProxyProtocol`, so it is refused here with a message that says so
24
+ * instead of failing later inside a request.
25
+ *
26
+ * Credentials live in `<state dir>/proxy.json` and never leave the process:
27
+ * `describe()` is the only view the HTTP panel and `/health` get, and it carries
28
+ * host:port only.
29
+ */
30
+
31
+ const crypto = require("crypto");
32
+ const fs = require("fs");
33
+ const os = require("os");
34
+ const path = require("path");
35
+
36
+ const CONFIG_FILE_NAME = "proxy.json";
37
+ const HEALTH_FILE_NAME = "pool-health.json";
38
+ const HEALTH_VERSION = 1;
39
+ const ENV_OVERRIDE = "UPSTREAM_PROXY_URL";
40
+ const POOL_ENV = "UPSTREAM_PROXY_POOL";
41
+ const STRATEGY_ENV = "UPSTREAM_PROXY_STRATEGY";
42
+
43
+ const STRATEGIES = new Set(["round-robin", "failover", "random", "priority-failover"]);
44
+ const DEFAULT_STRATEGY = "round-robin";
45
+ const DEFAULT_COOLDOWN_MS = 120000;
46
+ const DEFAULT_MAX_COOLDOWN_MS = 1800000;
47
+
48
+ interface ProxyUrlResult {
49
+ ok: boolean;
50
+ url?: string;
51
+ error?: string;
52
+ }
53
+
54
+ /** One pool entry as stored in proxy.json (credentials included). */
55
+ interface PoolEntry {
56
+ id: string;
57
+ label: string;
58
+ url: string;
59
+ direct: boolean;
60
+ enabled: boolean;
61
+ weight: number;
62
+ meter: boolean;
63
+ }
64
+
65
+ /** Loose shape accepted from config/env before validation. */
66
+ interface PoolEntryInput {
67
+ id?: unknown;
68
+ label?: unknown;
69
+ url?: unknown;
70
+ direct?: boolean;
71
+ enabled?: unknown;
72
+ weight?: unknown;
73
+ meter?: unknown;
74
+ }
75
+
76
+ interface PoolEntryResult {
77
+ ok: boolean;
78
+ entry?: PoolEntry;
79
+ error?: string;
80
+ }
81
+
82
+ interface PoolSpec {
83
+ entries: PoolEntry[];
84
+ errors: string[];
85
+ }
86
+
87
+ /** Payload accepted by `setPool`. */
88
+ interface PoolSpecInput {
89
+ entries?: unknown[];
90
+ strategy?: unknown;
91
+ cooldownMs?: unknown;
92
+ maxCooldownMs?: unknown;
93
+ }
94
+
95
+ /** Single-proxy state: the URL in force, where it came from, why it was refused. */
96
+ interface ProxyState {
97
+ url: string;
98
+ source: string;
99
+ error: string | null;
100
+ }
101
+
102
+ interface PoolState {
103
+ entries: PoolEntry[];
104
+ errors: string[];
105
+ strategy: string;
106
+ source: string;
107
+ error: string | null;
108
+ }
109
+
110
+ interface CooldownConfig {
111
+ baseMs: number;
112
+ maxMs: number;
113
+ }
114
+
115
+ /** Runtime observation for one egress; keyed by `keyOf()`, not by URL alone. */
116
+ interface HealthRecord {
117
+ failures: number;
118
+ cooldownUntil: number;
119
+ lastError: string | null;
120
+ lastOkAt: number;
121
+ lastUsedAt: number;
122
+ lastStatus: string | null;
123
+ }
124
+
125
+ interface HealthSnapshotRecord {
126
+ id: string;
127
+ label: string | null;
128
+ failures: number;
129
+ cooldownUntil: number;
130
+ lastError: string | null;
131
+ lastStatus: string | null;
132
+ lastOkAt: number | null;
133
+ lastUsedAt: number | null;
134
+ exitIp: string | null;
135
+ }
136
+
137
+ interface HealthSnapshot {
138
+ version: number;
139
+ savedAt: string;
140
+ entries: HealthSnapshotRecord[];
141
+ }
142
+
143
+ interface PickOptions {
144
+ exclude?: string | null;
145
+ now?: number;
146
+ }
147
+
148
+ /** The egress chosen for one request. */
149
+ interface PickResult {
150
+ url: string;
151
+ id: string | null;
152
+ label: string | null;
153
+ source: string;
154
+ cooling: boolean;
155
+ cooldownUntil?: number;
156
+ }
157
+
158
+ interface MarkFailureOptions {
159
+ reason?: string;
160
+ now?: number;
161
+ cooldownMs?: number | null;
162
+ }
163
+
164
+ interface NowOptions {
165
+ now?: number;
166
+ }
167
+
168
+ /** Per-egress traffic accounting for one day. */
169
+ interface UsageRecord {
170
+ requests: number;
171
+ okRequests: number;
172
+ requestBytes: number;
173
+ responseBytes: number;
174
+ promptTokens: number;
175
+ completionTokens: number;
176
+ }
177
+
178
+ interface UsageState {
179
+ day: string;
180
+ perEgress: Record<string, UsageRecord>;
181
+ }
182
+
183
+ interface UsageView {
184
+ day: string;
185
+ perEgress: Record<string, Record<string, unknown>>;
186
+ }
187
+
188
+ interface EntryDescription {
189
+ id: string;
190
+ label: string;
191
+ host: string | null;
192
+ enabled: boolean;
193
+ weight: number;
194
+ state: string;
195
+ cooldownMsLeft: number;
196
+ cooldownUntil: number;
197
+ failures: number;
198
+ lastError: string | null;
199
+ lastOkAt: number | null;
200
+ lastUsedAt: number | null;
201
+ }
202
+
203
+ interface PoolDescription {
204
+ active: boolean;
205
+ size: number;
206
+ enabled: number;
207
+ ready: number;
208
+ cooling: number;
209
+ strategy: string;
210
+ source: string;
211
+ cooldownMs: number;
212
+ maxCooldownMs: number;
213
+ error: string | null;
214
+ entries: EntryDescription[];
215
+ }
216
+
217
+ /** Public view handed to the panel and `/health`. */
218
+ interface ProxyDescription {
219
+ mode: string;
220
+ proxy: string | null;
221
+ hasCredentials: boolean;
222
+ source: string;
223
+ locked: boolean;
224
+ configPath: string;
225
+ error: string | null;
226
+ pool: PoolDescription;
227
+ }
228
+
229
+ interface ConfigResult {
230
+ ok: boolean;
231
+ error?: string;
232
+ }
233
+
234
+ /** A setter's verdict: refusal, or the whole new state. */
235
+ type SetResult = ConfigResult & Partial<ProxyDescription>;
236
+
237
+ /** A fetch init as callers pass it; Bun adds `proxy` for the egress. */
238
+ interface FetchInit {
239
+ proxy?: string | null;
240
+ body?: string | Uint8Array | null;
241
+ headers?: Record<string, string>;
242
+ signal?: AbortSignal;
243
+ [key: string]: unknown;
244
+ }
245
+
246
+ interface ExitIpResult {
247
+ ip: string | null;
248
+ error: string | null;
249
+ }
250
+
251
+ interface ProxyTestOptions {
252
+ timeoutMs?: number;
253
+ probeUrl?: string | null;
254
+ }
255
+
256
+ interface PoolTestOptions {
257
+ probeUrl?: string | null;
258
+ timeoutMs?: number;
259
+ }
260
+
261
+ interface ProxyTestResult {
262
+ ok: boolean;
263
+ apiStatus?: number;
264
+ exitIp?: string | null;
265
+ latencyMs?: number;
266
+ error?: string;
267
+ exitError?: string | null;
268
+ }
269
+
270
+ function stateDir(): string {
271
+ const raw = process.env.OPENCODE_BRIDGE_STATE_DIR;
272
+ if (raw !== undefined && String(raw).trim()) return String(raw).trim();
273
+ return path.join(os.homedir(), ".opencode-free-bridge");
274
+ }
275
+
276
+ function configFile(): string {
277
+ return path.join(stateDir(), CONFIG_FILE_NAME);
278
+ }
279
+
280
+ /**
281
+ * Pool health lives beside the config but in its own file: the config is
282
+ * operator intent, health is runtime observation. Writing one must never
283
+ * rewrite the other, and a corrupt health file must not cost the pool.
284
+ */
285
+ function healthFile(): string {
286
+ return path.join(stateDir(), HEALTH_FILE_NAME);
287
+ }
288
+
289
+ /**
290
+ * Canonical form of a proxy URL, or the reason it was refused.
291
+ *
292
+ * `""` is valid and means "direct": the panel clears the setting with an empty
293
+ * value rather than a separate verb, so both paths share one validator.
294
+ */
295
+ function parseProxyUrl(raw: unknown): ProxyUrlResult {
296
+ const value = String(raw === undefined || raw === null ? "" : raw).trim();
297
+ if (!value) return { ok: true, url: "" };
298
+
299
+ let u;
300
+ try {
301
+ u = new URL(value);
302
+ } catch {
303
+ return { ok: false, error: "URL proxy tidak valid. Contoh: http://user:pass@host:8080" };
304
+ }
305
+ if (u.protocol !== "http:" && u.protocol !== "https:") {
306
+ return {
307
+ ok: false,
308
+ error:
309
+ `Skema ${u.protocol} tidak didukung. Bun fetch hanya mendukung proxy http:// dan https:// ` +
310
+ "(tunnel CONNECT). SOCKS5 ditolak runtime, jadi tidak bisa dipakai di sini.",
311
+ };
312
+ }
313
+ if (!u.hostname) return { ok: false, error: "Host proxy kosong." };
314
+ if (u.pathname !== "/" || u.search || u.hash) {
315
+ return { ok: false, error: "URL proxy hanya boleh berisi skema, kredensial, host, dan port." };
316
+ }
317
+ // `u.username`/`u.password` stay percent-encoded exactly as the user typed them,
318
+ // which is what Bun expects. Rebuilding avoids the trailing slash `URL`
319
+ // normalization adds, so the stored value matches what the panel shows back.
320
+ const auth = u.username || u.password
321
+ ? `${u.username}${u.password ? `:${u.password}` : ""}@`
322
+ : "";
323
+ const port = u.port ? `:${u.port}` : "";
324
+ return { ok: true, url: `${u.protocol}//${auth}${u.hostname}${port}` };
325
+ }
326
+
327
+ /** `host:port` for display. Credentials are never part of this string. */
328
+ function displayHost(url: string | null): string | null {
329
+ if (!url) return null;
330
+ try {
331
+ const u = new URL(url);
332
+ return `${u.hostname}${u.port ? `:${u.port}` : ""}`;
333
+ } catch {
334
+ return "configured";
335
+ }
336
+ }
337
+
338
+ /** `id` for a URL that has none: stable across reloads, never leaks credentials. */
339
+ function fallbackId(url: string | null): string {
340
+ const host = displayHost(url) || "proxy";
341
+ return host.replace(/[^A-Za-z0-9.:-]/g, "");
342
+ }
343
+
344
+ /**
345
+ * One pool entry, or the reason it was refused. A string entry is shorthand for
346
+ * `{ url }`, so a pool can be written as a plain list of URLs.
347
+ *
348
+ * `{ direct: true }` is the bridge's own address: it lets the hosting machine's
349
+ * IP take part in the rotation instead of being the fallback used only when
350
+ * every proxy is down. That is worth a first-class entry because the host that
351
+ * runs the bridge usually has a usable IP of its own.
352
+ */
353
+ function parsePoolEntry(raw: PoolEntryInput | string, index: number): PoolEntryResult {
354
+ const source: PoolEntryInput = typeof raw === "string" ? { url: raw } : raw;
355
+ if (!source || typeof source !== "object") {
356
+ return { ok: false, error: `Entri #${index + 1} bukan objek atau URL.` };
357
+ }
358
+
359
+ const label = String(source.label == null ? "" : source.label).trim().slice(0, 64);
360
+
361
+ if (source.direct === true) {
362
+ const id = String(source.id == null ? "" : source.id).trim().slice(0, 64) || label || "direct";
363
+ const weight = Number(source.weight);
364
+ return {
365
+ ok: true,
366
+ entry: {
367
+ id,
368
+ label: label || id,
369
+ url: "",
370
+ direct: true,
371
+ enabled: source.enabled === undefined ? true : Boolean(source.enabled),
372
+ weight: Number.isFinite(weight) && weight > 0 ? Math.min(weight, 100) : 1,
373
+ // meter: false opts an entry out of usage accounting — meant for
374
+ // entries whose traffic is not scarce (VPS egress), keeping usage.json
375
+ // focused on the entries that cost real money, e.g. phone data.
376
+ meter: source.meter === undefined ? true : Boolean(source.meter),
377
+ },
378
+ };
379
+ }
380
+
381
+ const parsed = parseProxyUrl(source.url);
382
+ if (!parsed.ok) return { ok: false, error: `Entri #${index + 1}: ${parsed.error}` };
383
+ if (!parsed.url) return { ok: false, error: `Entri #${index + 1}: URL kosong.` };
384
+
385
+ const id = String(source.id == null ? "" : source.id).trim().slice(0, 64) || label || fallbackId(parsed.url);
386
+ // Weights stay optional: an operator that never sets one gets an even spread,
387
+ // and a weight only has to make relative sense within the pool.
388
+ const weight = Number(source.weight);
389
+ return {
390
+ ok: true,
391
+ entry: {
392
+ id,
393
+ label: label || id,
394
+ url: parsed.url,
395
+ direct: false,
396
+ enabled: source.enabled === undefined ? true : Boolean(source.enabled),
397
+ weight: Number.isFinite(weight) && weight > 0 ? Math.min(weight, 100) : 1,
398
+ meter: source.meter === undefined ? true : Boolean(source.meter),
399
+ },
400
+ };
401
+ }
402
+
403
+ /**
404
+ * Parse a `UPSTREAM_PROXY_POOL` value: URLs separated by commas or newlines,
405
+ * each optionally prefixed with `label=`. Empty entries are ignored so a
406
+ * trailing separator is not an error.
407
+ */
408
+ function parsePoolSpec(raw: unknown): PoolSpec {
409
+ const out = [];
410
+ const errors = [];
411
+ String(raw || "")
412
+ .split(/[\n,]+/)
413
+ .map((s) => s.trim())
414
+ .filter(Boolean)
415
+ .forEach((piece, index) => {
416
+ const eq = piece.indexOf("=");
417
+ const hasLabel = eq > 0 && !piece.slice(0, eq).includes("/");
418
+ const parsed = parsePoolEntry(
419
+ hasLabel ? { label: piece.slice(0, eq).trim(), url: piece.slice(eq + 1).trim() } : piece,
420
+ index
421
+ );
422
+ if (parsed.ok) out.push(parsed.entry);
423
+ else errors.push(parsed.error);
424
+ });
425
+ return { entries: out, errors };
426
+ }
427
+
428
+ // ---------------------------------------------------------------- state ---
429
+
430
+ /** Single-proxy state (legacy). `pool` below is used only when it has entries. */
431
+ let current: ProxyState = { url: "", source: "none", error: null };
432
+ let pool: PoolState = { entries: [], errors: [], strategy: DEFAULT_STRATEGY, source: "none", error: null };
433
+ let cooldowns: CooldownConfig = { baseMs: DEFAULT_COOLDOWN_MS, maxMs: DEFAULT_MAX_COOLDOWN_MS };
434
+
435
+ /**
436
+ * Health is keyed by egress identity, not by proxy URL: the "direct" entry has
437
+ * no URL, and two entries must never share a health record.
438
+ */
439
+ function keyOf(url: string | null | undefined): string {
440
+ return url ? url : "@direct";
441
+ }
442
+ /** Usage accounting gate: false skips an entry flagged `meter: false` in config. */
443
+ function shouldMeter(url: string | null): boolean {
444
+ const entry = url
445
+ ? pool.entries.find((e) => e.url === url)
446
+ : pool.entries.find((e) => e.direct);
447
+ return entry ? entry.meter !== false : true;
448
+ }
449
+
450
+ /** key -> { failures, cooldownUntil, lastError, lastOkAt, lastUsedAt } */
451
+ const health = new Map<string, HealthRecord>();
452
+ let cursor: number = 0;
453
+
454
+ function healthFor(url: string | null): HealthRecord {
455
+ const key = keyOf(url);
456
+ let h = health.get(key);
457
+ if (!h) {
458
+ h = { failures: 0, cooldownUntil: 0, lastError: null, lastOkAt: 0, lastUsedAt: 0, lastStatus: null };
459
+ health.set(key, h);
460
+ }
461
+ return h;
462
+ }
463
+
464
+ /**
465
+ * Drop health for egresses no longer in the pool, so a removed entry leaves no
466
+ * ghost. Pure: the caller persists, so a reload never writes a half-restored map
467
+ * over a file it has not read yet.
468
+ */
469
+ function pruneHealth(entries: PoolEntry[]): number {
470
+ const live = new Set(entries.map((e) => keyOf(e.url)));
471
+ if (current.url) live.add(current.url);
472
+ let removed = 0;
473
+ for (const key of [...health.keys()]) {
474
+ if (!live.has(key)) {
475
+ health.delete(key);
476
+ removed += 1;
477
+ }
478
+ }
479
+ return removed;
480
+ }
481
+
482
+ /**
483
+ * Stable, non-secret id for one egress. The health file sits beside a config
484
+ * that already holds proxy credentials; a second copy of every token would be
485
+ * a second thing to leak, and the record only has to be matchable, not readable.
486
+ */
487
+ function healthId(key: string): string {
488
+ return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
489
+ }
490
+
491
+ function healthLabel(key: string): string | null {
492
+ if (key === "@direct") return "direct";
493
+ const entry = pool.entries.find((e) => keyOf(e.url) === key);
494
+ return entry ? entry.label : null;
495
+ }
496
+
497
+ function healthSnapshot(now: number = Date.now()): HealthSnapshot {
498
+ return {
499
+ version: HEALTH_VERSION,
500
+ savedAt: new Date(now).toISOString(),
501
+ entries: [...health.entries()].map(([key, h]) => ({
502
+ id: healthId(key),
503
+ label: healthLabel(key),
504
+ failures: h.failures,
505
+ cooldownUntil: h.cooldownUntil,
506
+ lastError: h.lastError,
507
+ lastStatus: h.lastStatus,
508
+ lastOkAt: h.lastOkAt || null,
509
+ lastUsedAt: h.lastUsedAt || null,
510
+ // The address this cooldown belongs to. Without it a restart cannot tell
511
+ // a still-spent IP from one that has already rotated to a fresh
512
+ // allowance, and would keep the entry parked on stale evidence.
513
+ exitIp: exitIpByKey.get(key) || null,
514
+ })),
515
+ };
516
+ }
517
+
518
+ /** Bun/Node timer handle; only `unref` is read here. */
519
+ interface TimerHandle {
520
+ unref?: () => void;
521
+ }
522
+
523
+ let healthWriteTimer: TimerHandle | null = null;
524
+
525
+ /** Drop the health file: no egress has anything worth remembering. */
526
+ function removeHealthFile(): void {
527
+ try {
528
+ fs.unlinkSync(healthFile());
529
+ } catch (err) {
530
+ if (err.code !== "ENOENT") return;
531
+ }
532
+ }
533
+
534
+ /**
535
+ * Write observed health. Atomic via rename so a crash mid-write leaves the
536
+ * previous file intact — a truncated file would silently cost the pool every
537
+ * cooldown it had learned.
538
+ *
539
+ * Failure is never surfaced: health is a memory optimization, and a request
540
+ * must not fail because a cache file could not be written.
541
+ */
542
+ function writeHealthNow(now: number = Date.now()): void {
543
+ if (healthWriteTimer) {
544
+ clearTimeout(healthWriteTimer);
545
+ healthWriteTimer = null;
546
+ }
547
+ if (health.size === 0) {
548
+ removeHealthFile();
549
+ return;
550
+ }
551
+ try {
552
+ fs.mkdirSync(path.dirname(healthFile()), { recursive: true });
553
+ const tmp = `${healthFile()}.tmp`;
554
+ fs.writeFileSync(tmp, `${JSON.stringify(healthSnapshot(now), null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
555
+ fs.renameSync(tmp, healthFile());
556
+ fs.chmodSync(healthFile(), 0o600);
557
+ } catch {
558
+ // Best effort: the bridge keeps running with in-memory health.
559
+ }
560
+ }
561
+
562
+ /**
563
+ * Coalesce rapid writes. A success arrives with every request, and rewriting a
564
+ * file per request would turn a cheap memory update into disk churn.
565
+ */
566
+ function scheduleHealthWrite(delayMs: number = 1000): void {
567
+ if (healthWriteTimer) return;
568
+ healthWriteTimer = setTimeout(() => {
569
+ healthWriteTimer = null;
570
+ writeHealthNow();
571
+ }, delayMs);
572
+ // Never hold the process open for a cache write.
573
+ if (typeof healthWriteTimer.unref === "function") healthWriteTimer.unref();
574
+ }
575
+
576
+ /**
577
+ * Re-apply health saved by an earlier process. An upstream suspend or a service
578
+ * restart would otherwise forget which IPs are spent and re-burn all of them.
579
+ *
580
+ * The in-memory record wins when it already exists: a restart is the only thing
581
+ * that leaves the map empty, so a live record is by definition at least as
582
+ * fresh as the file.
583
+ */
584
+ function restoreHealth(entries: PoolEntry[], now: number = Date.now()): number {
585
+ let raw;
586
+ try {
587
+ raw = fs.readFileSync(healthFile(), "utf8");
588
+ } catch {
589
+ return 0;
590
+ }
591
+
592
+ let json = null;
593
+ try {
594
+ json = JSON.parse(raw);
595
+ } catch {
596
+ // A corrupt health file must cost nothing but the cooldowns.
597
+ removeHealthFile();
598
+ return 0;
599
+ }
600
+ if (!json || json.version !== HEALTH_VERSION || !Array.isArray(json.entries)) return 0;
601
+
602
+ const saved = new Map();
603
+ for (const record of json.entries) {
604
+ if (record && typeof record.id === "string") saved.set(record.id, record);
605
+ }
606
+
607
+ const keys = entries.map((e) => keyOf(e.url));
608
+ if (current.url) keys.push(current.url);
609
+
610
+ let restored = 0;
611
+ for (const key of keys) {
612
+ if (health.has(key)) continue;
613
+ const record = saved.get(healthId(key));
614
+ if (!record) continue;
615
+ const cooldownUntil = Number(record.cooldownUntil);
616
+ const failures = Number(record.failures);
617
+ const hasExitIp = typeof record.exitIp === "string" && record.exitIp;
618
+ // A cooldown is only trusted when the record says which address earned it.
619
+ // An older health file has no `exitIp`, and the free allowance is keyed to
620
+ // the address upstream sees — a phone on mobile data rotates it several
621
+ // times a day. A 13-hour `Retry-After` restored from a record that cannot
622
+ // name its address is an unverifiable claim, and trusting it kept a healthy
623
+ // phone parked all day. Clear it and let the next request re-learn: at worst
624
+ // one request per unverified entry, and a still-spent IP simply parks again
625
+ // with its own fresh `Retry-After`.
626
+ const rawUntil = Number.isFinite(cooldownUntil) && cooldownUntil > now ? cooldownUntil : 0;
627
+ health.set(key, {
628
+ failures: Number.isFinite(failures) && failures > 0 ? Math.floor(failures) : 0,
629
+ cooldownUntil: hasExitIp ? rawUntil : 0,
630
+ lastError: typeof record.lastError === "string" ? record.lastError : null,
631
+ lastOkAt: Number.isFinite(Number(record.lastOkAt)) ? Number(record.lastOkAt) : 0,
632
+ lastUsedAt: Number.isFinite(Number(record.lastUsedAt)) ? Number(record.lastUsedAt) : 0,
633
+ lastStatus: typeof record.lastStatus === "string" ? record.lastStatus : null,
634
+ });
635
+ if (hasExitIp) exitIpByKey.set(key, record.exitIp);
636
+ restored += 1;
637
+ }
638
+ return restored;
639
+ }
640
+
641
+ function normalizeStrategy(raw: unknown): string {
642
+ const value = String(raw || "").trim().toLowerCase();
643
+ return STRATEGIES.has(value) ? value : DEFAULT_STRATEGY;
644
+ }
645
+
646
+ function normalizeCooldowns(raw: unknown): CooldownConfig {
647
+ const base = Number(raw?.cooldownMs);
648
+ const max = Number(raw?.maxCooldownMs);
649
+ return {
650
+ baseMs: Number.isFinite(base) && base >= 1000 ? Math.min(base, 3600000) : DEFAULT_COOLDOWN_MS,
651
+ maxMs: Number.isFinite(max) && max >= 1000 ? Math.min(max, 7200000) : DEFAULT_MAX_COOLDOWN_MS,
652
+ };
653
+ }
654
+
655
+ function loadFromDisk(): PoolState {
656
+ const envPool = (process.env[POOL_ENV] || "").trim();
657
+ const envSingle = (process.env[ENV_OVERRIDE] || "").trim();
658
+
659
+ if (envPool) {
660
+ const spec = parsePoolSpec(envPool);
661
+ pool = {
662
+ entries: spec.entries,
663
+ errors: spec.errors,
664
+ strategy: normalizeStrategy(process.env[STRATEGY_ENV]),
665
+ source: "env",
666
+ error: spec.errors.length > 0 ? spec.errors.join(" ") : null,
667
+ };
668
+ current = { url: "", source: "env", error: null };
669
+ pruneHealth(pool.entries);
670
+ restoreHealth(pool.entries);
671
+ return pool;
672
+ }
673
+
674
+ if (envSingle) {
675
+ const parsed = parseProxyUrl(envSingle);
676
+ if (parsed.ok) {
677
+ current = { url: parsed.url, source: "env", error: null };
678
+ } else {
679
+ current = { url: "", source: "env", error: `${ENV_OVERRIDE}: ${parsed.error}` };
680
+ }
681
+ pool = { entries: [], errors: [], strategy: DEFAULT_STRATEGY, source: "env", error: null };
682
+ pruneHealth([]);
683
+ restoreHealth([]);
684
+ return pool;
685
+ }
686
+
687
+ let raw = null;
688
+ try {
689
+ raw = fs.readFileSync(configFile(), "utf8");
690
+ } catch {
691
+ current = { url: "", source: "none", error: null };
692
+ pool = { entries: [], errors: [], strategy: DEFAULT_STRATEGY, source: "none", error: null };
693
+ pruneHealth([]);
694
+ restoreHealth([]);
695
+ return pool;
696
+ }
697
+
698
+ let json = null;
699
+ try {
700
+ json = JSON.parse(raw);
701
+ } catch (err) {
702
+ // A corrupt file must not stop the bridge from starting. Direct egress is
703
+ // the safe fallback, and `error` surfaces the reason in the panel.
704
+ current = { url: "", source: "none", error: `proxy.json tidak terbaca: ${err.message}` };
705
+ pool = { entries: [], errors: [], strategy: DEFAULT_STRATEGY, source: "none", error: current.error };
706
+ pruneHealth([]);
707
+ restoreHealth([]);
708
+ return pool;
709
+ }
710
+
711
+ const entries = [];
712
+ const errors = [];
713
+ if (Array.isArray(json?.pool)) {
714
+ json.pool.forEach((item, index) => {
715
+ const parsed = parsePoolEntry(item, index);
716
+ if (parsed.ok) entries.push(parsed.entry);
717
+ else errors.push(parsed.error);
718
+ });
719
+ }
720
+
721
+ const single = parseProxyUrl(json?.url);
722
+ current = single.ok
723
+ ? { url: single.url, source: single.url ? "file" : "none", error: null }
724
+ : { url: "", source: "none", error: single.error };
725
+
726
+ pool = {
727
+ entries,
728
+ errors,
729
+ strategy: normalizeStrategy(json?.strategy),
730
+ source: entries.length > 0 ? "file" : "none",
731
+ error: errors.length > 0 ? errors.join(" ") : null,
732
+ };
733
+ cooldowns = normalizeCooldowns(json);
734
+ pruneHealth(entries);
735
+ restoreHealth(entries);
736
+ return pool;
737
+ }
738
+
739
+ function getProxyUrl(): string {
740
+ return current.url;
741
+ }
742
+
743
+ /** Enabled entries in config order; the pool's working set. */
744
+ function activeEntries(): PoolEntry[] {
745
+ return pool.entries.filter((e) => e.enabled);
746
+ }
747
+
748
+ function isCooling(url: string | null, now: number = Date.now()): boolean {
749
+ const h = health.get(keyOf(url));
750
+ return Boolean(h && h.cooldownUntil > now);
751
+ }
752
+
753
+ /**
754
+ * The egress for one request.
755
+ *
756
+ * Never returns empty while a pool has enabled entries: when every entry is
757
+ * cooling, the one whose cooldown ends first is used anyway. Refusing to send
758
+ * would turn a throttled pool into a dead bridge, and upstream answers a
759
+ * throttled IP with a normal refusal the caller already handles.
760
+ *
761
+ * `exclude` lets a retry avoid the egress that just failed.
762
+ */
763
+ function pick({ exclude = null, now = Date.now() }: PickOptions = {}): PickResult {
764
+ const entries = activeEntries();
765
+
766
+ if (entries.length === 0) {
767
+ return { url: current.url, id: null, label: null, source: current.url ? "single" : "direct", cooling: false };
768
+ }
769
+
770
+ // `null` means "no preference", which must not be confused with the direct
771
+ // entry's empty URL — both would map to the same health key.
772
+ const excluded = exclude === null || exclude === undefined ? null : keyOf(exclude);
773
+ let candidates = excluded === null ? entries.slice() : entries.filter((e) => keyOf(e.url) !== excluded);
774
+ if (candidates.length === 0) candidates = entries.slice();
775
+
776
+ const healthy = candidates.filter((e) => !isCooling(e.url, now));
777
+ let chosen;
778
+ let cooling = false;
779
+
780
+ if (healthy.length > 0) {
781
+ if (pool.strategy === "random") {
782
+ // Weighted pick: a weight only has to be relative within the pool.
783
+ const total = healthy.reduce((sum, e) => sum + e.weight, 0);
784
+ let roll = Math.random() * total;
785
+ chosen = healthy[healthy.length - 1];
786
+ for (const e of healthy) {
787
+ roll -= e.weight;
788
+ if (roll <= 0) {
789
+ chosen = e;
790
+ break;
791
+ }
792
+ }
793
+ } else if (pool.strategy === "priority-failover") {
794
+ // Config order IS the priority: entry #1 (the renewable phone IP) is
795
+ // preferred while healthy. Failover and recovery are both just health
796
+ // moving: a 429 cools the phone and the next entry serves; the priority
797
+ // watchdog probes cooling entries in the background and clears the
798
+ // cooldown the moment one answers 200, so the next pick() snaps back to
799
+ // the top without spending a real request.
800
+ chosen = healthy[0];
801
+ } else if (pool.strategy === "failover") {
802
+ // Sticky: keep using the first healthy entry, which preserves upstream
803
+ // prompt caching on that IP until it is throttled.
804
+ chosen = healthy[0];
805
+ } else {
806
+ // Round-robin across healthy candidates, skipping ones that are cooling.
807
+ // `candidates` already has `exclude` removed, so a retry that must leave a
808
+ // failed egress does not come back to it here.
809
+ chosen = healthy[cursor % healthy.length];
810
+ cursor = (cursor + 1) % Number.MAX_SAFE_INTEGER;
811
+ }
812
+ } else {
813
+ // Everything is throttled: use whichever recovers first.
814
+ cooling = true;
815
+ chosen = candidates
816
+ .slice()
817
+ .sort((a, b) => (health.get(keyOf(a.url))?.cooldownUntil || 0) - (health.get(keyOf(b.url))?.cooldownUntil || 0))[0];
818
+ }
819
+
820
+ if (!chosen) {
821
+ return { url: current.url, id: null, label: null, source: current.url ? "single" : "direct", cooling };
822
+ }
823
+
824
+ const h = healthFor(chosen.url);
825
+ h.lastUsedAt = now;
826
+ return {
827
+ url: chosen.url,
828
+ id: chosen.id,
829
+ label: chosen.label,
830
+ // `direct` means "this process's own address", whether it came from a pool
831
+ // entry or because no pool exists.
832
+ source: chosen.direct ? "direct" : "pool",
833
+ cooling,
834
+ cooldownUntil: h.cooldownUntil || 0,
835
+ };
836
+ }
837
+
838
+ /**
839
+ * Record that an egress was refused by upstream. The cooldown doubles per
840
+ * consecutive failure so a spent IP is retried less and less often, capped at
841
+ * `maxMs`; a success resets both.
842
+ *
843
+ * Only upstream throttling belongs here. A transport error (proxy unreachable)
844
+ * is also a reason to move on, but it must not look like a spent allowance, so
845
+ * the caller passes the reason and it is shown separately in the panel.
846
+ */
847
+ function markFailure(
848
+ egressUrl: string | null,
849
+ { reason = "throttled", now = Date.now(), cooldownMs = null }: MarkFailureOptions = {}
850
+ ): { failures: number; cooldownUntil: number; backoffMs: number } | null {
851
+ // An empty string is the `direct` entry, which is a real egress; only a
852
+ // missing target (null/undefined) means "nothing to record".
853
+ if (egressUrl === null || egressUrl === undefined) return null;
854
+ const h = healthFor(egressUrl);
855
+ h.failures += 1;
856
+ h.lastError = String(reason).slice(0, 200);
857
+ const base = Number.isFinite(cooldownMs) && cooldownMs > 0 ? cooldownMs : cooldowns.baseMs;
858
+ const backoff = Math.min(base * Math.pow(2, h.failures - 1), Math.max(cooldowns.maxMs, base));
859
+ h.cooldownUntil = now + backoff;
860
+ h.lastStatus = reason;
861
+ // A refusal is the expensive thing to rediscover: write it before the caller
862
+ // can act on it, so a restart in the next second does not forget the IP.
863
+ writeHealthNow(now);
864
+ return { failures: h.failures, cooldownUntil: h.cooldownUntil, backoffMs: backoff };
865
+ }
866
+
867
+ /** Clear an egress's failure history; called after a request succeeds. */
868
+ function markSuccess(egressUrl: string | null, { now = Date.now() }: NowOptions = {}): HealthRecord | null {
869
+ if (egressUrl === null || egressUrl === undefined) return null;
870
+ const h = healthFor(egressUrl);
871
+ h.failures = 0;
872
+ h.cooldownUntil = 0;
873
+ h.lastError = null;
874
+ h.lastOkAt = now;
875
+ h.lastStatus = "ok";
876
+ // Every request lands here, so this one is coalesced.
877
+ scheduleHealthWrite();
878
+ return h;
879
+ }
880
+
881
+ /**
882
+ * Remember the address an egress is currently exiting through.
883
+ *
884
+ * Called with the exit IP a probe already read, so a cooldown can record which
885
+ * address earned it. Optional by design: a probe that fails (proxy down, trace
886
+ * unreachable) leaves the mapping alone rather than inventing one, and the
887
+ * capped-cooldown path in `loadFromDisk` covers records written without it.
888
+ */
889
+ function noteExitIp(egressUrl: string | null, ip: unknown, { now = Date.now() }: NowOptions = {}): string | null {
890
+ if (egressUrl === null || egressUrl === undefined) return null;
891
+ if (typeof ip !== "string" || !ip) return null;
892
+ const key = keyOf(egressUrl);
893
+ if (exitIpByKey.get(key) === ip) return ip;
894
+ exitIpByKey.set(key, ip);
895
+ scheduleHealthWrite(now);
896
+ return ip;
897
+ }
898
+
899
+ function resetHealth(): void {
900
+ health.clear();
901
+ cursor = 0;
902
+ writeHealthNow();
903
+ }
904
+
905
+ /** Public view of one entry: host:port, health, and never the URL's credentials. */
906
+ function describeEntry(entry: PoolEntry, now: number = Date.now()): EntryDescription {
907
+ const h = health.get(keyOf(entry.url));
908
+ const cooling = Boolean(h && h.cooldownUntil > now);
909
+ return {
910
+ id: entry.id,
911
+ label: entry.label,
912
+ host: entry.direct ? "direct" : displayHost(entry.url),
913
+ enabled: entry.enabled,
914
+ weight: entry.weight,
915
+ state: !entry.enabled ? "disabled" : cooling ? "cooling" : "ready",
916
+ cooldownMsLeft: cooling ? Math.max(0, h.cooldownUntil - now) : 0,
917
+ cooldownUntil: cooling ? h.cooldownUntil : 0,
918
+ failures: h ? h.failures : 0,
919
+ lastError: h ? h.lastError : null,
920
+ lastOkAt: h ? h.lastOkAt || null : null,
921
+ lastUsedAt: h ? h.lastUsedAt || null : null,
922
+ };
923
+ }
924
+
925
+ function describe(now: number = Date.now()): ProxyDescription {
926
+ const entries = pool.entries;
927
+ const active = entries.filter((e) => e.enabled);
928
+ const ready = active.filter((e) => !isCooling(e.url, now));
929
+ const poolActive = active.length > 0;
930
+ const singleActive = !poolActive && Boolean(current.url);
931
+
932
+ const poolView = {
933
+ active: poolActive,
934
+ size: entries.length,
935
+ enabled: active.length,
936
+ ready: ready.length,
937
+ cooling: active.length - ready.length,
938
+ strategy: pool.strategy,
939
+ source: pool.source,
940
+ cooldownMs: cooldowns.baseMs,
941
+ maxCooldownMs: cooldowns.maxMs,
942
+ error: pool.error,
943
+ entries: entries.map((e) => describeEntry(e, now)),
944
+ };
945
+
946
+ return {
947
+ mode: poolActive ? "pool" : singleActive ? "proxy" : "direct",
948
+ proxy: poolActive ? `${active.length} proxy` : displayHost(current.url),
949
+ hasCredentials: poolActive
950
+ ? entries.some((e) => /\/\/[^/@]+@/.test(e.url))
951
+ : current.url
952
+ ? /\/\/[^/@]+@/.test(current.url)
953
+ : false,
954
+ source: poolActive ? pool.source : current.source,
955
+ locked: (poolActive ? pool.source : current.source) === "env",
956
+ configPath: configFile(),
957
+ error: current.error || pool.error || null,
958
+ pool: poolView,
959
+ };
960
+ }
961
+
962
+ /** Write the whole config atomically-ish: one file, owner-only. */
963
+ function writeConfig(next: Record<string, unknown>): ConfigResult {
964
+ try {
965
+ fs.mkdirSync(path.dirname(configFile()), { recursive: true });
966
+ fs.writeFileSync(configFile(), `${JSON.stringify(next, null, 2)}\n`, {
967
+ encoding: "utf8",
968
+ mode: 0o600,
969
+ });
970
+ // A file created earlier keeps its old mode; chmod so credentials created by
971
+ // an older release are not left readable by every local user.
972
+ fs.chmodSync(configFile(), 0o600);
973
+ return { ok: true };
974
+ } catch (err) {
975
+ return { ok: false, error: `Gagal menulis ${configFile()}: ${err.message}` };
976
+ }
977
+ }
978
+
979
+ /** Current on-disk shape, so one setter never drops the other's fields. */
980
+ function readConfigObject(): Record<string, unknown> {
981
+ try {
982
+ const json = JSON.parse(fs.readFileSync(configFile(), "utf8"));
983
+ return json && typeof json === "object" ? json : {};
984
+ } catch {
985
+ return {};
986
+ }
987
+ }
988
+
989
+ function refuseWhenLocked(): ConfigResult | null {
990
+ if (pool.source === "env" || current.source === "env") {
991
+ return {
992
+ ok: false,
993
+ error: `${POOL_ENV}/${ENV_OVERRIDE} diset di environment. Ubah variabel itu lalu restart service.`,
994
+ };
995
+ }
996
+ return null;
997
+ }
998
+
999
+ /**
1000
+ * Persist a new single-proxy setting. `raw` may be empty to go back to direct
1001
+ * egress.
1002
+ *
1003
+ * `UPSTREAM_PROXY_URL` is an operator override, so a runtime edit is refused
1004
+ * instead of silently losing to the environment on the next restart.
1005
+ */
1006
+ function setProxyUrl(raw: unknown): SetResult {
1007
+ const locked = refuseWhenLocked();
1008
+ if (locked) return locked;
1009
+ const parsed = parseProxyUrl(raw);
1010
+ if (!parsed.ok) return { ok: false, error: parsed.error };
1011
+
1012
+ const config = readConfigObject();
1013
+
1014
+ if (!parsed.url) {
1015
+ delete config.url;
1016
+ if (Array.isArray(config.pool) && config.pool.length > 0) {
1017
+ if (!writeConfig(config).ok) return { ok: false, error: `Gagal menulis ${configFile()}` };
1018
+ } else {
1019
+ try {
1020
+ fs.unlinkSync(configFile());
1021
+ } catch (err) {
1022
+ if (err.code !== "ENOENT") {
1023
+ return { ok: false, error: `Gagal menghapus ${configFile()}: ${err.message}` };
1024
+ }
1025
+ }
1026
+ }
1027
+ current = { url: "", source: "none", error: null };
1028
+ loadFromDisk();
1029
+ return { ok: true, ...describe() };
1030
+ }
1031
+
1032
+ config.url = parsed.url;
1033
+ const written = writeConfig(config);
1034
+ if (!written.ok) return written;
1035
+ current = { url: parsed.url, source: "file", error: null };
1036
+ return { ok: true, ...describe() };
1037
+ }
1038
+
1039
+ /**
1040
+ * Replace the pool. `raw` accepts:
1041
+ * - an array of entries (`{id,label,url,enabled,weight}` or bare URL strings)
1042
+ * - `{ entries: [...], strategy, cooldownMs, maxCooldownMs }`
1043
+ * - `[]` / `{ entries: [] }` to clear it and fall back to direct/single egress
1044
+ */
1045
+ function setPool(raw: PoolSpecInput | unknown[] | null | undefined): SetResult {
1046
+ const locked = refuseWhenLocked();
1047
+ if (locked) return locked;
1048
+
1049
+ const spec: PoolSpecInput | null = Array.isArray(raw) ? { entries: raw } : raw && typeof raw === "object" ? raw : null;
1050
+ if (!spec) return { ok: false, error: "Format pool tidak valid." };
1051
+
1052
+ const source = Array.isArray(spec.entries) ? spec.entries : [];
1053
+ const entries = [];
1054
+ const errors = [];
1055
+ source.forEach((item, index) => {
1056
+ const parsed = parsePoolEntry(item, index);
1057
+ if (parsed.ok) entries.push(parsed.entry);
1058
+ else errors.push(parsed.error);
1059
+ });
1060
+ if (errors.length > 0) return { ok: false, error: errors.join(" ") };
1061
+
1062
+ const seen = new Set();
1063
+ for (const entry of entries) {
1064
+ const key = keyOf(entry.url);
1065
+ if (seen.has(key)) {
1066
+ return { ok: false, error: `Egress ganda di pool: ${entry.direct ? "direct" : displayHost(entry.url)}` };
1067
+ }
1068
+ seen.add(key);
1069
+ }
1070
+
1071
+ const config = readConfigObject();
1072
+ if (entries.length === 0) {
1073
+ delete config.pool;
1074
+ } else {
1075
+ config.pool = entries;
1076
+ }
1077
+ if (spec.strategy !== undefined) config.strategy = normalizeStrategy(spec.strategy);
1078
+ if (spec.cooldownMs !== undefined) config.cooldownMs = normalizeCooldowns({ cooldownMs: spec.cooldownMs }).baseMs;
1079
+ if (spec.maxCooldownMs !== undefined) {
1080
+ config.maxCooldownMs = normalizeCooldowns({ maxCooldownMs: spec.maxCooldownMs }).maxMs;
1081
+ }
1082
+
1083
+ if (!config.url && !config.pool) {
1084
+ try {
1085
+ fs.unlinkSync(configFile());
1086
+ } catch (err) {
1087
+ if (err.code !== "ENOENT") return { ok: false, error: `Gagal menghapus ${configFile()}: ${err.message}` };
1088
+ }
1089
+ } else {
1090
+ const written = writeConfig(config);
1091
+ if (!written.ok) return written;
1092
+ }
1093
+
1094
+ // Deliberately not `resetHealth()`: an operator saving the pool (even just to
1095
+ // change the strategy) must not forget which IPs are spent. In-memory health
1096
+ // wins over the file during reload, so unchanged entries keep their cooldown
1097
+ // and removed ones were just pruned.
1098
+ loadFromDisk();
1099
+ cursor = 0;
1100
+ for (const entry of entries) healthFor(entry.url);
1101
+ writeHealthNow();
1102
+ return { ok: true, ...describe() };
1103
+ }
1104
+
1105
+ /**
1106
+ * Add `proxy:` to a fetch init. Callers pass their own init untouched, so a
1107
+ * request that pins its own proxy keeps it.
1108
+ *
1109
+ * With a pool this picks an egress per call. A caller that needs one egress for
1110
+ * several fetches (a retry that must stay on the IP that answered) should call
1111
+ * `pick()` once and pass the result explicitly instead.
1112
+ *
1113
+ * An empty target is meaningful: it selects the `direct` pool entry, which is
1114
+ * this process's own address, so the fetch goes out without a proxy.
1115
+ */
1116
+ function withProxy(init: FetchInit | null | undefined, egressUrl: string | null = null): FetchInit | null | undefined {
1117
+ if (init && init.proxy) return init;
1118
+ // A caller that pins an egress passes the URL, and "" is the direct entry —
1119
+ // distinct from passing nothing, which asks the pool to choose.
1120
+ const target = egressUrl === null || egressUrl === undefined ? pick().url : egressUrl;
1121
+ if (!target) return init;
1122
+ return { ...(init || {}), proxy: target };
1123
+ }
1124
+
1125
+ /** fetch() through the resolved egress. The single egress entry point. */
1126
+ function netFetch(url: string, init?: FetchInit, egressUrl: string | null = null): Promise<Response> {
1127
+ const metering = shouldMeter(egressUrl);
1128
+ const body = init?.body;
1129
+ const requestBytes =
1130
+ typeof body === "string"
1131
+ ? Buffer.byteLength(body)
1132
+ : body && body.byteLength
1133
+ ? body.byteLength
1134
+ : 0;
1135
+ return fetch(url, withProxy(init, egressUrl)).then((res) => {
1136
+ if (metering) recordUsage(egressUrl, requestBytes, 0, { ok: res.ok && res.status < 400 });
1137
+ // Count response bytes as the stream is read: the response is always SSE
1138
+ // here, so wrapping the reader catches every payload without buffering it.
1139
+ if (metering && res.body && typeof res.body.getReader === "function") {
1140
+ const origGetReader = res.body.getReader.bind(res.body);
1141
+ let counted = false;
1142
+ res.body.getReader = () => {
1143
+ if (counted) return origGetReader();
1144
+ counted = true;
1145
+ const reader = origGetReader();
1146
+ const origRead = reader.read.bind(reader);
1147
+ reader.read = () =>
1148
+ origRead().then((chunk) => {
1149
+ if (chunk && chunk.value && chunk.value.byteLength) {
1150
+ loadUsage();
1151
+ const e = usageEntry(keyOf(egressUrl));
1152
+ e.responseBytes += chunk.value.byteLength;
1153
+ persistUsage();
1154
+ }
1155
+ return chunk;
1156
+ });
1157
+ return reader;
1158
+ };
1159
+ }
1160
+ return res;
1161
+ });
1162
+ }
1163
+
1164
+ // ------------------------------------------------------------- usage meter ---
1165
+
1166
+ /**
1167
+ * Per-egress traffic accounting, persisted to usage.json beside the config.
1168
+ *
1169
+ * The point is phone data: when the egress is the Android phone over Tailscale,
1170
+ * every upstream byte is mobile data. Requests and response bytes are counted
1171
+ * here rather than derived from tokens because the wire carries headers, SSE
1172
+ * framing, and identity payloads that tokens do not describe. The bridge hands
1173
+ * the same numbers to OpenBot in `usage` (chat requests) and `/health`, so a
1174
+ * token-to-data ratio can be computed from one place.
1175
+ */
1176
+ const USAGE_FILE_NAME = "usage.json";
1177
+ function usageFile(): string {
1178
+ return path.join(stateDir(), USAGE_FILE_NAME);
1179
+ }
1180
+ let usage: UsageState = {
1181
+ // day = UTC date string; rolls when a request lands on a new day.
1182
+ day: new Date().toISOString().slice(0, 10),
1183
+ perEgress: {}, // key -> { requests, okRequests, requestBytes, responseBytes, promptTokens, completionTokens }
1184
+ };
1185
+ let usageLoaded: boolean = false;
1186
+
1187
+ function usageEntry(key: string): UsageRecord {
1188
+ const today = new Date().toISOString().slice(0, 10);
1189
+ if (today !== usage.day) {
1190
+ usage = { day: today, perEgress: {} };
1191
+ persistUsage();
1192
+ }
1193
+ if (!usage.perEgress[key]) {
1194
+ usage.perEgress[key] = {
1195
+ requests: 0,
1196
+ okRequests: 0,
1197
+ requestBytes: 0,
1198
+ responseBytes: 0,
1199
+ promptTokens: 0,
1200
+ completionTokens: 0,
1201
+ };
1202
+ }
1203
+ return usage.perEgress[key];
1204
+ }
1205
+
1206
+ function loadUsage(): void {
1207
+ if (usageLoaded) return;
1208
+ usageLoaded = true;
1209
+ try {
1210
+ const json = JSON.parse(fs.readFileSync(usageFile(), "utf8"));
1211
+ if (json && typeof json.day === "string" && json.perEgress && typeof json.perEgress === "object") {
1212
+ if (json.day === new Date().toISOString().slice(0, 10)) usage = { day: json.day, perEgress: json.perEgress };
1213
+ }
1214
+ } catch {}
1215
+ }
1216
+
1217
+ function persistUsage(): void {
1218
+ try {
1219
+ fs.mkdirSync(path.dirname(usageFile()), { recursive: true });
1220
+ fs.writeFileSync(usageFile(), `${JSON.stringify(usage, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
1221
+ } catch {}
1222
+ }
1223
+
1224
+ /** Record one wire transaction through an egress. Coarse, by design. */
1225
+ function recordUsage(
1226
+ egressUrl: string | null,
1227
+ requestBytes: number,
1228
+ responseBytes: number,
1229
+ { ok = false, promptTokens = 0, completionTokens = 0 } = {}
1230
+ ): void {
1231
+ // Entries flagged `meter: false` in proxy.json stay out of usage.json —
1232
+ // the accounting exists for scarce links (phone data), not free ones.
1233
+ if (!shouldMeter(egressUrl)) return;
1234
+ // null/undefined means the direct entry; keyOf maps it to "@direct" so
1235
+ // direct traffic is accounted too, not silently dropped.
1236
+ loadUsage();
1237
+ const e = usageEntry(keyOf(egressUrl));
1238
+ e.requests += 1;
1239
+ e.requestBytes += Math.max(0, Math.round(requestBytes) || 0);
1240
+ e.responseBytes += Math.max(0, Math.round(responseBytes) || 0);
1241
+ if (ok) {
1242
+ e.okRequests += 1;
1243
+ e.promptTokens += Math.max(0, Math.round(promptTokens) || 0);
1244
+ e.completionTokens += Math.max(0, Math.round(completionTokens) || 0);
1245
+ }
1246
+ persistUsage();
1247
+ }
1248
+
1249
+ /** Read view for /health and tests; adds derived MB and token/data ratio. */
1250
+ function describeUsage(): UsageView {
1251
+ loadUsage();
1252
+ const out = { day: usage.day, perEgress: {} };
1253
+ for (const [key, e] of Object.entries(usage.perEgress)) {
1254
+ const mb = (e.requestBytes + e.responseBytes) / 1_000_000;
1255
+ const tokens = e.promptTokens + e.completionTokens;
1256
+ out.perEgress[key] = {
1257
+ ...e,
1258
+ label: healthLabel(key),
1259
+ totalMB: Math.round(mb * 100) / 100,
1260
+ tokensPerMB: mb > 0.01 ? Math.round(tokens / mb) : null,
1261
+ };
1262
+ }
1263
+ return out;
1264
+ }
1265
+
1266
+ /**
1267
+ * Prove one proxy works before it becomes the live egress.
1268
+ *
1269
+ * Two probes: the API the bridge actually calls, and a trace endpoint that
1270
+ * answers with the exit IP so the panel can show that egress moved. The API
1271
+ * probe is the one that decides `ok`; the IP probe is best-effort.
1272
+ */
1273
+ async function testProxy(url: unknown, { timeoutMs = 15000, probeUrl = null }: ProxyTestOptions = {}): Promise<ProxyTestResult> {
1274
+ if (typeof Bun === "undefined") {
1275
+ return { ok: false, error: "Proxy egress hanya berjalan di Bun; runtime Node tidak mendukung opsi proxy." };
1276
+ }
1277
+ const parsed = parseProxyUrl(url);
1278
+ if (!parsed.ok) return { ok: false, error: parsed.error };
1279
+ if (!parsed.url) return { ok: false, error: "URL proxy kosong." };
1280
+
1281
+ const started = Date.now();
1282
+ const exit = await probeExitIp(parsed.url, timeoutMs);
1283
+ let res;
1284
+ try {
1285
+ // Default matches the shipped wire endpoint. The caller passes the live one
1286
+ // so a catalog migration does not turn a working proxy into a false failure.
1287
+ res = await fetch(probeUrl || "https://opencode.ai/inference/v1/models", {
1288
+ proxy: parsed.url,
1289
+ headers: { Authorization: "Bearer public" },
1290
+ signal: AbortSignal.timeout(timeoutMs),
1291
+ });
1292
+ } catch (err) {
1293
+ return {
1294
+ ok: false,
1295
+ exitIp: exit.ip,
1296
+ latencyMs: Date.now() - started,
1297
+ error: `Tidak bisa menghubungi upstream lewat proxy: ${err.message}`,
1298
+ };
1299
+ }
1300
+ const latencyMs = Date.now() - started;
1301
+ if (!res.ok) {
1302
+ return {
1303
+ ok: false,
1304
+ apiStatus: res.status,
1305
+ exitIp: exit.ip,
1306
+ latencyMs,
1307
+ error:
1308
+ res.status === 403
1309
+ ? "Proxy tersambung, tapi upstream menolak egress-nya (403). Coba proxy lain."
1310
+ : `Proxy tersambung, upstream menjawab ${res.status}.`,
1311
+ };
1312
+ }
1313
+ return { ok: true, apiStatus: res.status, exitIp: exit.ip, latencyMs, exitError: exit.error || null };
1314
+ }
1315
+
1316
+ /**
1317
+ * Probe every entry of the pool concurrently, and record the verdict in the
1318
+ * health map so the panel's result is also what the next request uses. A
1319
+ * throttled entry goes into cooldown; a working one is cleared.
1320
+ */
1321
+ async function testPool({ probeUrl = null, timeoutMs = 15000 }: PoolTestOptions = {}): Promise<{ ok: boolean; entries: unknown[] }> {
1322
+ const entries = pool.entries.slice();
1323
+ if (entries.length === 0) return { ok: true, entries: [] };
1324
+ const results = await Promise.all(
1325
+ entries.map(async (entry) => {
1326
+ if (!entry.enabled) return { id: entry.id, label: entry.label, host: displayHost(entry.url), skipped: true };
1327
+ const verdict = await testProxy(entry.url, { probeUrl, timeoutMs });
1328
+ const ok = verdict.ok;
1329
+ if (ok) markSuccess(entry.url);
1330
+ else if (verdict.apiStatus === 403) markFailure(entry.url, { reason: "upstream 403" });
1331
+ // Record where this entry exits, so a later cooldown can name the address
1332
+ // that earned it and a rotation can be told apart from a still-spent IP.
1333
+ if (verdict.exitIp) noteExitIp(entry.url, verdict.exitIp);
1334
+ // `health` is keyed by keyOf(), which maps the direct entry's empty URL to
1335
+ // "@direct" — reading it by the raw url would silently report no state.
1336
+ const h = health.get(keyOf(entry.url));
1337
+ return {
1338
+ id: entry.id,
1339
+ label: entry.label,
1340
+ host: displayHost(entry.url),
1341
+ ok: verdict.ok,
1342
+ apiStatus: verdict.apiStatus || null,
1343
+ exitIp: verdict.exitIp || null,
1344
+ latencyMs: verdict.latencyMs || null,
1345
+ error: verdict.error || null,
1346
+ state: h && h.cooldownUntil > Date.now() ? "cooling" : verdict.ok ? "ready" : "error",
1347
+ };
1348
+ })
1349
+ );
1350
+ return { ok: results.some((r) => r.ok), entries: results };
1351
+ }
1352
+
1353
+ async function probeExitIp(proxyUrl: string | null, timeoutMs: number): Promise<ExitIpResult> {
1354
+ try {
1355
+ const res = await fetch("https://www.cloudflare.com/cdn-cgi/trace", {
1356
+ proxy: proxyUrl,
1357
+ signal: AbortSignal.timeout(Math.min(timeoutMs, 8000)),
1358
+ });
1359
+ if (!res.ok) return { ip: null, error: `trace HTTP ${res.status}` };
1360
+ const text = await res.text();
1361
+ const ip = (text.match(/^ip=(.+)$/m) || [])[1] || null;
1362
+ return { ip, error: ip ? null : "trace tanpa field ip" };
1363
+ } catch (err) {
1364
+ return { ip: null, error: err.message };
1365
+ }
1366
+ }
1367
+
1368
+ /**
1369
+ * Priority-failover recovery watchdog.
1370
+ *
1371
+ * Config order is priority. When a high-priority egress (the renewable phone
1372
+ * IP) is parked by a 429 and lower-priority entries are serving, a plain
1373
+ * "cooldown expiry" model only puts the phone back in the candidate list —
1374
+ * but `pick()` sticks to the first *healthy* entry, so it would not actually
1375
+ * return to the top until the serving entry also fails. This watchdog probes
1376
+ * a cooling entry once its cooldown has fully elapsed: one cheap
1377
+ * GET /v1/models through that egress. 200 clears the cooldown via
1378
+ * `markSuccess`, so the next `pick()` snaps back to the top entry; anything
1379
+ * else re-parks it with a fresh backoff. The walk order is the pool order,
1380
+ * so the highest-priority entry always recovers first.
1381
+ */
1382
+ const RECOVERY_PROBE_INTERVAL_MS = 60_000;
1383
+ /**
1384
+ * Last exit IP seen per egress key.
1385
+ *
1386
+ * Upstream keys the free allowance to the address it sees, not to the URL of
1387
+ * the proxy in front of it. A phone on mobile data rotates its address several
1388
+ * times a day, and every rotation hands back a fresh allowance — but the pool
1389
+ * only knew the proxy URL, so a `Retry-After` of 13 hours (measured: 47674s,
1390
+ * i.e. the next midnight UTC) kept the phone parked long after its address,
1391
+ * and with it the refusal, was gone. That is why a healthy entry could sit
1392
+ * cooling all day while the same URL answered 200 in a burst test.
1393
+ *
1394
+ * So an exit-IP change is treated as evidence the refusal no longer applies:
1395
+ * the cooldown is cleared and the entry returns to the pool. The mapping is
1396
+ * also persisted in the health file so a restart mid-cooldown can still notice
1397
+ * the rotation instead of trusting a stale park.
1398
+ */
1399
+ const exitIpByKey = new Map<string, string>();
1400
+ let recoveryProbeBusy: boolean = false;
1401
+ async function recoveryProbeTick(): Promise<void> {
1402
+ if (recoveryProbeBusy) return;
1403
+ if (pool.strategy !== "priority-failover" || pool.entries.length === 0) return;
1404
+ recoveryProbeBusy = true;
1405
+ const now = Date.now();
1406
+ try {
1407
+ const active = activeEntries();
1408
+ // Address rotation outranks the cooldown clock: check the highest-priority
1409
+ // parked entry whose exit address is still worth re-reading. One probe per
1410
+ // tick, so the cost is a single trace request per minute at worst.
1411
+ const parked = active.find((e) => {
1412
+ const h = health.get(keyOf(e.url));
1413
+ return h && h.cooldownUntil > now;
1414
+ });
1415
+ if (parked) {
1416
+ const key = keyOf(parked.url);
1417
+ const seen = exitIpByKey.get(key);
1418
+ const exit = await probeExitIp(parked.url || null, 8_000);
1419
+ if (exit && exit.ip) {
1420
+ if (seen && seen !== exit.ip) {
1421
+ console.log(
1422
+ `[opencode-free-bridge] Egress ${displayHost(parked.url) || "direct"} rotated ${seen} -> ${exit.ip}; clearing the cooldown that IP earned`
1423
+ );
1424
+ exitIpByKey.set(key, exit.ip);
1425
+ markSuccess(parked.url);
1426
+ return;
1427
+ }
1428
+ if (!seen) exitIpByKey.set(key, exit.ip);
1429
+ }
1430
+ }
1431
+ // Walk the pool in priority order and probe the first entry whose
1432
+ // cooldown has fully elapsed. One probe per tick keeps the cost at one
1433
+ // models call per minute, worst case.
1434
+ const candidates = active.filter((e) => {
1435
+ const h = health.get(keyOf(e.url));
1436
+ return h && h.cooldownUntil > 0 && h.cooldownUntil <= now;
1437
+ });
1438
+ const entry = candidates[0];
1439
+ if (!entry) return;
1440
+ const before = health.get(keyOf(entry.url));
1441
+ if (before) before.cooldownUntil = now + RECOVERY_PROBE_INTERVAL_MS; // hold position during probe
1442
+ const probeUrl = process.env.OPENCODE_MODELS_URL || "https://opencode.ai/inference/v1/models";
1443
+ try {
1444
+ const res = await netFetch(probeUrl, {
1445
+ headers: { Authorization: "Bearer public" },
1446
+ signal: AbortSignal.timeout(10_000),
1447
+ }, entry.url || null);
1448
+ if (res.status === 200) {
1449
+ console.log(
1450
+ `[opencode-free-bridge] Priority egress ${displayHost(entry.url) || "direct"} recovered (probe 200); returning to top of pool`
1451
+ );
1452
+ markSuccess(entry.url);
1453
+ } else {
1454
+ markFailure(entry.url, { reason: `recovery probe ${res.status}` });
1455
+ }
1456
+ } catch (err) {
1457
+ markFailure(entry.url, { reason: `recovery probe transport: ${err.message}`.slice(0, 200) });
1458
+ }
1459
+ } finally {
1460
+ recoveryProbeBusy = false;
1461
+ }
1462
+ }
1463
+
1464
+ loadFromDisk();
1465
+
1466
+ module.exports = {
1467
+ ENV_OVERRIDE,
1468
+ POOL_ENV,
1469
+ STRATEGY_ENV,
1470
+ configFile,
1471
+ healthFile,
1472
+ parseProxyUrl,
1473
+ parsePoolEntry,
1474
+ parsePoolSpec,
1475
+ displayHost,
1476
+ getProxyUrl,
1477
+ getPool: () => pool.entries.slice(),
1478
+ describe,
1479
+ setProxyUrl,
1480
+ setPool,
1481
+ pick,
1482
+ markFailure,
1483
+ markSuccess,
1484
+ resetHealth,
1485
+ noteExitIp,
1486
+ withProxy,
1487
+ netFetch,
1488
+ testProxy,
1489
+ testPool,
1490
+ recoveryProbeTick,
1491
+ recordUsage,
1492
+ describeUsage,
1493
+ get strategy() {
1494
+ return pool.strategy;
1495
+ },
1496
+ __setForTest(state: ProxyState) {
1497
+ current = state;
1498
+ },
1499
+ __reload: loadFromDisk,
1500
+ /** Simulate a process start: in-memory state gone, everything re-read from disk. */
1501
+ __restart() {
1502
+ health.clear();
1503
+ cursor = 0;
1504
+ loadFromDisk();
1505
+ },
1506
+ /** Force the coalesced health write, so a test can assert persisted state. */
1507
+ __flushHealth: () => writeHealthNow(),
1508
+ };