From 4d8fad84d201108349f262751674d3b441200abe Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:53:17 +0000 Subject: [PATCH 1/9] watcher: add BUN_WATCHER_USE_POLLING stat-polling fallback for --watch/--hot On Docker bind mounts from a Windows/macOS host, WSL /mnt/... paths, and NFS/SMB shares, the native file-change APIs (inotify/kqueue/ ReadDirectoryChangesW) succeed but never deliver events, so --watch and --hot silently stop reloading. This adds an opt-in polling backend alongside the native one, selected at Watcher::init time via BUN_WATCHER_USE_POLLING=1 (interval configurable via BUN_WATCHER_POLL_INTERVAL, default 100ms). When enabled, the watcher thread periodically stat()s each file in the watchlist and emits a WRITE event when mtime/size/ino change, or DELETE when the file disappears. The baseline stat is captured at the moment add_file registers the path (same point where inotify would start listening), so a write that lands between registration and the first poll cycle is detected. The Watcher.platform field becomes a Backend enum with Native and Polling variants; the native watch_loop_cycle accesses the Platform via Backend::native()/native_mut(). No behaviour change when the env var is unset. Closes #5841 --- docs/runtime/environment-variables.mdx | 1 + docs/runtime/watch-mode.mdx | 16 ++ src/bun_core/env_var.rs | 6 + src/watcher/INotifyWatcher.rs | 2 +- src/watcher/KEventWatcher.rs | 2 +- src/watcher/PollingWatcher.rs | 211 +++++++++++++++++++++++++ src/watcher/Watcher.rs | 94 +++++++++-- src/watcher/WindowsWatcher.rs | 16 +- src/watcher/lib.rs | 3 + test/cli/watch/watch.test.ts | 70 ++++++++ 10 files changed, 399 insertions(+), 22 deletions(-) create mode 100644 src/watcher/PollingWatcher.rs diff --git a/docs/runtime/environment-variables.mdx b/docs/runtime/environment-variables.mdx index 1680f0c0251b..ccc12b21801a 100644 --- a/docs/runtime/environment-variables.mdx +++ b/docs/runtime/environment-variables.mdx @@ -202,6 +202,7 @@ Bun reads these environment variables to configure aspects of its behavior. | `FORCE_COLOR` | If `FORCE_COLOR=1`, then ANSI color output is forced on, even if `NO_COLOR` is set. | | `BUN_CONFIG_MAX_HTTP_REQUESTS` | Sets the maximum number of concurrent HTTP requests sent by fetch and `bun install`. Defaults to `256`. Lower it if you run into rate limits or connection issues. | | `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD` | If `BUN_CONFIG_NO_CLEAR_TERMINAL_ON_RELOAD=true`, then `bun --watch` does not clear the console on reload | +| `BUN_WATCHER_USE_POLLING` | If `BUN_WATCHER_USE_POLLING=1`, `--watch` and `--hot` poll the filesystem instead of using native change events. Use this for Docker bind mounts, WSL `/mnt/...` paths, and network filesystems where native events do not fire. `BUN_WATCHER_POLL_INTERVAL` sets the poll interval in milliseconds (default `100`). | | `DO_NOT_TRACK` | Disable uploading crash reports to `bun.report` on crash. On macOS & Windows, crash report uploads are enabled by default. Other telemetry is not sent, though we plan to add some. If `DO_NOT_TRACK=1`, then auto-uploading crash reports and telemetry are both [disabled](https://do-not-track.dev/). | | `BUN_OPTIONS` | Prepends command-line arguments to any Bun execution. For example, `BUN_OPTIONS="--hot"` makes `bun run dev` behave like `bun --hot run dev`. | diff --git a/docs/runtime/watch-mode.mdx b/docs/runtime/watch-mode.mdx index 8e1c2f45211e..f93a3e08f488 100644 --- a/docs/runtime/watch-mode.mdx +++ b/docs/runtime/watch-mode.mdx @@ -76,6 +76,22 @@ bun --watch test --no-clear-screen`. +### Docker, WSL, and network filesystems + +Bun's watcher relies on the operating system's native file-change APIs (inotify on Linux, kqueue on macOS, `ReadDirectoryChangesW` on Windows). These do not fire for files that live on certain mounted filesystems, including: + +- Docker bind mounts where the host is Windows or macOS +- WSL paths under `/mnt/c/...` +- NFS, SMB, and other network shares + +If edits on the host are not picked up inside the container, set `BUN_WATCHER_USE_POLLING=1` to switch `--watch` and `--hot` to a polling backend that periodically `stat()`s each watched file: + +```bash terminal icon="terminal" +BUN_WATCHER_USE_POLLING=1 bun --watch index.ts +``` + +The poll interval defaults to 100 ms and can be changed with `BUN_WATCHER_POLL_INTERVAL` (in milliseconds). Polling uses more CPU than native watching, so only enable it when native events are unavailable. + --- ## `--hot` mode diff --git a/src/bun_core/env_var.rs b/src/bun_core/env_var.rs index 579cda9d82fb..d21ade40e8e1 100644 --- a/src/bun_core/env_var.rs +++ b/src/bun_core/env_var.rs @@ -118,6 +118,12 @@ platform_specific_new!(pub LIBRARY_PATH: string, posix = "LIBRARY_PATH", windows new!(pub BUN_TEST_DRAIN_EVENT_LOOP: boolean, "BUN_TEST_DRAIN_EVENT_LOOP", { default: false }); new!(pub BUN_TMPDIR: string, "BUN_TMPDIR", {}); new!(pub BUN_WATCHER_TRACE: string, "BUN_WATCHER_TRACE", {}); +// Poll the filesystem instead of using inotify/kqueue/ReadDirectoryChangesW +// for `--watch` / `--hot`. Needed on mounts that can't deliver native change +// events (Docker bind mounts from a Windows/macOS host, WSL `/mnt/...`, +// NFS/SMB). See src/watcher/PollingWatcher.rs. +new!(pub BUN_WATCHER_USE_POLLING: boolean, "BUN_WATCHER_USE_POLLING", { default: false }); +new!(pub BUN_WATCHER_POLL_INTERVAL: unsigned, "BUN_WATCHER_POLL_INTERVAL", {}); new!(pub CI: boolean, "CI", {}); new!(pub CI_COMMIT_SHA: string, "CI_COMMIT_SHA", {}); new!(pub CI_JOB_URL: string, "CI_JOB_URL", {}); diff --git a/src/watcher/INotifyWatcher.rs b/src/watcher/INotifyWatcher.rs index e9d3bebaaca4..343ff18d9dfd 100644 --- a/src/watcher/INotifyWatcher.rs +++ b/src/watcher/INotifyWatcher.rs @@ -372,7 +372,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { use crate::watcher_impl::WatchItemColumns; let _flush = Output::flush_guard(); - let events = this.platform.read()?; + let events = this.platform.native_mut().read()?; if events.is_empty() { return Ok(()); } diff --git a/src/watcher/KEventWatcher.rs b/src/watcher/KEventWatcher.rs index 01cecd8f473b..70eba3a886b9 100644 --- a/src/watcher/KEventWatcher.rs +++ b/src/watcher/KEventWatcher.rs @@ -52,7 +52,7 @@ pub(crate) fn watch_event_from_kevent(kevent: &libc::kevent) -> WatchEvent { pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { let _flush = Output::flush_guard(); - let fd = this.platform.fd; + let fd = this.platform.native().fd; let mut changelist: [libc::kevent; CHANGELIST_COUNT] = bun_core::ffi::zeroed(); diff --git a/src/watcher/PollingWatcher.rs b/src/watcher/PollingWatcher.rs new file mode 100644 index 000000000000..61ce398bb5d1 --- /dev/null +++ b/src/watcher/PollingWatcher.rs @@ -0,0 +1,211 @@ +//! Stat-polling fallback for filesystems where native change notifications +//! don't fire (Docker/WSL bind mounts, NFS/SMB, virtiofs/9p). Enabled via +//! `BUN_WATCHER_USE_POLLING=1`; interval via `BUN_WATCHER_POLL_INTERVAL` (ms). + +use std::collections::HashMap; +use std::time::Duration; + +use bun_core::ZStr; +use bun_sys::{self as sys, stat_mtime}; + +use crate::watcher_impl::{ + Backend, HashType, MAX_COUNT, Op, WatchEvent, WatchItemColumns, WatchItemIndex, WatchItemKind, + Watcher, +}; + +bun_core::declare_scope!(watcher, visible); + +pub const DEFAULT_INTERVAL_MS: u64 = 100; + +#[derive(Clone, Copy, Default)] +struct Snapshot { + mtime_sec: i64, + mtime_nsec: i64, + size: u64, + ino: u64, + /// last stat succeeded + exists: bool, +} + +impl Snapshot { + fn differs(&self, other: &Snapshot) -> bool { + self.exists != other.exists + || self.mtime_sec != other.mtime_sec + || self.mtime_nsec != other.mtime_nsec + || self.size != other.size + || self.ino != other.ino + } +} + +pub struct PollingWatcher { + pub interval: Duration, + /// Baseline stat per watched file, keyed by `WatchItem.hash` so + /// `flush_evictions`' `swap_remove` reordering doesn't invalidate state. + /// Guarded by `Watcher.mutex` (written from `add_file` on the JS thread + /// and from the watcher thread's diff step). + snapshots: HashMap, + /// Scratch reused across cycles; only touched by the watcher thread. + scratch_idx: Vec<(WatchItemIndex, HashType)>, + scratch_path: Vec>, + scratch_stat: Vec, +} + +impl PollingWatcher { + pub fn new(interval_ms: u64) -> Self { + Self { + interval: Duration::from_millis(interval_ms.max(1)), + snapshots: HashMap::new(), + scratch_idx: Vec::new(), + scratch_path: Vec::new(), + scratch_stat: Vec::new(), + } + } + + /// Capture the baseline stat for `path` at the moment it's registered + /// (same point where inotify/kqueue would start listening), so a write + /// that lands between registration and the first poll cycle is detected. + /// Caller must hold `Watcher.mutex`. + pub(crate) fn register(&mut self, hash: HashType, path: &[u8]) { + self.snapshots.insert(hash, stat_path(path)); + } + + pub fn stop(&mut self) {} +} + +fn stat_path(path: &[u8]) -> Snapshot { + let mut buf = bun_paths::path_buffer_pool::get(); + if path.len() >= buf.len() { + return Snapshot::default(); + } + buf[..path.len()].copy_from_slice(path); + buf[path.len()] = 0; + let z = ZStr::from_buf(&buf[..], path.len()); + match sys::stat(z) { + Ok(st) => { + let mt = stat_mtime(&st); + #[cfg(unix)] + let (size, ino) = (st.st_size as u64, st.st_ino as u64); + #[cfg(windows)] + let (size, ino) = (st.st_size, st.st_ino); + Snapshot { + mtime_sec: mt.sec, + mtime_nsec: mt.nsec, + size, + ino, + exists: true, + } + } + Err(_) => Snapshot::default(), + } +} + +/// One polling cycle: sleep, snapshot the watchlist under the mutex, stat each +/// file, diff against the previous snapshot, emit events. +pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> sys::Result<()> { + let _flush = bun_core::output::flush_guard(); + + let interval = match &this.platform { + Backend::Polling(p) => p.interval, + Backend::Native(_) => unreachable!(), + }; + + // Sleep in short slices so `shutdown()` (which clears `running`) doesn't + // have to wait out a long interval. + let mut remaining = interval; + let slice = Duration::from_millis(20); + while remaining > Duration::ZERO { + if !this.running.load() { + return Ok(()); + } + let step = remaining.min(slice); + std::thread::sleep(step); + remaining = remaining.saturating_sub(step); + } + if !this.running.load() { + return Ok(()); + } + + // Move the watcher-thread-only scratch buffers out so `&mut this` stays + // free for `dispatch_file_updates`; `snapshots` stays in place because the + // JS thread's `register()` may write it concurrently under `this.mutex`. + let Backend::Polling(poll) = &mut this.platform else { + unreachable!() + }; + let mut scratch_idx = core::mem::take(&mut poll.scratch_idx); + let mut scratch_path = core::mem::take(&mut poll.scratch_path); + let mut scratch_stat = core::mem::take(&mut poll.scratch_stat); + scratch_idx.clear(); + scratch_path.clear(); + scratch_stat.clear(); + + // Snapshot (index, hash, path) under the mutex. Between unlock and + // `dispatch_file_updates`' re-lock the JS thread can only append, so + // indices stay valid. + { + let _guard = this.mutex.lock_guard(); + let paths = this.watchlist.items_file_path(); + let hashes = this.watchlist.items_hash(); + let kinds = this.watchlist.items_kind(); + scratch_idx.reserve(paths.len()); + scratch_path.reserve(paths.len()); + for i in 0..paths.len() { + if kinds[i] != WatchItemKind::File { + continue; + } + scratch_idx.push((i as WatchItemIndex, hashes[i])); + scratch_path.push(paths[i].to_vec()); + } + } + + for path in &scratch_path { + scratch_stat.push(stat_path(path)); + } + + // Diff under the mutex so `register()` from the JS thread can't interleave. + let mut event_id: usize = 0; + { + let _guard = this.mutex.lock_guard(); + let Backend::Polling(poll) = &mut this.platform else { + unreachable!() + }; + for (k, &(index, hash)) in scratch_idx.iter().enumerate() { + let now = scratch_stat[k]; + let op = match poll.snapshots.get(&hash) { + Some(prev) if now.differs(prev) => { + if now.exists { + Op::WRITE + } else { + Op::DELETE + } + } + Some(_) => continue, + None => { + poll.snapshots.insert(hash, now); + continue; + } + }; + poll.snapshots.insert(hash, now); + + if event_id < MAX_COUNT { + this.watch_events[event_id] = WatchEvent { + index, + op, + name_off: 0, + name_len: 0, + }; + event_id += 1; + } + } + } + + if event_id > 0 { + this.dispatch_file_updates(event_id, 0); + } + + if let Backend::Polling(poll) = &mut this.platform { + poll.scratch_idx = scratch_idx; + poll.scratch_path = scratch_path; + poll.scratch_stat = scratch_stat; + } + Ok(()) +} diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index 7f99097eed26..4f4c152bfac0 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -9,6 +9,7 @@ use bun_sys::{self as sys, Fd}; use bun_threading::Mutex; use crate::Loader; +use crate::polling_watcher::{self as polling, PollingWatcher}; use crate::watcher_trace as WatcherTrace; // Android: same kernel inotify ABI as glibc/musl Linux, so list both. @@ -85,6 +86,51 @@ impl AnyResolveWatcher { // ideally, the constants above can be inlined pub(crate) type Platform = platform::Platform; +/// Runtime-selected watch backend. `Native` is the compile-time +/// inotify/kqueue/ReadDirectoryChangesW implementation; `Polling` stat()s +/// each watched file on an interval for mounts that can't deliver native +/// change events. +pub enum Backend { + Native(Platform), + Polling(PollingWatcher), +} + +impl Backend { + /// Unwrap the native platform. Only called from native + /// `watch_loop_cycle` / kqueue registration, which `watch_loop()` + /// dispatches to only when `self` is `Native`. + #[inline] + #[cfg_attr(any(target_os = "linux", target_os = "android"), allow(dead_code))] + pub(crate) fn native(&self) -> &Platform { + match self { + Backend::Native(p) => p, + Backend::Polling(_) => unreachable!("native() on polling backend"), + } + } + + #[inline] + #[cfg_attr(any(target_os = "macos", target_os = "freebsd"), allow(dead_code))] + pub(crate) fn native_mut(&mut self) -> &mut Platform { + match self { + Backend::Native(p) => p, + Backend::Polling(_) => unreachable!("native_mut() on polling backend"), + } + } + + #[inline] + #[cfg_attr(not(any(target_os = "macos", target_os = "freebsd")), allow(dead_code))] + pub(crate) fn is_polling(&self) -> bool { + matches!(self, Backend::Polling(_)) + } + + fn stop(&mut self) { + match self { + Backend::Native(p) => p.stop(), + Backend::Polling(p) => p.stop(), + } + } +} + /// `?[:0]u8` — name of a changed file inside a watched directory, borrowed /// from the platform's event buffer (inotify event names / kqueue udata). /// Ownership stays with the platform buffer for the duration of one @@ -100,7 +146,7 @@ pub struct Watcher { pub changed_filepaths: [ChangedFilePath; MAX_COUNT], /// The platform-specific implementation of the watcher - pub platform: Platform, + pub platform: Backend, pub watchlist: WatchList, pub mutex: Mutex, @@ -187,6 +233,16 @@ impl Watcher { ctx.on_watch_error(err); } + let platform = if bun_core::env_var::BUN_WATCHER_USE_POLLING::get().unwrap_or(false) { + let interval = bun_core::env_var::BUN_WATCHER_POLL_INTERVAL + .get() + .unwrap_or(polling::DEFAULT_INTERVAL_MS); + log!("using polling backend (interval={}ms)", interval); + Backend::Polling(PollingWatcher::new(interval)) + } else { + Backend::Native(Platform::new(top_level_dir)?) + }; + let this = Box::new(Watcher { watchlist: WatchList::default(), mutex: Mutex::default(), @@ -194,7 +250,7 @@ impl Watcher { ctx: ctx.cast::<()>(), on_file_update: on_file_update_wrapped::, on_error: on_error_wrapped::, - platform: Platform::new(top_level_dir)?, + platform, watch_events: vec![WatchEvent::default(); MAX_COUNT].into_boxed_slice(), changed_filepaths: [const { None }; MAX_COUNT], watchloop_handle: bun_core::AtomicCell::new(false), @@ -424,7 +480,7 @@ impl Watcher { // route to the right module; EV_ADD on an existing (ident, filter) replaces in // place. See #29524. #[cfg(any(target_os = "macos", target_os = "freebsd"))] - { + if !self.platform.is_polling() { if (item as usize) < self.watchlist.len() { let moved_fd = self.watchlist.items_fd()[item as usize]; if moved_fd.is_valid() { @@ -442,7 +498,10 @@ impl Watcher { fn watch_loop(&mut self) -> sys::Result<()> { while self.running.load() { // individual platform implementation will call onFileUpdate - platform::watch_loop_cycle(self)?; + match self.platform { + Backend::Native(_) => platform::watch_loop_cycle(self)?, + Backend::Polling(_) => polling::watch_loop_cycle(self)?, + } } Ok(()) } @@ -483,7 +542,7 @@ impl Watcher { // Basically: // - We register the event here. // our while(true) loop above receives notification of changes to any of the events created here. - let _ = bun_sys::kevent(self.platform.fd, &[event], &mut [], None); + let _ = bun_sys::kevent(self.platform.native().fd, &[event], &mut [], None); } fn append_file_assume_capacity( @@ -523,10 +582,15 @@ impl Watcher { Cow::Borrowed(unsafe { bun_collections::detach_lifetime(file_path) }) }; + if let Backend::Polling(p) = &mut self.platform { + p.register(hash, file_path); + } #[cfg(any(target_os = "macos", target_os = "freebsd"))] - self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); + if !self.platform.is_polling() { + self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); + } #[cfg(any(target_os = "linux", target_os = "android"))] - let eventlist_index = { + let eventlist_index = if let Backend::Native(p) = &mut self.platform { // inotify needs a trailing NUL. When // CLONE_FILE_PATH is true the caller's `file_path` is NOT NUL-terminated, // so we must copy into a NUL-terminated scratch buffer (mirrors the @@ -542,7 +606,9 @@ impl Watcher { // interned in `bun.fs.FileSystem` with a NUL sentinel at [len]. unsafe { ZStr::from_raw(file_path.as_ptr(), file_path.len()) } }; - self.platform.watch_path(slice)? + p.watch_path(slice)? + } else { + 0 }; self.watchlist.append_assume_capacity(WatchItem { @@ -603,9 +669,11 @@ impl Watcher { let watchlist_id = self.watchlist.len(); #[cfg(any(target_os = "macos", target_os = "freebsd"))] - self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); + if !self.platform.is_polling() { + self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); + } #[cfg(any(target_os = "linux", target_os = "android"))] - let eventlist_index = { + let eventlist_index = if let Backend::Native(p) = &mut self.platform { let mut buf = bun_paths::path_buffer_pool::get(); let path: &ZStr = if CLONE_FILE_PATH && !file_path.is_empty() @@ -625,9 +693,9 @@ impl Watcher { ZStr::from_buf(&buf[..], trailing_slash.len()) }; - self.platform - .watch_dir(path) - .map_err(|e| e.with_path(file_path))? + p.watch_dir(path).map_err(|e| e.with_path(file_path))? + } else { + 0 }; self.watchlist.append_assume_capacity(WatchItem { diff --git a/src/watcher/WindowsWatcher.rs b/src/watcher/WindowsWatcher.rs index 0350c0511255..ddb0c1b78388 100644 --- a/src/watcher/WindowsWatcher.rs +++ b/src/watcher/WindowsWatcher.rs @@ -398,14 +398,14 @@ pub(crate) enum Timeout { pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // We re-borrow buf inside the inner loop instead of holding `&this.platform.buf` // across calls to `this.platform.next()`. - let base_idx = this.platform.base_idx; + let base_idx = this.platform.native().base_idx; let mut event_id: usize = 0; // first wait has infinite timeout - we're waiting for the next event and don't want to spin let mut timeout = Timeout::Infinite; loop { - let mut iter = match this.platform.next(timeout)? { + let mut iter = match this.platform.native_mut().next(timeout)? { Some(it) => it, None => break, }; @@ -423,14 +423,16 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // live for the duration of this iteration (no `prepare()` until the // outer loop reiterates) — encapsulated by the `RawSlice` invariant. let filename: &[u16] = event.filename.slice(); - let convert_res = - strings::copy_utf16_into_utf8(&mut this.platform.buf[base_idx..], filename); + let convert_res = strings::copy_utf16_into_utf8( + &mut this.platform.native_mut().buf[base_idx..], + filename, + ); let eventpath_len = base_idx + convert_res.written as usize; bun_core::scoped_log!( watcher, "watcher update event: (filename: {}, action: {}", - bstr::BStr::new(&this.platform.buf[..eventpath_len]), + bstr::BStr::new(&this.platform.native().buf[..eventpath_len]), <&'static str>::from(event.action) ); @@ -449,7 +451,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // are released before we touch `this.watch_events` or hand the // whole `&mut Watcher` to `process_watch_event_batch`. let rel = { - let eventpath = &this.platform.buf[..eventpath_len]; + let eventpath = &this.platform.native().buf[..eventpath_len]; let path = &this.watchlist.items_file_path()[item_idx]; let rel = is_parent_or_equal(path.as_ref(), eventpath); bun_core::scoped_log!( @@ -481,7 +483,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // then dereference a pointer with invalidated provenance — UB that MIRI flags. // The callee never touches `platform.watcher`, so re-deriving the pointer // here from the now-current `&mut Watcher` restores valid provenance. - iter.watcher = BackRef::new(&this.platform.watcher); + iter.watcher = BackRef::new(&this.platform.native().watcher); // Reset event_id to start a new batch event_id = 0; } diff --git a/src/watcher/lib.rs b/src/watcher/lib.rs index 61a898240380..0e51e9d748fa 100644 --- a/src/watcher/lib.rs +++ b/src/watcher/lib.rs @@ -21,6 +21,9 @@ pub mod kevent_watcher; #[path = "WindowsWatcher.rs"] pub mod windows_watcher; +#[path = "PollingWatcher.rs"] +pub mod polling_watcher; + #[path = "WatcherTrace.rs"] pub mod watcher_trace; diff --git a/test/cli/watch/watch.test.ts b/test/cli/watch/watch.test.ts index 3ddfe6ea182e..646611d7a0f7 100644 --- a/test/cli/watch/watch.test.ts +++ b/test/cli/watch/watch.test.ts @@ -47,6 +47,76 @@ afterEach(() => { watchee?.kill(); }); +// https://github.com/oven-sh/bun/issues/5841 +// +// Simulates a Docker bind mount / WSL /mnt/c path: inotify_add_watch reports +// success but the kernel never delivers events. Without BUN_WATCHER_USE_POLLING +// the watcher blocks on read() forever and never reloads; with it, the polling +// backend stats the file and picks up the change. +it.skipIf(!isLinux || !(Bun.which("cc") || Bun.which("gcc") || Bun.which("clang")))( + "BUN_WATCHER_USE_POLLING reloads when inotify events never fire", + async () => { + const cc = Bun.which("cc") || Bun.which("gcc") || Bun.which("clang"); + const SHIM_C = /* c */ ` +#define _GNU_SOURCE +static int next_wd = 1; +int inotify_add_watch(int fd, const char *path, unsigned int mask) { + (void)fd; (void)path; (void)mask; + return next_wd++; +} +`; + using dir = tempDir("watch-poll", { + "shim.c": SHIM_C, + "watchee.js": `console.log("tick", 0);\n`, + }); + const cwd = String(dir); + const shimPath = join(cwd, "shim.so"); + await using ccProc = Bun.spawn({ + cmd: [cc!, "-shared", "-fPIC", "-o", shimPath, join(cwd, "shim.c")], + env: bunEnv, + stderr: "pipe", + stdout: "pipe", + }); + const [ccOut, ccErr, ccExit] = await Promise.all([ccProc.stdout.text(), ccProc.stderr.text(), ccProc.exited]); + if (ccExit !== 0) throw new Error(`shim compile failed: ${ccErr || ccOut}`); + + const existing = bunEnv.LD_PRELOAD; + watchee = spawn({ + cwd, + cmd: [bunExe(), "--watch", "--no-clear-screen", "watchee.js"], + env: { + ...bunEnv, + LD_PRELOAD: existing ? `${shimPath}:${existing}` : shimPath, + BUN_WATCHER_USE_POLLING: "1", + BUN_WATCHER_POLL_INTERVAL: "50", + }, + stdout: "pipe", + stderr: "pipe", + stdin: "ignore", + }); + + const decoder = new TextDecoder(); + let buf = ""; + let i = 0; + for await (const chunk of watchee.stdout) { + buf += decoder.decode(chunk); + while (buf.includes("\n")) { + const nl = buf.indexOf("\n"); + const line = buf.slice(0, nl); + buf = buf.slice(nl + 1); + if (!line.startsWith("tick ")) continue; + expect(line).toBe(`tick ${i}`); + i++; + if (i === 4) break; + await Bun.write(join(cwd, "watchee.js"), `console.log("tick", ${i});\n`); + } + if (i === 4) break; + } + expect(i).toBe(4); + }, + 20000, +); + // Watcher::start() must propagate a failed thread spawn as an Err through its // Result return instead of aborting inside start() with `.expect()`. An // LD_PRELOAD shim arms on inotify_init1 (which Watcher::init() calls on Linux From 728cdb7e007e5831751a3efde866d6f4ef51c6f4 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 01:05:56 +0000 Subject: [PATCH 2/9] fix clippy: use bun_collections::HashMap, drop dead_code cfg_attrs --- src/watcher/KEventWatcher.rs | 2 +- src/watcher/PollingWatcher.rs | 6 +++--- src/watcher/Watcher.rs | 27 +++++++-------------------- src/watcher/WindowsWatcher.rs | 8 ++++---- 4 files changed, 15 insertions(+), 28 deletions(-) diff --git a/src/watcher/KEventWatcher.rs b/src/watcher/KEventWatcher.rs index 70eba3a886b9..f35941ddd087 100644 --- a/src/watcher/KEventWatcher.rs +++ b/src/watcher/KEventWatcher.rs @@ -52,7 +52,7 @@ pub(crate) fn watch_event_from_kevent(kevent: &libc::kevent) -> WatchEvent { pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { let _flush = Output::flush_guard(); - let fd = this.platform.native().fd; + let fd = this.platform.native_mut().fd; let mut changelist: [libc::kevent; CHANGELIST_COUNT] = bun_core::ffi::zeroed(); diff --git a/src/watcher/PollingWatcher.rs b/src/watcher/PollingWatcher.rs index 61ce398bb5d1..8a560858c002 100644 --- a/src/watcher/PollingWatcher.rs +++ b/src/watcher/PollingWatcher.rs @@ -2,9 +2,9 @@ //! don't fire (Docker/WSL bind mounts, NFS/SMB, virtiofs/9p). Enabled via //! `BUN_WATCHER_USE_POLLING=1`; interval via `BUN_WATCHER_POLL_INTERVAL` (ms). -use std::collections::HashMap; use std::time::Duration; +use bun_collections::{HashMap, IdentityContext}; use bun_core::ZStr; use bun_sys::{self as sys, stat_mtime}; @@ -43,7 +43,7 @@ pub struct PollingWatcher { /// `flush_evictions`' `swap_remove` reordering doesn't invalidate state. /// Guarded by `Watcher.mutex` (written from `add_file` on the JS thread /// and from the watcher thread's diff step). - snapshots: HashMap, + snapshots: HashMap>, /// Scratch reused across cycles; only touched by the watcher thread. scratch_idx: Vec<(WatchItemIndex, HashType)>, scratch_path: Vec>, @@ -54,7 +54,7 @@ impl PollingWatcher { pub fn new(interval_ms: u64) -> Self { Self { interval: Duration::from_millis(interval_ms.max(1)), - snapshots: HashMap::new(), + snapshots: HashMap::default(), scratch_idx: Vec::new(), scratch_path: Vec::new(), scratch_stat: Vec::new(), diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index 4f4c152bfac0..33abf4c2f307 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -90,6 +90,9 @@ pub(crate) type Platform = platform::Platform; /// inotify/kqueue/ReadDirectoryChangesW implementation; `Polling` stat()s /// each watched file on an interval for mounts that can't deliver native /// change events. +// `Watcher` is itself `Box`'d in `init()` and there is one per process, so +// the size skew between variants costs one heap slot, not stack. +#[allow(clippy::large_enum_variant)] pub enum Backend { Native(Platform), Polling(PollingWatcher), @@ -100,16 +103,6 @@ impl Backend { /// `watch_loop_cycle` / kqueue registration, which `watch_loop()` /// dispatches to only when `self` is `Native`. #[inline] - #[cfg_attr(any(target_os = "linux", target_os = "android"), allow(dead_code))] - pub(crate) fn native(&self) -> &Platform { - match self { - Backend::Native(p) => p, - Backend::Polling(_) => unreachable!("native() on polling backend"), - } - } - - #[inline] - #[cfg_attr(any(target_os = "macos", target_os = "freebsd"), allow(dead_code))] pub(crate) fn native_mut(&mut self) -> &mut Platform { match self { Backend::Native(p) => p, @@ -117,12 +110,6 @@ impl Backend { } } - #[inline] - #[cfg_attr(not(any(target_os = "macos", target_os = "freebsd")), allow(dead_code))] - pub(crate) fn is_polling(&self) -> bool { - matches!(self, Backend::Polling(_)) - } - fn stop(&mut self) { match self { Backend::Native(p) => p.stop(), @@ -480,7 +467,7 @@ impl Watcher { // route to the right module; EV_ADD on an existing (ident, filter) replaces in // place. See #29524. #[cfg(any(target_os = "macos", target_os = "freebsd"))] - if !self.platform.is_polling() { + if matches!(self.platform, Backend::Native(_)) { if (item as usize) < self.watchlist.len() { let moved_fd = self.watchlist.items_fd()[item as usize]; if moved_fd.is_valid() { @@ -542,7 +529,7 @@ impl Watcher { // Basically: // - We register the event here. // our while(true) loop above receives notification of changes to any of the events created here. - let _ = bun_sys::kevent(self.platform.native().fd, &[event], &mut [], None); + let _ = bun_sys::kevent(self.platform.native_mut().fd, &[event], &mut [], None); } fn append_file_assume_capacity( @@ -586,7 +573,7 @@ impl Watcher { p.register(hash, file_path); } #[cfg(any(target_os = "macos", target_os = "freebsd"))] - if !self.platform.is_polling() { + if matches!(self.platform, Backend::Native(_)) { self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); } #[cfg(any(target_os = "linux", target_os = "android"))] @@ -669,7 +656,7 @@ impl Watcher { let watchlist_id = self.watchlist.len(); #[cfg(any(target_os = "macos", target_os = "freebsd"))] - if !self.platform.is_polling() { + if matches!(self.platform, Backend::Native(_)) { self.add_file_descriptor_to_kqueue_without_checks(fd, watchlist_id); } #[cfg(any(target_os = "linux", target_os = "android"))] diff --git a/src/watcher/WindowsWatcher.rs b/src/watcher/WindowsWatcher.rs index ddb0c1b78388..f5d9a04f4ee4 100644 --- a/src/watcher/WindowsWatcher.rs +++ b/src/watcher/WindowsWatcher.rs @@ -398,7 +398,7 @@ pub(crate) enum Timeout { pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // We re-borrow buf inside the inner loop instead of holding `&this.platform.buf` // across calls to `this.platform.next()`. - let base_idx = this.platform.native().base_idx; + let base_idx = this.platform.native_mut().base_idx; let mut event_id: usize = 0; @@ -432,7 +432,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { bun_core::scoped_log!( watcher, "watcher update event: (filename: {}, action: {}", - bstr::BStr::new(&this.platform.native().buf[..eventpath_len]), + bstr::BStr::new(&this.platform.native_mut().buf[..eventpath_len]), <&'static str>::from(event.action) ); @@ -451,7 +451,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // are released before we touch `this.watch_events` or hand the // whole `&mut Watcher` to `process_watch_event_batch`. let rel = { - let eventpath = &this.platform.native().buf[..eventpath_len]; + let eventpath = &this.platform.native_mut().buf[..eventpath_len]; let path = &this.watchlist.items_file_path()[item_idx]; let rel = is_parent_or_equal(path.as_ref(), eventpath); bun_core::scoped_log!( @@ -483,7 +483,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> bun_sys::Result<()> { // then dereference a pointer with invalidated provenance — UB that MIRI flags. // The callee never touches `platform.watcher`, so re-deriving the pointer // here from the now-current `&mut Watcher` restores valid provenance. - iter.watcher = BackRef::new(&this.platform.native().watcher); + iter.watcher = BackRef::new(&this.platform.native_mut().watcher); // Reset event_id to start a new batch event_id = 0; } From b0fb36cccb97dbc96a4c79cac3c87471e2e37e9b Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 01:12:11 +0000 Subject: [PATCH 3/9] trim comments --- src/bun_core/env_var.rs | 6 ++---- src/watcher/PollingWatcher.rs | 16 ++++------------ src/watcher/Watcher.rs | 13 ++++--------- 3 files changed, 10 insertions(+), 25 deletions(-) diff --git a/src/bun_core/env_var.rs b/src/bun_core/env_var.rs index d21ade40e8e1..4ceb1a0486c7 100644 --- a/src/bun_core/env_var.rs +++ b/src/bun_core/env_var.rs @@ -118,10 +118,8 @@ platform_specific_new!(pub LIBRARY_PATH: string, posix = "LIBRARY_PATH", windows new!(pub BUN_TEST_DRAIN_EVENT_LOOP: boolean, "BUN_TEST_DRAIN_EVENT_LOOP", { default: false }); new!(pub BUN_TMPDIR: string, "BUN_TMPDIR", {}); new!(pub BUN_WATCHER_TRACE: string, "BUN_WATCHER_TRACE", {}); -// Poll the filesystem instead of using inotify/kqueue/ReadDirectoryChangesW -// for `--watch` / `--hot`. Needed on mounts that can't deliver native change -// events (Docker bind mounts from a Windows/macOS host, WSL `/mnt/...`, -// NFS/SMB). See src/watcher/PollingWatcher.rs. +// `--watch`/`--hot` stat-polling fallback for mounts without native change +// events (Docker/WSL bind mounts, NFS). See src/watcher/PollingWatcher.rs. new!(pub BUN_WATCHER_USE_POLLING: boolean, "BUN_WATCHER_USE_POLLING", { default: false }); new!(pub BUN_WATCHER_POLL_INTERVAL: unsigned, "BUN_WATCHER_POLL_INTERVAL", {}); new!(pub CI: boolean, "CI", {}); diff --git a/src/watcher/PollingWatcher.rs b/src/watcher/PollingWatcher.rs index 8a560858c002..aa536459da2d 100644 --- a/src/watcher/PollingWatcher.rs +++ b/src/watcher/PollingWatcher.rs @@ -39,12 +39,9 @@ impl Snapshot { pub struct PollingWatcher { pub interval: Duration, - /// Baseline stat per watched file, keyed by `WatchItem.hash` so - /// `flush_evictions`' `swap_remove` reordering doesn't invalidate state. - /// Guarded by `Watcher.mutex` (written from `add_file` on the JS thread - /// and from the watcher thread's diff step). + /// Keyed by `WatchItem.hash`; guarded by `Watcher.mutex`. snapshots: HashMap>, - /// Scratch reused across cycles; only touched by the watcher thread. + /// Watcher-thread-only scratch, reused across cycles. scratch_idx: Vec<(WatchItemIndex, HashType)>, scratch_path: Vec>, scratch_stat: Vec, @@ -61,10 +58,8 @@ impl PollingWatcher { } } - /// Capture the baseline stat for `path` at the moment it's registered - /// (same point where inotify/kqueue would start listening), so a write - /// that lands between registration and the first poll cycle is detected. - /// Caller must hold `Watcher.mutex`. + /// Baseline stat at registration time so a write between `add_file` and + /// the first poll cycle is detected. Caller holds `Watcher.mutex`. pub(crate) fn register(&mut self, hash: HashType, path: &[u8]) { self.snapshots.insert(hash, stat_path(path)); } @@ -125,9 +120,6 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> sys::Result<()> { return Ok(()); } - // Move the watcher-thread-only scratch buffers out so `&mut this` stays - // free for `dispatch_file_updates`; `snapshots` stays in place because the - // JS thread's `register()` may write it concurrently under `this.mutex`. let Backend::Polling(poll) = &mut this.platform else { unreachable!() }; diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index 33abf4c2f307..987010f83508 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -86,12 +86,9 @@ impl AnyResolveWatcher { // ideally, the constants above can be inlined pub(crate) type Platform = platform::Platform; -/// Runtime-selected watch backend. `Native` is the compile-time -/// inotify/kqueue/ReadDirectoryChangesW implementation; `Polling` stat()s -/// each watched file on an interval for mounts that can't deliver native -/// change events. -// `Watcher` is itself `Box`'d in `init()` and there is one per process, so -// the size skew between variants costs one heap slot, not stack. +/// Runtime-selected watch backend: the compile-time native impl or the +/// stat-polling fallback for mounts without native change events. +// `Watcher` is `Box`'d and per-process; the variant size skew is one heap slot. #[allow(clippy::large_enum_variant)] pub enum Backend { Native(Platform), @@ -99,9 +96,7 @@ pub enum Backend { } impl Backend { - /// Unwrap the native platform. Only called from native - /// `watch_loop_cycle` / kqueue registration, which `watch_loop()` - /// dispatches to only when `self` is `Native`. + /// Only reached from paths `watch_loop()` dispatches when `self` is Native. #[inline] pub(crate) fn native_mut(&mut self) -> &mut Platform { match self { From 67837108ab316bfc8365955f90868d5867294077 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 01:19:03 +0000 Subject: [PATCH 4/9] watcher: auto-enable polling on 9p/NFS/SMB mounts (WSL /mnt/*) When BUN_WATCHER_USE_POLLING is unset, statfs() the project root and switch to the polling backend when f_type indicates a filesystem that accepts inotify watches but never emits events for remote changes (9p/drvfs on WSL, NFS, SMB/CIFS, Parallels shared folders). Prints a one-line note so the user knows why. BUN_WATCHER_USE_POLLING=0 forces it off. --- docs/runtime/watch-mode.mdx | 4 ++-- src/watcher/PollingWatcher.rs | 36 ++++++++++++++++++++++++++++++++++- src/watcher/Watcher.rs | 13 ++++++++++++- 3 files changed, 49 insertions(+), 4 deletions(-) diff --git a/docs/runtime/watch-mode.mdx b/docs/runtime/watch-mode.mdx index f93a3e08f488..9920c20516d7 100644 --- a/docs/runtime/watch-mode.mdx +++ b/docs/runtime/watch-mode.mdx @@ -84,13 +84,13 @@ Bun's watcher relies on the operating system's native file-change APIs (inotify - WSL paths under `/mnt/c/...` - NFS, SMB, and other network shares -If edits on the host are not picked up inside the container, set `BUN_WATCHER_USE_POLLING=1` to switch `--watch` and `--hot` to a polling backend that periodically `stat()`s each watched file: +On Linux, Bun automatically falls back to polling when it detects that the project root is on one of these filesystems (9p, NFS, SMB/CIFS) and prints a note. For other setups, or to force the behavior, set `BUN_WATCHER_USE_POLLING=1` to switch `--watch` and `--hot` to a polling backend that periodically `stat()`s each watched file: ```bash terminal icon="terminal" BUN_WATCHER_USE_POLLING=1 bun --watch index.ts ``` -The poll interval defaults to 100 ms and can be changed with `BUN_WATCHER_POLL_INTERVAL` (in milliseconds). Polling uses more CPU than native watching, so only enable it when native events are unavailable. +The poll interval defaults to 100 ms and can be changed with `BUN_WATCHER_POLL_INTERVAL` (in milliseconds). Polling uses more CPU than native watching; set `BUN_WATCHER_USE_POLLING=0` to disable it if Bun enables it and you prefer native events. --- diff --git a/src/watcher/PollingWatcher.rs b/src/watcher/PollingWatcher.rs index aa536459da2d..da37e0fbcaab 100644 --- a/src/watcher/PollingWatcher.rs +++ b/src/watcher/PollingWatcher.rs @@ -1,6 +1,7 @@ //! Stat-polling fallback for filesystems where native change notifications //! don't fire (Docker/WSL bind mounts, NFS/SMB, virtiofs/9p). Enabled via -//! `BUN_WATCHER_USE_POLLING=1`; interval via `BUN_WATCHER_POLL_INTERVAL` (ms). +//! `BUN_WATCHER_USE_POLLING=1`, or automatically on Linux when the project +//! root is on such a filesystem; interval via `BUN_WATCHER_POLL_INTERVAL` (ms). use std::time::Duration; @@ -17,6 +18,39 @@ bun_core::declare_scope!(watcher, visible); pub const DEFAULT_INTERVAL_MS: u64 = 100; +/// Returns `true` when `root` is on a Linux filesystem whose inotify watches +/// are accepted but never emit events for remote changes, so the polling +/// backend should be selected even without `BUN_WATCHER_USE_POLLING=1`. +/// Deliberately conservative: overlayfs and FUSE are excluded because the +/// common Docker/local case works; users on those can opt in explicitly. +/// Constants from `include/uapi/linux/magic.h`. +pub(crate) fn should_auto_poll(root: &[u8]) -> bool { + #[cfg(target_os = "linux")] + { + const V9FS_MAGIC: i64 = 0x0102_1997; // WSL2 drvfs (/mnt/*) + const SMB_MAGIC: i64 = 0x517B; + const SMB2_MAGIC: i64 = 0xFE53_4D42; + const CIFS_MAGIC: i64 = 0xFF53_4D42; + const NFS_MAGIC: i64 = 0x6969; + const PRL_FS_MAGIC: i64 = 0x7C7C_6673; // Parallels shared folders + + let mut buf = bun_paths::path_buffer_pool::get(); + let len = root.len().min(buf.len() - 1); + buf[..len].copy_from_slice(&root[..len]); + buf[len] = 0; + let zpath = ZStr::from_buf(&buf[..], len); + if let Ok(st) = sys::statfs(zpath) { + let ty = st.f_type as i64; + return matches!( + ty, + V9FS_MAGIC | SMB_MAGIC | SMB2_MAGIC | CIFS_MAGIC | NFS_MAGIC | PRL_FS_MAGIC + ); + } + } + let _ = root; + false +} + #[derive(Clone, Copy, Default)] struct Snapshot { mtime_sec: i64, diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index 987010f83508..b738a396b6f5 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -215,7 +215,18 @@ impl Watcher { ctx.on_watch_error(err); } - let platform = if bun_core::env_var::BUN_WATCHER_USE_POLLING::get().unwrap_or(false) { + let use_polling = match bun_core::env_var::BUN_WATCHER_USE_POLLING::get() { + Some(v) => v, + None if polling::should_auto_poll(top_level_dir) => { + bun_core::note!( + "{} is on a filesystem that does not report file changes; falling back to polling for --watch/--hot. Set BUN_WATCHER_USE_POLLING=0 to disable.", + bstr::BStr::new(top_level_dir), + ); + true + } + None => false, + }; + let platform = if use_polling { let interval = bun_core::env_var::BUN_WATCHER_POLL_INTERVAL .get() .unwrap_or(polling::DEFAULT_INTERVAL_MS); From 17bea52ebaafdaddfa626afd698885d2865df665 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 01:28:29 +0000 Subject: [PATCH 5/9] address review: don't advance baseline past MAX_COUNT; only ENOENT/ENOTDIR means gone; prune snapshots on eviction; inherit stderr in test --- src/watcher/PollingWatcher.rs | 49 ++++++++++++++++++++++------------- src/watcher/Watcher.rs | 3 +++ test/cli/watch/watch.test.ts | 2 +- 3 files changed, 35 insertions(+), 19 deletions(-) diff --git a/src/watcher/PollingWatcher.rs b/src/watcher/PollingWatcher.rs index da37e0fbcaab..1eaa6de13848 100644 --- a/src/watcher/PollingWatcher.rs +++ b/src/watcher/PollingWatcher.rs @@ -78,7 +78,7 @@ pub struct PollingWatcher { /// Watcher-thread-only scratch, reused across cycles. scratch_idx: Vec<(WatchItemIndex, HashType)>, scratch_path: Vec>, - scratch_stat: Vec, + scratch_stat: Vec>, } impl PollingWatcher { @@ -95,16 +95,23 @@ impl PollingWatcher { /// Baseline stat at registration time so a write between `add_file` and /// the first poll cycle is detected. Caller holds `Watcher.mutex`. pub(crate) fn register(&mut self, hash: HashType, path: &[u8]) { - self.snapshots.insert(hash, stat_path(path)); + self.snapshots + .insert(hash, stat_path(path).unwrap_or_default()); + } + + /// Caller holds `Watcher.mutex`. + pub(crate) fn unregister(&mut self, hash: HashType) { + self.snapshots.remove(&hash); } pub fn stop(&mut self) {} } -fn stat_path(path: &[u8]) -> Snapshot { +/// `None` = transient errno (ESTALE/EIO/…); caller keeps the previous snapshot. +fn stat_path(path: &[u8]) -> Option { let mut buf = bun_paths::path_buffer_pool::get(); if path.len() >= buf.len() { - return Snapshot::default(); + return Some(Snapshot::default()); } buf[..path.len()].copy_from_slice(path); buf[path.len()] = 0; @@ -116,15 +123,18 @@ fn stat_path(path: &[u8]) -> Snapshot { let (size, ino) = (st.st_size as u64, st.st_ino as u64); #[cfg(windows)] let (size, ino) = (st.st_size, st.st_ino); - Snapshot { + Some(Snapshot { mtime_sec: mt.sec, mtime_nsec: mt.nsec, size, ino, exists: true, - } + }) } - Err(_) => Snapshot::default(), + Err(err) => match err.get_errno() { + sys::E::ENOENT | sys::E::ENOTDIR => Some(Snapshot::default()), + _ => None, + }, } } @@ -195,7 +205,7 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> sys::Result<()> { unreachable!() }; for (k, &(index, hash)) in scratch_idx.iter().enumerate() { - let now = scratch_stat[k]; + let Some(now) = scratch_stat[k] else { continue }; let op = match poll.snapshots.get(&hash) { Some(prev) if now.differs(prev) => { if now.exists { @@ -210,17 +220,20 @@ pub(crate) fn watch_loop_cycle(this: &mut Watcher) -> sys::Result<()> { continue; } }; - poll.snapshots.insert(hash, now); - - if event_id < MAX_COUNT { - this.watch_events[event_id] = WatchEvent { - index, - op, - name_off: 0, - name_len: 0, - }; - event_id += 1; + // Only advance the baseline when the event is actually emitted, so + // changes past MAX_COUNT in one cycle surface on the next cycle + // instead of being silently swallowed. + if event_id >= MAX_COUNT { + break; } + poll.snapshots.insert(hash, now); + this.watch_events[event_id] = WatchEvent { + index, + op, + name_off: 0, + name_len: 0, + }; + event_id += 1; } } diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index b738a396b6f5..1dcb545a0e37 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -466,6 +466,9 @@ impl Watcher { if item == last_item || self.watchlist.len() <= item as usize { continue; } + if let Backend::Polling(p) = &mut self.platform { + p.unregister(self.watchlist.items_hash()[item as usize]); + } self.watchlist.swap_remove(item as usize); // swapRemove put a different entry at `item`, but its kqueue registration still diff --git a/test/cli/watch/watch.test.ts b/test/cli/watch/watch.test.ts index 646611d7a0f7..0326d2e5bca2 100644 --- a/test/cli/watch/watch.test.ts +++ b/test/cli/watch/watch.test.ts @@ -91,7 +91,7 @@ int inotify_add_watch(int fd, const char *path, unsigned int mask) { BUN_WATCHER_POLL_INTERVAL: "50", }, stdout: "pipe", - stderr: "pipe", + stderr: "inherit", stdin: "ignore", }); From 165d0c17e3c4a81718b318268478ceea3c363d55 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 01:47:31 +0000 Subject: [PATCH 6/9] env_var: drop default on BUN_WATCHER_USE_POLLING so unset reaches auto-detect With { default: false }, get() returned Some(false) when unset (never None), so the should_auto_poll arm in Watcher::init was unreachable. --- src/bun_core/env_var.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/bun_core/env_var.rs b/src/bun_core/env_var.rs index 4ceb1a0486c7..08491baf9847 100644 --- a/src/bun_core/env_var.rs +++ b/src/bun_core/env_var.rs @@ -119,8 +119,8 @@ new!(pub BUN_TEST_DRAIN_EVENT_LOOP: boolean, "BUN_TEST_DRAIN_EVENT_LOOP", { defa new!(pub BUN_TMPDIR: string, "BUN_TMPDIR", {}); new!(pub BUN_WATCHER_TRACE: string, "BUN_WATCHER_TRACE", {}); // `--watch`/`--hot` stat-polling fallback for mounts without native change -// events (Docker/WSL bind mounts, NFS). See src/watcher/PollingWatcher.rs. -new!(pub BUN_WATCHER_USE_POLLING: boolean, "BUN_WATCHER_USE_POLLING", { default: false }); +// events (Docker/WSL bind mounts, NFS). No default: unset → auto-detect. +new!(pub BUN_WATCHER_USE_POLLING: boolean, "BUN_WATCHER_USE_POLLING", {}); new!(pub BUN_WATCHER_POLL_INTERVAL: unsigned, "BUN_WATCHER_POLL_INTERVAL", {}); new!(pub CI: boolean, "CI", {}); new!(pub CI_COMMIT_SHA: string, "CI_COMMIT_SHA", {}); From 3ca78947e14016c39a6b40f70fe8177f3331d74f Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 02:14:38 +0000 Subject: [PATCH 7/9] watcher: make requires_file_descriptors runtime-aware of polling backend Callers on macOS/FreeBSD were still opening per-file fds (and bailing on open failure) when polling is active, even though the polling backend stats by path and never uses the fd. --- src/bundler/bundle_v2.rs | 5 +++-- src/jsc/hot_reloader.rs | 8 ++++++++ src/runtime/bake/dev_server/mod.rs | 5 +++-- src/runtime/jsc_hooks.rs | 14 +++++++------- src/watcher/Watcher.rs | 18 ++++++++++++++---- 5 files changed, 35 insertions(+), 15 deletions(-) diff --git a/src/bundler/bundle_v2.rs b/src/bundler/bundle_v2.rs index 49d092acb299..2698eae3b76a 100644 --- a/src/bundler/bundle_v2.rs +++ b/src/bundler/bundle_v2.rs @@ -4362,10 +4362,11 @@ pub mod bv2_impl { break 'add_watchers; } + let bun_watcher = this.bun_watcher_mut().unwrap(); // TODO: support explicit watchFiles array. this is not done // right now because DevServer requires a table to map // watched files and dirs to their respective dependants. - let fd = if bun_watcher::REQUIRES_FILE_DESCRIPTORS { + let fd = if bun_watcher.requires_file_descriptors() { let mut buf = bun_paths::path_buffer_pool::get(); // On kqueue platforms paths are already // posix-separated so `z()` alone suffices. @@ -4382,7 +4383,7 @@ pub mod bv2_impl { }; // Failures to watch are intentionally ignored. - let _ = this.bun_watcher_mut().unwrap().add_file::( + let _ = bun_watcher.add_file::( fd, &load.path, bun_wyhash::hash(load.path.as_ref()) as u32, diff --git a/src/jsc/hot_reloader.rs b/src/jsc/hot_reloader.rs index 678cfdc6e936..d19687ef6b2a 100644 --- a/src/jsc/hot_reloader.rs +++ b/src/jsc/hot_reloader.rs @@ -53,6 +53,14 @@ impl ImportWatcher { } } + #[inline] + pub fn requires_file_descriptors(&self) -> bool { + match self { + ImportWatcher::Hot(w) | ImportWatcher::Watch(w) => w.requires_file_descriptors(), + ImportWatcher::None => false, + } + } + /// Look up the cached fd (and `package_json` column) for `hash` under the /// watcher's mutex, snapshotting both before returning. /// diff --git a/src/runtime/bake/dev_server/mod.rs b/src/runtime/bake/dev_server/mod.rs index 00c3b6f4e712..f71e3035b8a3 100644 --- a/src/runtime/bake/dev_server/mod.rs +++ b/src/runtime/bake/dev_server/mod.rs @@ -1356,7 +1356,8 @@ impl DirectoryWatchStore { Ok(None) | Err(_) => None, }; - let (fd, owned_fd): (bun_sys::Fd, bool) = if bun_watcher::REQUIRES_FILE_DESCRIPTORS { + let requires_fds = self.dev_bun_watcher().requires_file_descriptors(); + let (fd, owned_fd): (bun_sys::Fd, bool) = if requires_fds { if let Some(fd) = cache_fd { (fd, false) } else { @@ -1389,7 +1390,7 @@ impl DirectoryWatchStore { (bun_sys::Fd::INVALID, false) }; let fd_guard = scopeguard::guard(fd, move |fd| { - if bun_watcher::REQUIRES_FILE_DESCRIPTORS && owned_fd { + if requires_fds && owned_fd { fd.close(); } }); diff --git a/src/runtime/jsc_hooks.rs b/src/runtime/jsc_hooks.rs index 519a84d04ab0..c7cb9962d671 100644 --- a/src/runtime/jsc_hooks.rs +++ b/src/runtime/jsc_hooks.rs @@ -3337,9 +3337,14 @@ fn transpile_source_code_inner( { break 'auto_watch; } + // SAFETY: `bun_watcher` is the `*mut ImportWatcher` + // set when `is_watcher_enabled()`; cast recovers the concrete + // type. + let watcher = + unsafe { &mut *(*jsc_vm).bun_watcher.cast::() }; // kqueue watchers need a file descriptor to receive event - // notifications on it; inotify/win32 watch by path. - let input_fd = if bun_watcher::REQUIRES_FILE_DESCRIPTORS { + // notifications on it; inotify/win32/polling watch by path. + let input_fd = if watcher.requires_file_descriptors() { let mut buf = bun_paths::path_buffer_pool::get(); if path.text.len() >= buf.len() { break 'auto_watch; @@ -3353,11 +3358,6 @@ fn transpile_source_code_inner( bun_sys::Fd::INVALID }; let hash = bun_watcher::Watcher::get_hash(path.text); - // SAFETY: `bun_watcher` is the `*mut ImportWatcher` - // set when `is_watcher_enabled()`; cast recovers the concrete - // type. - let watcher = - unsafe { &mut *(*jsc_vm).bun_watcher.cast::() }; if watcher .add_file::( input_fd, diff --git a/src/watcher/Watcher.rs b/src/watcher/Watcher.rs index 1dcb545a0e37..3082eef1f5db 100644 --- a/src/watcher/Watcher.rs +++ b/src/watcher/Watcher.rs @@ -28,6 +28,9 @@ bun_core::define_scoped_log!(log, watcher, visible); pub const MAX_COUNT: usize = 128; +/// Prefer [`Watcher::requires_file_descriptors`] when a `Watcher` is in scope; +/// this compile-time value is `true` on kqueue platforms even when the polling +/// backend (which needs no fds) is active. #[cfg(any(target_os = "macos", target_os = "freebsd"))] pub const REQUIRES_FILE_DESCRIPTORS: bool = true; #[cfg(not(any(target_os = "macos", target_os = "freebsd")))] @@ -347,6 +350,14 @@ impl Watcher { bun_wyhash::hash(filepath) as HashType } + /// Runtime check: the kqueue backend watches by fd, so callers must open + /// one per file; inotify/Windows/polling watch by path and pass + /// `Fd::INVALID`. + #[inline] + pub fn requires_file_descriptors(&self) -> bool { + REQUIRES_FILE_DESCRIPTORS && matches!(self.platform, Backend::Native(_)) + } + /// # Safety /// `this` must be the unique heap pointer returned from [`init`]. The /// watcher thread takes ownership: after `watch_loop` exits, this function @@ -867,8 +878,7 @@ impl Watcher { } // Only open fd if we might need it - #[cfg(any(target_os = "macos", target_os = "freebsd"))] - let fd: Fd = { + let fd: Fd = if self.requires_file_descriptors() { let mut path_z = bun_paths::PathBuffer::uninit(); if file_path.len() >= path_z.len() { return false; @@ -882,9 +892,9 @@ impl Watcher { Ok(opened) => opened, Err(_) => return false, } + } else { + Fd::INVALID }; - #[cfg(not(any(target_os = "macos", target_os = "freebsd")))] - let fd: Fd = Fd::INVALID; let res = self.add_file::(fd, file_path, hash, loader, Fd::INVALID, None); match res { From 7ba9f93585c76de535636f56b158252bd2cf855e Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 02:47:04 +0000 Subject: [PATCH 8/9] docs: note that polling does not detect newly-created files --- docs/runtime/watch-mode.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/runtime/watch-mode.mdx b/docs/runtime/watch-mode.mdx index 9920c20516d7..7a931a338f6d 100644 --- a/docs/runtime/watch-mode.mdx +++ b/docs/runtime/watch-mode.mdx @@ -92,6 +92,8 @@ BUN_WATCHER_USE_POLLING=1 bun --watch index.ts The poll interval defaults to 100 ms and can be changed with `BUN_WATCHER_POLL_INTERVAL` (in milliseconds). Polling uses more CPU than native watching; set `BUN_WATCHER_USE_POLLING=0` to disable it if Bun enables it and you prefer native events. +Polling tracks changes to files that are already in the module graph. Creating a new file that satisfies a previously failing import is not detected until a watched file is edited or the process is restarted. + --- ## `--hot` mode From 2d87a4937c5cb6c524fa400eda6d43e2a978eee0 Mon Sep 17 00:00:00 2001 From: robobun <117481402+robobun@users.noreply.github.com> Date: Wed, 29 Jul 2026 03:57:40 +0000 Subject: [PATCH 9/9] ci: retrigger