mogol / centrifuge-swift

Swift Websocket client for Centrifugo and Centrifuge library

SwiftCentrifuge

SwiftCentrifuge is a Websocket client for Centrifugo and Centrifuge library. This client uses Protobuf protocol for client-server communication.

SwiftCentrifuge runs all operations in its own queues and provides necessary callbacks so you don't need to worry about managing concurrency yourself.

Status of library

This library is feature rich and supports almost all Centrifuge/Centrifugo features (see feature matrix below). But it's very young and still at active development. Any help and feedback is very appreciated to make it production ready.

Installation

There are several convenient ways.

CocoaPods

To integrate SwiftCentrifuge into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'SwiftCentrifuge'

Carthage

Add the line github "centrifugal/centrifuge-swift" to your Cartfile. Then run carthage update.

Manual

Clone the repo and drag files from Sources folder into your Xcode project.

Dependencies

This library depends on two libraries:

• SwiftProtobuf
• Starscream

Requirements

• iOS 9.0
• Xcode 10.0

Getting Started

An example app is included demonstrating basic client functionality.

Basic usage

Connect to server based on Centrifuge library:

import SwiftCentrifuge

class ClientDelegate : NSObject, CentrifugeClientDelegate {
    func onConnect(_ client: CentrifugeClient, _ e: CentrifugeConnectEvent) {
        print("connected with id", e.client)
    }
    func onDisconnect(_ client: CentrifugeClient, _ e: CentrifugeDisconnectEvent) {
        print("disconnected", e.reason, "reconnect", e.reconnect)
    }
}

let config = CentrifugeClientConfig()
let url = "ws://127.0.0.1:8000/connection/websocket?format=protobuf"
let client = CentrifugeClient(url: url, config: config, delegate: ClientDelegate())
client.connect()

Note that you must use ?format=protobuf in connection URL as this client communicates with Centrifugo/Centrifuge over Protobuf protocol.

To connect to Centrifugo you need to additionally set connection JWT:

...
let client = CentrifugeClient(url: url, config: config, delegate: ClientDelegate())
client.setToken("YOUR CONNECTION JWT")
client.connect()

Now let's look at how to subscribe to channel and listen to messages published into it:

import SwiftCentrifuge

class ClientDelegate : NSObject, CentrifugeClientDelegate {
    func onConnect(_ client: CentrifugeClient, _ e: CentrifugeConnectEvent) {
        print("connected with id", e.client)
    }
    func onDisconnect(_ client: CentrifugeClient, _ e: CentrifugeDisconnectEvent) {
        print("disconnected", e.reason, "reconnect", e.reconnect)
    }
}

class SubscriptionDelegate : NSObject, CentrifugeClientDelegate {
    func onPublish(_ s: CentrifugeSubscription, _ e: CentrifugePublishEvent) {
        let data = String(data: e.data, encoding: .utf8) ?? ""
        print("message from channel", s.channel, data)
    }
}

let config = CentrifugeClientConfig()
let url = "ws://127.0.0.1:8000/connection/websocket?format=protobuf"
let client = CentrifugeClient(url: url, config: config, delegate: ClientDelegate())
client.connect()

do {
    let sub = try client.newSubscription(channel: "example", delegate: SubscriptionDelegate())
    sub.subscribe()
} catch {
    print("Can not create subscription: \(error)")
}

Feature matrix

• connect to server using JSON protocol format
• connect to server using Protobuf protocol format
• connect with JWT
• connect with custom header
• support automatic reconnect in case of errors, network problems etc
• connect and disconnect events
• handle disconnect reason
• subscribe on channel and handle asynchronous Publications
• handle Join and Leave messages
• handle Unsubscribe notifications
• handle subscribe error
• support publish, unsubscribe, presence, presence stats and history methods
• send asynchronous messages to server
• handle asynchronous messages from server
• send RPC commands
• subscribe to private channels with JWT
• support connection JWT refresh
• support private channel subscription JWT refresh
• ping/pong to find broken connection
• support message recovery mechanism

License

SwiftCentrifuge is available under the MIT license. See LICENSE for details.