Skip to content

Commit f7c22c8

Browse files
committed
fix(captcha): wire worker solving across all build paths with in-process fallback
The worker move (TriDefender#55) embedded the entry via a static `with { type: "file" }` asset import in captcha-solver.ts, which broke every non-Bun-compile path: - esbuild (Android server bundle) rejects the import attribute at parse time — build:android-bundle and the release build-android job failed - a fresh checkout has no gitignored worker bundle, so dev mode / the Docker TS-source image failed to even LOAD captcha-solver on start-plan - release.yml invokes `bun build --compile` directly (no npm lifecycle hooks), so the prebuild hook never ran and all five release binaries failed to resolve the asset Restructure so the attribute syntax lives only in captcha-worker-asset.ts, reached via dynamic import from captcha-worker-dispatch.ts with an in-process solveTraceless fallback when the asset is unavailable (dev, Docker, Android) or the worker entry fails to load (module-not-found only; runtime crashes stay hard failures so an OOM never migrates to the main thread). Mode transitions are announced once on stderr. - package.json: every compile script self-generates the worker bundle; android esbuild marks the asset module --external (falls back on device) - release.yml build-binaries generates the bundle before compiling - Dockerfile bundles the entry at image build time - tsconfig excludes the generated bundle from typechecking - README privacy section reworded for upstream voice + README_EN parity Verified: tsc clean; 888 tests (3 new dispatch tests, incl. a real worker_threads round trip); android bundle builds; compiled exe embeds the asset via the dynamic-import chain and solves through a worker (6.7s live); no-bundle dev run degrades and solves in-process.
1 parent 293df5c commit f7c22c8

10 files changed

Lines changed: 302 additions & 103 deletions

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ jobs:
151151
grep -q "\"version\": \"${RELEASE_VERSION}\"" package.json
152152
- name: Build binary
153153
run: >-
154+
bun run scripts/build-fork-worker.ts &&
154155
bun build --compile --target=${{ matrix.target }}
155156
--define "require.resolve=undefined"
156157
src/index.ts --outfile ${{ matrix.outfile }}

‎Dockerfile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ WORKDIR /app
1010
COPY --from=deps /app/node_modules ./node_modules
1111
COPY package.json tsconfig.json config.example.yaml ./
1212
COPY src ./src
13+
COPY scripts ./scripts
14+
# The image runs TS sources, so the worker-thread captcha entry must be
15+
# bundled at image build time (gitignored build input; without it the solver
16+
# silently falls back to main-thread solving).
17+
RUN bun run scripts/build-fork-worker.ts && rm -rf scripts
1318
RUN mkdir -p /data && chown bun:bun /data
1419
ENV ZCODE_PROXY_PORT=8080
1520
ENV ZCODE_PROXY_CONFIG=/data/config.yaml

‎README.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -242,10 +242,7 @@ bun run dev # 开发模式启动面板
242242

243243
## Privacy
244244

245-
This fork adds **no telemetry, no analytics, and no outbound reporting** of
246-
any kind. Nothing about your usage, device, or configuration leaves your
247-
machine. (Inherited from upstream: the proxy is fully local; debug/dump logs
248-
auto-redact API keys, JWTs, and proxy keys.)
245+
本代理完全本地运行:**无遥测、无分析、无任何形式的外发报告**。你的使用数据、设备信息与配置不会离开本机;debug/dump 日志会自动脱敏 API key、JWT 与 proxy key。
249246

250247
## License
251248

‎README_EN.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,13 @@ bun run dev # start the panel in dev mode
241241

242242
For architecture and implementation details, see the comments inside the source files under [`src/`](src/).
243243

244+
## Privacy
245+
246+
The proxy runs fully locally: **no telemetry, no analytics, and no outbound
247+
reporting of any kind**. Nothing about your usage, device, or configuration
248+
leaves your machine; debug/dump logs auto-redact API keys, JWTs, and proxy
249+
keys.
250+
244251
## License
245252

246253
MIT

‎package.json‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,12 @@
66
"dev": "bun run src/index.ts",
77
"start": "bun run src/index.ts",
88
"test": "bun test",
9-
"prebuild": "bun run scripts/build-fork-worker.ts",
10-
"build": "bun build --compile --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy.exe",
11-
"build:linux-x64": "bun build --compile --target bun-linux-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-x64",
12-
"build:linux-arm64": "bun build --compile --target bun-linux-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-arm64",
13-
"build:darwin-x64": "bun build --compile --target bun-darwin-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-x64",
14-
"build:darwin-arm64": "bun build --compile --target bun-darwin-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-arm64",
15-
"build:android-bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/android/server.cjs --define:process.env.NODE_ENV=\\\"production\\\"",
9+
"build": "bun run scripts/build-fork-worker.ts && bun build --compile --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy.exe",
10+
"build:linux-x64": "bun run scripts/build-fork-worker.ts && bun build --compile --target bun-linux-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-x64",
11+
"build:linux-arm64": "bun run scripts/build-fork-worker.ts && bun build --compile --target bun-linux-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-linux-arm64",
12+
"build:darwin-x64": "bun run scripts/build-fork-worker.ts && bun build --compile --target bun-darwin-x64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-x64",
13+
"build:darwin-arm64": "bun run scripts/build-fork-worker.ts && bun build --compile --target bun-darwin-arm64 --define \"require.resolve=undefined\" src/index.ts --outfile zcode-proxy-darwin-arm64",
14+
"build:android-bundle": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/android/server.cjs --define:process.env.NODE_ENV=\\\"production\\\" --external:./captcha-worker-asset.js",
1615
"build:android-apk": "bash scripts/build-android-apk.sh",
1716
"regen:mcp": "bun run scripts/regen-mcp-catalogue.ts"
1817
},

