Rename asGRPCStatus() to makeGRPCStatus(), add documentation. (#690)

Motivation:

We should make sure we're happy with various names and documentation
before tagging 1.0.0. `asGRPCStatus()` didn't feel right as a name.

Modifications:

- Rename `asGRPCStatus()` to `makeGRPCStatus()`
- Add some documentation to `GRPCStatusTranformable`
- Add a temporary shim for `asGRPCStatus()`

Result:

Better naming.

Sources/GRPC/CallHandlers/_BaseCallHandler.swift

@@ -82,11 +82,11 @@ extension _BaseCallHandler: ChannelInboundHandler {
     if let errorWithContext = error as? GRPCError.WithContext {
       self.errorDelegate?.observeLibraryError(errorWithContext.error)
       status = self.errorDelegate?.transformLibraryError(errorWithContext.error)
-          ?? errorWithContext.error.asGRPCStatus()
+          ?? errorWithContext.error.makeGRPCStatus()
     } else {
       self.errorDelegate?.observeLibraryError(error)
       status = self.errorDelegate?.transformLibraryError(error)
-          ?? (error as? GRPCStatusTransformable)?.asGRPCStatus()
+          ?? (error as? GRPCStatusTransformable)?.makeGRPCStatus()
           ?? .processingError
     }
 

Sources/GRPC/GRPCChannelHandler.swift

@@ -74,11 +74,11 @@ extension GRPCChannelHandler: ChannelInboundHandler, RemovableChannelHandler {
     if let errorWithContext = error as? GRPCError.WithContext {
       self.errorDelegate?.observeLibraryError(errorWithContext.error)
       status = self.errorDelegate?.transformLibraryError(errorWithContext.error)
-          ?? errorWithContext.error.asGRPCStatus()
+          ?? errorWithContext.error.makeGRPCStatus()
     } else {
       self.errorDelegate?.observeLibraryError(error)
       status = self.errorDelegate?.transformLibraryError(error)
-          ?? (error as? GRPCStatusTransformable)?.asGRPCStatus()
+          ?? (error as? GRPCStatusTransformable)?.makeGRPCStatus()
           ?? .processingError
     }
 

Sources/GRPC/GRPCClientResponseChannelHandler.swift

@@ -104,10 +104,10 @@ internal class GRPCClientResponseChannelHandler<ResponseMessage: Message>: Chann
           file: errorWithContext.file,
           line: errorWithContext.line
       )
-      self.onStatus(errorWithContext.error.asGRPCStatus())
+      self.onStatus(errorWithContext.error.makeGRPCStatus())
     } else {
       self.errorDelegate?.didCatchErrorWithoutContext(error, logger: self.logger)
-      self.onStatus((error as? GRPCStatusTransformable)?.asGRPCStatus() ?? .processingError)
+      self.onStatus((error as? GRPCStatusTransformable)?.makeGRPCStatus() ?? .processingError)
     }
   }
 

Sources/GRPC/GRPCError.swift

@@ -36,7 +36,7 @@ public enum GRPCError {
       return "RPC '\(self.rpc)' is not implemented"
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .unimplemented, message: self.description)
     }
   }
@@ -48,7 +48,7 @@ public enum GRPCError {
     public init() {
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .cancelled, message: self.description)
     }
   }
@@ -66,7 +66,7 @@ public enum GRPCError {
       return "RPC timed out (timeout=\(self.timeout.wireEncoding)) before completing"
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .deadlineExceeded, message: self.description)
     }
   }
@@ -78,7 +78,7 @@ public enum GRPCError {
     public init() {
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: self.description)
     }
   }
@@ -90,7 +90,7 @@ public enum GRPCError {
     public init() {
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: self.description)
     }
   }
@@ -102,7 +102,7 @@ public enum GRPCError {
     public init() {
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: self.description)
     }
   }
@@ -114,7 +114,7 @@ public enum GRPCError {
     public init() {
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .unimplemented, message: self.description)
     }
   }
@@ -137,7 +137,7 @@ public enum GRPCError {
       }
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: self.description)
     }
   }
@@ -159,7 +159,7 @@ public enum GRPCError {
       }
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: self.description)
     }
   }
@@ -181,7 +181,7 @@ public enum GRPCError {
       }
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .init(httpStatus: self.status), message: self.description)
     }
   }
@@ -198,7 +198,7 @@ public enum GRPCError {
       return "Invalid HTTP response status, but gRPC status was present"
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return self.status
     }
   }
@@ -215,7 +215,7 @@ public enum GRPCError {
       return self.message
     }
 
-    public func asGRPCStatus() -> GRPCStatus {
+    public func makeGRPCStatus() -> GRPCStatus {
       return GRPCStatus(code: .internalError, message: "Invalid state: \(self.message)")
     }
   }

Sources/GRPC/GRPCStatus.swift

@@ -175,30 +175,35 @@ extension GRPCStatus {
   }
 }
 
