New protocol and generator options for asynchronous mutating traversal of messages

## Motivation

Our current `Visitor` protocol and generated `traverse` methods allow synchronous throwing traversal of the message fields. This works great for how our current serializers are working; however, often one wants to implement validators or transformers that mutate the fields of message. Sometimes this mutation is even asynchronous.

## Modification

This PR adds a few things:
- A new `AsyncVisitor` protocol that allows to asynchronously traverse and mutate the fields of a message
- A code generator option to generate the new async traverse method
- Tests that validate that mutating async traversal is working

## Result

We can now implement async visitors that mutate message fields.

Author: FranzBusch

PluginExamples/Package.swift

@@ -47,13 +47,23 @@ let package = Package(
                 .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
             ]
         ),
+        .target(
+            name: "AsyncTraverse",
+            dependencies: [
+                .product(name: "SwiftProtobuf", package: "swift-protobuf")
+            ],
+            plugins: [
+                .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
+            ]
+        ),
         .testTarget(
             name: "ExampleTests",
             dependencies: [
                 .target(name: "Simple"),
                 .target(name: "Nested"),
                 .target(name: "Import"),
                 .target(name: "AccessLevelOnImport"),
+                .target(name: "AsyncTraverse"),
             ]
         ),
     ],

PluginExamples/[email protected]

@@ -14,6 +14,7 @@ let package = Package(
                 .target(name: "Simple"),
                 .target(name: "Nested"),
                 .target(name: "Import"),
+                .target(name: "AsyncTraverse"),
             ]
         ),
         .target(
@@ -43,5 +44,14 @@ let package = Package(
                 .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
             ]
         ),
+        .target(
+            name: "AsyncTraverse",
+            dependencies: [
+                .product(name: "SwiftProtobuf", package: "swift-protobuf")
+            ],
+            plugins: [
+                .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
+            ]
+        ),
     ]
 )

PluginExamples/[email protected]

@@ -47,13 +47,23 @@ let package = Package(
                 .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
             ]
         ),
+        .target(
+            name: "AsyncTraverse",
+            dependencies: [
+                .product(name: "SwiftProtobuf", package: "swift-protobuf")
+            ],
+            plugins: [
+                .plugin(name: "SwiftProtobufPlugin", package: "swift-protobuf")
+            ]
+        ),
         .testTarget(
             name: "ExampleTests",
             dependencies: [
                 .target(name: "Simple"),
                 .target(name: "Nested"),
                 .target(name: "Import"),
                 .target(name: "AccessLevelOnImport"),
+                .target(name: "AsyncTraverse"),
             ]
         ),
     ]

PluginExamples/Sources/AsyncTraverse/AsyncTraverse.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+message AsyncTraverseMessage {
+    bytes data = 1;
+    Nested nested = 2;
+    repeated bytes repeated_data = 3;
+    repeated Nested repeated_nested = 4;
+}
+
+message Nested {
+    bytes data = 1;
+    NestedNested nestedNested = 2;
+}
+
+message NestedNested {
+    bytes data = 1;
+}

PluginExamples/Sources/AsyncTraverse/empty.swift

@@ -0,0 +1,3 @@
+/// DO NOT DELETE.
+///
+/// We need to keep this file otherwise the plugin is not running.

PluginExamples/Sources/AsyncTraverse/swift-protobuf-config.json

@@ -0,0 +1,11 @@
+{
+    "invocations": [
+        {
+            "protoFiles": [
+                "AsyncTraverse.proto",
+            ],
+            "visibility": "public",
+            "asyncTraverse": true,
+        }
+    ]
+}

PluginExamples/Sources/ExampleTests/AsyncTraverse.swift

@@ -0,0 +1,54 @@
+import AsyncTraverse
+import SwiftProtobuf
+import XCTest
+
+final class AsyncTraverseTests: XCTestCase {
+    func testAsyncTraverse() async throws {
+        var message = AsyncTraverseMessage.with {
+            $0.data = .init([UInt8(0)])
+            $0.nested = .with {
+                $0.data = .init([UInt8(1)])
+                $0.nestedNested = .with {
+                    $0.data = .init([UInt8(2)])
+                }
+            }
+            $0.repeatedData = [.init([UInt8(3)]), .init([UInt8(4)])]
+            $0.repeatedNested = [
+                .with {
+                    $0.data = .init([UInt8(5)])
+                    $0.nestedNested = .with {
+                        $0.data = .init([UInt8(6)])
+                    }
+                }
+            ]
+        }
+        var visitor = MyVisitor()
+        try await message.traverse(visitor: &visitor)
+        XCTAssertEqual(message.data, .init([UInt8(1)]))
+        XCTAssertEqual(message.nested.data, .init([UInt8(2)]))
+        XCTAssertEqual(message.nested.nestedNested.data, .init([UInt8(3)]))
+        XCTAssertEqual(message.repeatedData, [.init([UInt8(4)]), .init([UInt8(5)])])
+        XCTAssertEqual(message.repeatedNested[0].data, .init([UInt8(6)]))
+        XCTAssertEqual(message.repeatedNested[0].nestedNested.data, .init([UInt8(7)]))
+    }
+}
+
+struct MyVisitor: AsyncVisitor {
+    mutating func visitSingularMessageField(value: inout some Message, fieldNumber: Int) async throws {
+        try await value.traverse(visitor: &self)
+    }
+
+    mutating func visitRepeatedMessageField<M>(value: inout [M], fieldNumber: Int) async throws
+    where M: SwiftProtobuf.Message {
+        for index in value.indices {
+            try await value[index].traverse(visitor: &self)
+        }
+    }
+
+    mutating func visitSingularBytesField(value: inout Data, fieldNumber: Int) async throws {
+        value = Data([value.first! + UInt8(1)])
+    }
+    mutating func visitRepeatedBytesField(value: inout [Data], fieldNumber: Int) async throws {
+        value = value.map { Data([$0.first! + UInt8(1)]) }
+    }
+}

Plugins/SwiftProtobufPlugin/plugin.swift

@@ -87,6 +87,8 @@ struct SwiftProtobufPlugin {
             var implementationOnlyImports: Bool?
             /// Whether import statements should be preceded with visibility.
             var useAccessLevelOnImports: Bool?
+            /// Whether an async traverse method should be generated.
+            var asyncTraverse: Bool?
         }
 
         /// The path to the `protoc` binary.
@@ -197,6 +199,10 @@ struct SwiftProtobufPlugin {
             protocArgs.append("--swift_opt=UseAccessLevelOnImports=\(useAccessLevelOnImports)")
         }
 
+        if let asyncTraverse = invocation.asyncTraverse {
+            protocArgs.append("--swift_opt=AsyncTraverse=\(asyncTraverse)")
+        }
+
         var inputFiles = [Path]()
         var outputFiles = [Path]()