Deprecate redactedHeaderFields (#32)

Deprecate redactedHeaderFields

### Motivation

For details, see apple/swift-openapi-generator#113.

### Modifications

 This PR deprecates the feature in the current 0.1.x version, so that it can be removed in 0.2.0.

### Result

When adopters use this feature in 0.1.x, they will get a deprecation warning.

### Test Plan

Moved the tests to the deprecated section as well, to be removed before we tag 0.2.0.


Reviewed by: FranzBusch, simonjbeaumont

Builds:
     ✔︎ pull request validation (5.8) - Build finished. 
     ✔︎ pull request validation (5.9) - Build finished. 
     ✔︎ pull request validation (api breakage) - Build finished. 
     ✔︎ pull request validation (docc test) - Build finished. 
     ✔︎ pull request validation (integration test) - Build finished. 
     ✔︎ pull request validation (nightly) - Build finished. 
     ✔︎ pull request validation (soundness) - Build finished. 

#32

Author: czechboy0

Sources/OpenAPIRuntime/Conversion/CurrencyExtensions.swift

@@ -16,7 +16,7 @@ import Foundation
 extension HeaderField: CustomStringConvertible {
     public var description: String {
         let value: String
-        if HeaderField.redactedHeaderFields.contains(name.lowercased()) {
+        if HeaderField.internalRedactedHeaderFields.contains(name.lowercased()) {
             value = "<redacted>"
         } else {
             value = self.value

Sources/OpenAPIRuntime/Deprecated/Deprecated_RedactedHeaderFields.swift

@@ -0,0 +1,93 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+#if canImport(Darwin)
+import Foundation
+#else
+@preconcurrency import Foundation
+#endif
+
+/// A protected-by-locks storage for ``redactedHeaderFields``.
+private class RedactedHeadersStorage: @unchecked Sendable {
+    /// The underlying storage of ``redactedHeaderFields``,
+    /// protected by a lock.
+    private var _locked_redactedHeaderFields: Set<String> = HeaderField.defaultRedactedHeaderFields
+
+    /// The header fields to be redacted.
+    var redactedHeaderFields: Set<String> {
+        get {
+            lock.lock()
+            defer {
+                lock.unlock()
+            }
+            return _locked_redactedHeaderFields
+        }
+        set {
+            lock.lock()
+            defer {
+                lock.unlock()
+            }
+            _locked_redactedHeaderFields = newValue
+        }
+    }
+
+    /// The lock used for protecting access to `_locked_redactedHeaderFields`.
+    private let lock: NSLock = {
+        let lock = NSLock()
+        lock.name = "com.apple.swift-openapi-runtime.lock.redactedHeaderFields"
+        return lock
+    }()
+}
+
+extension HeaderField {
+    /// Names of the header fields whose values should be redacted.
+    ///
+    /// All header field names are lowercased when added to the set.
+    ///
+    /// The values of header fields with the provided names will are replaced
+    /// with "<redacted>" when using `HeaderField.description`.
+    ///
+    /// Use this to avoid leaking sensitive tokens into application logs.
+    @available(*, deprecated, message: "This feature is deprecated and will be removed in a future version.")
+    public static var redactedHeaderFields: Set<String> {
+        set {
+            internalRedactedHeaderFields = newValue
+        }
+        get {
+            internalRedactedHeaderFields
+        }
+    }
+
+    /// Names of the header fields whose values should be redacted.
+    ///
+    /// Should be called by code in the runtime library to avoid emitting a deprecation warning.
+    internal static var internalRedactedHeaderFields: Set<String> {
+        set {
+            // Save lowercased versions of the header field names to make
+            // membership checking O(1).
+            redactedHeadersStorage.redactedHeaderFields = Set(newValue.map { $0.lowercased() })
+        }
+        get {
+            return redactedHeadersStorage.redactedHeaderFields
+        }
+    }
+
+    /// The default header field names whose values are redacted.
+    public static let defaultRedactedHeaderFields: Set<String> = [
+        "authorization",
+        "cookie",
+        "set-cookie",
+    ]
+
+    private static let redactedHeadersStorage = RedactedHeadersStorage()
+}

Sources/OpenAPIRuntime/Interface/CurrencyTypes.swift

@@ -18,38 +18,6 @@ import Foundation
 @preconcurrency import Foundation
 #endif
 
-/// A protected-by-locks storage for ``redactedHeaderFields``.
-private class RedactedHeadersStorage: @unchecked Sendable {
-    /// The underlying storage of ``redactedHeaderFields``,
-    /// protected by a lock.
-    private var _locked_redactedHeaderFields: Set<String> = HeaderField.defaultRedactedHeaderFields
-
-    /// The header fields to be redacted.
-    var redactedHeaderFields: Set<String> {
-        get {
-            lock.lock()
-            defer {
-                lock.unlock()
-            }
-            return _locked_redactedHeaderFields
-        }
-        set {
-            lock.lock()
-            defer {
-                lock.unlock()
-            }
-            _locked_redactedHeaderFields = newValue
-        }
-    }
-
-    /// The lock used for protecting access to `_locked_redactedHeaderFields`.
-    private let lock: NSLock = {
-        let lock = NSLock()
-        lock.name = "com.apple.swift-openapi-runtime.lock.redactedHeaderFields"
-        return lock
-    }()
-}
-
 /// A header field used in an HTTP request or response.
 public struct HeaderField: Equatable, Hashable, Sendable {
 
@@ -69,36 +37,6 @@ public struct HeaderField: Equatable, Hashable, Sendable {
     }
 }
 
-extension HeaderField {
-    /// Names of the header fields whose values should be redacted.
-    ///
-    /// All header field names are lowercased when added to the set.
-    ///
-    /// The values of header fields with the provided names will are replaced
-    /// with "<redacted>" when using `HeaderField.description`.
-    ///
-    /// Use this to avoid leaking sensitive tokens into application logs.
-    public static var redactedHeaderFields: Set<String> {
-        set {
-            // Save lowercased versions of the header field names to make
-            // membership checking O(1).
-            redactedHeadersStorage.redactedHeaderFields = Set(newValue.map { $0.lowercased() })
-        }
-        get {
-            return redactedHeadersStorage.redactedHeaderFields
-        }
-    }
-
-    /// The default header field names whose values are redacted.
-    public static let defaultRedactedHeaderFields: Set<String> = [
-        "authorization",
-        "cookie",
-        "set-cookie",
-    ]
-
-    private static let redactedHeadersStorage = RedactedHeadersStorage()
-}
-
 /// Describes the HTTP method used in an OpenAPI operation.
 ///
 /// https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-7

Tests/OpenAPIRuntimeTests/Interface/Test_CurrencyTypes.swift renamed to Tests/OpenAPIRuntimeTests/Deprecated/Test_Deprecated_RedactedHeaderFields.swift

@@ -12,10 +12,11 @@
 //
 //===----------------------------------------------------------------------===//
 import XCTest
-import OpenAPIRuntime
+@_spi(Generated)@testable import OpenAPIRuntime
 
-final class Test_CurrencyTypes: Test_Runtime {
+final class Test_Deprecated_RedactedHeaderFields: Test_Runtime {
 
+    @available(*, deprecated)
     func _resetRedactedHeaderFields() {
         HeaderField.redactedHeaderFields = HeaderField.defaultRedactedHeaderFields
     }
@@ -35,11 +36,13 @@ final class Test_CurrencyTypes: Test_Runtime {
         }
     }
 
+    @available(*, deprecated)
     override func tearDown() async throws {
         _resetRedactedHeaderFields()
         try await super.tearDown()
     }
 
+    @available(*, deprecated)
     func testDefaultRedactedHeaderFields() {
         XCTAssertEqual(
             HeaderField.redactedHeaderFields,
@@ -51,6 +54,7 @@ final class Test_CurrencyTypes: Test_Runtime {
         )
     }
 
+    @available(*, deprecated)
     func testCustomizeExtraRedactedHeaderField() {
         XCTAssertEqual(
             HeaderField.redactedHeaderFields,