From 986f2eb62fad3e3867da2979862b77ba7020ba45 Mon Sep 17 00:00:00 2001 From: owjs3901 Date: Sun, 15 Nov 2026 17:25:16 +0900 Subject: [PATCH] fix(next-plugin): fail a build whose coordinator CSS is incomplete The coordinator's /css wait used to give up after a quiet window or its hard timeout and still answer 200 with whatever the sheet held. A build bundles that first answer as its stylesheet, so a missing file shipped class names without their rules and the build reported success. The base and bucket waits now resolve with a reason when they give up, and /css answers 500 with a message naming the files that never extracted. The CSS loader passes the coordinator's reason into the loader error, so Turbopack fails the build with it. Only builds wait; next dev never asks to, so development behaviour is unchanged. The idle heuristic used when no expected file set exists still answers 200. Refs #686 Co-Authored-By: Claude Opus 5.5 --- ...changepack_log_next_partial_css_error.json | 1 + .../src/__tests__/coordinator.test.ts | 150 +++++++++--------- .../src/__tests__/css-loader.test.ts | 37 ++++- packages/next-plugin/src/coordinator.ts | 141 ++++++++++------ packages/next-plugin/src/css-loader.ts | 12 +- 5 files changed, 212 insertions(+), 129 deletions(-) create mode 100644 .changepacks/changepack_log_next_partial_css_error.json diff --git a/.changepacks/changepack_log_next_partial_css_error.json b/.changepacks/changepack_log_next_partial_css_error.json new file mode 100644 index 000000000..7a348c934 --- /dev/null +++ b/.changepacks/changepack_log_next_partial_css_error.json @@ -0,0 +1 @@ +{"changes":{"packages/next-plugin/package.json":"Patch"},"note":"Fail a Turbopack build whose CSS the coordinator cannot prove complete, naming the files that never extracted, instead of answering with partial CSS","date":"2026-11-15T00:00:00.000Z"} diff --git a/packages/next-plugin/src/__tests__/coordinator.test.ts b/packages/next-plugin/src/__tests__/coordinator.test.ts index 7d346a6ba..0a1fecd58 100644 --- a/packages/next-plugin/src/__tests__/coordinator.test.ts +++ b/packages/next-plugin/src/__tests__/coordinator.test.ts @@ -767,15 +767,19 @@ describe('coordinator', () => { try { // Request CSS with waitForIdle=true but no extractions ever happen - // (totalExtractions === 0), so it should timeout and return CSS anyway + // (totalExtractions === 0): the wait times out and refuses to answer + // with CSS it cannot prove complete. const res = await httpRequest( port, 'GET', '/css?importMainCss=false&waitForIdle=true', ) - expect(res.status).toBe(200) - expect(res.body).toBe('timeout-css') + expect(res.status).toBe(500) + expect(res.body).toBe( + '[devup-ui] coordinator: base CSS is incomplete (not complete after 60000ms); refusing to serve partial CSS.', + ) + expect(getCssSpy).not.toHaveBeenCalled() } finally { dateNowSpy.mockRestore() } @@ -1385,40 +1389,38 @@ describe('coordinator per-bucket completion', () => { coordinator.close() }) - // T3: a bucket member that never arrives -> the per-bucket wait fails open - // after maxWaitMs (serves whatever exists) instead of hanging the build. - it('fails open and serves partial CSS when a bucket member never extracts', async () => { + // T3: a bucket member that never arrives -> the per-bucket wait gives up + // after maxWaitMs with an error naming the member, instead of hanging the + // build or serving the chunk without that member's rules. + it('fails the request instead of serving partial CSS when a bucket member never extracts', async () => { codeExtractSpy.mockReturnValue(extractResult('devup-ui-1.css')) getCssSpy.mockReturnValue('partial-css') - const warnSpy = spyOn(console, 'warn').mockReturnValue(undefined) - try { - // m1 is a member of the bucket but is never POSTed to /extract. - const canonicalMap = { 'src/m1.tsx': 'src/bucket.tsx' } - const { coordinator, port } = await startAndGetPort( - makeOptions({ canonicalMap, idleThresholdMs: 100, maxWaitMs: 150 }), - ) - // Extract only the bucket root; src/m1.tsx stays missing forever. - await extract(port, 'src/bucket.tsx') + // m1 is a member of the bucket but is never POSTed to /extract. + const canonicalMap = { 'src/m1.tsx': 'src/bucket.tsx' } + const { coordinator, port } = await startAndGetPort( + makeOptions({ canonicalMap, idleThresholdMs: 100, maxWaitMs: 150 }), + ) + // Extract only the bucket root; src/m1.tsx stays missing forever. + await extract(port, 'src/bucket.tsx') + getCssSpy.mockClear() - const t0 = Date.now() - const res = await httpRequest( - port, - 'GET', - '/css?fileNum=1&importMainCss=true&waitForIdle=true', - ) - const elapsed = Date.now() - t0 + const t0 = Date.now() + const res = await httpRequest( + port, + 'GET', + '/css?fileNum=1&importMainCss=true&waitForIdle=true', + ) + const elapsed = Date.now() - t0 - // Resolves via the hard timeout (fail open) rather than hanging. - expect(res.status).toBe(200) - expect(res.body).toBe('partial-css') - expect(elapsed).toBeGreaterThanOrEqual(150) - expect(warnSpy).toHaveBeenCalled() - expect(getCssSpy).toHaveBeenCalledWith(1, true) + // Resolves via the hard timeout rather than hanging, and says why. + expect(res.status).toBe(500) + expect(res.body).toBe( + '[devup-ui] coordinator: bucket "src/bucket.tsx" is incomplete (not complete after 150ms); refusing to serve partial CSS. Files not extracted: src/m1.tsx.', + ) + expect(elapsed).toBeGreaterThanOrEqual(150) + expect(getCssSpy).not.toHaveBeenCalled() - coordinator.close() - } finally { - warnSpy.mockRestore() - } + coordinator.close() }) // T4: base css resolves DETERMINISTICALLY once every route-reachable runtime @@ -1552,49 +1554,39 @@ describe('coordinator per-bucket completion', () => { coordinator.close() }) - // T7: legacy callers that do not prewarm still fail open after the quiet - // window when a graph member never reports, rather than hanging forever. - // Production plugin builds take the deterministic prewarmed path instead. - it('serves a bucket via the quiet exit when a member is never compiled', async () => { + // T7: when a known member never reports and extraction goes quiet, the wait + // gives up early with an error naming it. Production plugin builds take the + // deterministic prewarmed path instead and never get here. + it('fails a bucket after the quiet window when a member is never compiled', async () => { codeExtractSpy.mockReturnValue(extractResult('devup-ui-1.css')) getCssSpy.mockReturnValue('bucket-css') - const infoSpy = spyOn(console, 'info').mockReturnValue(undefined) - try { - const warnSpy = spyOn(console, 'warn').mockReturnValue(undefined) - try { - const canonicalMap = { 'src/phantom.tsx': 'src/bucket.tsx' } - const { coordinator, port } = await startAndGetPort( - makeOptions({ canonicalMap, quietMs: 100, maxWaitMs: 10_000 }), - ) - await extract(port, 'src/bucket.tsx') + const canonicalMap = { 'src/phantom.tsx': 'src/bucket.tsx' } + const { coordinator, port } = await startAndGetPort( + makeOptions({ canonicalMap, quietMs: 100, maxWaitMs: 10_000 }), + ) + await extract(port, 'src/bucket.tsx') - const t0 = Date.now() - const res = await httpRequest( - port, - 'GET', - '/css?fileNum=1&importMainCss=true&waitForIdle=true', - ) - const elapsed = Date.now() - t0 - - expect(res.status).toBe(200) - expect(res.body).toBe('bucket-css') - // Resolved by the quiet exit (~100ms), NOT the 10s wall-clock backstop. - expect(elapsed).toBeLessThan(5000) - expect(infoSpy).toHaveBeenCalled() - expect(warnSpy).not.toHaveBeenCalled() - - coordinator.close() - } finally { - warnSpy.mockRestore() - } - } finally { - infoSpy.mockRestore() - } + const t0 = Date.now() + const res = await httpRequest( + port, + 'GET', + '/css?fileNum=1&importMainCss=true&waitForIdle=true', + ) + const elapsed = Date.now() - t0 + + expect(res.status).toBe(500) + expect(res.body).toBe( + '[devup-ui] coordinator: bucket "src/bucket.tsx" is incomplete (no extraction for 100ms); refusing to serve partial CSS. Files not extracted: src/phantom.tsx.', + ) + // Ended by the quiet window (~100ms), NOT the 10s wall-clock backstop. + expect(elapsed).toBeLessThan(5000) + + coordinator.close() }) - // T8: the same legacy quiet fallback applies to an expected base file when - // the caller did not seed prewarmed completion state. - it('serves base css via the quiet exit when an expectedBaseFile is never compiled', async () => { + // T8: the same quiet window ends a base wait whose expected file never + // reports when the caller did not seed prewarmed completion state. + it('fails base css after the quiet window when an expectedBaseFile is never compiled', async () => { codeExtractSpy.mockReturnValue(extractResult('devup-ui.css')) getCssSpy.mockReturnValue('base-css') const { coordinator, port } = await startAndGetPort( @@ -1614,17 +1606,19 @@ describe('coordinator per-bucket completion', () => { ) const elapsed = Date.now() - t0 - expect(res.status).toBe(200) - expect(res.body).toBe('base-css') + expect(res.status).toBe(500) + expect(res.body).toBe( + '[devup-ui] coordinator: base CSS is incomplete (no extraction for 100ms); refusing to serve partial CSS. Files not extracted: src/phantom.tsx.', + ) // Quiet exit (~100ms), not the 10s backstop. expect(elapsed).toBeLessThan(5000) coordinator.close() }) - // T6: a phantom expectedBaseFile that never extracts fails open via the - // dormant maxWaitMs backstop instead of hanging the build forever. - it('fails open on a phantom expectedBaseFile via maxWaitMs', async () => { + // T6: a phantom expectedBaseFile that never extracts ends the wait via the + // dormant maxWaitMs backstop with an error instead of hanging the build. + it('fails a phantom expectedBaseFile via maxWaitMs', async () => { codeExtractSpy.mockReturnValue(extractResult('devup-ui.css')) getCssSpy.mockReturnValue('base-css') const { coordinator, port } = await startAndGetPort( @@ -1643,8 +1637,10 @@ describe('coordinator per-bucket completion', () => { ) const elapsed = Date.now() - t0 - expect(res.status).toBe(200) - expect(res.body).toBe('base-css') + expect(res.status).toBe(500) + expect(res.body).toBe( + '[devup-ui] coordinator: base CSS is incomplete (not complete after 150ms); refusing to serve partial CSS. Files not extracted: src/phantom.tsx.', + ) expect(elapsed).toBeGreaterThanOrEqual(150) coordinator.close() diff --git a/packages/next-plugin/src/__tests__/css-loader.test.ts b/packages/next-plugin/src/__tests__/css-loader.test.ts index a9fa200a0..c01572492 100644 --- a/packages/next-plugin/src/__tests__/css-loader.test.ts +++ b/packages/next-plugin/src/__tests__/css-loader.test.ts @@ -397,7 +397,42 @@ describe('devupUICssLoader', () => { } as unknown as CssLoaderThis)(Buffer.from(''), '', '') }) - expect(error.message).toBe('Coordinator CSS error: 500') + expect(error.message).toBe( + 'Coordinator CSS error: 500: Internal Server Error', + ) + server.close() + }) + + it('should error with only the status when the coordinator sends no reason', async () => { + const server = http.createServer((_req, res) => { + res.writeHead(503) + res.end() + }) + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)) + const port = (server.address() as { port: number }).port + const portFile = `test-coordinator-empty-err-${port}.port` + + existsSyncSpy.mockImplementation((p: unknown) => p === portFile) + readFileSyncSpy.mockImplementation((p: unknown) => + p === portFile ? String(port) : '{}', + ) + + const error = await new Promise((resolve) => { + const asyncCallback = mock((err: Error | null) => { + if (err) resolve(err) + }) + devupUICssLoader.bind({ + async: () => asyncCallback, + addContextDependency: mock(), + getOptions: () => ({ + ...defaultOptions, + coordinatorPortFile: portFile, + }), + resourcePath: 'devup-ui.css', + } as unknown as CssLoaderThis)(Buffer.from(''), '', '') + }) + + expect(error.message).toBe('Coordinator CSS error: 503') server.close() }) diff --git a/packages/next-plugin/src/coordinator.ts b/packages/next-plugin/src/coordinator.ts index 892f8287d..8b73c5891 100644 --- a/packages/next-plugin/src/coordinator.ts +++ b/packages/next-plugin/src/coordinator.ts @@ -55,16 +55,17 @@ export interface CoordinatorOptions { */ idleThresholdMs?: number /** - * Legacy fail-open window (ms) used when completion was not prewarmed and a - * graph member never reports. A quiet window cannot prove that Turbopack is - * finished scheduling loaders, so the production plugin avoids depending on - * this heuristic by extracting its complete route closure up front. Defaults - * to 10000. Exposed for tests; the plugin omits it. + * Quiet window (ms) after which a wait whose known files are still missing + * gives up with an error naming them, instead of serving partial CSS. The + * production plugin prewarms its whole route closure, so this only fires + * when that closure and the loaders disagree. Defaults to 10000. Exposed for + * tests; the plugin omits it. */ quietMs?: number /** - * Hard timeout (ms) for both the idle and per-bucket waits before failing - * open. Defaults to 60000. Exposed for tests; the plugin omits it. + * Hard timeout (ms) for both the idle and per-bucket waits. A wait that hits + * it answers `/css` with an error rather than partial CSS. Defaults to 60000. + * Exposed for tests; the plugin omits it. */ maxWaitMs?: number } @@ -199,10 +200,10 @@ let idleThresholdMs = 2500 let quietMs = 10_000 let maxWaitMs = 60_000 -// Legacy fail-open signal for callers that could not prewarm a deterministic -// file set. It only observes extraction traffic; it is NOT a Turbopack -// compilation-complete signal. Production builds seed `extractedFiles` with -// their prewarmed route closure and therefore do not depend on this path. +// Give-up signal for a wait whose known files never report. It only observes +// extraction traffic; it is NOT a Turbopack compilation-complete signal, so it +// ends the wait with an error, never with partial CSS. Production builds seed +// `extractedFiles` with their prewarmed route closure and never reach it. function bundlerQuiet(now: number): boolean { return ( totalExtractions > 0 && @@ -222,7 +223,27 @@ function baseFilesComplete(): boolean { return true } -function waitForBase(): Promise { +function missingFiles(files: Iterable): string[] { + return [...files].filter((file) => !extractedFiles.has(file)) +} + +/** + * Why a `/css` wait could not prove its CSS complete. The CSS loader fails the + * build with this message: Turbopack bundles the first `/css` answer as the + * stylesheet, so partial CSS would ship class names without their rules. + */ +function incompleteCssError( + target: string, + reason: string, + missing: string[], +): string { + const files = + missing.length > 0 ? ` Files not extracted: ${missing.join(', ')}.` : '' + return `[devup-ui] coordinator: ${target} is incomplete (${reason}); refusing to serve partial CSS.${files}` +} + +/** Resolves with an error message when the base sheet cannot be completed. */ +function waitForBase(): Promise { const start = Date.now() return new Promise((resolve) => { const check = () => { @@ -231,18 +252,30 @@ function waitForBase(): Promise { // Last-resort backstop (see waitForBucket). Never fires on a healthy // build: either every expected file extracts, or the idle fallback // resolves first. - resolve() + resolve( + incompleteCssError( + 'base CSS', + `not complete after ${maxWaitMs}ms`, + missingFiles(expectedBaseFiles), + ), + ) return } // Primary, deterministic path. if (baseFilesComplete()) { - resolve() + resolve(undefined) return } - // Legacy fail-open for a caller that supplied expected files without - // prewarming them. The Next plugin's production path completes above. + // Expected files stopped arriving. The Next plugin's production path + // prewarms them and completes above, so this is a real gap. if (expectedBaseFiles.size > 0 && bundlerQuiet(now)) { - resolve() + resolve( + incompleteCssError( + 'base CSS', + `no extraction for ${quietMs}ms`, + missingFiles(expectedBaseFiles), + ), + ) return } // Fallback ONLY when no deterministic signal exists (no routes detected / @@ -254,7 +287,7 @@ function waitForBase(): Promise { pendingExtractStarts === 0 && now - lastCompletedAt >= idleThresholdMs ) { - resolve() + resolve(undefined) return } setTimeout(check, 25) @@ -300,33 +333,29 @@ function buildBucketToMembers( return map } -function waitForBucket(bucket: string): Promise { +/** Resolves with an error message when the bucket cannot be completed. */ +function waitForBucket(bucket: string): Promise { const members = bucketToMembers.get(bucket) ?? new Set([bucket]) const start = Date.now() return new Promise((resolve) => { const check = () => { - let allExtracted = true - for (const member of members) { - if (!extractedFiles.has(member)) { - allExtracted = false - break - } - } - if (allExtracted) { - resolve() + const missing = missingFiles(members) + if (missing.length === 0) { + resolve(undefined) return } const now = Date.now() - // Legacy fail-open for a caller that did not seed the bucket through - // prewarming. Quiet time alone cannot distinguish an erased import from - // a later Turbopack extraction wave; production builds complete via the - // allExtracted branch above. + // Members stopped arriving. Quiet time alone cannot tell an erased + // import from a later Turbopack wave, so serving now could drop a late + // member's rules; production builds complete above via prewarming. if (bundlerQuiet(now)) { - const missing = [...members].filter((m) => !extractedFiles.has(m)) - console.info( - `[devup-ui] coordinator: serving bucket "${bucket}" through the legacy quiet fallback; treating unreported member(s) as erased imports: ${missing.join(', ')}`, + resolve( + incompleteCssError( + `bucket "${bucket}"`, + `no extraction for ${quietMs}ms`, + missing, + ), ) - resolve() return } if (now - start > maxWaitMs) { @@ -335,11 +364,13 @@ function waitForBucket(bucket: string): Promise { // within the whole window (a continuously busy build with a genuinely // missing member). Turbopack exposes no compilation-complete hook, so // a timer is the only available backstop against hanging forever. - const missing = [...members].filter((m) => !extractedFiles.has(m)) - console.warn( - `[devup-ui] coordinator: bucket "${bucket}" not complete after ${maxWaitMs}ms; serving partial CSS (missing: ${missing.join(', ')})`, + resolve( + incompleteCssError( + `bucket "${bucket}"`, + `not complete after ${maxWaitMs}ms`, + missing, + ), ) - resolve() return } setTimeout(check, 25) @@ -408,15 +439,27 @@ export function startCoordinator(options: CoordinatorOptions): { const fileNum = fileNumParam != null ? parseInt(fileNumParam) : undefined if (shouldWait) { - if (fileNum != null && fileNumToBucket.has(fileNum)) { - // Deterministic: block until every member of this collapsed bucket - // has been extracted, then serve the complete chunk. - await waitForBucket(fileNumToBucket.get(fileNum)!) - } else { - // Base css (no fileNum) or a bucket no member has reported yet: - // wait for the deterministic route-reachable file set (idle fallback - // only when that set is unavailable). - await waitForBase() + const incomplete = + fileNum != null && fileNumToBucket.has(fileNum) + ? // Deterministic: block until every member of this collapsed + // bucket has been extracted, then serve the complete chunk. + await waitForBucket(fileNumToBucket.get(fileNum)!) + : // Base css (no fileNum) or a bucket no member has reported yet: + // wait for the deterministic route-reachable file set (idle + // fallback only when that set is unavailable). + await waitForBase() + if (incomplete !== undefined) { + // Only builds wait (`next dev` never asks to), and a build bundles + // this answer as its stylesheet: fail it rather than ship gaps. + res.writeHead(500, { 'Content-Type': 'text/plain' }) + res.end(incomplete) + reportProfile('coordinator.css', { + durationMs: elapsedMs(cssStartedAt), + fileNum, + incomplete: true, + waitForIdle: shouldWait, + }) + return } } diff --git a/packages/next-plugin/src/css-loader.ts b/packages/next-plugin/src/css-loader.ts index 5a414c8cd..9f1b8577f 100644 --- a/packages/next-plugin/src/css-loader.ts +++ b/packages/next-plugin/src/css-loader.ts @@ -64,11 +64,19 @@ function fetchCssFromCoordinator( const chunks: Buffer[] = [] res.on('data', (chunk: Buffer) => chunks.push(chunk)) res.on('end', () => { + const body = Buffer.concat(chunks).toString('utf-8') if (res.statusCode !== 200) { - callback(new Error(`Coordinator CSS error: ${res.statusCode}`)) + // The coordinator says why (e.g. which files never extracted). + callback( + new Error( + body + ? `Coordinator CSS error: ${res.statusCode}: ${body}` + : `Coordinator CSS error: ${res.statusCode}`, + ), + ) return } - callback(null, Buffer.concat(chunks).toString('utf-8')) + callback(null, body) }) }, )