fix(blob): harden FileBackedBlob.stream() cancel/cleanup paths (#1457)

[kriszyp]

Closes #1457.

Fixes pre-existing reliability/correctness hazards in resources/blob.ts FileBackedBlob.stream(), surfaced by the cross-model review of #1454 / PR #1456 in code those PRs do not change. None are regressions from #1456 — they predate it.

What changed

The five hazards listed in #1457:

1. fd not nulled after close → double-close on a reassigned descriptor. All closes now route through a closeFd() helper that guards on fd != null and nulls it. A later GC-driven cancel() after a successful read can no longer close a descriptor the OS may have reassigned to an unrelated file/socket.
2. cancel() before open() resolves → close(undefined) throw. Same fd != null guard.
3. start() open-retry 20ms timer was untracked (different scope than pull()'s timer), leaking an fd if cancelled during the file-creation wait. Tracked as openTimer and cleared in cancel().
4. Double onError — a slow async read completing with an error after the watcher-timeout path already called onError() ran it twice (double close + duplicated #onError callbacks). Added a per-pull settled guard.
5. Slice read sequentially from byte 0 — slice(start,end).stream() read and discarded a 256KB buffer per chunk from offset 0 instead of seeking to HEADER_SIZE + start. Now seeks directly.

Latent correctness bug fixed alongside #5

The slice trim used the file position where it needed the content offset (position - HEADER_SIZE). Any slice whose bound landed past the first 0x40000 chunk returned bytes shifted by HEADER_SIZE. Existing tests only sliced within the first chunk, so it was never exercised. The seek rewrite corrects the accounting; the new cross-chunk slice test fails on the old code.

Cross-model review caught two blockers (also fixed here)

A first pass relied on a per-pull settled flag, which cancel() (a different scope) can't set. Codex and Gemini both flagged the gap:

• fd leak — cancel() before start()'s open() resolved couldn't close the descriptor open() later acquired (pull()/cancel() never run again). A realistic abort-during-open path.
• cancel race — a late read callback after cancel could recurse into read(null,…) → synchronous ERR_INVALID_ARG_TYPE crash, or reject the already-cancelled pull (unhandled rejection).

Both are fixed by a stream-wide cancelled flag set in cancel(), gating the open-retry loop, the open() success path (closes an fd acquired post-cancel), readMore() entry, and both read callbacks.

Tests

Added to unitTests/resources/blob.test.js:

• cross-chunk slice via stream() (boundary-straddling, both-bounds-in-later-chunk seek path, third-chunk-to-EOF, within-first-chunk regression) — verified to fail on the old code.
• cancel mid-read — no throw / no unhandled rejection.
• cancel before open() resolves — fd accounting via /proc/self/fd; verified 50/50 fds leaked without the guard, flat with it.

npm run build clean; full blob unit file green (58 passing).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request addresses several robustness issues in FileBackedBlob stream handling, specifically preventing file descriptor leaks, double-close errors, and unhandled rejections during stream cancellation. It introduces a stream-wide cancelled flag, an openTimer to track open-retry timeouts, and a settled flag to ensure pull operations are settled exactly once. Additionally, it optimizes the slicing of multi-chunk blobs by seeking directly to the slice start rather than reading and discarding preceding chunks. Comprehensive unit tests have been added to verify these fixes, including tests for multi-chunk slicing, mid-read cancellation, and cancellation before file opening resolves. I have no further feedback as the changes are well-implemented and thoroughly tested.

[claude]

Reviewed; no blockers found.

[cb1kenobi]

Do we need the undefined?

Suggested change

	if (cancelled) return resolve(undefined); // consumer cancelled before/while opening; stop retrying
	if (cancelled) return resolve(); // consumer cancelled before/while opening; stop retrying