grpc-swift/README.md

gRPC Swift

This repository contains a gRPC Swift API and code generator.

It is intended for use with Apple's SwiftProtobuf support for Protocol Buffers. Both projects contain code generation plugins for protoc, Google's Protocol Buffer compiler, and both contain libraries of supporting code that is needed to build and run the generated code.

APIs and generated code is provided for both gRPC clients and servers, and can be built either with Xcode or the Swift Package Manager. Support is provided for all four gRPC API styles (Unary, Server Streaming, Client Streaming, and Bidirectional Streaming) and connections can be made either over secure (TLS) or insecure channels.

gRPC Swift is built on top of Swift NIO as opposed to the core library provided by the gRPC project.

Supported Platforms

gRPC Swift's platform support is identical to the platform support of Swift NIO.

Getting Started

There are two parts to gRPC Swift: the gRPC library and an API code generator.

Getting the gRPC library

Note that this package requires Swift 5.

Swift Package Manager

The Swift Package Manager is the preferred way to get gRPC Swift. Simply add the package dependency to your Package.swift and depend on "GRPC" in the necessary targets:

dependencies: [
  .package(url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0-alpha.5")
]

Xcode

From Xcode 11 it is possible to add Swift Package dependencies to Xcode projects and link targets to products of those packages; this is the easiest way to integrate gRPC Swift with an existing xcodeproj.

Manual Integration

Alternatively, gRPC Swift can be manually integrated into a project:

1. Build an Xcode project: swift package generate-xcodeproj,
2. Add the generated project to your own project, and
3. Add a build dependency on GRPC.

CocoaPods

CocoaPods support will be added in v1.0.

Getting the protoc Plugins

Binary releases of protoc, the Protocol Buffer Compiler, are available on GitHub.

To build the plugins, run make plugin in the main directory. This uses the Swift Package Manager to build both of the necessary plugins: protoc-gen-swift, which generates Protocol Buffer support code and protoc-gen-swiftgrpc, which generates gRPC interface code.

To install these plugins, just copy the two executables (protoc-gen-swift and protoc-gen-swiftgrpc) that show up in the main directory into a directory that is part of your PATH environment variable. Alternatively the full path to the plugins can be specified when using protoc.

Using gRPC Swift

Recommended

The recommended way to use gRPC Swift is to first define an API using the Protocol Buffer language and then use the Protocol Buffer Compiler and the Swift Protobuf and Swift gRPC plugins to generate the necessary support code.

Example

This example demonstrates how to create a simple service which echoes any requests it receives back to the caller. We will also demonstrate how to call the service using a generated client.

We will only cover the unary calls in this example. All call types are demonstrated in the Echo example.

Three main steps are required:

1. Defining the service in the proto interface definition language,
2. Generating the service and client code, and
3. Implementing the service code.

Defining the Service

The first step is to define our service defined in the Protocol Buffer language as follows:

syntax = "proto3";

// The namespace for our service, we may have multiple services within a
// single package.
package echo;

// The definition of our service.
service Echo {
  // Get takes a single EchoRequest protobuf message as input and returns a
  // single EchoResponse protobuf message in response.
  rpc Get(EchoRequest) returns (EchoResponse) {}
}

// The EchoRequest protobuf message definition.
message EchoRequest {
  // The text of a message to be echoed.
  string text = 1;
}

// The EchoResponse protobuf message definition.
message EchoResponse {
  // The text of an echo response.
  string text = 1;
}

Generating the Service and Client Code

Once we have defined our service we can generate the necessary code to implement our service and client.

Models (such as EchoRequest and EchoResponse) are generated using the protoc plugin provided by SwiftProtobuf. Assuming the above definition for the Echo service and models were saved as echo.proto and the protoc-gen-swift plugin is available in your PATH then the following will generate the models and write them to echo.pb.swift in the current directory:

protoc echo.proto --swift_out=.

gRPC Swift provides a plugin (protoc-gen-swiftgrpc) to generate the client and server for the Echo service defined above. It can be invoked to produce echo.grpc.swift as such:

protoc echo.proto --swiftgrpc_out=.

By default both the client and service code is generated (see Plugin Options for more details).

Implementing the Service Code

The generated service code includes a protocol called Echo_EchoProvider which defines the set of RPCs that the service offers. The service can be implemented by creating a class which conforms to the protocol.

import GRPC
import NIO

class EchoProvider: Echo_EchoProvider {
  func get(request: Echo_EchoRequest, context: StatusOnlyCallContext) -> EventLoopFuture<Echo_EchoResponse> {
    let response = Echo_EchoResponse.with {
      $0.text = "Swift echo get: \(request.text)"
    }
    return context.eventLoop.makeSucceededFuture(response)
  }
}

Using the Service Provider and Generated Client

Now that we have implemented our service code and generated a client, we can put it all together.

First we need the appropriate imports:

import GRPC
import NIO
import Foundation

Since this is just a locally hosted example we'll run the server on localhost port 8080.

let host = "localhost"
let port = 8080

First we need to start the server and provide the Echo service using the EchoProvider we implemented above. We create an event loop group which will spawn a single thread to run events on the server. Note that you can also use System.coreCount to get the number of logical cores on your system.

We also wait for the server to start before setting up a client.

let serverEventLoopGroup = PlatformSupport.makeEventLoopGroup(loopCount: 1)
let configuration = Server.Configuration(
  target: .hostAndPort(host, port),
  eventLoopGroup: serverEventLoopGroup,
  serviceProviders: [EchoProvider()]
)

let server = try Server.start(configuration: configuration).wait()

Note that the at the end of the program, the serverEventLoopGroup whould be shutdown (try serverEventLoopGroup.syncShutdownGracefully()).

Normally the client would be in a different binary to the server, however, for this example we will include them together.

Once the server has started we can create a client by defining the connection configuration, starting the connection, and then using that connection as a means to make gRPC calls via a generated client. Note that Echo_EchoServiceClient is the client we generated from echo.proto.

let clientEventLoopGroup = PlatformSupport.makeEventLoopGroup(loopCount: 1)
let configuration = ClientConnection.Configuration(
  target: .hostAndPort(host, port),
  eventLoopGroup: clientEventLoopGroup
)

let connection = ClientConnection(configuration: configuration)
// This is our generated client, we only need to pass it a connection.
let echo = Echo_EchoServiceClient(connection: connection)

Note that the clientEventLoopGroup should also be shutdown when it is no longer required.

We can also define some options on our call, such as custom metadata and a timeout. Note that options are not required at the call-site and may be omitted entirely. If options are omitted from the call then they are taken from the client instead. Default client options may be passed as an additional argument to the generated client.

var callOptions = CallOptions()
// Add a request id header to the call.
callOptions.customMetadata.add(name: "x-request-id", value: UUID().uuidString)
// Set the timeout to 5 seconds. This may throw since the timeout is validated against
// the gRPC specification, which limits timeouts to be at most 8 digits long.
callOptions.timeout = try .seconds(5)

We can now make an asynchronous call to the service by using the functions on the generated client:

let request = Echo_EchoRequest.with {
  $0.text = "Hello!"
}

let get = echo.get(request, callOptions: callOptions)

The returned get object is of type UnaryClientCall<Echo_EchoRequest, Echo_EchoResponse> and has futures for the initial metadata, response, trailing metadata and call status. The differences between call types is detailed in API Types.

Note that the call can be made synchronous by waiting on the response property of the get object:

let response = try get.response.wait()

We can register callbacks on the response to observe its value:

get.response.whenSuccess { response in
  print("Received '\(response.text)' from the Echo service")
}

We can also register a callback on the response to observe an error should the call fail:

get.response.whenFailure { error in
  print("The Get call to the Echo service failed: \(error)")
}

The call will always terminate with a status which includes a status code and optionally a message and trailing metadata.

This is often the most useful way to determine the outcome of a call. However, it should be noted that even if the call fails, the status future will be succeeded.

get.status.whenSuccess { status in
  if let message = status.message {
    print("Get completed with status code \(status.code) and message '\(message)'")
  } else {
    print("Get completed with status code \(status.code)")
  }
}

If the program succeeds it should emit the following output (if you're running the example the program may terminate before the callbacks are called, to avoid this you can simply wait() on the call status):

Received 'Swift echo get: Hello!' from the Echo service
Get completed with status code ok and message 'OK'

Without a Generated Client

It is also possible to call gRPC services without a generated client. The models for the requests and responses are required, however.

If you are calling a service which you don't have any generated client, you can use AnyServiceClient. For example, to call "Get" on the Echo service you can do the following:

let connection = ... // get a ClientConnection
let anyService = AnyServiceClient(connection: connection)

let get = anyService.makeUnaryCall(
  path: "/echo.Echo/Get",
  request: Echo_EchoRequest.with { $0.text = "Hello!" },
  responseType: Echo_EchoResponse.self
)

Calls for client-, server- and bidirectional-streaming are done in a similar way using makeClientStreamingCall, makeServerStreamingCall, and makeBidirectionalStreamingCall respectively.

These methods are also available on generated clients, allowing you to call methods which have been added to the service since the client was generated.

API Types

gRPC Swift provides all four API styles: Unary, Server Streaming, Client Streaming, and Bidirectional Streaming. Calls to the generated types will return an object of the approriate type:

• UnaryCall<Request, Response>
• ClientStreamingCall<Request, Response>
• ServerStreamingCall<Request, Response>
• BidirectionalStreamingCall<Request, Response>

Each call object provides futures for the initial metadata, trailing metadata, and status. Unary response calls also have a future for the response whilst streaming response calls will call a handler for each response. Calls with unary requests send their message when instantiating the call, streaming request calls include methods on the call object to send messages (sendMessage(_:), sendMessages(_:), sendMessage(_:promise:), sendMessages(_:promise:)) as well as methods for terminating the stream of messages (sendEnd() and sendEnd(promise:)).

These differences are summarised in the following table.

API Type	Response	Send Message
Unary	Future	At call time
Client Streaming	Future	On the call object
Server Streaming	Handler	At call time
Bidirectional Streaming	Handler	On the call object

Using TLS

gRPC calls can be made over a secure channel by configuring TLS. This requires specifying tls on ClientConnection.Configuration or Server.Configuration.

For the client, tls can be as simple as:

let tls = ClientConnection.Configuration.TLS()

For the server, tls is slightly more complicated as it requires a certificate chain and private key:

# Load the certificates from "cert.pem"
let certificates: [NIOSSLCertificate] = try NIOSSLCertificate.fromPEMFile("cert.pem")

let tls = Server.Configuration.TLS(
  certificateChain: certificates.map { .certificate($0) },
  privateKey: .file("key.pem")
)

The TLS configuration is a subset of TLSConfiguration provided by NIOSSL to ensure it meets the gRPC specification. Users may also initialize TLS with TLSConfiguration should they require.

NIO vs. NIO Transport Services

NIO offers extensions to provide first-class support for Apple platforms (iOS 12+, macOS 10.14+, tvOS 12+, watchOS 6+) via NIO Transport Services. NIO Transport Services uses Network.framework and DispatchQueues to schedule tasks.

To use NIO Transport Services in gRPC Swift you need to provide a NIOTSEventLoopGroup to the configuration of your server or client connection. gRPC Swift provides a helper method to provide the correct EventLoopGroup based on the network preference:

PlatformSupport.makeEventLoopGroup(loopCount:networkPreference:) -> EventLoopGroup

Here networkPreference defaults to .best, which chooses the .networkFramework implementation if it is available (iOS 12+, macOS 10.14+, tvOS 12+, watchOS 6+) and uses .posix otherwise.

Using the TLS provided by Network.framework via NIO Transport Services is not currently supported. Instead, TLS is provided by NIOSSL.

Plugin Options

To pass extra parameters to the plugin, use a comma-separated parameter list separated from the output directory by a colon.

Flag	Values	Default	Description
Visibility	Internal/Public	Internal	ACL of generated code
Server	true/false	true	Whether to generate server code
Client	true/false	true	Whether to generate client code
FileNaming	FullPath/PathToUnderscores/DropPath	FullPath	How to handle the naming of generated sources, see documentation
ExtraModuleImports	String		Extra module to import in generated code. This parameter may be included multiple times to import more than one module

For example, to generate only client stubs:

protoc <your proto> --swiftgrpc_out=Client=true,Server=false:.

License

gRPC Swift is released under the same license as gRPC, repeated in LICENSE.

Contributing

Please get involved! See our guidelines for contributing.