Add readiness signal to DirectoryWatcher, fix DirectoryWatcherTest. (#2066)

Author: jglogan

Sources/APIServer/APIServer+Start.swift

@@ -134,7 +134,7 @@ extension APIServer {
                     group.addTask {
                         do {
                             let localhostResolver = LocalhostDNSHandler(log: log)
-                            await localhostResolver.monitorResolvers()
+                            try await localhostResolver.monitorResolvers()
 
                             let nxDomainResolver = NxDomainResolver()
                             let compositeResolver = CompositeResolver(handlers: [localhostResolver, nxDomainResolver])

Sources/APIServer/LocalhostDNSHandler.swift

@@ -38,8 +38,10 @@ actor LocalhostDNSHandler: DNSHandler {
         self.dns = [DNSName: IPv4Address]()
     }
 
-    public func monitorResolvers() async {
-        await self.watcher.startWatching { [weak self] filePaths in
+    public func monitorResolvers() async throws {
+        var readyIterator = await self.watcher.readyEvents.makeAsyncIterator()
+
+        try await self.watcher.startWatching { [weak self] filePaths in
             var dns: [DNSName: IPv4Address] = [:]
             let regex = try Regex(HostDNSResolver.localhostOptionsRegex)
 
@@ -65,6 +67,11 @@ actor LocalhostDNSHandler: DNSHandler {
                 Task { await self.updateDNS(dns) }
             }
         }
+
+        // Wait for the watcher to actually be watching before returning, so callers can rely on
+        // resolver file changes being observed once this call completes, instead of racing the
+        // watcher's own poll cadence.
+        await readyIterator.next()
     }
 
     public func answer(query: Message) async throws -> Message? {

Sources/ContainerOS/DirectoryWatcher.swift

@@ -27,6 +27,9 @@ import SystemPackage
 /// If the target directory does not exist yet, it polls until the directory is created.
 /// the target is created, then transitions to watching the target directly.
 ///
+/// Each instance supports exactly one `startWatching` session and one reader of `readyEvents`.
+/// Calling `startWatching` a second time throws; create a new instance to watch again.
+///
 /// Example usage:
 /// ```swift
 /// let watcher = DirectoryWatcher(directoryPath: myPath, log: logger)
@@ -46,6 +49,18 @@ public actor DirectoryWatcher {
 
     private let log: Logger?
 
+    /// Emits an event each time the watcher transitions from not-watching to actively watching,
+    /// i.e. immediately after its `DispatchSource` is resumed. Buffered (`.unbounded`), so a
+    /// consumer that starts iterating after the event fired still observes it — callers should
+    /// grab this stream before calling `startWatching` and `await` it instead of sleeping a
+    /// guessed duration to know when the watcher is actually live.
+    ///
+    /// Supports only one concurrent reader: `AsyncStream` delivers each value to a single
+    /// waiting iterator, not to every iterator, so a second consumer would race the first for
+    /// events instead of both observing them.
+    public let readyEvents: AsyncStream<Void>
+    private let readyEventsContinuation: AsyncStream<Void>.Continuation
+
     /// Creates a new `DirectoryWatcher` for the given directory path.
     ///
     /// - Parameters:
@@ -56,13 +71,21 @@ public actor DirectoryWatcher {
         self.monitorQueue = DispatchQueue(label: "monitor:\(directoryPath.string)")
         self.log = log
         self.source = Mutex(nil)
+        (self.readyEvents, self.readyEventsContinuation) = AsyncStream.makeStream()
     }
 
     /// Starts watching the directory for changes.
     ///
     /// - Parameters:
     ///   - handler: handler to run on directory state change.
-    public func startWatching(handler: @Sendable @escaping ([FilePath]) throws -> Void) {
+    /// - Throws: `ContainerizationError(.invalidState)` if this watcher is already watching.
+    ///   Only one `startWatching` session is supported per `DirectoryWatcher` instance; create a
+    ///   new instance if you need to watch again after stopping.
+    public func startWatching(handler: @Sendable @escaping ([FilePath]) throws -> Void) throws {
+        guard task == nil else {
+            throw ContainerizationError(.invalidState, message: "already watching \(directoryPath.string)")
+        }
+
         self.task = Task {
             var exists: Bool
             var isDir: ObjCBool = false
@@ -130,10 +153,12 @@ public actor DirectoryWatcher {
 
         source.withLock { $0 = dispatchSource }
         dispatchSource.resume()
+        readyEventsContinuation.yield()
     }
 
     deinit {
         self.task?.cancel()
         source.withLock { $0?.cancel() }
+        readyEventsContinuation.finish()
     }
 }

Tests/ContainerOSTests/DirectoryWatcherTest.swift

@@ -52,23 +52,35 @@ struct DirectoryWatcherTest {
         }
     }
 
+    /// Polls `condition` until it returns true or `timeout` elapses. Used only to wait for the
+    /// handler's async invocation after a mutation, never to guess how long watcher setup takes.
+    private func waitUntil(timeout: Duration = .seconds(10), condition: () -> Bool) async throws {
+        let deadline = ContinuousClock.now + timeout
+        while !condition() && ContinuousClock.now < deadline {
+            try await Task.sleep(for: .milliseconds(50))
+        }
+    }
+
     @Test func testWatchingExistingDirectory() async throws {
         try await withTempDir { tempPath in
-
             let watcher = DirectoryWatcher(directoryPath: tempPath, log: nil)
+            var readyIterator = await watcher.readyEvents.makeAsyncIterator()
             let createdPaths = CreatedPaths()
             let name = "newFile"
 
-            await watcher.startWatching { [createdPaths] paths in
+            try await watcher.startWatching { [createdPaths] paths in
                 for path in paths where path.lastComponent?.string == name {
                     createdPaths.paths.append(path)
                 }
             }
 
-            try await Task.sleep(for: .milliseconds(100))
+            // Wait for the watcher to actually resume watching, instead of guessing a sleep
+            // duration that can race the watcher's own poll cadence.
+            await readyIterator.next()
+
             let newFile = tempPath.appending(name)
             FileManager.default.createFile(atPath: newFile.string, contents: nil)
-            try await Task.sleep(for: .milliseconds(500))
+            try await waitUntil { !createdPaths.paths.isEmpty }
 
             #expect(!createdPaths.paths.isEmpty, "directory watcher failed to detect new file")
             #expect(createdPaths.paths.first!.lastComponent?.string == name)
@@ -81,22 +93,25 @@ struct DirectoryWatcherTest {
             let childPath = tempPath.appending(uuid)
 
             let watcher = DirectoryWatcher(directoryPath: childPath, log: nil)
+            var readyIterator = await watcher.readyEvents.makeAsyncIterator()
             let createdPaths = CreatedPaths()
             let name = "newFile"
 
-            await watcher.startWatching { [createdPaths] paths in
+            try await watcher.startWatching { [createdPaths] paths in
                 for path in paths where path.lastComponent?.string == name {
                     createdPaths.paths.append(path)
                 }
             }
 
-            try await Task.sleep(for: .milliseconds(100))
             try FileManager.default.createDirectory(atPath: childPath.string, withIntermediateDirectories: true)
 
-            try await Task.sleep(for: DirectoryWatcher.watchPeriod)
+            // Wait for the watcher to actually resume watching, instead of guessing a sleep
+            // duration that can race the watcher's own poll cadence.
+            await readyIterator.next()
+
             let newFile = childPath.appending(name)
             FileManager.default.createFile(atPath: newFile.string, contents: nil)
-            try await Task.sleep(for: .milliseconds(500))
+            try await waitUntil { !createdPaths.paths.isEmpty }
 
             #expect(!createdPaths.paths.isEmpty, "directory watcher failed to detect parent directory")
             #expect(createdPaths.paths.first!.lastComponent?.string == name)
@@ -110,23 +125,25 @@ struct DirectoryWatcherTest {
             let childPath = tempPath.appending(parent).appending(child)
 
             let watcher = DirectoryWatcher(directoryPath: childPath, log: nil)
+            var readyIterator = await watcher.readyEvents.makeAsyncIterator()
             let createdPaths = CreatedPaths()
             let name = "newFile"
 
-            await watcher.startWatching { paths in
+            try await watcher.startWatching { paths in
                 for path in paths where path.lastComponent?.string == name {
                     createdPaths.paths.append(path)
                 }
             }
 
-            try await Task.sleep(for: .milliseconds(100))
             try FileManager.default.createDirectory(atPath: childPath.string, withIntermediateDirectories: true)
 
-            try await Task.sleep(for: DirectoryWatcher.watchPeriod)
+            // Wait for the watcher to actually resume watching, instead of guessing a sleep
+            // duration that can race the watcher's own poll cadence.
+            await readyIterator.next()
 
             let newFile = childPath.appending(name)
             FileManager.default.createFile(atPath: newFile.string, contents: nil)
-            try await Task.sleep(for: .milliseconds(500))
+            try await waitUntil { !createdPaths.paths.isEmpty }
 
             #expect(!createdPaths.paths.isEmpty, "directory watcher failed to detect parent directory")
             #expect(createdPaths.paths.first!.lastComponent?.string == name)
@@ -139,36 +156,41 @@ struct DirectoryWatcherTest {
             try FileManager.default.createDirectory(atPath: dirPath.string, withIntermediateDirectories: true)
 
             let watcher = DirectoryWatcher(directoryPath: dirPath, log: nil)
+            var readyIterator = await watcher.readyEvents.makeAsyncIterator()
             let createdPaths = CreatedPaths()
             let beforeDelete = "beforeDelete"
             let afterDelete = "afterDelete"
 
-            await watcher.startWatching { [createdPaths] paths in
+            try await watcher.startWatching { [createdPaths] paths in
                 for path in paths
                 where path.lastComponent?.string == beforeDelete || path.lastComponent?.string == afterDelete {
                     createdPaths.paths.append(path)
                 }
             }
 
-            try await Task.sleep(for: .milliseconds(100))
+            // Wait for the watcher to actually resume watching, instead of guessing a sleep
+            // duration that can race the watcher's own poll cadence.
+            await readyIterator.next()
+
             let file1 = dirPath.appending(beforeDelete)
             FileManager.default.createFile(atPath: file1.string, contents: nil)
-            try await Task.sleep(for: .milliseconds(100))
+            try await waitUntil { createdPaths.paths.contains { $0.lastComponent?.string == beforeDelete } }
 
             try FileManager.default.removeItem(atPath: dirPath.string)
-            try await Task.sleep(for: .milliseconds(100))
             try FileManager.default.createDirectory(atPath: dirPath.string, withIntermediateDirectories: true)
-            try await Task.sleep(for: DirectoryWatcher.watchPeriod)
+
+            // `readyEvents` yields once per resume, so this waits however long the watcher
+            // actually takes to notice the delete, then re-arm on the recreated directory —
+            // no guessing needed even though this transition takes an unknown amount of time.
+            await readyIterator.next()
 
             let file2 = dirPath.appending(afterDelete)
             FileManager.default.createFile(atPath: file2.string, contents: nil)
-
-            try await Task.sleep(for: .milliseconds(500))
+            try await waitUntil { createdPaths.paths.contains { $0.lastComponent?.string == afterDelete } }
 
             #expect(!createdPaths.paths.isEmpty, "directory watcher failed to detect new file")
             #expect(
                 Set(createdPaths.paths.compactMap { $0.lastComponent?.string }) == Set([beforeDelete, afterDelete]))
         }
-
     }
 }