SwiftStomp

• SwiftStomp
  • An elegent Stomp client for swift, based on iOS URLSessionWebSocketTask.
• TOC
  • Fetures
  • Usage
    • Setup
    • Delegate
    • Upstreams
    • Connect
    • Subscription
    • Send Message
    • Connection Status check
    • Manual Pinging
    • Auto Pinging
  • Test Environment
  • Example
  • Requirements
  • Installation
    • CocoaPods
    • Swift Package Manager
  • Author
  • Contributors
  • License

• Easy to setup, Very light-weight
• Support all STOMP V1.2 frames. CONNECT, SUBSCRIBE, RECEIPT and ....
• Auto object serialize using native JSON Encoder.
• Send and receive Data and Text
• Auto reconnect
• Logging
• Reactive programming ready.

Quick initialize with minimum requirements:

let url = URL(string: "ws://192.168.88.252:8081/socket")!
        
self.swiftStomp = SwiftStomp(host: url) //< Create instance
self.swiftStomp.delegate = self //< Set delegate
self.swiftStomp.autoReconnect = true //< Auto reconnect on error or cancel

self.swiftStomp.connect() //< Connect

Implement all delegate methods to handle all STOMP events!

func onConnect(swiftStomp : SwiftStomp, connectType : StompConnectType)
    
func onDisconnect(swiftStomp : SwiftStomp, disconnectType : StompDisconnectType)

func onMessageReceived(swiftStomp: SwiftStomp, message: Any?, messageId: String, destination: String, headers : [String : String])

func onReceipt(swiftStomp : SwiftStomp, receiptId : String)

func onError(swiftStomp : SwiftStomp, briefDescription : String, fullDescription : String?, receiptId : String?, type : StompErrorType)

In the case that you are more comfort to use Combine publishers, instead of delegate, SwiftStomp can report all events, messages and receiptIds through upstreams. This functionality shines, especially, when you want to use SwiftStomp in the SwiftUI projects. Please check the example project, to see how we can use upstreams, in SwiftUI projects.

// ** Subscribe to events: [Connect/Disconnect/Errors]
swiftStomp.eventsUpstream
    .receive(on: RunLoop.main)
    .sink { event in
               
        switch event {
        case let .connected(type):
            print("Connected with type: \(type)")
        case .disconnected(_):
            print("Disconnected with type: \(type)")
        case let .error(error):
            print("Error: \(error)")
        }
    }
    .store(in: &subscriptions)

// ** Subscribe to messages: [Text/Data]
swiftStomp.messagesUpstream
    .receive(on: RunLoop.main)
    .sink { message in
               
        switch message {
        case let .text(message, messageId, destination, _):
            print("\(Date().formatted()) [id: \(messageId), at: \(destination)]: \(message)\n")
        case let .data(data, messageId, destination, _):
            print("Data message with id `\(messageId)` and binary length `\(data.count)` received at destination `\(destination)`")
        }
    }
    .store(in: &subscriptions)

// ** Subscribe to receipts: [Receipt IDs]
swiftStomp.receiptUpstream
    .sink { receiptId in
        print("SwiftStop: Receipt received: \(receiptId)")
    }
    .store(in: &subscriptions)

Full Connect signature:

self.swiftStomp.connect(timeout: 5.0, acceptVersion: "1.1,1.2")

If you want to reconnect after any un-expected disconnections, enable autoReconnect property.

self.swiftStomp.autoReconnect = true

Notice: If you disconnect manually using disconnect() function, and autoReconnect is enable, socket will try to reconnect after disconnection. If this is not thing you want, please disable autoReconnect before call the disconnect().

Full Subsribe signature. Please notice to subscribe only when you ensure connected to the STOMP. I suggest do it in the onConnect delegate with connectType == .toStomp

swiftStomp.subscribe(to: "/topic/greeting", mode: .clientIndividual)

You have full controll for sending messages. Full signature is as follows:

swiftStomp.send(body: "This is message's text body", to: "/app/greeting", receiptId: "msg-\(Int.random(in: 0..<1000))", headers: [:])

You can check the status of the SwiftStomp by using connectionStatus property:

switch self.swiftStomp.connectionStatus {
case .connecting:
    print("Connecting to the server...")
case .socketConnected:
    print("Scoket is connected but STOMP as sub-protocol is not connected yet.")
case .fullyConnected:
    print("Both socket and STOMP is connected. Ready for messaging...")
case .socketDisconnected:
    print("Socket is disconnected")
}

You control for sending WebSocket 'Ping' messages. Full signature is as follows:

func ping(data: Data = Data(), completion: (() -> Void)? = nil)

You will receive 'Pong' message as a response.

If you want to ensure your connection will still alive, you can use 'Auto Ping' feature. Full signature is as follows:

func enableAutoPing(pingInterval: TimeInterval = 10)

The 'autoPing' feature, will send ping command to websocket server, after pingInterval time ellapsed from last sent sendFrame commands (ex: connect, ack, send ....).

Notice: Auto ping is disabled by default. So you have to enable it after you connected to the server. Also please consider, if you disconnect from the server or call disconnect() explicitly, you must call enableAutoPing() again.

To disable the 'Auto Ping' functionality, use disableAutoPing().

This example was test with a Spring Boot websocket server with RabbitMQ as an external message broker.

Please refer to the Example for more functionalities

To run the example project, clone the repo, and run pod install from the Example directory first.

• iOS 10 or above

SwiftStomp is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'SwiftStomp'

From Xcode 11, you can use Swift Package Manager to add SwiftStomp to your project.

1. Select File > Swift Packages > Add Package Dependency. Enter https://github.com/Romixery/SwiftStomp.git in the "Choose Package Repository" dialog.
2. In the next page, specify the version resolving rule as "Up to Next Major" with "1.0.4" as its earliest version.
3. After Xcode checking out the source and resolving the version, you can choose the "SwiftStomp" library and add it to your app target.

Ahmad Daneshvar, romixery@gmail.com

Very special thanks to: @stuartcamerondeakin, @hunble, @aszter

SwiftStomp is available under the MIT license. See the LICENSE file for more info.