ReviewOS

stacks/stx

streaming: suspense error-UI fallback is untested — silent regression risk

#1711
Closed glennmichael123 opened this 23 days ago · 0 comments
23 days ago

TL;DR

packages/stx/src/streaming.ts:334 contains the catch handler that renders the error UI to the client when an async island (suspense boundary, @async component, etc.) rejects mid-stream. Zero tests cover this path. If someone refactors the streaming pipeline and the error UI silently stops rendering, no test will catch it — production users would see a hang or an empty container instead of the intended fallback.

What the path does

(Paraphrasing from the audit; see the file for the actual implementation.)

Inside the streaming response loop, when one of the suspended chunks' promises rejects, the catch:

  • logs the error server-side
  • writes a fallback marker into the response stream so the client-side runtime knows to swap that island's placeholder for the error UI
  • continues streaming the rest of the document

If any of those three steps regress, the failure mode is invisible (empty or stuck island, no error in the console of the user's tab; only the server log mentions it).

Why it's hard to test

The natural way to exercise the path is:

  1. Render a page with a @async component
  2. Have the async work throw or reject
  3. Assert the streamed response contains the error fallback marker
  4. Assert that when the client runtime sees that marker, it renders the error UI in the right slot

That requires a streaming integration test — not the typical processDirectives() unit test pattern that most of the directive tests use. The test infrastructure exists (bun:test with happy-dom preloaded), but no test currently sets up a streaming response + reject + assertion.

Proposed shape of a regression test

import { describe, it, expect } from 'bun:test'
import { renderToStream } from 'stx'

describe('streaming: suspense error fallback', () => {
  it('renders the error UI when an async island rejects', async () => {
    const stream = renderToStream(`
      @async('FailingIsland', timeout: 1000)
      @fallback
        <div data-test="fallback">loading…</div>
      @enderror

      <FailingIsland />
    `, {
      // force the async resolver to throw for FailingIsland
      mockAsyncResolvers: { FailingIsland: () => Promise.reject(new Error('boom')) },
    })
    const text = await new Response(stream).text()
    expect(text).toContain('data-stx-async-error')   // the marker
    // …and a client-side test that the runtime swaps it to error UI
  })
})

The audit also flagged these untested error paths in the same neighborhood, lower severity:

  • packages/stx/src/inline-assets.ts:27, 103, 154 — file-read errors return null silently (assets skipped without warning)
  • packages/stx/src/middleware.ts:118 — middleware execution errors logged but continue
  • packages/stx/src/component-renderer.ts:147 — JSON.parse() on __stx_* prop fails silently

If a regression suite for streaming + suspense is being added, including these would close out the user-facing untested error surface in one pass.

Found during a deep-scan audit.

🤖 Filed via Claude Code

Sign in to comment on this issue.