Skip to content

fix(next-plugin): keep coordinator state per process on a shared distDir - #941

Open
owjs3901 wants to merge 2 commits into
mainfrom
fix/next-state-per-process
Open

owjs3901 wants to merge 2 commits into
mainfrom
fix/next-state-per-process

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes the remaining part of audit item NXT-08 (P1, NONDET). On main, the port file is already separated: if another live process holds distDir/coordinator.port, coordinator.<pid>.port is used. But the state files (sheet.json, classMap.json, fileMap.json, canonicalMap.json, setup.bin) still used the same paths. So next dev and next build in the same directory overwrote each other's state, and the next restore could pick up a state mixing two builds.

  • Added resolveStateDir(distDir, portFile) to coordinator-port.ts
    • A process holding the shared port file uses distDir, as before
    • A process that got its own port file uses distDir/state.<pid>
  • Such a process writes state only to state.<pid> (coordinator writes, loader options, canonical map, production setup handoff).
  • Restore always reads from the shared distDir files, because the Turbopack persistent cache was built against that state.
  • On startup, removeStaleStateDirs(distDir) removes state.<pid> directories of exited processes (if locked on Windows, it retries on the next start).
  • A single process still uses distDir, so behavior and loader option keys in the common case do not change.
  • cssDir (devup-ui*.css) is still shared. In Turbopack coordinator mode, CSS content comes from each coordinator's /css, and the files on disk only serve as invalidation triggers and placeholders, so they do not pollute each other's CSS. However, the other process's writes can cause unnecessary recompiles.

Overlap with other PRs

Test plan

  • bun test --coverage (plugin, coordinator-port, coordinator, loader, css-loader): plugin.ts, coordinator-port.ts 100% lines / functions
    • Shared port → distDir, own port → state.<pid>
    • Removes only directories of exited pids and keeps its own / live / non-matching-name directories. Does not throw if distDir is missing or rmSync fails
    • With its own port file: creates state.<pid>, restores from the shared state, and coordinator / loader / canonical map / setup handoff write to state.<pid>
    • Changed the existing restart restore tests to path-based mocks (because the port file check now happens before restore)
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (changed files)
  • Locally, 3 tests in plugin.test.ts (native engine / seedFileMap) fail the same way on main as well, due to stale WASM / native builds.

요약

감사 항목 NXT-08 (P1, NONDET)의 남은 부분 수정입니다. main에서 port 파일은 이미 분리됩니다: 다른 live 프로세스가 distDir/coordinator.port를 갖고 있으면 coordinator.<pid>.port를 씁니다. 하지만 상태 파일(sheet.json, classMap.json, fileMap.json, canonicalMap.json, setup.bin)은 여전히 같은 경로를 썼습니다. 그래서 같은 디렉터리의 next dev와 next build가 서로의 상태를 덮어쓰고, 다음 restore가 두 빌드가 섞인 상태를 가져올 수 있었습니다.

  • coordinator-port.ts에 resolveStateDir(distDir, portFile) 추가
    • 공유 port 파일을 가진 프로세스는 기존처럼 distDir
    • 자기 port 파일을 받은 프로세스는 distDir/state.<pid>
  • 그런 프로세스는 상태를 state.<pid>에만 씁니다 (코디네이터 쓰기, loader 옵션, canonical map, production setup handoff).
  • restore는 항상 공유 distDir 파일에서 읽습니다. Turbopack persistent cache가 그 상태를 기준으로 만들어졌기 때문입니다.
  • 시작할 때 removeStaleStateDirs(distDir)가 종료된 프로세스의 state.<pid> 디렉터리를 지웁니다 (Windows에서 잠겨 있으면 다음 시작에서 다시 시도).
  • 단일 프로세스는 계속 distDir을 쓰므로 일반적인 경우의 동작과 loader 옵션 키는 바뀌지 않습니다.
  • cssDir(devup-ui*.css)는 여전히 공유합니다. Turbopack 코디네이터 모드에서 CSS 내용은 각 코디네이터의 /css에서 오고, 디스크 파일은 무효화 트리거와 placeholder 역할만 하므로 서로의 CSS를 오염시키지 않습니다. 대신 상대 프로세스의 쓰기가 불필요한 재컴파일을 일으킬 수는 있습니다.

다른 PR과의 겹침

테스트 계획

  • bun test --coverage (plugin, coordinator-port, coordinator, loader, css-loader): plugin.ts, coordinator-port.ts 100% lines / functions
    • 공유 port면 distDir, 자기 port면 state.<pid>
    • 종료된 pid의 디렉터리만 지우고 자신 / live / 이름이 맞지 않는 디렉터리는 남김. distDir이 없거나 rmSync가 실패해도 throw하지 않음
    • 자기 port 파일을 받은 경우 state.<pid> 생성, 공유 상태에서 restore, 코디네이터 / loader / canonical map / setup handoff는 state.<pid>로 씀
    • 기존 restart restore 테스트를 경로 기반 mock으로 바꿈 (port 파일 확인이 restore보다 먼저 일어나도록 바뀌었기 때문)
  • bunx tsc --noEmit -p packages/next-plugin
  • bunx prettier --single-quote --no-semi --check (변경 파일)
  • 로컬에서 plugin.test.ts의 3개 테스트(native 엔진 / seedFileMap)는 오래된 WASM / native 빌드 때문에 main에서도 동일하게 실패합니다.

Refs #694

🤖 Generated with Claude Code

A process that finds another live coordinator on its distDir already
takes its own coordinator.<pid>.port, but it still wrote the same
sheet.json, classMap.json, fileMap.json, canonicalMap.json and
setup.bin. A next dev and a next build in one directory therefore
overwrote each other's state, and the next restore imported a mix of
both.

Such a process now writes its state to distDir/state.<pid>. It still
restores from the shared distDir files, which are what Turbopack's
persistent cache was built against. The process holding the shared
port file keeps distDir, so the single-process case is unchanged.
Startup removes the state.<pid> directories of processes that have
exited.

Refs #694

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

codecov Bot commented Nov 15, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

Files with missing lines Coverage Δ
packages/next-plugin/src/coordinator-port.ts 100.00% <100.00%> (ø)
packages/next-plugin/src/plugin.ts 100.00% <100.00%> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

#918 restores session state through restoreSessionState; keep calling it
with the shared distDir files, so a process with its own state dir still
starts from what the cache was built against.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant