Add basic RawSpan support for initializing and merging messages (#1857)

On platforms targeting Swift 6.2 and later this allows a `RawSpan` in
lieu of `SwiftProtobufContiguousBytes`-conforming type when creating or
merging a protobuf message. This will improve memory usage by reducing
allocations, for example when parsing a large document that includes
protobuf messages as part of its binary. Unlike the internal `_merge`
function, this does not expose unsafe API while retaining its benefits.

- I decided to make a twin declaration of the initializer and `merge`
function instead of conforming `RawSpan` to
`SwiftProtobufContiguousTypes`, because
  - a) `RawSpan` is not mutable, and
  - b) `Span` types are non-owning and cannot conform to initializers.
- I used the conditional compilation block and `@available` directive
per ~~analogy to [this implementation in
SwiftNIO](https://github.com/apple/swift-nio/blob/main/Sources/NIOCore/ByteBuffer-core.swift#L1066)~~
[docs](https://developer.apple.com/documentation/swift/rawspan).

---------

Co-authored-by: Franz Busch <[email protected]>

Author: pawelmajcher

Sources/SwiftProtobuf/Message+BinaryAdditions.swift

@@ -100,6 +100,34 @@ extension Message {
         try merge(serializedBytes: bytes, extensions: extensions, partial: partial, options: options)
     }
 
+    #if compiler(>=6.2)
+    /// Creates a new message by decoding the bytes provided by a `RawSpan`
+    /// containing a serialized message in Protocol Buffer binary format.
+    ///
+    /// - Parameters:
+    ///   - serializedBytes: The `RawSpan` of binary-encoded message data to decode.
+    ///   - extensions: An ``ExtensionMap`` used to look up and decode any
+    ///     extensions in this message or messages nested within this message's
+    ///     fields.
+    ///   - partial: If `false` (the default), this method will check
+    ///     ``Message/isInitialized-6abgi`` after decoding to verify that all required
+    ///     fields are present. If any are missing, this method throws
+    ///     ``BinaryDecodingError/missingRequiredFields``.
+    ///   - options: The ``BinaryDecodingOptions`` to use.
+    /// - Throws: ``BinaryDecodingError`` if decoding fails.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public init(
+        serializedBytes bytes: RawSpan,
+        extensions: (any ExtensionMap)? = nil,
+        partial: Bool = false,
+        options: BinaryDecodingOptions = BinaryDecodingOptions()
+    ) throws {
+        self.init()
+        try merge(serializedBytes: bytes, extensions: extensions, partial: partial, options: options)
+    }
+    #endif
+
     /// Updates the message by decoding the given `SwiftProtobufContiguousBytes` value
     /// containing a serialized message in Protocol Buffer binary format into the
     /// receiver.
@@ -131,6 +159,39 @@ extension Message {
         }
     }
 
+    #if compiler(>=6.2)
+    /// Updates the message by decoding the bytes provided by a `RawSpan` containing
+    /// a serialized message in Protocol Buffer binary format into the receiver.
+    ///
+    /// - Note: If this method throws an error, the message may still have been
+    ///   partially mutated by the binary data that was decoded before the error
+    ///   occurred.
+    ///
+    /// - Parameters:
+    ///   - serializedBytes: The `RawSpan` of binary-encoded message data to decode.
+    ///   - extensions: An ``ExtensionMap`` used to look up and decode any
+    ///     extensions in this message or messages nested within this message's
+    ///     fields.
+    ///   - partial: If `false` (the default), this method will check
+    ///     ``Message/isInitialized-6abgi`` after decoding to verify that all required
+    ///     fields are present. If any are missing, this method throws
+    ///     ``BinaryDecodingError/missingRequiredFields``.
+    ///   - options: The ``BinaryDecodingOptions`` to use.
+    /// - Throws: ``BinaryDecodingError`` if decoding fails.
+    @inlinable
+    @available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *)
+    public mutating func merge(
+        serializedBytes bytes: RawSpan,
+        extensions: (any ExtensionMap)? = nil,
+        partial: Bool = false,
+        options: BinaryDecodingOptions = BinaryDecodingOptions()
+    ) throws {
+        try bytes.withUnsafeBytes { (body: UnsafeRawBufferPointer) in
+            try _merge(rawBuffer: body, extensions: extensions, partial: partial, options: options)
+        }
+    }
+    #endif
+
     // Helper for `merge()`s to keep the Decoder internal to SwiftProtobuf while
     // allowing the generic over `SwiftProtobufContiguousBytes` to get better codegen from the
     // compiler by being `@inlinable`. For some discussion on this see

