Skip to content

Modern Docker Management, Designed for Everyone

fix(fswatch): only sync on project file changes, not bare directory events (#2271)

Michael Kaltner5ffac97cb99f
diff --git a/backend/pkg/fswatch/watcher.go b/backend/pkg/fswatch/watcher.go
index 0021eea48..6ca063292 100644
--- a/backend/pkg/fswatch/watcher.go
+++ b/backend/pkg/fswatch/watcher.go
@@ -155,10 +155,16 @@ func (fw *Watcher) processEventInternal(ctx context.Context, event fsnotify.Even
if !ok {
return true
}
- if !fw.shouldHandleEvent(event) {
+
+ // handleEventInternal runs for every event — its job is to keep the
+ // underlying fsnotify subscriptions in sync (attaching newly-created
+ // directories so we can discover compose files that land inside them
+ // afterwards). Sync-firing is gated separately by shouldHandleEventInternal.
+ fw.handleEventInternal(ctx, event)
+
+ if !fw.shouldHandleEventInternal(event) {
return false
}
- fw.handleEvent(ctx, event)
if !debounceTimer.Stop() {
select {
case <-debounceTimer.C:
@@ -188,7 +194,12 @@ func (fw *Watcher) fireDebounceInternal(ctx context.Context, debouncePending *bo
return false
}
-func (fw *Watcher) handleEvent(ctx context.Context, event fsnotify.Event) {
+// handleEventInternal keeps the underlying fsnotify subscriptions in sync with
+// the filesystem: when a new directory is created inside a watched path, it is
+// attached recursively so that compose files dropped inside it are discovered.
+// It does NOT decide whether the event should trigger a sync — that is
+// shouldHandleEventInternal's job.
+func (fw *Watcher) handleEventInternal(ctx context.Context, event fsnotify.Event) {
if event.Has(fsnotify.Create) {
if fw.isWatchableDirectory(event.Name) {
if fw.shouldWatchDir(event.Name) {
@@ -206,17 +217,19 @@ func (fw *Watcher) handleEvent(ctx context.Context, event fsnotify.Event) {
"operation", event.Op.String())
}
-func (fw *Watcher) shouldHandleEvent(event fsnotify.Event) bool {
- name := filepath.Base(event.Name)
-
- // Watch for new directories, compose files, .env being manipulated.
- if event.Has(fsnotify.Write) || event.Has(fsnotify.Create) || event.Has(fsnotify.Rename) || event.Has(fsnotify.Remove) || event.Has(fsnotify.Chmod) {
- if fw.isWatchableDirectory(event.Name) || projects.IsProjectFile(name) || fw.isWatchablePath(event.Name) {
- return true
- }
+// shouldHandleEventInternal reports whether an fsnotify event should trigger a
+// project sync. Only events on known compose / env files qualify; bare
+// directory events do not, because build tools (ESPHome, PlatformIO, npm,
+// etc.) churn through subdirectories and would otherwise spin the sync loop
+// forever. New project directories are still discovered: once the directory
+// create event has been processed by handleEventInternal (which attaches a
+// watch), the compose file's own Create event reaches this filter and passes
+// via IsProjectFile.
+func (fw *Watcher) shouldHandleEventInternal(event fsnotify.Event) bool {
+ if !event.Has(fsnotify.Write) && !event.Has(fsnotify.Create) && !event.Has(fsnotify.Rename) && !event.Has(fsnotify.Remove) {
+ return false
}
-
- return false
+ return projects.IsProjectFile(filepath.Base(event.Name))
}
func (fw *Watcher) addExistingDirectories(root string) error {
@@ -322,16 +335,3 @@ func (fw *Watcher) isWatchableDirectory(path string) bool {
return resolvedInfo.IsDir()
}
-func (fw *Watcher) isWatchablePath(path string) bool {
- cleanPath := filepath.Clean(path)
- if cleanPath == fw.watchedPath {
- return true
- }
-
- parent := filepath.Dir(cleanPath)
- if parent == "." {
- return false
- }
-
- return fw.shouldWatchDir(parent)
-}
diff --git a/backend/pkg/fswatch/watcher_test.go b/backend/pkg/fswatch/watcher_test.go
index 3d8d99097..def4c437d 100644
--- a/backend/pkg/fswatch/watcher_test.go
+++ b/backend/pkg/fswatch/watcher_test.go
@@ -48,17 +48,18 @@ func TestWatcher_StartWatchesExistingSymlinkDirectoriesWhenEnabled(t *testing.T)
}
}
-func TestWatcher_StartTriggersOnAtomicSaveTempFileInsideProjectDir(t *testing.T) {
+func TestWatcher_StartIgnoresNonProjectFileWritesInsideProjectDir(t *testing.T) {
root := t.TempDir()
projectDir := filepath.Join(root, "demo")
- require.NoError(t, os.MkdirAll(projectDir, 0o755))
+ buildDir := filepath.Join(projectDir, ".esphome", "build", "node-1", ".piolibdeps", "node-1", "ESPMicroSpeechFeatures")
+ require.NoError(t, os.MkdirAll(buildDir, 0o755))
changeCh := make(chan struct{}, 1)
ctx := t.Context()
watcher, err := NewWatcher(root, WatcherOptions{
Debounce: 25 * time.Millisecond,
- MaxDepth: 1,
+ MaxDepth: 0,
OnChange: func(context.Context) {
select {
case changeCh <- struct{}{}:
@@ -72,16 +73,24 @@ func TestWatcher_StartTriggersOnAtomicSaveTempFileInsideProjectDir(t *testing.T)
require.NoError(t, watcher.Stop())
}()
- require.NoError(t, os.WriteFile(filepath.Join(projectDir, ".compose.yaml.tmp"), []byte("services: {}\n"), 0o644))
+ // Let the initial attach settle so the build dir is subscribed.
+ time.Sleep(100 * time.Millisecond)
+
+ // Simulate ESPHome / PlatformIO churning through build artifacts inside a
+ // watched project tree. None of these writes touch a compose or env file,
+ // so the sync callback must never fire.
+ for i := 0; i < 5; i++ {
+ require.NoError(t, os.WriteFile(filepath.Join(buildDir, "artifact.bin"), []byte{0x01, 0x02, 0x03}, 0o644))
+ }
select {
case <-changeCh:
- case <-time.After(2 * time.Second):
- t.Fatal("expected temp file change inside project directory to trigger watcher callback")
+ t.Fatal("did not expect non-project file writes to trigger watcher callback")
+ case <-time.After(500 * time.Millisecond):
}
}
-func TestWatcher_StartTriggersOnChmodInsideProjectDir(t *testing.T) {
+func TestWatcher_StartIgnoresChmodOnNonProjectFiles(t *testing.T) {
root := t.TempDir()
projectDir := filepath.Join(root, "demo")
require.NoError(t, os.MkdirAll(projectDir, 0o755))
@@ -110,10 +119,55 @@ func TestWatcher_StartTriggersOnChmodInsideProjectDir(t *testing.T) {
require.NoError(t, os.Chmod(targetFile, 0o600))
+ // Chmod on a non-project file is exactly the noise we're filtering.
+ select {
+ case <-changeCh:
+ t.Fatal("did not expect chmod on a non-project file to trigger watcher callback")
+ case <-time.After(500 * time.Millisecond):
+ }
+}
+
+func TestWatcher_StartFiresOnComposeFileDroppedIntoNewlyCreatedDirectory(t *testing.T) {
+ root := t.TempDir()
+
+ changeCh := make(chan struct{}, 1)
+ ctx := t.Context()
+
+ watcher, err := NewWatcher(root, WatcherOptions{
+ Debounce: 25 * time.Millisecond,
+ MaxDepth: 0,
+ OnChange: func(context.Context) {
+ select {
+ case changeCh <- struct{}{}:
+ default:
+ }
+ },
+ })
+ require.NoError(t, err)
+ require.NoError(t, watcher.Start(ctx))
+ defer func() {
+ require.NoError(t, watcher.Stop())
+ }()
+
+ // A freshly-created subdirectory by itself must NOT trigger a sync.
+ projectDir := filepath.Join(root, "fresh-project")
+ require.NoError(t, os.MkdirAll(projectDir, 0o755))
+
+ select {
+ case <-changeCh:
+ t.Fatal("did not expect plain directory create to trigger watcher callback")
+ case <-time.After(500 * time.Millisecond):
+ }
+
+ // But dropping a compose file inside it must trigger — proving the new
+ // directory was attached to the underlying fsnotify watcher even though
+ // the create itself was not sync-worthy.
+ require.NoError(t, os.WriteFile(filepath.Join(projectDir, "compose.yaml"), []byte("services: {}\n"), 0o644))
+
select {
case <-changeCh:
case <-time.After(2 * time.Second):
- t.Fatal("expected chmod inside project directory to trigger watcher callback")
+ t.Fatal("expected compose file inside newly-created directory to trigger watcher callback")
}
}
@@ -187,7 +241,7 @@ func TestWatcher_StartTriggersOnNestedProjectFileBeyondDepthOne(t *testing.T) {
}
}
-func TestWatcher_StartTriggersOnNestedDirectoryCreateAndRemove(t *testing.T) {
+func TestWatcher_StartIgnoresBareNestedDirectoryCreateAndRemove(t *testing.T) {
root := t.TempDir()
changeCh := make(chan struct{}, 4)
@@ -209,21 +263,25 @@ func TestWatcher_StartTriggersOnNestedDirectoryCreateAndRemove(t *testing.T) {
require.NoError(t, watcher.Stop())
}()
+ // Creating nested directories by themselves must not trigger a sync.
+ // This is what prevents the ESPHome / PlatformIO churn from spinning the
+ // sync loop — they mkdir thousands of build subdirectories during a
+ // compile but never drop compose files in them.
nestedDir := filepath.Join(root, "main-project", "sub-project1")
require.NoError(t, os.MkdirAll(nestedDir, 0o755))
select {
case <-changeCh:
- case <-time.After(2 * time.Second):
- t.Fatal("expected nested directory create to trigger watcher callback")
+ t.Fatal("did not expect plain nested directory create to trigger watcher callback")
+ case <-time.After(500 * time.Millisecond):
}
require.NoError(t, os.RemoveAll(filepath.Join(root, "main-project")))
select {
case <-changeCh:
- case <-time.After(2 * time.Second):
- t.Fatal("expected nested directory removal to trigger watcher callback")
+ t.Fatal("did not expect plain nested directory removal to trigger watcher callback")
+ case <-time.After(500 * time.Millisecond):
}
}