[NIOFileSystem] Provide an API to specify allowing unlimited sized reads

Motivation:

As described in issue [apple#2877](apple#2877), there is no API available to specify allowing a read of unlimited size.

Modifications:

- Add a new `public static` property, `unlimited`, to `ByteCount` representing an unlimited amount of bytes.
- Adapt `ReadableFileHandleProtocol.readToEnd(fromAbsoluteOffset:maximumSizeAllowed:)` to work with `maximumSizeAllowed` being `ByteCount.unlimited`.

Result:

An API to specify allowing a read of an unlimited size will be available.

Sources/NIOFileSystem/ByteCount.swift

@@ -93,6 +93,11 @@ extension ByteCount {
 
         return ByteCount(bytes: Int64(byteBufferMaxIndex))
     }
+
+    /// A ``ByteCount`` for an unlimited amount of bytes.
+    public static var unlimited: ByteCount {
+        ByteCount(bytes: .max)
+    }
 }
 
 extension ByteCount: AdditiveArithmetic {

Sources/NIOFileSystem/FileHandleProtocol.swift

@@ -335,6 +335,11 @@ extension ReadableFileHandleProtocol {
         fromAbsoluteOffset offset: Int64 = 0,
         maximumSizeAllowed: ByteCount
     ) async throws -> ByteBuffer {
+        var maximumSizeAllowed = maximumSizeAllowed
+        if maximumSizeAllowed == .unlimited {
+            maximumSizeAllowed = .byteBufferCapacity
+        }
+
         let info = try await self.info()
         let fileSize = Int64(info.size)
         let readSize = max(Int(fileSize - offset), 0)

Tests/NIOFileSystemIntegrationTests/FileSystemTests.swift

@@ -1818,6 +1818,16 @@ extension FileSystemTests {
             }
         }
     }
+
+    func testReadWithUnlimitedMaximumSizeAllowed() async throws {
+        let path = try await self.fs.temporaryFilePath()
+
+        try await self.fs.withFileHandle(forReadingAndWritingAt: path) { fileHandle in
+            await XCTAssertNoThrowAsync(
+                try await fileHandle.readToEnd(maximumSizeAllowed: .unlimited)
+            )
+        }
+    }
 }
 
 #if !canImport(Darwin) && swift(<5.9.2)

Tests/NIOFileSystemIntegrationTests/XCTestExtensions.swift

@@ -69,4 +69,16 @@ func XCTAssertThrowsFileSystemErrorAsync<R>(
         }
     }
 }
+
+func XCTAssertNoThrowAsync<T>(
+    _ expression: @autoclosure () async throws -> T,
+    file: StaticString = #file,
+    line: UInt = #line
+) async {
+    do {
+        _ = try await expression()
+    } catch {
+        XCTFail("Expression did throw: \(error)", file: file, line: line)
+    }
+}
 #endif

Tests/NIOFileSystemTests/ByteCountTests.swift

@@ -52,6 +52,11 @@ class ByteCountTests: XCTestCase {
         XCTAssertEqual(byteCount.bytes, 10_737_418_240)
     }
 
+    func testByteCountUnlimited() {
+        let byteCount = ByteCount.unlimited
+        XCTAssertEqual(byteCount.bytes, .max)
+    }
+
     func testByteCountEquality() {
         let byteCount1 = ByteCount.bytes(10)
         let byteCount2 = ByteCount.bytes(20)