+/// This protocol serves as a customisation point for error types so that gRPC calls may be
+/// terminated with an appropriate status.
 public protocol GRPCStatusTransformable: Error {
-  func asGRPCStatus() -> GRPCStatus
+  /// Make a `GRPCStatus` from the underlying error.
+  ///
+  /// - Returns: A `GRPCStatus` representing the underlying error.
+  func makeGRPCStatus() -> GRPCStatus
 }
 
 extension GRPCStatus: GRPCStatusTransformable {
-  public func asGRPCStatus() -> GRPCStatus {
+  public func makeGRPCStatus() -> GRPCStatus {
     return self
   }
 }
 
 extension NIOHTTP2Errors.StreamClosed: GRPCStatusTransformable {
-  public func asGRPCStatus() -> GRPCStatus {
+  public func makeGRPCStatus() -> GRPCStatus {
     return .init(code: .unavailable, message: self.localizedDescription)
   }
 }
 
 extension NIOHTTP2Errors.IOOnClosedConnection: GRPCStatusTransformable {
-  public func asGRPCStatus() -> GRPCStatus {
+  public func makeGRPCStatus() -> GRPCStatus {
     return .init(code: .unavailable, message: "The connection is closed")
   }
 }
 
 extension ChannelError: GRPCStatusTransformable {
-  public func asGRPCStatus() -> GRPCStatus {
+  public func makeGRPCStatus() -> GRPCStatus {
     switch self {
     case .inputClosed, .outputClosed, .ioOnClosedChannel:
       return .init(code: .unavailable, message: "The connection is closed")

Sources/GRPC/ServerCallContexts/StreamingResponseCallContext.swift

@@ -61,7 +61,7 @@ open class StreamingResponseCallContextImpl<ResponseMessage: Message>: Streaming
       .recover { [weak errorDelegate] error in
         errorDelegate?.observeRequestHandlerError(error, request: request)
         return errorDelegate?.transformRequestHandlerError(error, request: request)
-          ?? (error as? GRPCStatusTransformable)?.asGRPCStatus()
+          ?? (error as? GRPCStatusTransformable)?.makeGRPCStatus()
           ?? .processingError
       }
       // Finish the call by returning the final status.

Sources/GRPC/ServerCallContexts/UnaryResponseCallContext.swift

@@ -80,7 +80,7 @@ open class UnaryResponseCallContextImpl<ResponseMessage: Message>: UnaryResponse
       .recover { [weak errorDelegate] error in
         errorDelegate?.observeRequestHandlerError(error, request: request)
         return errorDelegate?.transformRequestHandlerError(error, request: request)
-          ?? (error as? GRPCStatusTransformable)?.asGRPCStatus()
+          ?? (error as? GRPCStatusTransformable)?.makeGRPCStatus()
           ?? .processingError
       }
       // Finish the call by returning the final status.

Sources/GRPC/Shims.swift

@@ -40,3 +40,10 @@ extension ClientErrorDelegate {
   @available(*, deprecated, message: "Please use 'didCatchError(_:logger:file:line:)' instead")
   public func didCatchError(_ error: Error, file: StaticString, line: Int) { }
 }
+
+extension GRPCStatusTransformable {
+  @available(*, deprecated, renamed: "makeGRPCStatus")
+  func asGRPCStatus() -> GRPCStatus {
+    return self.makeGRPCStatus()
+  }
+}

Tests/GRPCTests/GRPCChannelHandlerTests.swift

@@ -31,7 +31,7 @@ class GRPCChannelHandlerTests: GRPCChannelHandlerResponseCapturingTestCase {
     XCTAssertEqual(expectedError, errorCollector.errors.first as? GRPCError.RPCNotImplemented)
 
     responses[0].assertStatus { status in
-      XCTAssertEqual(status, expectedError.asGRPCStatus())
+      XCTAssertEqual(status, expectedError.makeGRPCStatus())
     }
   }
 
@@ -69,7 +69,7 @@ class GRPCChannelHandlerTests: GRPCChannelHandlerResponseCapturingTestCase {
 
     responses[0].assertHeaders()
     responses[1].assertStatus { status in
-      XCTAssertEqual(status, expectedError.asGRPCStatus())
+      XCTAssertEqual(status, expectedError.makeGRPCStatus())
     }
   }
 }

Tests/GRPCTests/HTTP1ToRawGRPCServerCodecTests.swift

@@ -45,7 +45,7 @@ class HTTP1ToRawGRPCServerCodecTests: GRPCChannelHandlerResponseCapturingTestCas
 
     responses[0].assertHeaders()
     responses[1].assertStatus { status in
-      XCTAssertEqual(status, expectedError.asGRPCStatus())
+      XCTAssertEqual(status, expectedError.makeGRPCStatus())
     }
   }
 
@@ -92,7 +92,7 @@ class HTTP1ToRawGRPCServerCodecTests: GRPCChannelHandlerResponseCapturingTestCas
 
     responses[0].assertHeaders()
     responses[1].assertStatus { status in
-      XCTAssertEqual(status, expectedError.asGRPCStatus())
+      XCTAssertEqual(status, expectedError.makeGRPCStatus())
     }
   }
 
@@ -117,7 +117,7 @@ class HTTP1ToRawGRPCServerCodecTests: GRPCChannelHandlerResponseCapturingTestCas
 
     responses[0].assertHeaders()
     responses[1].assertStatus { status in
-      XCTAssertEqual(status, expected.asGRPCStatus())
+      XCTAssertEqual(status, expected.makeGRPCStatus())
     }
   }