Tests/SwiftProtobufTests/Test_RawSpan.swift

@@ -0,0 +1,84 @@
+import Foundation
+import SwiftProtobuf
+import XCTest
+
+#if compiler(>=6.2)
+
+final class Test_RawSpan: XCTestCase {
+    func testEmptyRawSpan() throws {
+        guard #available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *) else {
+            throw XCTSkip("Span structs not available on selected platform")
+        }
+
+        let emptyRawSpan = RawSpan()
+
+        let decoded = try SwiftProtoTesting_TestAllTypes(serializedBytes: emptyRawSpan)
+        let expected = SwiftProtoTesting_TestAllTypes()
+
+        XCTAssertEqual(decoded, expected, "Empty span should decode to equal empty message")
+    }
+
+    func testRawSpanReencodedEmptyByteArray() throws {
+        guard #available(macOS 26, iOS 26, watchOS 26, tvOS 26, visionOS 26, *) else {
+            throw XCTSkip("span.bytes not available on selected platform")
+        }
+
+        let expected: [UInt8] = []
+        let expectedRawSpan = expected.span.bytes
+
+        let decoded = try SwiftProtoTesting_TestAllTypes(serializedBytes: expectedRawSpan)
+        let reencoded: [UInt8] = try decoded.serializedBytes()
+
+        XCTAssertEqual(
+            reencoded,
+            expected,
+            "Raw span of empty array of bytes should decode and encode as empty message"
+        )
+    }
+
+    func testRawSpanDataEncodeDecode() throws {
+        guard #available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *) else {
+            throw XCTSkip("Span structs not available on selected platform")
+        }
+
+        let expected = SwiftProtoTesting_TestAllTypes.with {
+            $0.optionalInt32 = 1
+            $0.optionalInt64 = Int64.max
+            $0.optionalString = "RawSpan test"
+            $0.repeatedBool = [true, false]
+        }
+
+        let encoded: Data = try expected.serializedBytes()
+        let encodedRawSpan: RawSpan = encoded.bytes
+
+        let decoded = try SwiftProtoTesting_TestAllTypes(serializedBytes: encodedRawSpan)
+
+        XCTAssertEqual(decoded, expected, "")
+    }
+
+    func testRawSpanTruncated() throws {
+        guard #available(macOS 10.14.4, iOS 12.2, watchOS 5.2, tvOS 12.2, visionOS 1.0, *) else {
+            throw XCTSkip("Span structs not available on selected platform")
+        }
+
+        let expected = SwiftProtoTesting_TestAllTypes.with {
+            $0.optionalInt32 = 1
+            $0.optionalInt64 = Int64.max
+            $0.optionalString = "RawSpan test"
+            $0.repeatedBool = [true, false]
+        }
+
+        let encoded: Data = try expected.serializedBytes()
+        let truncatedRawSpan: RawSpan = encoded.bytes.extracting(droppingLast: 1)
+
+        var decoded = SwiftProtoTesting_TestAllTypes()
+
+        XCTAssertThrowsError(
+            try decoded.merge(serializedBytes: truncatedRawSpan)
+        ) { error in
+            XCTAssertEqual(error as? BinaryDecodingError, BinaryDecodingError.truncated)
+        }
+    }
+}
+
+#endif