feat: Add Combine support (#667)

- feat: Amplify Category APIs that accept optional listeners now default them
  to `nil`, simplifying the call site
- feat: HubChannel is now Hashable
- feat: Add 'underlying error' constructor to AmplifyError
- chore: Fix OperationTestBase and reenable previously disabled tests
- chore: Change GraphQLOperation and GraphQLSubscriptionOperation to subclasses
  rather than typealiases

Author: palpatim

Amplify.xcodeproj/project.pbxproj

@@ -0,0 +1,23 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// No-listener versions of the public APIs, to clean call sites that use Combine
+// publishers to get results
+
+extension APICategoryGraphQLBehavior {
+    public func query<R: Decodable>(request: GraphQLRequest<R>) -> GraphQLOperation<R> {
+        query(request: request, listener: nil)
+    }
+
+    public func mutate<R: Decodable>(request: GraphQLRequest<R>) -> GraphQLOperation<R> {
+        mutate(request: request, listener: nil)
+    }
+
+    public func subscribe<R>(request: GraphQLRequest<R>) -> GraphQLSubscriptionOperation<R> {
+        subscribe(request: request, valueListener: nil, completionListener: nil)
+    }
+}

Amplify/Categories/API/ClientBehavior/AmplifyAPICategory+GraphQLBehavior+Combine.swift

@@ -0,0 +1,61 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+// No-listener versions of the public APIs, to clean call sites that use Combine
+// publishers to get results
+
+extension APICategoryRESTBehavior {
+    /// Perform an HTTP GET operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func get(request: RESTRequest) -> RESTOperation {
+        get(request: request, listener: nil)
+    }
+
+    /// Perform an HTTP PUT operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func put(request: RESTRequest) -> RESTOperation {
+        put(request: request, listener: nil)
+    }
+
+    /// Perform an HTTP POST operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func post(request: RESTRequest) -> RESTOperation {
+        post(request: request, listener: nil)
+    }
+
+    /// Perform an HTTP DELETE operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func delete(request: RESTRequest) -> RESTOperation {
+        delete(request: request, listener: nil)
+    }
+
+    /// Perform an HTTP HEAD operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func head(request: RESTRequest) -> RESTOperation {
+        head(request: request, listener: nil)
+    }
+
+    /// Perform an HTTP PATCH operation
+    ///
+    /// - Parameter request: Contains information such as path, query parameters, body.
+    /// - Returns: An operation that can be observed for its value
+    public func patch(request: RESTRequest) -> RESTOperation {
+        patch(request: request, listener: nil)
+    }
+}

Amplify/Categories/API/ClientBehavior/AmplifyAPICategory+RESTBehavior+Combine.swift

