Add GRPCStreamStateMachine

Sources/GRPCCore/Internal/Base64.swift

@@ -26,11 +26,11 @@
  met:
 
  1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
+ notice, this list of conditions and the following disclaimer.
 
  2. Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in the
-    documentation and/or other materials provided with the distribution.
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
 
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
@@ -70,25 +70,59 @@
  SOFTWARE.
  */
 
-internal enum Base64 {}
-
-extension Base64 {
-  internal struct DecodingOptions: OptionSet {
+// swift-format-ignore: DontRepeatTypeInStaticProperties
+enum Base64 {
+  struct DecodingOptions: OptionSet {
     internal let rawValue: UInt
     internal init(rawValue: UInt) { self.rawValue = rawValue }
 
     internal static let base64UrlAlphabet = DecodingOptions(rawValue: UInt(1 << 0))
     internal static let omitPaddingCharacter = DecodingOptions(rawValue: UInt(1 << 1))
   }
 
-  internal enum DecodingError: Error, Equatable {
+  enum DecodingError: Error, Equatable {
     case invalidLength
     case invalidCharacter(UInt8)
     case unexpectedPaddingCharacter
     case unexpectedEnd
   }
 
-  internal static func decode(
+  static func encode<Buffer: Collection>(bytes: Buffer) -> String where Buffer.Element == UInt8 {
+    guard !bytes.isEmpty else {
+      return ""
+    }
+
+    // In Base64, 3 bytes become 4 output characters, and we pad to the
+    // nearest multiple of four.
+    let base64StringLength = ((bytes.count + 2) / 3) * 4
+    let alphabet = Base64.encodeBase64
+
+    return String(customUnsafeUninitializedCapacity: base64StringLength) { backingStorage in
+      var input = bytes.makeIterator()
+      var offset = 0
+      while let firstByte = input.next() {
+        let secondByte = input.next()
+        let thirdByte = input.next()
+
+        backingStorage[offset] = Base64.encode(alphabet: alphabet, firstByte: firstByte)
+        backingStorage[offset + 1] = Base64.encode(
+          alphabet: alphabet,
+          firstByte: firstByte,
+          secondByte: secondByte
+        )
+        backingStorage[offset + 2] = Base64.encode(
+          alphabet: alphabet,
+          secondByte: secondByte,
+          thirdByte: thirdByte
+        )
+        backingStorage[offset + 3] = Base64.encode(alphabet: alphabet, thirdByte: thirdByte)
+        offset += 4
+      }
+      return offset
+    }
+  }
+
+  static func decode(
     string encoded: String,
     options: DecodingOptions = []
   ) throws -> [UInt8] {
@@ -204,7 +238,7 @@ extension Base64 {
     }
   }
 
-  static func withUnsafeDecodingTablesAsBufferPointers<R>(
+  private static func withUnsafeDecodingTablesAsBufferPointers<R>(
     options: Base64.DecodingOptions,
     _ body: (
       UnsafeBufferPointer<UInt32>, UnsafeBufferPointer<UInt32>, UnsafeBufferPointer<UInt32>,
@@ -232,10 +266,64 @@ extension Base64 {
     }
   }
 
-  internal static let encodePaddingCharacter: UInt8 = 61
-  static let badCharacter: UInt32 = 0x01FF_FFFF
+  private static let encodePaddingCharacter: UInt8 = 61
+
+  private static let encodeBase64: [UInt8] = [
+    UInt8(ascii: "A"), UInt8(ascii: "B"), UInt8(ascii: "C"), UInt8(ascii: "D"),
+    UInt8(ascii: "E"), UInt8(ascii: "F"), UInt8(ascii: "G"), UInt8(ascii: "H"),
+    UInt8(ascii: "I"), UInt8(ascii: "J"), UInt8(ascii: "K"), UInt8(ascii: "L"),
+    UInt8(ascii: "M"), UInt8(ascii: "N"), UInt8(ascii: "O"), UInt8(ascii: "P"),
+    UInt8(ascii: "Q"), UInt8(ascii: "R"), UInt8(ascii: "S"), UInt8(ascii: "T"),
+    UInt8(ascii: "U"), UInt8(ascii: "V"), UInt8(ascii: "W"), UInt8(ascii: "X"),
+    UInt8(ascii: "Y"), UInt8(ascii: "Z"), UInt8(ascii: "a"), UInt8(ascii: "b"),
+    UInt8(ascii: "c"), UInt8(ascii: "d"), UInt8(ascii: "e"), UInt8(ascii: "f"),
+    UInt8(ascii: "g"), UInt8(ascii: "h"), UInt8(ascii: "i"), UInt8(ascii: "j"),
+    UInt8(ascii: "k"), UInt8(ascii: "l"), UInt8(ascii: "m"), UInt8(ascii: "n"),
+    UInt8(ascii: "o"), UInt8(ascii: "p"), UInt8(ascii: "q"), UInt8(ascii: "r"),
+    UInt8(ascii: "s"), UInt8(ascii: "t"), UInt8(ascii: "u"), UInt8(ascii: "v"),
+    UInt8(ascii: "w"), UInt8(ascii: "x"), UInt8(ascii: "y"), UInt8(ascii: "z"),
+    UInt8(ascii: "0"), UInt8(ascii: "1"), UInt8(ascii: "2"), UInt8(ascii: "3"),
+    UInt8(ascii: "4"), UInt8(ascii: "5"), UInt8(ascii: "6"), UInt8(ascii: "7"),
+    UInt8(ascii: "8"), UInt8(ascii: "9"), UInt8(ascii: "+"), UInt8(ascii: "/"),
+  ]
+
+  private static func encode(alphabet: [UInt8], firstByte: UInt8) -> UInt8 {
+    let index = firstByte >> 2
+    return alphabet[Int(index)]
+  }
+
+  private static func encode(alphabet: [UInt8], firstByte: UInt8, secondByte: UInt8?) -> UInt8 {
+    var index = (firstByte & 0b00000011) << 4
+    if let secondByte = secondByte {
+      index += (secondByte & 0b11110000) >> 4
+    }
+    return alphabet[Int(index)]
+  }
 
-  static let decoding0: [UInt32] = [
+  private static func encode(alphabet: [UInt8], secondByte: UInt8?, thirdByte: UInt8?) -> UInt8 {
+    guard let secondByte = secondByte else {
+      // No second byte means we are just emitting padding.
+      return Base64.encodePaddingCharacter
+    }
+    var index = (secondByte & 0b00001111) << 2
+    if let thirdByte = thirdByte {
+      index += (thirdByte & 0b11000000) >> 6
+    }
+    return alphabet[Int(index)]
+  }
+
+  private static func encode(alphabet: [UInt8], thirdByte: UInt8?) -> UInt8 {
+    guard let thirdByte = thirdByte else {
+      // No third byte means just padding.
+      return Base64.encodePaddingCharacter
+    }
+    let index = thirdByte & 0b00111111
+    return alphabet[Int(index)]
+  }
+
+  private static let badCharacter: UInt32 = 0x01FF_FFFF
+
+  private static let decoding0: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
@@ -281,7 +369,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding1: [UInt32] = [
+  private static let decoding1: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
@@ -327,7 +415,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding2: [UInt32] = [
+  private static let decoding2: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
@@ -373,7 +461,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding3: [UInt32] = [
+  private static let decoding3: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
@@ -419,7 +507,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding0url: [UInt32] = [
+  private static let decoding0url: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 0
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 6
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 12
@@ -465,7 +553,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding1url: [UInt32] = [
+  private static let decoding1url: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 0
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 6
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 12
@@ -511,7 +599,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding2url: [UInt32] = [
+  private static let decoding2url: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 0
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 6
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 12
@@ -557,7 +645,7 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 
-  static let decoding3url: [UInt32] = [
+  private static let decoding3url: [UInt32] = [
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 0
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 6
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,  // 12
@@ -603,3 +691,42 @@ extension Base64 {
     0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF, 0x01FF_FFFF,
   ]
 }
+
+extension String {
+  /// This is a backport of a proposed String initializer that will allow writing directly into an uninitialized String's backing memory.
+  ///
+  /// As this API does not exist prior to 5.3 on Linux, or on older Apple platforms, we fake it out with a pointer and accept the extra copy.
+  init(
+    backportUnsafeUninitializedCapacity capacity: Int,
+    initializingUTF8With initializer: (_ buffer: UnsafeMutableBufferPointer<UInt8>) throws -> Int
+  ) rethrows {
+
+    // The buffer will store zero terminated C string
+    let buffer = UnsafeMutableBufferPointer<UInt8>.allocate(capacity: capacity + 1)
+    defer {
+      buffer.deallocate()
+    }
+
+    let initializedCount = try initializer(buffer)
+    precondition(initializedCount <= capacity, "Overran buffer in initializer!")
+
+    // add zero termination
+    buffer[initializedCount] = 0
+
+    self = String(cString: buffer.baseAddress!)
+  }
+
+  init(
+    customUnsafeUninitializedCapacity capacity: Int,
+    initializingUTF8With initializer: (_ buffer: UnsafeMutableBufferPointer<UInt8>) throws -> Int
+  ) rethrows {
+    if #available(macOS 11.0, iOS 14.0, tvOS 14.0, watchOS 7.0, *) {
+      try self.init(unsafeUninitializedCapacity: capacity, initializingUTF8With: initializer)
+    } else {
+      try self.init(
+        backportUnsafeUninitializedCapacity: capacity,
+        initializingUTF8With: initializer
+      )
+    }
+  }
+}

Sources/GRPCCore/Metadata.swift

@@ -85,6 +85,17 @@ public struct Metadata: Sendable, Hashable {
   public enum Value: Sendable, Hashable {
     case string(String)
     case binary([UInt8])
+
+    /// The value as a String. If it was originally stored as a binary, the base64-encoded String version
+    /// of the binary data will be returned instead.
+    public func encoded() -> String {
+      switch self {
+      case .string(let string):
+        return string
+      case .binary(let bytes):
+        return Base64.encode(bytes: bytes)
+      }
+    }
   }
 
   /// A metadata key-value pair.

Sources/GRPCHTTP2Core/Compression/CompressionAlgorithm.swift

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2024, gRPC Authors All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/// Supported message compression algorithms.
+///
+/// These algorithms are indicated in the "grpc-encoding" header. As such, a lack of "grpc-encoding"
+/// header indicates that there is no message compression.
+public struct CompressionAlgorithm: Hashable, Sendable {
+  /// Identity compression; "no" compression but indicated via the "grpc-encoding" header.
+  public static let identity = CompressionAlgorithm(.identity)
+  public static let deflate = CompressionAlgorithm(.deflate)
+  public static let gzip = CompressionAlgorithm(.gzip)
+
+  // The order here is important: most compression to least.
+  public static let all: [CompressionAlgorithm] = [.gzip, .deflate, .identity]
+
+  public var name: String {
+    return self.algorithm.rawValue
+  }
+
+  internal enum Algorithm: String {
+    case identity
+    case deflate
+    case gzip
+  }
+
+  internal let algorithm: Algorithm
+
+  private init(_ algorithm: Algorithm) {
+    self.algorithm = algorithm
+  }
+
+  internal init?(rawValue: String) {
+    guard let algorithm = Algorithm(rawValue: rawValue) else {
+      return nil
+    }
+    self.algorithm = algorithm
+  }
+}