Swiftpack.co - Package - grpc/grpc-swift

Build Status

Swift gRPC

This repository contains an experimental Swift gRPC API and code generator.

It is intended for use with Apple's swift-protobuf 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.

The Echo example provides a comprehensive demonstration of currently-supported features.

Swift Package Manager builds may also be made on Linux systems. Please see DOCKER.md and LINUX.md for details.

CocoaPods integration

Swift gRPC is currently available from CocoaPods. To integrate, add the following line to your Podfile:

pod 'SwiftGRPC'

Then, run pod install from command line and use your project's generated .xcworkspace file.

Manual integration

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.

Please also note that your project will need to include the SwiftProtobuf.xcodeproj from Swift Protobuf and the source files that you generate with protoc/plugins.

See Echo for a working Xcode-based example, and don't hesitate to file issues if you find any problems.

Usage

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 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.

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 protoc-gen-swift plugin and --swiftgrpc_out invokes protoc-gen-swiftgrpc.

Parameters

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 | | Async | true/false | true | Whether to generate asynchronous code | | Sync | true/false | true | Whether to generate synchronous code | | Implementations | true/false | 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 | | TestStubs | true/false | false | Whether to generate test stub code | | FileNaming | FullPath/PathToUnderscores/DropPath | FullPath | How to handle the naming of generated sources | | ExtraModuleImports | String | `` | Extra module to import in generated code. This parameter may be included multiple times to import more than one module |

Example:

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

Building your project

Most 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 mentioned above.

Low-level gRPC

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.

Known issues

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 ClientNetworkMonitor that monitors the device for events that can cause gRPC to disconnect silently. We recommend utilizing this component to call shutdown() (or destroy) any active Channel instances, and start new ones when the network is reachable.

Setting the keepAliveTimeout argument on channels is also encouraged.

Details:

  • 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 ClientNetworkMonitor will 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 9.1
  • Swift 4.0
  • swift-protobuf 1.3.1

SwiftGRPCNIO package

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 libnghttp2 dependency from SwiftNIOHTTP2

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.

License

grpc-swift is released under the same license as gRPC, repeated in LICENSE.

Contributing

Please get involved! See our guidelines for contributing.

Releasing

When issuing a new release, the following steps should be followed:

  1. Run the CocoaPods linter to ensure that there are no new warnings/errors:

    $ pod spec lint SwiftGRPC.podspec

  2. Update the Carthage Xcode project (diff will need to be checked in with the version bump):

    $ make project-carthage

  3. Bump the version in the SwiftGRPC.podspec file

  4. Merge these changes, then create a new Release with corresponding Tag. Be sure to include a list of changes in the message

  5. Push the update to the CocoaPods specs repo:

    $ pod trunk push

Github

link
Stars: 586
Help us keep the lights on

Releases