‎src/proxy/captcha-solver.ts‎

Lines changed: 9 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,24 @@
11
/**
2-
* Solver backend dispatch -- fork patch: out-of-thread solving.
2+
* Solver backend dispatch — fully in-process, self-contained.
33
*
4-
* Backend (ZCODE_CAPTCHA_BACKEND): "happy" (default) -- the happy-dom solver
5-
* in src/proxy/captcha-happy.ts.
6-
*
7-
* Fork change: the solver runs in a worker_threads Worker instead of on the
8-
* main thread. In-process solving froze the proxy's event loop via
9-
* Atomics.wait sync XHRs (each up to 30s), so a burst of parallel solves
10-
* stalled EVERY connection -- the "thinking for minutes after idle" failure.
11-
* Worker solving also isolates happy-dom's global browser-frame/cookie state
12-
* per solve (one Worker per solve, terminated after), removing cross-solve
13-
* races the in-process path suffered under parallel waves.
14-
*
15-
* Bundling: `bun build --compile` cannot resolve `new Worker(new URL(...))`
16-
* at runtime (module paths don't exist in the single-file binary), so the
17-
* worker entry is imported as a build-time FILE ASSET
18-
* (`import entryPath from "./captcha-worker-entry.ts" with { type: "file" }`)
19-
* and extracted to a temp path by the compiled runtime. Verified working in
20-
* compiled exes on Bun 1.4; plain `bun run` resolves the same asset import.
4+
* Backend (ZCODE_CAPTCHA_BACKEND): "happy" (default) — the happy-dom solver
5+
* in src/proxy/captcha-happy.ts, executed per captcha-worker-dispatch.ts:
6+
* one worker thread per solve (keeps Atomics.wait sync XHRs off the proxy's
7+
* event loop — issue #54) with an in-process fallback where the worker asset
8+
* is unavailable (dev checkouts, Docker TS-source image, Android bundle).
219
*/
22-
import { Worker } from "node:worker_threads";
23-
// Asset import: embeds the PRE-BUNDLED worker (plain JS, self-contained ESM --
24-
// built by scripts/build-fork-worker.ts before compilation; raw .ts assets
25-
// are not parsed by the compiled runtime). If the bundle is missing, run
26-
// scripts/build-fork-worker.ts to regenerate it (package.json wires it as
27-
// the prebuild hook). @ts-expect-error -- Bun's `with { type: "file" }`
28-
// asset import has no DOM-lib type declaration; the default export is the
29-
// extracted file path at runtime.
30-
// @ts-expect-error asset import
31-
import captchaWorkerEntryPath from "./captcha-worker-entry.bundle.js" with { type: "file" };
10+
import { solveViaWorkerOrInProcess } from "./captcha-worker-dispatch.js";
3211

3312
const BACKEND = process.env.ZCODE_CAPTCHA_BACKEND?.trim().toLowerCase() || "happy";
3413

35-
/** Per-solve timeout: overall deadline the worker gets before termination. */
36-
const SOLVE_WORKER_TIMEOUT_MS = Number(process.env.CAPTCHA_SOLVE_TIMEOUT_MS || 20_000);
37-
38-
interface SolveRequest {
39-
id: number;
40-
scene: string;
41-
region: string;
42-
prefix: string;
43-
}
44-
type SolveResponse = { id: number; ok: true; param: string } | { id: number; ok: false; error: string };
45-
46-
let nextSolveId = 0;
47-
4814
export async function runCaptchaSolve(scene: string, region: string, prefix: string): Promise<string> {
4915
if (BACKEND !== "happy") {
5016
throw new Error(`captcha backend "${BACKEND}" is not available; use ZCODE_CAPTCHA_BACKEND=happy`);
5117
}
52-
return solveInWorker({ scene, region, prefix });
53-
}
54-
55-
/**
56-
* One solve = one Worker. Startup cost is a few ms (happy-dom loads lazily
57-
* inside the entry on first message); termination guarantees no state leaks
58-
* between solves. A hung solve cannot wedge anything: the pool's takeToken
59-
* race deadline (25s) fires first, and the worker is force-terminated here.
60-
*/
61-
function solveInWorker(req: { scene: string; region: string; prefix: string }): Promise<string> {
62-
const id = ++nextSolveId;
63-
return new Promise<string>((resolve, reject) => {
64-
let settled = false;
65-
let worker: Worker | null = null;
66-
const settle = (fn: () => void) => {
67-
if (settled) return;
68-
settled = true;
69-
clearTimeout(timer);
70-
try { worker?.terminate(); } catch {}
71-
fn();
72-
};
73-
const timer = setTimeout(() => {
74-
settle(() => reject(new Error(`captcha worker timeout (${SOLVE_WORKER_TIMEOUT_MS}ms)`)));
75-
}, SOLVE_WORKER_TIMEOUT_MS);
76-
77-
try {
78-
worker = new Worker(captchaWorkerEntryPath);
79-
} catch (err) {
80-
settle(() => reject(new Error(`captcha worker spawn failed: ${(err as Error).message}`)));
81-
return;
82-
}
83-
const msg: SolveRequest = { id, ...req };
84-
worker.on("message", (m: SolveResponse) => {
85-
if (!m || m.id !== id) return;
86-
if (m.ok) settle(() => resolve(m.param));
87-
else settle(() => reject(new Error(m.error)));
88-
});
89-
worker.on("error", (err: Error) => {
90-
settle(() => reject(new Error(`captcha worker error: ${err.message}`)));
91-
});
92-
worker.on("exit", (code) => {
93-
if (code !== 0 && !settled) {
94-
settle(() => reject(new Error(`captcha worker exited (code ${code}) before solving`)));
95-
} else if (!settled) {
96-
settle(() => reject(new Error("captcha worker exited before responding")));
97-
}
98-
});
99-
worker.postMessage(msg);
100-
});
18+
return solveViaWorkerOrInProcess({ scene, region, prefix });
10119
}
10220

103-
/** Worker-per-solve needs no concurrency plumbing -- kept for the pool API. */
21+
/** Worker-per-solve needs no concurrency plumbing — kept for the pool API. */
10422
export function setCaptchaSolverConcurrency(_n: number): void {}
10523

10624
/** Nothing long-lived to shut down: workers are terminated per solve. */

