Add explicit availability annotations (#2234)

Motivation:

gRPC is moving from specifying the platforms in the package manifest to
annotating code with availability annotations.

Modifications:

- Explicitly annotate public API
- Add '-require-explicit-availability' to CI
- Drop platforms

Result:

- gRPC can be used by packages which don't specify their platforms in
the manifest

Author: glbrntt

.github/workflows/main.yml

@@ -13,8 +13,8 @@ jobs:
     with:
       linux_5_9_enabled: false
       linux_5_10_enabled: false
-      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors"
-      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors"
+      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors -Xswiftc -require-explicit-availability"
+      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors -Xswiftc -require-explicit-availability"
       linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
       linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
 

.github/workflows/pull_request.yml

@@ -22,8 +22,8 @@ jobs:
     with:
       linux_5_9_enabled: false
       linux_5_10_enabled: false
-      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors"
-      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors"
+      linux_6_0_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors -Xswiftc -require-explicit-availability"
+      linux_6_1_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors -Xswiftc -require-explicit-availability"
       linux_nightly_next_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
       linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error -Xswiftc -require-explicit-sendable"
 

Package.swift

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import CompilerPluginSupport
 import PackageDescription
 
 let products: [Product] = [
@@ -45,12 +46,28 @@ let dependencies: [Package.Dependency] = [
   ),
 ]
 
-let defaultSwiftSettings: [SwiftSetting] = [
-  .swiftLanguageMode(.v6),
-  .enableUpcomingFeature("ExistentialAny"),
-  .enableUpcomingFeature("InternalImportsByDefault"),
-  .enableUpcomingFeature("MemberImportVisibility"),
-]
+// -------------------------------------------------------------------------------------------------
+
+// This adds some build settings which allow us to map "@available(gRPCSwift 2.x, *)" to
+// the appropriate OS platforms.
+let nextMinorVersion = 2
+let availabilitySettings: [SwiftSetting] = (0 ... nextMinorVersion).map { minor in
+  let name = "gRPCSwift"
+  let version = "2.\(minor)"
+  let platforms = "macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0"
+  let setting = "AvailabilityMacro=\(name) \(version):\(platforms)"
+  return .enableExperimentalFeature(setting)
+}
+
+let defaultSwiftSettings: [SwiftSetting] =
+  availabilitySettings + [
+    .swiftLanguageMode(.v6),
+    .enableUpcomingFeature("ExistentialAny"),
+    .enableUpcomingFeature("InternalImportsByDefault"),
+    .enableUpcomingFeature("MemberImportVisibility"),
+  ]
+
+// -------------------------------------------------------------------------------------------------
 
 let targets: [Target] = [
   // Runtime serialization components
@@ -107,13 +124,6 @@ let targets: [Target] = [
 
 let package = Package(
   name: "grpc-swift",
-  platforms: [
-    .macOS(.v15),
-    .iOS(.v18),
-    .tvOS(.v18),
-    .watchOS(.v11),
-    .visionOS(.v2),
-  ],
   products: products,
   dependencies: dependencies,
   targets: targets

Sources/GRPCCodeGen/CodeGenError.swift

@@ -15,6 +15,7 @@
  */
 
 /// A error thrown by the ``SourceGenerator`` to signal errors in the ``CodeGenerationRequest`` object.
+@available(gRPCSwift 2.0, *)
 public struct CodeGenError: Error, Hashable, Sendable {
   /// The code indicating the domain of the error.
   public var code: Code
@@ -33,6 +34,7 @@ public struct CodeGenError: Error, Hashable, Sendable {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension CodeGenError {
   public struct Code: Hashable, Sendable {
     private enum Value {
@@ -63,6 +65,7 @@ extension CodeGenError {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension CodeGenError: CustomStringConvertible {
   public var description: String {
     return "\(self.code): \"\(self.message)\""

Sources/GRPCCodeGen/CodeGenerationRequest.swift

@@ -16,6 +16,7 @@
 
 /// Describes the services, dependencies and trivia from an IDL file,
 /// and the IDL itself through its specific serializer and deserializer.
+@available(gRPCSwift 2.0, *)
 public struct CodeGenerationRequest {
   /// The name of the source file containing the IDL, including the extension if applicable.
   public var fileName: String
@@ -81,6 +82,7 @@ public struct CodeGenerationRequest {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension CodeGenerationRequest {
   @available(*, deprecated, renamed: "makeSerializerSnippet")
   public var lookupSerializer: (_ messageType: String) -> String {
@@ -120,6 +122,7 @@ extension CodeGenerationRequest {
 }
 
 /// Represents an import: a module or a specific item from a module.
+@available(gRPCSwift 2.0, *)
 public struct Dependency: Equatable {
   /// If the dependency is an item, the property's value is the item representation.
   /// If the dependency is a module, this property is nil.
@@ -261,6 +264,7 @@ public struct Dependency: Equatable {
 }
 
 /// Represents a service described in an IDL file.
+@available(gRPCSwift 2.0, *)
 public struct ServiceDescriptor: Hashable {
   /// Documentation from comments above the IDL service description.
   /// It is already formatted, meaning it contains  "///" and new lines.
@@ -285,6 +289,7 @@ public struct ServiceDescriptor: Hashable {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ServiceDescriptor {
   @available(*, deprecated, renamed: "init(documentation:name:methods:)")
   public init(
@@ -317,6 +322,7 @@ extension ServiceDescriptor {
 }
 
 /// Represents a method described in an IDL file.
+@available(gRPCSwift 2.0, *)
 public struct MethodDescriptor: Hashable {
   /// Documentation from comments above the IDL method description.
   /// It is already formatted, meaning it contains  "///" and new lines.
@@ -357,6 +363,7 @@ public struct MethodDescriptor: Hashable {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension MethodDescriptor {
   @available(*, deprecated, message: "Use MethodName instead of Name")
   public init(
@@ -380,6 +387,7 @@ extension MethodDescriptor {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 public struct ServiceName: Hashable {
   /// The identifying name as used in the service/method descriptors including any namespace.
   ///
@@ -414,6 +422,7 @@ public struct ServiceName: Hashable {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 public struct MethodName: Hashable {
   /// The identifying name as used in the service/method descriptors.
   ///
@@ -445,6 +454,7 @@ public struct MethodName: Hashable {
 
 /// Represents the name associated with a namespace, service or a method, in three different formats.
 @available(*, deprecated, message: "Use ServiceName/MethodName instead.")
+@available(gRPCSwift 2.0, *)
 public struct Name: Hashable {
   /// The base name is the name used for the namespace/service/method in the IDL file, so it should follow
   /// the specific casing of the IDL.
@@ -473,6 +483,7 @@ public struct Name: Hashable {
 }
 
 @available(*, deprecated, message: "Use ServiceName/MethodName instead.")
+@available(gRPCSwift 2.0, *)
 extension Name {
   /// The base name replacing occurrences of "." with "_".
   ///

Sources/GRPCCodeGen/CodeGenerator.swift

@@ -15,10 +15,12 @@
  */
 
 @available(*, deprecated, renamed: "CodeGenerator")
+@available(gRPCSwift 2.0, *)
 public typealias SourceGenerator = CodeGenerator
 
 /// Generates ``SourceFile`` objects containing generated code for the RPCs represented
 /// in a ``CodeGenerationRequest`` object.
+@available(gRPCSwift 2.0, *)
 public struct CodeGenerator: Sendable {
   /// The options regarding the access level, indentation for the generated code
   /// and whether to generate server and client code.
@@ -41,8 +43,10 @@ public struct CodeGenerator: Sendable {
     /// Whether or not server code should be generated.
     public var server: Bool
     /// The name of the core gRPC module.
+    @available(gRPCSwift 2.1, *)
     public var grpcCoreModuleName: String
     /// The availability annotations to use on the generated code.
+    @available(gRPCSwift 2.2, *)
     public var availability: AvailabilityAnnotations = .default
 
     /// Creates a new configuration.
@@ -88,6 +92,7 @@ public struct CodeGenerator: Sendable {
     }
 
     // The availability that generated code is annotated with.
+    @available(gRPCSwift 2.2, *)
     public struct AvailabilityAnnotations: Sendable, Hashable {
       public struct Platform: Sendable, Hashable {
         /// The name of the OS, e.g. 'macOS'.
@@ -156,6 +161,7 @@ public struct CodeGenerator: Sendable {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension AvailabilityDescription {
   init(_ availability: CodeGenerator.Config.AvailabilityAnnotations) throws {
     switch availability.wrapped {

Sources/GRPCCodeGen/Internal/Renderer/RendererProtocol.swift

@@ -31,6 +31,7 @@
 /// into Swift files.
 ///
 /// Rendering is the last phase of the generator pipeline.
+@available(gRPCSwift 2.0, *)
 protocol RendererProtocol {
 
   /// Renders the specified structured code into a raw Swift file.

Sources/GRPCCodeGen/Internal/Renderer/TextBasedRenderer.swift

@@ -111,6 +111,7 @@ extension TextBasedRenderer: Sendable {}
 
 /// A renderer that uses string interpolation and concatenation
 /// to convert the provided structure code into raw string form.
+@available(gRPCSwift 2.0, *)
 struct TextBasedRenderer: RendererProtocol {
 
   func render(
@@ -1207,6 +1208,7 @@ extension String {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension TextBasedRenderer {
 
   /// Returns the provided expression rendered as a string.

Sources/GRPCCodeGen/Internal/StructuredSwift+Client.swift

@@ -194,6 +194,7 @@ extension FunctionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ProtocolDescription {
   /// ```
   /// protocol <Name>: Sendable {
@@ -233,6 +234,7 @@ extension ProtocolDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ExtensionDescription {
   /// ```
   /// extension <Name> {
@@ -503,6 +505,7 @@ extension FunctionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ExtensionDescription {
   /// ```
   /// extension <Name> {
@@ -662,6 +665,7 @@ extension FunctionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension StructDescription {
   /// ```
   /// struct <Name><Transport>: <ClientProtocol> where Transport: GRPCCore.ClientTransport {
@@ -752,6 +756,7 @@ extension StructDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 private func docs(
   for method: MethodDescriptor,
   serializers includeSerializers: Bool = true
@@ -793,6 +798,7 @@ private func docs(
   return Docs.interposeDocs(method.documentation, between: summary, and: allParameters)
 }
 
+@available(gRPCSwift 2.0, *)
 private func explodedDocs(for method: MethodDescriptor) -> String {
   let summary = "/// Call the \"\(method.name.identifyingName)\" method."
   var parameters = """

Sources/GRPCCodeGen/Internal/StructuredSwift+Server.swift

@@ -48,6 +48,7 @@ extension FunctionSignatureDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ProtocolDescription {
   /// ```
   /// protocol <Name>: GRPCCore.RegistrableRPCService {
@@ -101,6 +102,7 @@ extension ProtocolDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ExtensionDescription {
   /// ```
   /// extension <ExtensionName> {
@@ -136,6 +138,7 @@ extension ExtensionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ProtocolDescription {
   /// ```
   /// protocol <Name>: <StreamingProtocol> {
@@ -304,6 +307,7 @@ extension FunctionCallDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension FunctionDescription {
   /// ```
   /// func registerMethods(with router: inout GRPCCore.RPCRouter) {
@@ -451,6 +455,7 @@ extension FunctionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ExtensionDescription {
   /// ```
   /// extension <ExtensionName> {
@@ -548,6 +553,7 @@ extension FunctionSignatureDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ProtocolDescription {
   /// ```
   /// protocol SimpleServiceProtocol: <ServiceProtocol> {
@@ -763,6 +769,7 @@ extension FunctionDescription {
   }
 }
 
+@available(gRPCSwift 2.0, *)
 extension ExtensionDescription {
   /// ```
   /// extension ServiceProtocol {