0.8.0 - Mar 1, 2019

  • Update CocoaPods & Carthage for 0.8.0 release (#370) - Michael Rebello (8b064bd)
  • Add ClientNetworkMonitor for tracking network changes (#387) - Michael Rebello (3b3c5c5)
  • First pass implementation of NIO client (#357) - George Barnett (97ff923)
  • Clean up gRPC.swift (#386) - Michael Rebello (ee0f374)
  • Add ability to manually shut down channels (#384) - Michael Rebello (930440a)
  • Update releasing instructions (#383) - Michael Rebello (f5c0d63)
  • Comments/cleanup to Package.swift. (#371) - Daniel Alm (ba335b2)
  • Refactor channel connectivity to avoid multiple spin loops (#380) - Michael Rebello (10aff09)
  • Improve error handling in NIO server. (#364) - George Barnett (158c4ef)
  • Fix channel credentials memory leak in shims (#369) - Kevin Sweeney (587218a)
  • Make ConnectivityObserver class final (#375) - Michael Rebello (5f24269)
  • Store the root certificates as a multi-line string literal. (#372) - Daniel Alm (ac3e175)
  • Run ChannelCrashTests on Linux/CI (#379) - Michael Rebello (b899a30)
  • Move ConnectivityState to new file & update initializer (#376) - Michael Rebello (9dff24d)
  • Merge pull request #350 from sergiocampama/http1 - Tim Burks (ac1939e)
  • Adds Echo Web example with functional prototype - Sergio Campama (86748a7)
  • Add HTTP1 Tests for GRPCSwiftNIO - Sergio Campama (eee57da)
  • Add gRPC Web support. - Sergio Campama (24c8e5d)
  • Proposal to fix #362. (#363) - Alexey Gordeev (0195dfd)
  • Allow client to specify metadata per call (#356) - Taeho Kim (3cd505a)
  • Update SwiftProtobuf to 1.3.1 (#367) - Michael Rebello (96bf49e)
  • Improve memory management in Channel (#368) - Kevin Sweeney (fcb8ab3)
  • XCode 10.1 + Carthage support (#360) - Dmitry Malakhov (99d3834)
  • Upgrade swift-nio to 1.12 - George Barnett (a43337c)
  • Allow "FileNaming" option to be set via CLI - George Barnett (78c5fed)
  • Bump podspec to 0.7.0 - Michael Rebello (6928fb2)

0.7.0 - Dec 22, 2018

  • Support proto-gen-swift's proto-to-module mapping. (ff2d161 - Tony Allevato)
  • Update Linux build documentation (#346) (824814b - George Barnett)
  • Add libnghttp2 depdendency to Docker image (#338) (#344) (c3a03f1 - George Barnett)
  • Add environment flag for BoringSSL/OpenSSL on MacOS (#341) (54659b8 - james h)
  • First implementation of gRPC based on SwiftNIO (#281) (bf20e93 - Daniel Alm)
  • Remove .swift-version file (d3ad74b - Yosuke Ishikawa)
  • Add support for RPC status (#331) (b6dc500 - Sebastian Thiebaud)
  • Fix crash during Channel with subscription is destroying (#328) (2fd06dc - slavabulgakov)
  • Improve the documentation on building the protoc plugins and add a make plugin option. (48c274f - Daniel Alm)
  • Remove build-carthage altogether from CI for now. (7e6e28c - Daniel Alm)
  • Pull build-carthage to the beginning of the build process for faster CI iteration times on failing Carthage builds. (8cd1420 - Daniel Alm)
  • Minor tweaks in preparation for SwiftGRPCNIO. (00d18f6 - Daniel Alm)
  • Transmission type parameters for sync/async code generation (611e527 - Pontus Andersson)
  • Re-run make project-carthage (6cc5371 - Yosuke Ishikawa)
  • Replace absolute path with relative path after generating xcodeproj (30441f7 - Yosuke Ishikawa)
  • Docs/add question template (#310) (0faf1d6 - tikidunpon)
  • Add io.grpc. prefix to bundle identifier (c9b15b8 - Yosuke Ishikawa)
  • Update README.md (02b8fc5 - Daniel Alm)
  • Update README.md (8ff1778 - Daniel Alm)
  • Update README.md (ec7c3e4 - Daniel Alm)
  • Update README.md (52195d2 - Daniel Alm)
  • Tweak Echo Readme (see #273) (a387dd6 - Daniel Alm)
  • docs: add a mention about resolved issues about ssl. (5ba63b6 - tikidunpon)
  • docs: add issue template for bug reporting. (660adca - tikidunpon)

0.6.0 - Nov 16, 2018

  • Cut a 0.6.0 release due to the breaking changes in SwiftProtobuf 1.1 (ed8a7e5 - GitHub)
  • Several fixes to the example projects. (696cd46 - Daniel Alm)
  • Update CLA link to point to CNCF CLA. (c3a071b - Tim Burks)
  • Update Carthage project with SwiftProtobuf 1.1.1 (9841080 - Michael Rebello)
  • Update examples to SwiftProtobuf 1.1.1 (a86b934 - Michael Rebello)
  • Update README with swift-protobuf version (9db4d0b - Michael Rebello)
  • Update SwiftProtobuf to 1.1.1 (6c6d9be - Michael Rebello)
  • Remove Linux RUNME.sh script (5dfda65 - Michael Rebello)

0.5.1 - Nov 16, 2018

  • Fix -Wstrict-prototypes warning (c03c5c7 - Michael Rebello)
  • Bump podspec to 0.5.1 (021075e - Michael Rebello)
  • Project patch script rework. (4984951 - Daniel Alm)
  • Only make the Swift Xcode project (instead of a full Xcode build) on macOS CI, as that is covered by the Carthage build already. (165f684 - Daniel Alm)
  • Fix make clean and switch to Carthage debug builds on CI for improved performance. (3e8720e - Daniel Alm)
  • Support folding the output of individual build steps in the Travis log. (5130063 - Daniel Alm)
  • Lock the SwiftProtobuf dependency to 1.0.3, up to next minor (#289) (78ac010 - Daniel Alm)
  • version SwiftGRPC-Carthage.xcodeproj after CgRPC fix (55cc056 - Jonas Vautherin)
  • fix CgRPC target in generated xcodeproj files (bea6195 - Jonas Vautherin)
  • Add "Releasing" section for CocoaPods to the ReadMe (36dbda1 - Michael Rebello)
  • Update carthage xcodeproj (4cc9c3c - Jonas Vautherin)
  • version SwiftGRPC-Carthage.xcodeproj for Carthage (e07895f - Jonas Vautherin)
  • Add make target generating an xcodeproj for Carthage. (ea2babf - Jonas Vautherin)
  • fix make clean target (d8b2b51 - Jonas Vautherin)
  • [README] Update the link to the Echo sample project. (3eade39 - Shinping Bai)
  • PR Feedback (7340be3 - Brian Hatfield)
  • Expose google cgrpc credential mode (b4414b8 - Brian Hatfield)
  • Remove Czlib dependency from SimpleXcode example (325c9cf - koichi.tanaka)
  • Fix a header search path for CgRPC and some compile error for „Echo“ example (44dfc81 - koichi.tanaka)
  • Remove Czlib from README (0c3ce55 - koichi.tanaka)
  • Remove Czlib from dependencies (ec3c2a9 - koichi.tanaka)
  • Update Dockerfile (62e4e3c - GitHub)
  • add "make project" (05b27cb - GitHub)

0.5.0 - Nov 16, 2018

  • Update podspec to version 0.5.0. (f11ad0b - Tim Burks)
  • Create ServerStatus in Core (045bc17 - ito_kyohei)
  • Code review fixes. (5f0531d - Daniel Alm)
  • Fix compilation under Linux. (3130eea - Daniel Alm)
  • Fix a bug and test for it. (b34303c - Daniel Alm)
  • Add a few more tests to ensure that trailing metadata is sent as expected. (22dee41 - Daniel Alm)
  • Reword documentation (c317f9d - Nate Armstrong)
  • Rename "services" to "serviceProviders". (a6e8cbb - Daniel Alm)
  • Add security tests to LinuxMain (df96858 - Nate Armstrong)
  • Document rootCerts param (22da1da - Nate Armstrong)
  • Update TestKeys generator and include cert files (1e19905 - Nate Armstrong)
  • Remove comment (d5ff00d - Nate Armstrong)
  • Add tests for mutual auth (18af90f - Nate Armstrong)
  • For service servers, replace inheritance with composition. (98f7fa6 - Daniel Alm)
  • Added requited designation to allow to create ServiceClient dynamically (12340a4 - Carlos Pages)
  • Make ChannelArgument extensible with custom values. (4f9e7a5 - Daniel Alm)
  • Make the build commands less verbose. (ec8f37b - Daniel Alm)
  • Pass pointer (2252397 - Nate Armstrong)
  • Fix memory leak and whitespace (706ed74 - Nate Armstrong)
  • Cast malloc result (a2b983a - Nate Armstrong)
  • Pass NULL if client certs or key are not given (f477ce5 - Nate Armstrong)
  • Update ServiceClient init (b795d14 - Nate Armstrong)
  • Add support for TLS mutual auth (0251dd8 - Nate Armstrong)
  • Fix building with a clean Xcode and add a CI run to ensure just that. (56ecb72 - Daniel Alm)
  • Fix linking with OpenSSL on Linux. (8ef093b - Daniel Alm)
  • Move another compiler directive into vendor-grpc.sh. (03f4309 - Daniel Alm)
  • Re-add swift-nio-zlib-support for macOS builds. (c12125b - Daniel Alm)
  • Update Google sample for recent API changes. (2cc6af7 - Tim Burks)
  • Move a compilation flag out of the Makefile and fix-project-settings.rb and into vendor-grpc.sh, which adds them to Sources/CgRPC/third_party/nanopb/pb.h. (4a16c13 - Daniel Alm)
  • Re-add swift-nio-zlib-support for macOS builds. (0368de9 - Daniel Alm)
  • Also update the Mac Travis system images to Xcode 9.3. (070170d - Daniel Alm)
  • Update .travis-install.sh to Swift 4.1.1. (470fb2f - Daniel Alm)
  • Update CgRPC to v1.12.0 and BoringSSL to 10.0.4 (I guess?). This change requires Swift 4.1 and Ruby (with the 'xcodeproj' gem) installed to compile if building via SPM. (75940a4 - Daniel Alm)
  • Link CgRPC with openssl instead of BoringSSL under Linux. (d56e1ca - Daniel Alm)
  • Add a few channel arguments (3cd89dd - Sebastian Thiebaud)
  • PR changes (0d25ef8 - Sebastian Thiebaud)
  • Remove print statements (ad6e022 - Sebastian Thiebaud)
  • PR changes (4ca615a - Sebastian Thiebaud)
  • Add comments (e853032 - Sebastian Thiebaud)
  • PR changes (0891482 - Sebastian Thiebaud)
  • Add timeout argument to makeCall (0d67da9 - ito_kyohei)
  • PR changes (255ce88 - Sebastian Thiebaud)
  • Make ServiceServer log calls to unknown methods. (e144258 - Daniel Alm)
  • Replace Metadata.description with Metadata.dictionaryRepresentation.description. (588963a - Daniel Alm)
  • Explicitly import dispatch (76faf09 - Chris Vanderschuere)
  • Implement connectivity state property and observers (#8) (0bd14d8 - Chris Vanderschuere)