Skip to content

Bun.serve: read a regular file whose st_size is 0 to its end - #43974

Draft
robobun wants to merge 1 commit into
farm/0d5eeba7/fifo-response-eof-framingfrom
robobun/00c06367/serve-file-unknown-size
Draft

robobun wants to merge 1 commit into
farm/0d5eeba7/fifo-response-eof-framingfrom
robobun/00c06367/serve-file-unknown-size

Conversation

@robobun

@robobun robobun commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator

Part of #44064

Stacked on #37082. Questions for alii or Jarred-Sumner:

  1. Is this shape right? Leave a body stream unsized when the file's st_size is 0 #41593 needs the same decision.
  2. Is one pread of one byte the right test, or fstatfs?

Problem

  • Bun.serve sends Content-Length: 0 and no body for new Response(Bun.file("/proc/version")) (219 bytes).
  • do_sendfile (RequestContext.rs:1857) and FileRoute::serve (FileRoute.rs:335) frame from st_size. procfs and cgroupfs report 0.

Fix

  • On Linux, one pread of one byte finds content in a regular file with st_size 0.
  • A file with content takes the arm of a pipe: FileResponseStream reads it to EOF. GET and HEAD get no Content-Length, Range or validator from the stat.
  • An empty file keeps each answer of its stat.
  • Verified: bun-serve-file.test.ts, serve-file-slice-read-error.test.ts: 29 new tests, 22 fail on the base. Self-reviewed: 27 concerns raised on the revision before, 24 addressed.

Background

