feat(host-service): generic worker_threads pool — git status + commit-files off the event loop
Merged
KI
4mo ago+1469+1469+0123456789012345678901234567890123456789-18-18-01234567890123456789
Links
- Linear: SUPER-1544
- Design + measurements:
plans/20260717-host-service-git-worker-pool.md(#5746)
Summary
- Adds a generic
worker_threadspool inside host-service (packages/host-service/src/workers/) and movesgit.getStatus+git.getCommitFilescompute onto it. The worker spawns the git subprocesses itself, so stdout draining AND parsing leave the event loop that also relays terminal I/O and serves all tRPC/WS for the org. - v1 had exactly this offload (
git-task-worker); v2 lost it. Stress tests showed backgroundgetStatusqueueing 3.7–14.6s under 8-workspace churn — this PR is the infrastructure that makes raising the limiter's concurrency safe (deferred, see Follow-ups).
How It Works
- Runner:
WorkerTaskRunnerported from v1 desktop (v1 keeps its copy; it retires with v1) with two changes: idle reaping (workers terminated after 30s idle — host-service is per-org and long-lived, a 3-org machine must not hold 12 warm workers) and demand-sized spawning (v1 spawned the full pool on any task). - Static registry: task modules export
defineWorkerTask<In, Out>defs, namespacedgit/*;host-worker.tsimports them into a build-time registry. Callers pass the same def toHostWorkerPool.run()for end-to-end typing. Adding a domain = one task module + one import. - Inline fallback: missing bundle → run handlers on the main thread (pre-PR behavior) with one warning; worker crash → task retried inline, 3 crashes/60s opens a circuit to inline-only. Pool infrastructure can never fail a caller.
- Credential env:
createGitEnvResolversplit out ofcreateGitFactory— the env is resolved in-process (needs the credential provider) and crosses to the worker as plain data; the worker builds its own SimpleGit. - Bundling (side-by-side with host-service.js, same pattern as pty-daemon): electron-vite input via
apps/desktop/src/main/host-worker/index.ts, secondBun.buildinpackages/host-service/build.ts, copy inpackages/cli/scripts/build-dist.ts. Resolution:SUPERSET_HOST_WORKER_SCRIPT_PATH→ side-by-side → workspace dist → inline fallback.
Manual QA Checklist
- Dev app E2E:
git.getStatuson the superset repo through the real app returns a correct snapshot in worker mode (435ms; zero[host-worker-pool]fallback warnings in the host-service log;dist/main/host-worker.jsemitted) - Standalone bundle:
bun run build:hostemitsdist/host-worker.js; plain-node smoke (new Worker('./dist/host-worker.js')) round-trips the task protocol (ESM entry works under node)
Testing
src/workers/host-worker-pool.test.ts(6 tests): worker↔inline parity on a real fixture repo (modified/staged/untracked buckets), unknown-task error propagation, idle reaping, missing-bundle inline fallback, crash → inline retry → circuit open. Mutation-verified: disabling reaping fails the reap test; removing the inline retry fails the crash test.src/workers/no-native-worker-imports.test.ts: worker graph stays free of native addons and process singletons (db/events/daemon); transitive regressions fail the host-worker bundle build.- Full host-service suite (904 tests),
bun run typecheck(host-service + desktop),bun run lintclean.
Design Decisions
- Copy the v1 runner instead of extracting a shared package: v1 is sunset; its copy dies with it (repo v1/v2 duplication policy).
- Handlers ship in both the main bundle and the worker bundle: the inline fallback requires them in-process anyway; the git helpers were already in the main bundle.
- Pool concurrency mirrors the limiter's
min(4, cpus−1): the limiter stays the only queue for status refreshes; pooled tasks never meaningfully queue behind it.
Known Limitations
scheduleBaseRefFetch's dedupe state is per-thread now — N workers can, worst case, schedule up to N base-ref fetches for the same worktree within one freshness window. Bounded and rare; noting rather than complicating the payload.
Follow-ups
- Raise
gitStatusRefreshLimiterconcurrency now that snapshots don't cost loop time (measure first) - GitWatcher rescan/filtering offload — the actual loop-stall driver under many-workspace churn (per the measured findings)
getDiff/listCommits/getBranchSyncStatustenants
Summary by cubic
Introduces a generic worker_threads pool for packages/host-service and moves git.getStatus and git.getCommitFiles off the event loop to cut stalls and improve responsiveness. Addresses SUPER-1544 by restoring v1’s offload pattern, adding commit-file task deduping ahead of a small cap, and hardening the inline fallback (sync-throw safe, coalesced inline crash-retry).
-
New Features
- Added
WorkerTaskRunnerpool with demand-based spawning and 30s idle reaping; concurrency defaults tomin(4, cpus−1)+2. - Inline fallback and crash handling: worker crashes retry inline; coalesced crashes count once; after 3 crashes/60s open an inline-only circuit and reject the queued backlog; inline path mirrors timeout/abort semantics and is sync-throw safe; re-drains after
postMessagefailures so bad payloads don’t wedge a slot. - Typed task registry and worker entry for
git/*tasks;createGitEnvResolverresolves credential env in-process and passes plain data to the worker. - Switched tRPC
git.getStatusSnapshotandgit.getCommitFilesto the pool with 15s timeouts; commit-file tasks capped at 2 and deduped by key outside the cap so identical requests share one slot and one run.
- Added
-
Dependencies
- Built and ship
host-worker.jsside-by-side withhost-service.js:apps/desktopaddssrc/main/host-worker/index.tsto electron-vite.packages/host-service/build.tsemitshost-worker.js(ESM);packages/cli/scripts/build-dist.tscopies it next tohost-service.js.
- Added
exportsentry./host-workerinpackages/host-service/package.jsonand resolution orderSUPERSET_HOST_WORKER_SCRIPT_PATH→ side-by-side → workspacedist→ inline fallback.
- Built and ship
Summary by CodeRabbit
- New Features
- Git status and commit-file operations now run in the background for improved app responsiveness.
- Added support for efficient handling of repeated Git requests.
- Bug Fixes
- Improved resilience when background processing is unavailable or interrupted by automatically retrying operations through a fallback path.
- Added safeguards for timeouts, cancellation, and worker failures.
- Chores
- Updated desktop and distribution packaging to include the required background-processing support.