A library that provides Combine framework integration for Swift gRPC

by iOS Example

CombineGRPC

CombineGRPC is a library that provides Combine framework integration for Swift gRPC.

CombineGRPC provides two flavours of functionality, call and handle. Use call to make gRPC calls on the client side, and handle to handle incoming requests on the server side. The library provides versions of call and handle for all RPC styles. Here are the input and output types for each.

RPC Style Input and Output Types
Unary Request -> AnyPublisher<Response, RPCError>
Server streaming Request -> AnyPublisher<Response, RPCError>
Client streaming AnyPublisher<Request, Error> -> AnyPublisher<Response, RPCError>
Bidirectional streaming AnyPublisher<Request, Error> -> AnyPublisher<Response, RPCError>

When you make a unary call, you provide a request message, and get back a response publisher. The response publisher will either publish a single response, or fail with an RPCError error. Similarly, if you are handling a unary RPC call, you provide a handler that takes a request parameter and returns an AnyPublisher<Response, RPCError>.

You can follow the same intuition to understand the types for the other RPC styles. The only difference is that publishers for the streaming RPCs may publish zero or more messages instead of the single response message that is expected from the unary response publisher.

Quick Tour

Let's see a quick example. Consider the following protobuf definition for a simple echo service. The service defines one bidirectional RPC. You send it a stream of messages and it echoes the messages back to you.

syntax = "proto3";

service EchoService {
  rpc SayItBack (stream EchoRequest) returns (stream EchoResponse);
}

message EchoRequest {
  string message = 1;
}

message EchoResponse {
  string message = 1;
}

Server Side

To implement the server, you provide a handler function that takes an input stream AnyPublisher<EchoRequest, Error> and returns an output stream AnyPublisher<EchoResponse, RPCError>.

import Foundation
import Combine
import CombineGRPC
import GRPC
import NIO

class EchoServiceProvider: EchoProvider {
  
  // Simple bidirectional RPC that echoes back each request message
  func sayItBack(context: StreamingResponseCallContext<EchoResponse>) -> EventLoopFuture<(StreamEvent<EchoRequest>) -> Void> {
    CombineGRPC.handle(context) { requests in
      requests
        .map { req in
          EchoResponse.with { $0.message = req.message }
        }
        .setFailureType(to: RPCError.self)
        .eraseToAnyPublisher()
    }
  }
}

Start the server. This is the same process as with Swift gRPC.

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
defer {
  try! eventLoopGroup.syncShutdownGracefully()
}

// Start the gRPC server and wait until it shuts down.
_ = try Server
  .insecure(group: eventLoopGroup)
  .withServiceProviders([EchoServiceProvider()])
  .bind(host: "localhost", port: 8080)
  .flatMap { $0.onClose }
  .wait()

Client Side

Now let's setup our client. Again, it's the same process that you would go through when using Swift gRPC.

let eventLoopGroup = MultiThreadedEventLoopGroup(numberOfThreads: 1)
let channel = ClientConnection
  .insecure(group: eventLoopGroup)
  .connect(host: "localhost", port: 8080)
let echoClient = EchoServiceClient(channel: channel)

To call the service, create a GRPCExecutor and use its call method. You provide it with a stream of requests AnyPublisher<EchoRequest, Error> and you get back a stream AnyPublisher<EchoResponse, RPCError> of responses from the server.

let requests = repeatElement(EchoRequest.with { $0.message = "hello"}, count: 10)
let requestStream: AnyPublisher<EchoRequest, Error> =
  Publishers.Sequence(sequence: requests).eraseToAnyPublisher()
let grpc = GRPCExecutor()

grpc.call(echoClient.sayItBack)(requestStream)
  .filter { $0.message == "hello" }
  .count()
  .sink(receiveValue: { count in
    assert(count == 10)
  })

That's it! You have set up bidirectional streaming between a server and client. The method sayItBack of EchoServiceClient is generated by Swift gRPC. Notice that call is curried. You can preselect RPC calls using partial application:

