Add a mode flags optionset to FileHandle. (#1597)

This PR adds an `OptionSet`-conforming type to `FileHandle` so that we
don't have to hard-code mode strings we pass to `fopen()`.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

Sources/Testing/Attachments/Attachment.swift

@@ -432,10 +432,9 @@ extension Attachable where Self: ~Copyable {
 #endif
 
     try withUnsafeBytes(for: attachment) { buffer in
-      // Note "x" in the mode string which indicates that the file should be
-      // created and opened exclusively. The underlying `fopen()` call will thus
-      // fail with `EEXIST` if a file exists at `filePath`.
-      let file = try FileHandle(atPath: filePath, mode: "wxeb")
+      // The underlying `fopen()` call should fail with `EEXIST` if a file
+      // exists at `filePath`.
+      let file = try FileHandle(atPath: filePath, options: [.writeAccess, .creationRequired])
       try file.write(buffer)
     }
   }

Sources/Testing/ExitTests/ExitTest.swift

@@ -674,21 +674,20 @@ extension ExitTest {
   ///
   /// The effect of calling this function more than once for the same
   /// environment variable is undefined.
-  private static func _makeFileHandle(forEnvironmentVariableNamed name: String, mode: String) -> FileHandle? {
+  private static func _makeFileHandle(forEnvironmentVariableNamed name: String, options: FileHandle.OpenOptions) -> FileHandle? {
     guard let environmentVariable = Environment.variable(named: name) else {
       return nil
     }
 
     // Erase the environment variable so that it cannot accidentally be opened
     // twice (nor, in theory, affect the code of the exit test.)
     Environment.setVariable(nil, named: name)
-
     var fd: CInt?
 #if SWT_TARGET_OS_APPLE || os(Linux) || os(FreeBSD) || os(OpenBSD)
     fd = CInt(environmentVariable)
 #elseif os(Windows)
     if let handle = UInt(environmentVariable).flatMap(HANDLE.init(bitPattern:)) {
-      var flags: CInt = switch (mode.contains("r"), mode.contains("w")) {
+      var flags: CInt = switch (options.contains(.readAccess), options.contains(.writeAccess)) {
       case (true, true):
         _O_RDWR
       case (true, false):
@@ -698,7 +697,7 @@ extension ExitTest {
       case (false, false):
         0
       }
-      flags |= _O_BINARY
+      flags |= _O_BINARY | _O_NOINHERIT
       fd = _open_osfhandle(Int(bitPattern: handle), flags)
     }
 #else
@@ -708,7 +707,7 @@ extension ExitTest {
       return nil
     }
 
-    return try? FileHandle(unsafePOSIXFileDescriptor: fd, mode: mode)
+    return try? FileHandle(unsafePOSIXFileDescriptor: fd, options: options)
   }
 
   /// Make a string suitable for use as the value of an environment variable
@@ -768,7 +767,7 @@ extension ExitTest {
     // If an exit test was found, inject back channel handling into its body.
     // External tools authors should set up their own back channel mechanisms
     // and ensure they're installed before calling ExitTest.callAsFunction().
-    guard let backChannel = _makeFileHandle(forEnvironmentVariableNamed: "SWT_BACKCHANNEL", mode: "wb") else {
+    guard let backChannel = _makeFileHandle(forEnvironmentVariableNamed: "SWT_BACKCHANNEL", options: [.writeAccess]) else {
       return result
     }
 
@@ -1105,7 +1104,7 @@ extension ExitTest {
   private mutating func _decodeCapturedValuesForEntryPoint() throws {
     // Read the content of the captured values stream provided by the parent
     // process above.
-    guard let fileHandle = Self._makeFileHandle(forEnvironmentVariableNamed: "SWT_CAPTURED_VALUES", mode: "rb") else {
+    guard let fileHandle = Self._makeFileHandle(forEnvironmentVariableNamed: "SWT_CAPTURED_VALUES", options: [.readAccess]) else {
       return
     }
     let capturedValuesJSON = try fileHandle.readToEnd()

Sources/Testing/Support/FileHandle.swift

@@ -48,15 +48,97 @@ struct FileHandle: ~Copyable, Sendable {
     Self(unsafeCFILEHandle: swt_stderr(), closeWhenDone: false)
   }
 
+  /// Options to apply when opening a file.
+  ///
+  /// An instance of this type does _not_ represent a value of type `mode_t`.
+  /// Use its ``stringValue`` property to get a string you can pass to `fopen()`
+  /// and related functions.
+  struct OpenOptions: RawRepresentable, OptionSet {
+    var rawValue: Int
+
+    /// The file should be opened for reading.
+    ///
+    /// This option is equivalent to the `"r"` character or `O_RDONLY`. If you
+    /// also specify ``writeAccess``, the two options combined are equivalent to
+    /// the `"w+"` characters or `O_RDWR`.
+    static var readAccess: Self { .init(rawValue: 1 << 0) }
+
+    /// The file should be opened for writing.
+    ///
+    /// This option is equivalent to the `"w"` character or `O_WRONLY`. If you
+    /// also specify ``readAccess``, the two options combined are equivalent to
+    /// the `"w+"` characters or `O_RDWR`.
+    static var writeAccess: Self { .init(rawValue: 1 << 1) }
+
+    /// The underlying file descriptor or handle should be inherited by any
+    /// child processes created by the current process.
+    ///
+    /// By default, the resulting file handle is not inherited by any child
+    /// processes (that is, `FD_CLOEXEC` is set on POSIX-like systems and
+    /// `HANDLE_FLAG_INHERIT` is cleared on Windows.).
+    ///
+    /// This option is equivalent to the `"e"` character (`"N"` on Windows) or
+    /// `O_CLOEXEC` (`_O_NOINHERIT` on Windows).
+    static var inheritedByChild: Self { .init(rawValue: 1 << 2) }
+
+    /// The file must be created when opened.
+    ///
+    /// When you use this option and a file already exists at the given path
+    /// when you try to open it, the testing library throws an error equivalent
+    /// to `EEXIST`.
+    ///
+    /// This option is equivalent to the `"x"` character or `O_CREAT | O_EXCL`.
+    static var creationRequired: Self { .init(rawValue: 1 << 3) }
+
+    /// The string representation of this instance, suitable for passing to
+    /// `fopen()` and related functions.
+    var stringValue: String {
+      var result = ""
+      result.reserveCapacity(8)
+
+      if contains(.writeAccess) {
+        result.append("w")
+      } else if contains(.readAccess) {
+        result.append("r")
+      }
+      // Always open files in binary mode, not text mode.
+      result.append("b")
+
+      if contains(.readAccess) && contains(.writeAccess) {
+        result.append("+")
+      }
+
+      if contains(.creationRequired) {
+        result.append("x")
+      }
+
+      if !contains(.inheritedByChild) {
+#if os(Windows)
+        // On Windows, "N" is used rather than "e" to signify that a file
+        // handle is not inherited.
+        result.append("N")
+#else
+        result.append("e")
+#endif
+      }
+
+#if DEBUG
+      assert(result.isContiguousUTF8, "Constructed a file mode string '\(result)' that isn't UTF-8.")
+#endif
+
+      return result
+    }
+  }
+
   /// Initialize an instance of this type by opening a file at the given path
-  /// with the given mode.
+  /// with the given options.
   ///
   /// - Parameters:
   ///   - path: The path to open.
-  ///   - mode: The mode to open `path` with, such as `"wb"`.
+  ///   - options: The options to open `path` with.
   ///
   /// - Throws: Any error preventing the stream from being opened.
-  init(atPath path: String, mode: String) throws {
+  init(atPath path: String, options: OpenOptions) throws {
 #if os(Windows)
     // Special-case CONOUT$ to map to stdout. This way, if somebody specifies
     // CONOUT$ as the target path for XML or JSON output from `swift test`,
@@ -68,21 +150,14 @@ struct FileHandle: ~Copyable, Sendable {
     // To our knowledge, this sort of special-casing is not required on
     // POSIX-like platforms (i.e. when opening "/dev/stdout"), but it can be
     // adapted for use there if some POSIX-like platform does need it.
-    if path == "CONOUT$" && mode.contains("w") {
+    if path == "CONOUT$" && options.contains(.writeAccess) {
       self = .stdout
       return
     }
 
-    // On Windows, "N" is used rather than "e" to signify that a file handle is
-    // not inherited.
-    var mode = mode
-    if let eIndex = mode.firstIndex(of: "e") {
-      mode.replaceSubrange(eIndex ... eIndex, with: "N")
-    }
-
     // Windows deprecates fopen() as insecure, so call _wfopen_s() instead.
     let fileHandle = try path.withCString(encodedAs: UTF16.self) { path in
-      try mode.withCString(encodedAs: UTF16.self) { mode in
+      try options.stringValue.withCString(encodedAs: UTF16.self) { mode in
         var file: SWT_FILEHandle?
         let result = _wfopen_s(&file, path, mode)
         guard let file, result == 0 else {
@@ -92,7 +167,7 @@ struct FileHandle: ~Copyable, Sendable {
       }
     }
 #else
-    guard let fileHandle = fopen(path, mode) else {
+    guard let fileHandle = fopen(path, options.stringValue) else {
       throw CError(rawValue: swt_errno())
     }
 #endif
@@ -103,28 +178,32 @@ struct FileHandle: ~Copyable, Sendable {
   ///
   /// - Parameters:
   ///   - path: The path to read from.
+  ///   - options: The options to open the file in. ``OpenOptions/readAccess``
+  ///     is added to this value automatically.
   ///
   /// - Throws: Any error preventing the stream from being opened.
   ///
   /// By default, the resulting file handle is not inherited by any child
   /// processes (that is, `FD_CLOEXEC` is set on POSIX-like systems and
   /// `HANDLE_FLAG_INHERIT` is cleared on Windows.).
-  init(forReadingAtPath path: String) throws {
-    try self.init(atPath: path, mode: "reb")
+  init(forReadingAtPath path: String, options: OpenOptions = []) throws {
+    try self.init(atPath: path, options: options.union(.readAccess))
   }
 
   /// Initialize an instance of this type to write to the given path.
   ///
   /// - Parameters:
   ///   - path: The path to write to.
+  ///   - options: The options to open the file in. ``OpenOptions/writeAccess``
+  ///     is added to this value automatically.
   ///
   /// - Throws: Any error preventing the stream from being opened.
   ///
   /// By default, the resulting file handle is not inherited by any child
   /// processes (that is, `FD_CLOEXEC` is set on POSIX-like systems and
   /// `HANDLE_FLAG_INHERIT` is cleared on Windows.).
-  init(forWritingAtPath path: String) throws {
-    try self.init(atPath: path, mode: "web")
+  init(forWritingAtPath path: String, options: OpenOptions = []) throws {
+    try self.init(atPath: path, options: options.union(.writeAccess))
   }
 
   /// Initialize an instance of this type with an existing C file handle.
@@ -148,17 +227,17 @@ struct FileHandle: ~Copyable, Sendable {
   ///   - fd: The POSIX file descriptor to wrap. The caller is responsible for
   ///     ensuring that this file handle is open in the expected mode and that
   ///     another part of the system won't close it.
-  ///   - mode: The mode `fd` was opened with, such as `"wb"`.
+  ///   - options: The options `fd` was opened with.
   ///
   /// - Throws: Any error preventing the stream from being opened.
   ///
   /// The resulting file handle takes ownership of `fd` and closes it when it is
   /// deinitialized or if an error is thrown from this initializer.
-  init(unsafePOSIXFileDescriptor fd: CInt, mode: String) throws {
+  init(unsafePOSIXFileDescriptor fd: CInt, options: OpenOptions) throws {
 #if os(Windows)
-    let fileHandle = _fdopen(fd, mode)
+    let fileHandle = _fdopen(fd, options.stringValue)
 #else
-    let fileHandle = fdopen(fd, mode)
+    let fileHandle = fdopen(fd, options.stringValue)
 #endif
     guard let fileHandle else {
       let errorCode = swt_errno()
@@ -566,11 +645,11 @@ extension FileHandle {
       defer {
         fdReadEnd = -1
       }
-      try readEnd = FileHandle(unsafePOSIXFileDescriptor: fdReadEnd, mode: "rb")
+      try readEnd = FileHandle(unsafePOSIXFileDescriptor: fdReadEnd, options: .readAccess)
       defer {
         fdWriteEnd = -1
       }
-      try writeEnd = FileHandle(unsafePOSIXFileDescriptor: fdWriteEnd, mode: "wb")
+      try writeEnd = FileHandle(unsafePOSIXFileDescriptor: fdWriteEnd, options: .writeAccess)
     } catch {
       // Don't leak file handles! Ensure we've cleared both pointers before
       // returning so the state is consistent in the caller.

Tests/TestingTests/AttachmentTests.swift

@@ -72,7 +72,7 @@ struct AttachmentTests {
 
 #if !SWT_NO_FILE_IO
   func compare(_ attachableValue: borrowing MySendableAttachable, toContentsOfFileAtPath filePath: String) throws {
-    let file = try FileHandle(forReadingAtPath: filePath)
+    let file = try Testing.FileHandle(forReadingAtPath: filePath)
     let bytes = try file.readToEnd()
 
     let decodedValue = if #available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *) {

Tests/TestingTests/Support/FileHandleTests.swift

@@ -48,7 +48,7 @@ struct FileHandleTests {
   @Test("Init from invalid file descriptor")
   func invalidFileDescriptor() throws {
     #expect(throws: CError.self) {
-      _ = try FileHandle(unsafePOSIXFileDescriptor: -1, mode: "")
+      _ = try FileHandle(unsafePOSIXFileDescriptor: -1, options: [])
     }
   }
 #endif
@@ -86,7 +86,7 @@ struct FileHandleTests {
   @Test("Writing requires contiguous storage")
   func writeIsContiguous() async {
     await #expect(processExitsWith: .failure) {
-      let fileHandle = try FileHandle.null(mode: "wb")
+      let fileHandle = try FileHandle.null(options: [.writeAccess])
       try fileHandle.write([1, 2, 3, 4, 5].lazy.filter { $0 == 1 })
     }
   }
@@ -110,15 +110,15 @@ struct FileHandleTests {
 
   @Test("Cannot write bytes to a read-only file")
   func cannotWriteBytesToReadOnlyFile() throws {
-    let fileHandle = try FileHandle.null(mode: "rb")
+    let fileHandle = try FileHandle.null(options: [.readAccess])
     #expect(throws: CError.self) {
       try fileHandle.write([0, 1, 2, 3, 4, 5])
     }
   }
 
   @Test("Cannot write string to a read-only file")
   func cannotWriteStringToReadOnlyFile() throws {
-    let fileHandle = try FileHandle.null(mode: "rb")
+    let fileHandle = try FileHandle.null(options: [.readAccess])
     #expect(throws: CError.self) {
       try fileHandle.write("Impossible!")
     }
@@ -181,7 +181,7 @@ struct FileHandleTests {
 
   @Test("/dev/null is not a TTY or pipe")
   func devNull() throws {
-    let fileHandle = try FileHandle.null(mode: "wb")
+    let fileHandle = try FileHandle.null(options: [.writeAccess])
     #expect(!Bool(fileHandle.isTTY))
 #if !SWT_NO_PIPES
     #expect(!Bool(fileHandle.isPipe))
@@ -230,11 +230,11 @@ extension FileHandle {
     return FileHandle(unsafeCFILEHandle: tmpFile, closeWhenDone: true)
   }
 
-  static func null(mode: String) throws -> FileHandle {
+  static func null(options: FileHandle.OpenOptions) throws -> FileHandle {
 #if os(Windows)
-    try FileHandle(atPath: "NUL", mode: mode)
+    try FileHandle(atPath: "NUL", options: options)
 #else
-    try FileHandle(atPath: "/dev/null", mode: mode)
+    try FileHandle(atPath: "/dev/null", options: options)
 #endif
   }
 }

Tests/TestingTests/SwiftPMTests.swift

@@ -223,7 +223,7 @@ struct SwiftPMTests {
       configuration.handleEvent(Event(.runEnded, testID: nil, testCaseID: nil), in: eventContext)
     }
 
-    let fileHandle = try FileHandle(forReadingAtPath: temporaryFilePath)
+    let fileHandle = try Testing.FileHandle(forReadingAtPath: temporaryFilePath)
     let fileContents = try fileHandle.readToEnd()
     #expect(!fileContents.isEmpty)
     #expect(fileContents.contains(UInt8(ascii: "<")))
@@ -241,7 +241,7 @@ struct SwiftPMTests {
       _ = remove(temporaryFilePath)
     }
     do {
-      let fileHandle = try FileHandle(forWritingAtPath: temporaryFilePath)
+      let fileHandle = try Testing.FileHandle(forWritingAtPath: temporaryFilePath)
       try fileHandle.write(
         """
         {

Tests/TestingTests/Traits/TagListTests.swift

@@ -143,7 +143,7 @@ struct TagListTests {
     }
     """
     try jsonContent.withUTF8 { jsonContent in
-      let fileHandle = try FileHandle(forWritingAtPath: jsonPath)
+      let fileHandle = try Testing.FileHandle(forWritingAtPath: jsonPath)
       try fileHandle.write(jsonContent)
     }
     defer {