‼️ Deprecation Notice ‼️
gRPC Swift versions
v0.x based on gRPC-Core will soon be replaced with a re-implementation based on SwiftNIO.
We strongly suggest that new projects use the re-implementation from the
nio branch which we consider to be production ready.
Please see DEPRECATION.md for more information.
This repository contains an experimental Swift gRPC API and code generator.
It is intended for use with Apple's
support for Protocol Buffers. Both projects contain
code generation plugins for
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.
The Echo example provides a comprehensive demonstration of currently-supported features.
Swift gRPC is currently available from CocoaPods.
To integrate, add the following line to your
pod install from command line and use your project's generated
When not using CocoaPods, Swift gRPC includes vendored copies of the gRPC Core library and BoringSSL (an OpenSSL fork that is used by the gRPC Core). These are built automatically in Swift Package Manager builds.
After building your project, add the generated
SwiftGRPC.xcodeproj to your project, and add build dependencies
on BoringSSL, CgRPC, and SwiftGRPC.
See Echo for a working Xcode-based example, and don't hesitate to file issues if you find any problems.
The recommended way to use Swift gRPC 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.
Getting the 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
protoc-gen-swift, which generates Protocol Buffer support code
protoc-gen-swiftgrpc, which generates gRPC interface code.
To install these plugins, just copy the two executables (
protoc-gen-swiftgrpc) that show up in the main directory into a directory that is part of your
PATH environment variable.
Using the plugins
To use the plugins,
protoc and both plugins should be in your
search path (see above). Invoke them with commands like the following:
protoc <your proto files> \ --swift_out=. \ --swiftgrpc_out=.
By convention the
--swift_out option invokes the
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 |
Internal | ACL of generated code |
true | Whether to generate server code |
true | Whether to generate client code |
true | Whether to generate asynchronous code |
true | Whether to generate synchronous code |
true | Whether to generate protocols and non-test service code. Toggling this to
false is mostly useful when combined with
TestStubs=true to generate files containing only test stub code |
false | Whether to generate test stub code |
FullPath | How to handle the naming of generated sources |
String | `` | Extra module to import in generated code. This parameter may be included multiple times to import more than one module |
$ protoc <your proto> --swiftgrpc_out=Client=true,Server=false:.
Building your project
grpc-swift development is done with the Swift Package Manager.
For usage in Xcode projects, we rely on the
swift package generate-xcodeproj
command to generate an Xcode project for the
grpc-swift core libraries.
The top-level Makefile uses the Swift Package Manager to generate an Xcode project for the SwiftGRPC package:
$ make && make project
This will create
SwiftGRPC.xcodeproj, which you should
add to your project, along with setting the necessary build dependencies
While the recommended way to use gRPC is with Protocol Buffers and generated code, at its core gRPC is a powerful HTTP/2-based communication system that can support arbitrary payloads. As such, each gRPC library includes low-level interfaces that can be used to directly build API clients and servers with no generated code. For an example of this in Swift, please see the Simple example.
The SwiftGRPC implementation that is backed by gRPC-Core (and not SwiftNIO) is known to have some connectivity issues on iOS clients - namely, silently disconnecting (making it seem like active calls/connections are hanging) when switching between wifi <> cellular or between cellular technologies (3G <> LTE). The root cause of these problems is that the backing gRPC-Core doesn't get the optimizations made by iOS' networking stack when these types of changes occur, and isn't able to handle them itself.
There is also documentation of this behavior in this gRPC-Core readme.
To aid in this problem, there is a
that monitors the device for events that can cause gRPC to disconnect silently. We recommend utilizing this component to
shutdown() (or destroy) any active
Channel instances, and start new ones when the network is reachable.
on channels is also encouraged.
- Switching between wifi <> cellular: Channels silently disconnect
- Switching between 3G <> LTE (etc.): Channels silently disconnect
- Network becoming unreachable: Most times channels will time out after a few seconds, but
ClientNetworkMonitorwill notify of these changes much faster
- Switching between background <> foreground: No known issues
Original SwiftGRPC issue: https://github.com/grpc/grpc-swift/issues/337.
Having build problems?
grpc-swift depends on Swift, Xcode, and swift-protobuf. We are currently testing with the following versions:
- Xcode 10.2
- Swift 4.2 / 5.0
- swift-protobuf 1.5.0
SwiftGRPCNIO is a clean-room implementation of the gRPC protocol on top of the
SwiftNIO library. This implementation is not yet production-ready as it lacks several things recommended for production use:
- Better test coverage
- Full error handling
- SSL support
- Client support
- Example projects
- iOS support
- Removal of the
However, if you are planning to implement a gRPC service based on
SwiftNIO or the Vapor framework, you might find this package useful. In addition, once ready, this package should provide more predictable and reliable behavior in the future, combined with an improved API and better developer experience.
You may also want to have a look at this presentation for more details on the motivation for this package.
Please get involved! See our guidelines for contributing.
When issuing a new release, the following steps should be followed:
Run the CocoaPods linter to ensure that there are no new warnings/errors:
$ pod spec lint SwiftGRPC.podspec
Update the Carthage Xcode project (diff will need to be checked in with the version bump):
$ make project-carthage
Bump the version in the
Merge these changes, then create a new
Tag. Be sure to include a list of changes in the message
Push the update to the CocoaPods specs repo:
$ pod trunk push
Help us keep the lights on
1.0.0-alpha.7 - Nov 14, 2019
Important: this change contains breaking changes to the generated client code.
- License header checking script (#587)
- Run CI on Swift 5.1 and Swift 5.0 (#588)
- Add missing environment variable for interop tests (#589)
- RPC state machine for client (#580)
- Add/update GOVERNANCE.md, CODE-OF-CONDUCT.md and CONTRIBUTING.md (#595)
- Add HelloWorld example (#590)
- Add a RouteGuide example and tutorial (#598)
- Fix up markdown (#600)
- Reduce logging in the message reader (#602)
- Workaround for SR-11564 (#608)
- Provide a channel handler using the client state machine (#601)
- Use string comparison instead of regex in the HTTPProtocolSwitcher (#618)
- Update the client to use the new state machine backed channel handler (#625)
- Update CI to use more recent Swift versions (#629)
- Reduce logging verbosity (#632)
- Inline service name into the generated path (#633)
- Require a lock to access the connectivity state delegate (#634)
- import FoundationNetworking if possible (#586)
- Remove unexported executables from products (#592)
- Fix interoperability tests. (#596)
0.10.0 - Oct 25, 2019
- Use protoToModuleMappings in input/output names. (#553)
- Update vendored gRPC-core to v1.23.0. (#563)
1.0.0-alpha.6 - Sep 18, 2019
- Fix deprecation warnings (#585) - George Barnett (3972a3f9)
- Rename the plugin: protoc-gen-swiftgrpc -> protoc-gen-grpc-swift (#584) - George Barnett (ca683154)
- Explain platform support in the readme. (#578) - Daniel Alm (99d51ca2)
- Add MAINTAINERS.md. (#564) (#576) - George Barnett (e0c70ce6)
1.0.0-alpha.5 - Sep 3, 2019
- Always use the same event loop for a client connection (#562)
- Allow timeouts to be rounded so they may comply with the spec (#569)
- Separate trailers from GRPCStatus (#572)
- Replace Commander usage with our own CLI parsing (#570)
- Split the Echo example into model, implementation and runtime (#567)
- CI and version updates (#561, #571, #568, #573)
1.0.0-alpha.4 - Aug 20, 2019
- Increase the minimum required version of NIOSSL (#559)
- Increase the minimum required version of NIOHTTP/2 (#548)
- Implement the connection backoff interoperability test (#557)
- Default to using backoff for making connections (#554)
- Make the connection backoff iterator continually produce backoff (#554)
- Fix a rare thread safety issue in tests (#551)
- Add server logging (#547)
- Use protoToModuleMappings in input/output names (#555)
- Package structure updates, typo fixes, dead code removal (#558, #556, #549, #546, #544)