Deprecate not-actually-public Base64 APIs (#3022)

Motivation:

The not-actually-public `_NIOBase64` module has public extensions on
`String`. These are visible when transitively depending on `_NIOBase64`
but shouldn't be.

Modifications:

- Add underscored variants
- Deprecate public variants

Result:

Stricter API

Sources/NIOCore/ByteBuffer-aux.swift

@@ -733,13 +733,13 @@ extension ByteBuffer: Codable {
     public init(from decoder: Decoder) throws {
         let container = try decoder.singleValueContainer()
         let base64String = try container.decode(String.self)
-        self = try ByteBuffer(bytes: base64String.base64Decoded())
+        self = try ByteBuffer(bytes: base64String._base64Decoded())
     }
 
     /// Encodes this buffer as a base64 string in a single value container.
     public func encode(to encoder: Encoder) throws {
         var container = encoder.singleValueContainer()
-        let base64String = String(base64Encoding: self.readableBytesView)
+        let base64String = String(_base64Encoding: self.readableBytesView)
         try container.encode(base64String)
     }
 }

Sources/NIOWebSocket/NIOWebSocketClientUpgrader.swift

@@ -149,7 +149,7 @@ extension NIOWebSocketClientUpgrader {
             UInt64.random(in: UInt64.min...UInt64.max, using: &generator),
             UInt64.random(in: UInt64.min...UInt64.max, using: &generator)
         )
-        return String(base64Encoding: buffer.readableBytesView)
+        return String(_base64Encoding: buffer.readableBytesView)
     }
     /// Generates a random WebSocket Request Key by generating 16 bytes randomly using the `SystemRandomNumberGenerator` and encoding them as a base64 string as defined in RFC6455 https://tools.ietf.org/html/rfc6455#section-4.1.
     /// - Returns: base64 encoded request key
@@ -179,7 +179,7 @@ private func _shouldAllowUpgrade(upgradeResponse: HTTPResponseHead, requestKey:
     var hasher = SHA1()
     hasher.update(string: requestKey)
     hasher.update(string: magicWebSocketGUID)
-    let expectedAcceptValue = String(base64Encoding: hasher.finish())
+    let expectedAcceptValue = String(_base64Encoding: hasher.finish())
 
     return expectedAcceptValue == acceptValueHeader[0]
 }

Sources/NIOWebSocket/NIOWebSocketServerUpgrader.swift

@@ -15,6 +15,7 @@
 import CNIOSHA1
 import NIOCore
 import NIOHTTP1
+import _NIOBase64
 
 let magicWebSocketGUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
@@ -303,7 +304,7 @@ private func _buildUpgradeResponse(
                 var hasher = SHA1()
                 hasher.update(string: key)
                 hasher.update(string: magicWebSocketGUID)
-                acceptValue = String(base64Encoding: hasher.finish())
+                acceptValue = String(_base64Encoding: hasher.finish())
             }
 
             extraHeaders.replaceOrAdd(name: "Upgrade", value: "websocket")

Sources/_NIOBase64/Base64.swift

@@ -16,15 +16,27 @@
 // https://github.com/fabianfett/swift-base64-kit
 
 extension String {
-
     /// Base64 encode a collection of UInt8 to a string, without the use of Foundation.
+    @available(*, deprecated, message: "This API was unintentionally made public.")
     @inlinable
     public init<Buffer: Collection>(base64Encoding bytes: Buffer) where Buffer.Element == UInt8 {
-        self = Base64.encode(bytes: bytes)
+        self.init(_base64Encoding: bytes)
     }
 
+    @available(*, deprecated, message: "This API was unintentionally made public.")
     @inlinable
     public func base64Decoded() throws -> [UInt8] {
+        try self._base64Decoded()
+    }
+
+    /// Base64 encode a collection of UInt8 to a string, without the use of Foundation.
+    @inlinable
+    public init<Buffer: Collection>(_base64Encoding bytes: Buffer) where Buffer.Element == UInt8 {
+        self = Base64.encode(bytes: bytes)
+    }
+
+    @inlinable
+    public func _base64Decoded() throws -> [UInt8] {
         try Base64.decode(string: self)
     }
 }