Downsides

  • Not changed: a BunFile after .size or exists() (Bun.file: do not use a cached stat size as the byte budget of a read or a copy #43910), Bun.file(fd), { dir } routes.
  • An empty file pays one pread (HEAD in a handler: open, pread, close). A sized file pays 3 to 20 instructions, no syscall. .text grows by 3,072 bytes.
  • A handler that serves paths from / now sends /proc/self/environ. The read holds the JS thread: 350 ms for /proc/pagetypeinfo (100 ms for the pread).
Notes

What the server sends

Raw HTTP/1.1, Connection: close, Linux x64, release builds. Base: #37082 at 26376b9. /proc/version has 219 bytes, /proc/cpuinfo 177,934 and /proc/kallsyms 12.5 MB here. "fetch handler" is fetch: () => new Response(Bun.file(path)). "static route" is routes: { "/x": new Response(Bun.file(path)) }.

request base this PR
GET /proc/version, fetch handler and static route Content-Length: 0 Content-Length: 219
GET Bun.file("/proc/version").slice(10, 60) Content-Length: 0 Content-Length: 50
GET /proc/cpuinfo (65 reads) Content-Length: 0 chunked, whole body, last chunk
GET /proc/kallsyms Content-Length: 0 chunked, whole body, last chunk
GET with Range: bytes=0-9 416, Content-Range: bytes */0 200, whole body
GET with If-Modified-Since in the future, static route 304 200, whole body
GET with If-None-Match: *, static route 304, Last-Modified 304
HEAD /proc/version, fetch handler and static route Content-Length: 0 no Content-Length
GET and HEAD of an empty file Content-Length: 0 the same
Empty file, static route: Last-Modified, 304 for If-Modified-Since, 416 for a Range yes the same
GET /proc/self/mem (pread fails with EIO) Content-Length: 0 the same
GET /proc/self/pagemap (pread of one byte fails with EINVAL) Content-Length: 0 the same
GET of a BunFile after .size or await exists() 0 bytes the same
GET Bun.file(fd), two times 0 bytes, position 0 the same
Static route whose Response has a Content-Length header Content-Length: 0 the same
TRACE in a fetch handler Content-Length: 0 the same
TLS with HTTP/1.1, HTTP/2 and HTTP/3, 219 bytes and 480 KB 0 bytes 219 bytes, 480 KB

The test for content

zero_size_file_has_content runs only for a regular file whose st_size is 0. It reads one byte with pread at the offset of the Blob. One byte back means content. End of file or an error means an empty file, and the stat answers as before. So a file that cannot give one byte keeps the answer of the base: /proc/self/mem (EIO) and /proc/self/pagemap (EINVAL, its records have 8 bytes).

The cost is in the kernel. A procfs file makes its content at read, so the pread makes the first record and the reader makes it again. Median of 11 runs on the test machine: pread of one byte and then read to EOF, against read to EOF with no pread.

file pread read to EOF after it read to EOF alone
/sys/fs/cgroup/memory.current (10 B) 0.001 ms 0.001 ms 0.001 ms
/proc/meminfo (1.6 KB) 0.006 ms 0.007 ms 0.006 ms
/proc/stat (11.6 KB) 0.071 ms 0.071 ms 0.067 ms
/proc/self/smaps_rollup (698 B) 0.119 ms 0.113 ms 0.113 ms
/proc/kallsyms (12.5 MB) 0.004 ms 58 ms 58 ms
/proc/slabinfo (45 KB) 0.010 ms 49 ms 50 ms
/proc/pagetypeinfo (3.9 KB) 100 ms 264 ms 267 ms
/proc/vmallocinfo (3.9 MB) 228 ms 40 ms 223 ms

fstatfs is the other test: the filesystem type tells procfs from a disk. It costs one syscall and no second record. It needs a list of filesystem types (procfs, cgroupfs, debugfs, tracefs, securityfs, FUSE with direct I/O), and Bun has no such list today. With it, /proc/self/pagemap is a body with no end and /proc/self/mem closes the connection. Question 2 asks a maintainer to choose.

The first revision of this shape (1924ab8) had no test: each file with st_size 0 went through the reader. On a static route, an empty file then lost Last-Modified, the 304 for If-Modified-Since and the 416 for a Range. It paid one read and 1 to 2 allocations.

BodyLength

StartOptions.length was an Option<u64>. Some(n) said two things: the producer wrote Content-Length: n, and the reader stops after n bytes. A slice of a file with no size needs the second and must not claim the first. BodyLength has one variant for each case:

  • Exact(n): the producer wrote Content-Length: n. Only this variant can use sendfile.
  • ToEof: no Content-Length, read to EOF. Pipes, sockets, and a whole file with no size.
  • UpTo(n): no Content-Length, read to EOF and not more than n bytes. A slice of a file with no size.

Code that decides the framing calls exact(). Open PRs that read StartOptions.length as an Option need that change at a rebase: #41622, #41474, #38107, #40875.

Measurements

Release builds of the base (26376b9) and of this PR, same machine and toolchain. strace, perf, valgrind and bloaty are not installed on the test machine. The counts come from two small ptrace tools. One logs each syscall of each thread. The other single-steps the JS thread. It counts the instructions and the calls of the mimalloc entry points (mi_malloc, mi_calloc, mi_zalloc, mi_realloc, the aligned and heap variants). One keep-alive connection, one request at a time.

User instructions of the JS thread for one request, from the return of recvfrom to the last write to the connection. The static and directory routes give the same count for each request. The fetch handler runs JavaScript, so its count changes from request to request. For a sized file its row is the least count of 60 requests after 300 warm-up requests. That count is also the one that most requests have. The other fetch handler rows give the median of 30 requests.

request base this PR
sized 219 B GET, static route 13,551 13,571 (+20)
sized 219 B HEAD, static route 12,446 12,463 (+17)
sized 219 B GET with Range: bytes=0-9, static route 15,812 15,829 (+17)
sized 219 B GET, directory route 16,167 16,172 (+5)
sized 219 B GET, fetch handler 21,422 21,434 (+12)
sized 219 B HEAD, fetch handler 19,327 19,330 (+3)
empty GET, static route 12,589 12,632 (+43)
empty HEAD, static route 12,462 12,513 (+51)
empty GET, fetch handler (median of 30) 43,753 43,776 (+23)
empty HEAD, fetch handler (median of 30) 42,352 42,603 (+251)
/proc/version GET, static route 12,592 12,454
/proc/version HEAD, static route 12,465 11,024
/proc/version GET, fetch handler (median of 30) 40,140 40,693
/proc/version HEAD, fetch handler (median of 30) 32,657 32,423

Syscalls per request, futex left out:

request base this PR
sized 219 B GET: fetch handler, static route, directory route 7 7
sized 219 B GET with Range: bytes=0-9, static route 7 7
sized 219 B HEAD: static route / fetch handler 6 / 4 6 / 4
sized 2 MiB GET (sendfile): fetch handler, static route 7 7
sized 219 B GET, handler that resolves after setImmediate 13 (7 sendto) 13 (7 sendto)
empty file GET: fetch handler, static route 6 7 (pread)
empty file HEAD, static route 6 7 (pread)
empty file HEAD, fetch handler 4 7 (open, pread, close)
/proc/version GET: fetch handler, static route 6 9 (pread, two read)
/proc/version GET, handler that resolves after setImmediate 11 (6 sendto) 17 (pread, two read, 9 sendto)
/proc/version HEAD, static route 6 7 (pread)
/proc/version HEAD, fetch handler 4 7 (open, pread, close)
/proc/cpuinfo GET: fetch handler, static route 6 79 (pread, 65 read, 8 sendto)
/proc/self/pagemap GET, static route 6 7 (pread that fails)

Heap allocations per request:

request base this PR
sized 219 B GET: static route, directory route 2 2
sized 219 B HEAD, static route 1 1
sized 219 B GET / HEAD, fetch handler 9 / 8 9 / 8
empty GET and HEAD, static route 1 1
empty GET and HEAD, fetch handler 8 8
/proc/version GET, static route 1 2
/proc/version GET, fetch handler 7 8
/proc/version HEAD: static route / fetch handler 1 / 8 1 / 8

Time that one GET from a fetch handler holds the event loop: the greatest gap of a 1 ms timer, median of 15 requests. Two rounds for each build, one build after the other, uid 0, load average 850 to 1300. The 1 ms of the timer is the floor.

file base this PR
sized file (219 B), empty file 1.0 ms to 1.1 ms 0.8 ms to 1.1 ms
/proc/version (219 B) 0.7 ms to 1.0 ms 0.9 ms to 1.1 ms
/proc/cpuinfo (178 KB) 0.6 ms to 1.0 ms 1.9 ms to 2.1 ms
/proc/self/smaps_rollup (698 B) at 0.03, 0.5 and 2 GiB resident 0.3 ms to 0.9 ms 2 ms, 19 ms, 75 ms
/proc/slabinfo (45 KB, mode 0400) 0.5 ms to 1.0 ms 45 ms to 46 ms
/proc/kallsyms (12.5 MB) 0.8 ms to 1.0 ms 61 ms
/proc/vmallocinfo (2.7 MB to 3.2 MB, mode 0400) 0.8 ms to 1.0 ms 219 ms to 236 ms
/proc/pagetypeinfo (3.9 KB, mode 0400) 0.9 ms 343 ms to 355 ms

The time is the time the kernel takes to make the content. The reader of FileResponseStream runs read on the JS thread for each file that does not go through sendfile, on the base too. The four Dockerfiles in dockerhub/ set no USER, so the images run as uid 0, which can read the files of mode 0400.

Binary size:

base this PR
.text section (size -A) 58,300,604 58,303,676 (+3,072)
text column of size, bun-profile 80,855,937 80,859,009 (+3,072)
bun, stripped, file bytes 80,995,912 81,000,008 (+4,096)

From nm -S, the functions grow by 3,192 bytes: do_sendfile +1,408 (176 in each of its 8 copies), do_render_head_response +620 (its 8 copies together), zero_size_path_has_content 584 (new), FileRoute::on +440, zero_size_file_has_content 111 (new), FileResponseStream::start +29. StartOptions keeps its size: BodyLength has the 16 bytes that Option<u64> had.

Source: +159 -33 lines in 4 files of src/.

Tests

  • New in test/js/bun/http/bun-serve-file.test.ts: 28 tests, Linux only but one. On a release build of the base, 21 fail and 7 pass. Of those 7, 6 hold an answer that must not change (an empty file, a file that cannot be read, Bun.file(fd)). One is a test.failing row for a BunFile after .size or exists() (Bun.file: do not use a cached stat size as the byte budget of a read or a copy #43910).
  • New in test/js/bun/http/serve-file-slice-read-error.test.ts: one test. A supervisor process makes the second read of /proc/loadavg fail. The response must not be complete. It fails on the base.
  • Every expected byte comes from a file that does not change: /proc/version and two files of a child process that stopped itself with SIGSTOP. Its environ has about 480 KB. Its maps has 64 added mappings and comes in reads of at most one page.
  • The tests do not name the framing of a large body. One strict parser reads each response. It fails for a body that is not the length of its Content-Length. It fails for a chunk size that is not hexadecimal, and for chunks with no last chunk. The FIFO tests of Bun.serve: terminate FIFO/pipe file responses at EOF #37082 use the same parser.
  • One test sends 13 requests on one keep-alive connection and finds no byte between the responses. One test sends GET and HEAD for a BunFile that all the responses of a handler share.
  • Debug build with ASAN: the two files above, serve-directory-routes.test.ts, bun-serve-static.test.ts, serve-if-none-match.test.ts, bun-serve-headers.test.ts, tls-bunfile-leak.test.ts, serve-http2.test.ts, serve-http3.test.ts. cargo clippy -p bun_runtime, bun run rust:check-all (12 targets) and test/internal/source-lints/ pass.
  • The machine of these runs had a load average of 250 to 1300. Three tests of bun-serve-file.test.ts that this PR does not change ("pollable Bun.file ...", from Bun.serve: pause the file reader while the response is backpressured #41244) start a debug build of bun. There they take 6 to 9 s and end at the 5 s limit. They pass with a longer limit, and with release builds of the base and of this PR.

Limits

Self-review

The review of the revision before (1924ab8) raised 27 concerns. 24 are addressed. The main ones:

  • the test for content, and HEAD
  • the test.failing row and the strict parser
  • the route with a Content-Length header
  • the test for a read that fails
  • the BodyLength contract above
  • corrections to this text and to the docs

Not taken:

Other PRs

PR Relation
#37082 The base. FileResponseStream::finish ends with resp.end(b""), which writes the last chunk.
#34242 The first attempt, for files with no slice. The stale sweep closed it on 2026-09-13 with no comment from a maintainer.
#41585 Sends HEAD of a fetch handler through do_sendfile, for each file. It changes the same lines. After it, do_sendfile tests the file for HEAD too, and zero_size_path_has_content can go.
#43910, #41593 The window of 0 bytes in Blob::resolve_size. #43910 changes RequestContext.rs and this test file.
#43871, #43897, #43964, #43965, #44026, #41590 The same class in other readers: Bun.file reads, fetch bodies, the module loader, dotenv, FormData. No file in common.
#41622, #41474, #38107, #40875 Read StartOptions.length as an Option<u64>. See BodyLength above.
#41621, #41874 Change other lines of FileResponseStream.rs.
#41626, #44036 Change the reader (src/io/PipeReader.rs), which this PR does not change.
#42819 Removes libuv on Windows and changes the same files. The code here does not run on Windows.

Found on the way, not in this PR:

The branches robobun/00c06367/serve-file-whole-body (64489d0) and robobun/00c06367/serve-file-chunked-body (86b62a0) hold the two shapes that read the file before the status line.

@robobun

robobun commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status: draft, stacked on #37082. This revision (e1bb808) tests a regular file whose st_size is 0 for content with one pread of one byte. A file with content goes through the reader that Bun.serve has for pipes. An empty file keeps each answer of its stat. A response to HEAD has no Content-Length and no validator from the stat either. The questions at the top of the description need an answer from a maintainer.

How to reproduce on main or bun 1.4.2, Linux:

await using server = Bun.serve({ port: 0, fetch: () => new Response(Bun.file("/proc/version")) });
const res = await fetch(server.url);
console.log(res.headers.get("content-length"), (await res.text()).length);
// main: "0" 0
// this PR: "219" 219

The same happens for a static route. #44064 tracks the parts that this PR does not change.

@robobun
robobun force-pushed the robobun/00c06367/serve-file-unknown-size branch from 5561b9f to 86b62a0 Compare September 25, 2026 22:51
@robobun

robobun commented Sep 25, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 5:18 PM PT - Sep 29th, 2026

✅ @robobun, your commit e1bb80848d035899fdee2fe4be79c60496219382 passed in Build #121710! 🎉


🧪   To try this PR locally:

bunx bun-pr 43974

That installs a local version of the PR into your bun-43974 executable, so you can run:

bun-43974 --bun

Comment thread src/bundler/LinkerContext.rs Resolved
Comment thread src/js/internal-for-testing.ts Resolved
Comment thread src/js/node/net.ts Resolved
Comment thread src/jsc/bindings/ZigSourceProvider.cpp Resolved
Comment thread src/runtime/socket/Listener.rs Resolved
Comment thread src/runtime/socket/Listener.rs Resolved
Comment thread src/uws/lib.rs Resolved
@robobun
robobun changed the base branch from farm/0d5eeba7/fifo-response-eof-framing to main September 26, 2026 22:33
@robobun
robobun changed the base branch from main to farm/0d5eeba7/fifo-response-eof-framing September 29, 2026 00:32
@robobun
robobun force-pushed the robobun/00c06367/serve-file-unknown-size branch from 64489d0 to 1924ab8 Compare September 29, 2026 00:32
@robobun robobun changed the title Bun.serve: read a regular file whose st_size is 0 before framing the response Bun.serve: read a regular file whose st_size is 0 to its end Sep 29, 2026
@robobun

robobun commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator Author

@alii this PR needs one decision from you, and it is the decision that is open on #41593 too.

Edited on 2026-09-29: the branch now tests a file for content before it answers, and it covers HEAD. The table and the questions describe this revision (e1bb808).

A regular file on procfs or cgroupfs reports st_size 0 and has content. Bun.serve sends it as an empty 200 today. Two shapes can send the bytes:

A: through the reader (this PR) B: read before the status line
Source lines +159 -33 +428 -6
/proc/version (219 B) Content-Length: 219 Content-Length: 219
/proc/cpuinfo (178 KB) chunked Content-Length: 177934
/proc/kallsyms (12.5 MB) chunked, whole body needs a second path for bodies over 256 KiB
The first read fails empty 200, as today error() gets the error
Empty file one pread, each answer of its stat one read
Needs #37082 yes for bodies over 256 KiB

Shape A is on this branch. Shape B is on robobun/00c06367/serve-file-whole-body. The description has the measurements for A.

Questions:

  1. Do you want shape A, shape B, or no change?
  2. Shape A tests a file with st_size 0 for content with one pread of one byte. A procfs file then produces its first record two times: /proc/pagetypeinfo holds the JS thread for 350 ms, 100 ms of it for the pread. fstatfs is the other test. It costs no second record, and it needs a list of filesystem types in Bun. Which test do you want?
  3. Must this land before or after Bun.file: do not use a cached stat size as the byte budget of a read or a copy #43910 (Blob size)? Both change do_sendfile. Bun.serve: resolve a file body for HEAD the same way as for GET #41585 (HEAD for each file) changes it too.
  4. Must a { dir } route send such files too? This PR leaves that route as it is.

@robobun
robobun force-pushed the robobun/00c06367/serve-file-unknown-size branch from 1924ab8 to 7cb6d8c Compare September 29, 2026 23:50
A regular file on procfs or cgroupfs reports st_size 0 and has content.
do_sendfile and FileRoute::serve framed the response from st_size, so
they sent Content-Length: 0 and no body.

For a regular file whose st_size is 0, one pread of one byte now tells a
file with content from an empty file. A file with content takes the arm
of a pipe: FileResponseStream reads it to EOF, and the response has no
Content-Length, Range or validator from the stat. A response to HEAD has
none of them either. A slice passes its window as the limit of the
reader (BodyLength::UpTo). An empty file, a descriptor of the caller, a
directory route, and a static route with a Content-Length header of its
own keep the answers of the stat.

StartOptions.length is now a BodyLength. Exact is a Content-Length that
the producer wrote. ToEof and UpTo are not.
@robobun

robobun commented Oct 23, 2026

Copy link
Copy Markdown
Collaborator Author

Status on 2026-10-23.

The bug is still on main. On the canary build (1.4.4, 5c6d4e2), Bun.serve answers 200 with Content-Length: 0 and no body for new Response(Bun.file("/proc/sys/kernel/ostype")) from a handler, and for routes: { "/route": Bun.file(path) }. A cgroupfs file (/sys/fs/cgroup/cgroup.controllers) gets the same answer.

Two things changed since the last push:

The questions at the top of the description are still open. The rebase waits for that answer and for #46528, because a rebase onto main today conflicts again when #46528 merges.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant