CombineGRPC
Status
CombineGRPC depends on Swift gRPC v1.0.0-alpha.16, and integrates with Apple's new Combine framework.
gRPC and Combine, Better Together
CombineGRPC is a library that provides Combine framework integration for Swift gRPC. It provides two flavours of functionality, call
and handle
. Use call
to make gRPC calls on the client side, and handle
to handle incoming RPC calls on the server side. CombineGRPC 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, GRPCStatus> |
Server streaming | Request -> AnyPublisher<Response, GRPCStatus> |
Client streaming | AnyPublisher<Request, Error> -> AnyPublisher<Response, GRPCStatus> |
Bidirectional streaming | AnyPublisher<Request, Error> -> AnyPublisher<Response, GRPCStatus> |
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 a GRPCStatus
error. Similarly, if you are handling a unary RPC call, you provide a handler that takes a request parameter and returns an AnyPublisher<Response, GRPCStatus>
.
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, GRPCStatus>
.
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> {
handle(context) { requests in
requests
.map { req in
EchoResponse.with { $0.message = req.message }
}
.setFailureType(to: GRPCStatus.self)
.eraseToAnyPublisher()
}
}
}
Start the server. This is the same process as with Swift gRPC.
let configuration = Server.Configuration(
target: ConnectionTarget.hostAndPort("localhost", 8080),
eventLoopGroup: PlatformSupport.makeEventLoopGroup(loopCount: 1),
serviceProviders: [EchoServiceProvider()]
)
_ = try Server.start(configuration: configuration).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 = PlatformSupport.makeEventLoopGroup(loopCount: eventLoopGroupSize)
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, GRPCStatus>
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: { status in
status.code == .unauthenticated
},
delayUntilNext: { retryCount 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 handlers 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 and the swift-protobuf plugin.
brew install protobuf
brew install swift-protobuf
Next, download the latest version of grpc-swift with NIO support. Currently that means Swift gRPC 1.0.0-alpha.16. Unarchive the downloaded file and build the Swift gRPC plugin by running make in the root directory of the project.
make plugin
Put the built binary 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 add CombineGRPC using Swift Package Manager by listing it as a dependency to your Package.swift configuration file.
dependencies: [
.package(url: "https://github.com/vyshane/grpc-swift-combine.git", from: "0.13.0"),
],
Compatibility
Since this library integrates with Combine, it only works on platforms that support Combine. This currently means the following minimum versions: macOS 10.15 Catalina, iOS 13, watchOS 6 and tvOS 13.
Project Status
RPC Client Calls
- Unary
- Client streaming
- Server streaming
- Bidirectional streaming
- Retry policy for automatic client call retries
Server Side Handlers
- Unary
- Client streaming
- Server streaming
- Bidirectional streaming
End-to-end Tests
- Unary
- Client streaming
- Server streaming
- Bidirectional streaming
Documentation
- README.md
- Inline documentation using markup in comments
Contributing
Unit Tests
Local Code Generation
The unit tests rely on some Swift code that is generated from Protobuf. You can easily generate these by running:
make protobuf
Docker
Code Generation withIf you have Docker installed you can also run:
make protobuf_docker
This will run protoc
in a docker image and copy all the generated files to the correct place in the project.