Connect-Swift

Connect-Swift is a small library (<200KB!) that provides support for using generated, type-safe, and idiomatic Swift APIs to communicate with your app's servers using Protocol Buffers (Protobuf). It works with the Connect, gRPC, and gRPC-Web protocols.

Imagine a world where you don't have to handwrite Codable models for REST/JSON endpoints and you can instead get right to building features by calling a generated API method that is guaranteed to match the server's modeling. Furthermore, imagine never having to worry about serialization again, and being able to easily write tests using generated mocks that conform to the same protocol that the real implementations do. All of this is possible with Connect-Swift.

Given a simple Protobuf schema, Connect-Swift generates idiomatic Swift protocol interfaces and client implementations:

public protocol Eliza_V1_ChatServiceClientInterface {
    func say(request: Eliza_V1_SayRequest, headers: Headers)
        async -> ResponseMessage<Eliza_V1_SayResponse>
}

public final class Eliza_V1_ChatServiceClient: Eliza_V1_ChatServiceClientInterface {
    private let client: ProtocolClientInterface

    public init(client: ProtocolClientInterface) {
        self.client = client
    }

    public func say(request: Eliza_V1_SayRequest, headers: Headers = [:])
        async -> ResponseMessage<Eliza_V1_SayResponse>
    {
        return await self.client.unary(path: "buf.connect.demo.eliza.v1.ElizaService/Say", request: request, headers: headers)
    }
}

This code can then be integrated with just a few lines:

final class MessagingViewModel: ObservableObject {
    private let elizaClient: Eliza_V1_ChatServiceClientInterface

    init(elizaClient: Eliza_V1_ChatServiceClientInterface) {
        self.elizaClient = elizaClient
    }

    @Published private(set) var messages: [Message] {...}

    func send(_ userSentence: String) async {
        let request = Eliza_V1_SayRequest.with { $0.sentence = userSentence }
        let response = await self.elizaClient.say(request: request, headers: [:])
        if let elizaSentence = response.message?.sentence {
            self.messages.append(Message(sentence: userSentence, author: .user))
            self.messages.append(Message(sentence: elizaSentence, author: .eliza))
        }
    }
}

That’s it! You no longer need to manually define Swift response models, add Codable conformances, type out URL(string: ...) initializers, or even create protocol interfaces to wrap service classes - all this is taken care of by Connect-Swift, and the underlying network transport is handled automatically.

Testing also becomes a breeze with generated mocks which conform to the same protocol interfaces as the production clients:

open class Eliza_V1_ChatServiceClientMock: Eliza_V1_ChatServiceClientInterface {
    public var mockAsyncSay = { (_: Eliza_V1_SayRequest) -> ResponseMessage<Eliza_V1_Response> in .init(message: .init()) }

    open func say(request: Eliza_V1_SayRequest, headers: Headers = [:])
        async -> ResponseMessage<Eliza_V1_SayResponse>
    {
        return self.mockAsyncSay(request)
    }
}

func testMessagingViewModel() async {
    let client = Eliza_V1_ChatServiceClientMock()
    client.mockAsyncSay = { request in
        XCTAssertEqual(request.sentence, "hello!")
        return ResponseMessage(message: .with { $0.sentence = "hi, i'm eliza!" })
    }

    let viewModel = MessagingViewModel(elizaClient: client)
    await viewModel.send("hello!")

    XCTAssertEqual(viewModel.messages.count, 2)
    XCTAssertEqual(viewModel.messages[0].message, "hello!")
    XCTAssertEqual(viewModel.messages[0].author, .user)
    XCTAssertEqual(viewModel.messages[1].message, "hi, i'm eliza!")
    XCTAssertEqual(viewModel.messages[1].author, .eliza)
}

Quick Start

Head over to our quick start tutorial to get started. It only takes ~10 minutes to complete a working SwiftUI chat app that uses Connect-Swift!

Documentation

Comprehensive documentation for everything, including interceptors, mocking/testing, streaming, and error handling is available on the connect.build website.

Example Apps

Example apps are available in the Examples directory and can be opened and built using Xcode. They demonstrate:

• Using streaming APIs
• Integrating with Swift Package Manager
• Integrating with CocoaPods
• Using the Connect protocol
• Using the gRPC protocol
• Using the gRPC-Web protocol

Contributing

We'd love your help making Connect better!

Extensive instructions for building the library and generator plugins locally, running tests, and contributing to the repository are available in our CONTRIBUTING.md guide. Please check it out for details.

Ecosystem

• connect-kotlin: Idiomatic gRPC & Connect RPCs for Kotlin
• connect-go: Go service stubs for servers
• connect-web: TypeScript clients for web browsers
• Buf Studio: Web UI for ad-hoc RPCs
• connect-crosstest: Connect, gRPC, and gRPC-Web interoperability tests

Status

This project is in beta, and we may make a few changes as we gather feedback from early adopters. Join us on Slack!

Legal

Offered under the Apache 2 license.