@@ -9,7 +9,6 @@ import Foundation
 
 /// Errors specific to the API Category
 public enum APIError {
-
     public typealias UserInfo = [String: Any]
     public typealias StatusCode = Int
 
@@ -37,6 +36,18 @@ public enum APIError {
 }
 
 extension APIError: AmplifyError {
+    public init(
+        errorDescription: ErrorDescription = "An unknown error occurred",
+        recoverySuggestion: RecoverySuggestion = "See `underlyingError` for more details",
+        error: Error
+    ) {
+        if let error = error as? Self {
+            self = error
+        } else {
+            self = .unknown(errorDescription, recoverySuggestion, error)
+        }
+    }
+
     public var errorDescription: ErrorDescription {
         switch self {
         case .unknown(let errorDescription, _, _):

Amplify/Categories/API/Error/APIError.swift

@@ -0,0 +1,106 @@
+//
+// Copyright 2018-2020 Amazon.com,
+// Inc. or its affiliates. All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Combine
+import Foundation
+
+// MARK: - GraphQLOperation
+
+@available(iOS 13.0, *)
+public extension GraphQLOperation {
+    /// Publishes the final result of the operation
+    var resultPublisher: AnyPublisher<Success, Failure> {
+        internalResultPublisher
+    }
+}
+
+// MARK: - GraphQLSubscriptionOperation
+
+@available(iOS 13.0, *)
+public extension GraphQLSubscriptionOperation {
+
+    /// Publishes the state of the GraphQL subscription's underlying network connection.
+    ///
+    /// Subscription termination will be reported as a `completion` on the
+    /// `subscriptionDataPublisher` completion, so this is really only useful if you
+    /// want to monitor the `.connected` state.
+    var connectionStatePublisher: AnyPublisher<SubscriptionConnectionState, APIError> {
+        // Suppress Void results from the result publisher, but continue to emit
+        // completions
+        let transformedResultPublisher = internalResultPublisher
+            .flatMap { _ in Empty<SubscriptionConnectionState, Failure>(completeImmediately: true) }
+
+        // Transform the in-process publisher to one that only outputs connectionState events
+        let transformedInProcessPublisher = internalInProcessPublisher
+            .compactMap { event -> SubscriptionConnectionState? in
+                switch event {
+                case .connection(let state):
+                    return state
+                default:
+                    return nil
+                }
+        }
+        .setFailureType(to: Failure.self)
+
+        // Now that the publisher signatures match, we can merge them
+        return transformedResultPublisher
+            .merge(with: transformedInProcessPublisher)
+            .eraseToAnyPublisher()
+    }
+
+    /// Publishes the data received from a GraphQL subscription.
+    ///
+    /// The publisher emits `GraphQLResponse` events, which are standard Swift `Result`
+    /// values that contain either a successfully decoded response value, or a
+    /// `GraphQLResponseError` describing the reason that a value could not be
+    /// successfully decoded. Receiving a `.failure` response does not mean the
+    /// subscription is terminated--the subscription may still receive values, and each
+    /// value is independently evaluated. Thus, you may see a data stream containing a
+    /// mix of successfully decoded responses, partially decoded responses, or decoding
+    /// errors, none of which affect the state of the underlying subscription
+    /// connection.
+    ///
+    /// When the subscription terminates with a cancellation or disconnection, this
+    /// publisher will receive a `completion`.
+    var subscriptionDataPublisher: AnyPublisher<GraphQLResponse<R>, Failure> {
+        // Suppress Void results from the result publisher, but continue to emit completions
+        let transformedResultPublisher = internalResultPublisher
+            .flatMap { _ in Empty<GraphQLResponse<R>, Failure>(completeImmediately: true) }
+
+        // Transform the in-process publisher to one that only outputs GraphQLResponse events
+        let transformedInProcessPublisher = internalInProcessPublisher
+            .compactMap { event -> GraphQLResponse<R>? in
+                switch event {
+                case .data(let result):
+                    return result
+                default:
+                    return nil
+                }
+        }
+        .setFailureType(to: Failure.self)
+
+        // Now that the publisher signatures match, we can merge them
+        return transformedResultPublisher
+            .merge(with: transformedInProcessPublisher)
+            .eraseToAnyPublisher()
+    }
+
+}
+
+// MARK: - RESTOperation
+
+@available(iOS 13.0, *)
+public extension AmplifyOperation
+    where
+    Request == RESTOperation.Request,
+    Success == RESTOperation.Success,
+    Failure == RESTOperation.Failure {
+    /// Publishes the final result of the operation
+    var resultPublisher: AnyPublisher<Success, Failure> {
+        internalResultPublisher
+    }
+}

Amplify/Categories/API/Operation/AmplifyOperation+APIPublishers.swift

@@ -5,18 +5,18 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
-public typealias GraphQLOperation<R: Decodable> = AmplifyOperation<
+open class GraphQLOperation<R: Decodable>: AmplifyOperation<
     GraphQLOperationRequest<R>,
     GraphQLResponse<R>,
     APIError
->
+> { }
 
-public typealias GraphQLSubscriptionOperation<R: Decodable> = AmplifyInProcessReportingOperation<
+open class GraphQLSubscriptionOperation<R: Decodable>: AmplifyInProcessReportingOperation<
     GraphQLOperationRequest<R>,
     SubscriptionEvent<GraphQLResponse<R>>,
     Void,
     APIError
->
+> { }
 
 public extension HubPayload.EventName.API {
     /// eventName for HubPayloads emitted by this operation

Amplify/Categories/API/Operation/GraphQLOperation.swift

@@ -28,6 +28,9 @@ public enum GraphQLResponseError<ResponseType: Decodable>: AmplifyError {
     /// response type. The RawGraphQLResponse contains the entire response from the service, including data and errors.
     case transformationError(RawGraphQLResponse, APIError)
 
+    /// An unknown error occurred
+    case unknown(ErrorDescription, RecoverySuggestion, Error?)
+
     public var errorDescription: ErrorDescription {
         switch self {
         case .error(let errors):
@@ -36,6 +39,8 @@ public enum GraphQLResponseError<ResponseType: Decodable>: AmplifyError {
             return "GraphQL service returned a partially-successful response containing errors: \(errors)"
         case .transformationError:
             return "Failed to decode GraphQL response to the `ResponseType` \(String(describing: ResponseType.self))"
+        case .unknown(let errorDescription, _, _):
+            return errorDescription
         }
     }
 
@@ -50,6 +55,8 @@ public enum GraphQLResponseError<ResponseType: Decodable>: AmplifyError {
             Failed to transform to `ResponseType`.
             Take a look at the `RawGraphQLResponse` and underlying error to see where it failed to decode.
             """
+        case .unknown(_, let recoverySuggestion, _):
+            return recoverySuggestion
         }
     }
 
@@ -61,6 +68,21 @@ public enum GraphQLResponseError<ResponseType: Decodable>: AmplifyError {
             return nil
         case .transformationError(_, let error):
             return error
+        case .unknown(_, _, let error):
+            return error
+        }
+    }
+
+    public init(
+        errorDescription: ErrorDescription = "An unknown error occurred",
+        recoverySuggestion: RecoverySuggestion = "See `underlyingError` for more details",
+        error: Error
+    ) {
+        if let error = error as? Self {
+            self = error
+        } else {
+            self = .unknown(errorDescription, recoverySuggestion, error)
         }
     }
+
 }

Amplify/Categories/API/Response/GraphQLResponse.swift

@@ -39,4 +39,17 @@ extension AnalyticsError: AmplifyError {
             return error
         }
     }
+
+    public init(
+        errorDescription: ErrorDescription = "An unknown error occurred",
+        recoverySuggestion: RecoverySuggestion = "(Ignored)",
+        error: Error
+    ) {
+        if let error = error as? Self {
+            self = error
+        } else {
+            self = .unknown(errorDescription, error)
+        }
+    }
+
 }