let sayItBack = grpc.call(echoClient.sayItBack)

sayItBack(requestStream).map { response in
  // ...
}

Configuring RPC Calls

The GRPCExecutor allows you to configure CallOptions for your RPC calls. You can provide the GRPCExecutor's initializer with a stream AnyPublisher<CallOptions, Never>, and the latest CallOptions value will be used when making calls.

let timeoutOptions = CallOptions(timeout: try! .seconds(5))
let grpc = GRPCExecutor(callOptions: Just(timeoutOptions).eraseToAnyPublisher())

Retry Policy

You can also configure GRPCExecutor to automatically retry failed calls by specifying a RetryPolicy. In the following example, we retry calls that fail with status .unauthenticated. We use CallOptions to add a Bearer token to the authorization header, and then retry the call.

// Default CallOptions with no authentication
let callOptions = CurrentValueSubject<CallOptions, Never>(CallOptions())

let grpc = GRPCExecutor(
  callOptions: callOptions.eraseToAnyPublisher(),
  retry: .failedCall(
    upTo: 1,
    when: { error in
      error.status.code == .unauthenticated
    },
    delayUntilNext: { retryCount, error in  // Useful for implementing exponential backoff
      // Retry the call with authentication
      callOptions.send(CallOptions(customMetadata: HTTPHeaders([("authorization", "Bearer xxx")])))
      return Just(()).eraseToAnyPublisher()
    },
    didGiveUp: {
      print("Authenticated call failed.")
    }
  )
)

grpc.call(client.authenticatedRpc)(request)
  .map { response in
    // ...
  }

You can imagine doing something along those lines to seamlessly retry calls when an ID token expires. The back-end service replies with status .unauthenticated, you obtain a new ID token using your refresh token, and the call is retried.

More Examples

Check out the CombineGRPC tests for examples of all the different RPC calls and handler implementations. You can find the matching protobuf here.

Logistics

Generating Swift Code from Protobuf

To generate Swift code from your .proto files, you'll need to first install the protoc Protocol Buffer compiler.

brew install protobuf

Next, download the swift and grpc-swift protoc plugins. Unarchive the downloaded file and move the binaries from the bin/ directory to somewhere in your $PATH.

Now you are ready to generate Swift code from protobuf interface definition files.

Let's generate the message types, gRPC server and gRPC client for Swift.

protoc example_service.proto --swift_out=Generated/
protoc example_service.proto --grpc-swift_out=Generated/

You'll see that protoc has created two source files for us.

ls Generated/
example_service.grpc.swift
example_service.pb.swift

Adding CombineGRPC to Your Project

You can easily add CombineGRPC to your project using either Swift Package Manager or CocoaPods.

Swift Package Manager

Add the package dependency to your Package.swift:

dependencies: [
  .package(url: "https://github.com/vyshane/grpc-swift-combine.git", from: "1.0.6"),
],

CocoaPods

Add the following line to your Podfile:

pod 'CombineGRPC', '~> 1.0.6'

Compatibility

Since this library integrates with Combine, it only works on platforms that support Combine. This currently means the following minimum versions:

Platform Minimum Supported Version
macOS 10.15 (Catalina)
iOS & iPadOS 13
tvOS 13
watchOS 6

Feature Status

RPC Client Calls

  • [x] Unary
  • [x] Client streaming
  • [x] Server streaming
  • [x] Bidirectional streaming
  • [x] Retry policy for automatic client call retries

Server Side Handlers

  • [x] Unary
  • [x] Client streaming
  • [x] Server streaming
  • [x] Bidirectional streaming

End-to-end Tests

  • [x] Unary
  • [x] Client streaming
  • [x] Server streaming
  • [x] Bidirectional streaming

Contributing

To generate the Xcode project, run:

make project

You can then open the project in Xcode, build and run the tests.

GitHub

https://github.com/vyshane/grpc-swift-combine