Tests/NIOBase64Tests/Base64Test.swift

@@ -13,59 +13,58 @@
 //===----------------------------------------------------------------------===//
 
 import XCTest
-
-@testable import _NIOBase64
+import _NIOBase64
 
 class Base64Test: XCTestCase {
     func testEncodeEmptyData() throws {
         let data = [UInt8]()
-        let encodedData = String(base64Encoding: data)
+        let encodedData = String(_base64Encoding: data)
         XCTAssertEqual(encodedData.count, 0)
     }
 
     func testBase64EncodingOfEmptyString() throws {
         let string = ""
-        let encoded = String(base64Encoding: string.utf8)
+        let encoded = String(_base64Encoding: string.utf8)
         XCTAssertEqual(encoded, "")
     }
 
     func testBase64DecodingOfEmptyString() throws {
         let encoded = ""
         XCTAssertNoThrow {
-            let decoded = try encoded.base64Decoded()
+            let decoded = try encoded._base64Decoded()
             XCTAssertEqual(decoded, [UInt8]())
         }
     }
 
     func testBase64EncodingArrayOfNulls() throws {
         let data = Array(repeating: UInt8(0), count: 10)
-        let encodedData = String(base64Encoding: data)
+        let encodedData = String(_base64Encoding: data)
         XCTAssertEqual(encodedData, "AAAAAAAAAAAAAA==")
     }
 
     func testBase64DecodeArrayOfNulls() throws {
         let encoded = "AAAAAAAAAAAAAA=="
-        let decoded = try! encoded.base64Decoded()
+        let decoded = try! encoded._base64Decoded()
         let expected = Array(repeating: UInt8(0), count: 10)
         XCTAssertEqual(decoded, expected)
     }
 
     func testBase64EncodeingHelloWorld() throws {
         let string = "Hello, world!"
-        let encoded = String(base64Encoding: string.utf8)
+        let encoded = String(_base64Encoding: string.utf8)
         let expected = "SGVsbG8sIHdvcmxkIQ=="
         XCTAssertEqual(encoded, expected)
     }
 
     func testBase64DecodeHelloWorld() throws {
         let encoded = "SGVsbG8sIHdvcmxkIQ=="
-        let decoded = try! encoded.base64Decoded()
+        let decoded = try! encoded._base64Decoded()
         XCTAssertEqual(decoded, "Hello, world!".utf8.map { UInt8($0) })
     }
 
     func testBase64EncodingAllTheBytesSequentially() throws {
         let data = Array(UInt8(0)...UInt8(255))
-        let encodedData = String(base64Encoding: data)
+        let encodedData = String(_base64Encoding: data)
         XCTAssertEqual(
             encodedData,
             "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0+P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn+AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq+wsbKztLW2t7i5uru8vb6/wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t/g4eLj5OXm5+jp6uvs7e7v8PHy8/T19vf4+fr7/P3+/w=="
@@ -74,14 +73,14 @@ class Base64Test: XCTestCase {
 
     func testBase64DecodingWithInvalidLength() {
         let encoded = "dGVzbA!=="
-        XCTAssertThrowsError(try encoded.base64Decoded()) { error in
+        XCTAssertThrowsError(try encoded._base64Decoded()) { error in
             XCTAssertEqual(error as? Base64Error, .invalidLength)
         }
     }
 
     func testBase64DecodeWithInvalidCharacter() throws {
         let encoded = "SGVsbG8sI_dvcmxkIQ=="
-        XCTAssertThrowsError(try encoded.base64Decoded()) { error in
+        XCTAssertThrowsError(try encoded._base64Decoded()) { error in
             XCTAssertEqual(error as? Base64Error, .invalidCharacter)
         }
     }