‎src/proxy/captcha-worker-asset.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// @ts-nocheck -- the `with { type: "file" }` asset import below is a Bun-only
2+
// extension with no type declaration, and its target exists only after
3+
// scripts/build-fork-worker.ts has run (gitignored build input).
4+
/**
5+
* captcha-worker-asset.ts — sole carrier of Bun's file-asset import.
6+
*
7+
* The `with { type: "file" }` attribute is what embeds the pre-bundled worker
8+
* into `bun build --compile` single-file binaries (extracted to a temp path at
9+
* runtime; `new Worker(new URL(...))` does not survive compilation). Two
10+
* constraints shape this module's isolation:
11+
*
12+
* - esbuild (the Android server bundle) REJECTS the attribute at parse time
13+
* ("Importing with a type attribute of 'file' is not supported"), so this
14+
* file must be kept out of the esbuild graph: build:android-bundle marks it
15+
* --external, and consumers may only reach it via dynamic import.
16+
* - The asset file is absent on a fresh checkout, so a static import would
17+
* break `bun run dev` and the Docker image (both run TS sources) at module
18+
* load. Consumers must therefore dynamic-import THIS module and treat any
19+
* failure as "worker path unavailable" (fall back to in-process solving).
20+
*/
21+
import entryPath from "./captcha-worker-entry.bundle.js" with { type: "file" };
22+
23+
export default entryPath;
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
import { afterAll, describe, expect, mock, test } from "bun:test";
2+
import fs from "node:fs";
3+
import os from "node:os";
4+
import path from "node:path";
5+
import {
6+
__resetCaptchaWorkerDispatchForTest,
7+
solveViaWorkerOrInProcess,
8+
} from "./captcha-worker-dispatch.js";
9+
10+
// The dispatch layer must degrade, not fail, when the worker path is
11+
// unusable. Worker mode is exercised with a REAL worker_threads round trip
12+
// against a canned fixture entry (no happy-dom, no network); the fallback
13+
// cases replace the in-process solver with a mock. Module-level caches are
14+
// reset between cases via the test hook. (This file deliberately does NOT
15+
// import captcha-solver.js: captcha-pool.test.ts registers a process-wide
16+
// mock.module for that specifier, which would shadow the real exports.)
17+
describe("captcha worker dispatch (worker / in-process)", () => {
18+
const fixtureDir = fs.mkdtempSync(path.join(os.tmpdir(), "cap-worker-"));
19+
const fixturePath = path.join(fixtureDir, "fixture-worker.mjs");
20+
fs.writeFileSync(
21+
fixturePath,
22+
[
23+
'import { parentPort } from "node:worker_threads";',
24+
"if (!parentPort) throw new Error('fixture requires parent port');",
25+
"parentPort.on('message', (m) => {",
26+
" parentPort.postMessage({ id: m.id, ok: true, param: `fixture-param:${m.scene}:${m.region}` });",
27+
"});",
28+
].join("\n"),
29+
"utf8",
30+
);
31+
afterAll(() => {
32+
try { fs.rmSync(fixtureDir, { recursive: true, force: true }); } catch {}
33+
});
34+
35+
test("solves via a real worker when the entry asset resolves", async () => {
36+
mock.module("./captcha-worker-asset.js", () => ({ default: fixturePath }));
37+
__resetCaptchaWorkerDispatchForTest();
38+
const param = await solveViaWorkerOrInProcess({ scene: "sc1", region: "rg1", prefix: "pf1" });
39+
expect(param).toBe("fixture-param:sc1:rg1");
40+
});
41+
42+
test("falls back to in-process solving when the entry is unavailable", async () => {
43+
mock.module("./captcha-worker-asset.js", () => ({ default: null }));
44+
mock.module("./captcha-happy.js", () => ({
45+
solveTraceless: async (opts: { scene: string }) => `inproc-param:${opts.scene}`,
46+
}));
47+
__resetCaptchaWorkerDispatchForTest();
48+
const param = await solveViaWorkerOrInProcess({ scene: "sc2", region: "rg2", prefix: "pf2" });
49+
expect(param).toBe("inproc-param:sc2");
50+
});
51+
52+
test("an unloadable worker entry degrades to in-process solving", async () => {
53+
// A path that cannot be loaded as a worker module (a directory): Bun
54+
// reports it via the worker 'error' event as a module-not-found, which
55+
// must fall back, not reject (a runtime crash inside a LOADED worker,
56+
// by contrast, stays a hard failure handled by the pool's retry ladder).
57+
mock.module("./captcha-worker-asset.js", () => ({ default: fixtureDir }));
58+
mock.module("./captcha-happy.js", () => ({
59+
solveTraceless: async (opts: { scene: string }) => `inproc-param:${opts.scene}`,
60+
}));
61+
__resetCaptchaWorkerDispatchForTest();
62+
const param = await solveViaWorkerOrInProcess({ scene: "sc3", region: "rg3", prefix: "pf3" });
63+
expect(param).toBe("inproc-param:sc3");
64+
});
65+
});

0 commit comments

Comments
 (0)