Name: Starscream
Owner: Rocket.Chat
Description: Websockets in swift for iOS and OSX
Forked from: daltoniam/Starscream
Created: 2017-11-06 11:45:45.0
Updated: 2017-11-06 11:45:46.0
Pushed: 2017-11-06 11:50:57.0
Homepage: null
Size: 1753
Language: Swift
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
Starscream is a conforming WebSocket (RFC 6455) client library in Swift.
Its Objective-C counterpart can be found here: Jetfire
First thing is to import the framework. See the Installation instructions on how to add the framework to your project.
rt Starscream
Once imported, you can open a connection to your WebSocket server. Note that socket is probably best as a property, so it doesn't get deallocated right after being setup.
et = WebSocket(url: URL(string: "ws://localhost:8080/")!)
et.delegate = self
et.connect()
After you are connected, there are some delegate methods that we need to implement.
websocketDidConnect is called as soon as the client connects to the server.
websocketDidConnect(socket: WebSocketClient) {
print("websocket is connected")
websocketDidDisconnect is called as soon as the client is disconnected from the server.
websocketDidDisconnect(socket: WebSocketClient, error: Error?) {
print("websocket is disconnected: \(error?.localizedDescription)")
websocketDidReceiveMessage is called when the client gets a text frame from the connection.
websocketDidReceiveMessage(socket: WebSocketClient, text: String) {
print("got some text: \(text)")
websocketDidReceiveData is called when the client gets a binary frame from the connection.
websocketDidReceiveData(socket: WebSocketClient, data: Data) {
print("got some data: \(data.count)")
websocketDidReceivePong is called when the client gets a pong response from the connection. You need to implement the WebSocketPongDelegate protocol and set an additional delegate, eg: socket.pongDelegate = self
websocketDidReceivePong(socket: WebSocketClient, data: Data?) {
print("Got pong! Maybe some data: \(data?.count)")
Or you can use closures.
et = WebSocket(url: URL(string: "ws://localhost:8080/")!)
bsocketDidConnect
et.onConnect = {
print("websocket is connected")
bsocketDidDisconnect
et.onDisconnect = { (error: Error?) in
print("websocket is disconnected: \(error?.localizedDescription)")
bsocketDidReceiveMessage
et.onText = { (text: String) in
print("got some text: \(text)")
bsocketDidReceiveData
et.onData = { (data: Data) in
print("got some data: \(data.count)")
u could do onPong as well.
et.connect()
One more: you can listen to socket connection and disconnection via notifications. Starscream posts WebsocketDidConnectNotification and WebsocketDidDisconnectNotification. You can find an Error that caused the disconection by accessing WebsocketDisconnectionErrorKeyName on notification userInfo.
The writeData method gives you a simple way to send Data (binary) data to the server.
et.write(data: data) //write some Data over the socket!
The writeString method is the same as writeData, but sends text/string.
et.write(string: "Hi Server!") //example on how to write text over the socket!
The writePing method is the same as write, but sends a ping control frame.
et.write(ping: Data()) //example on how to write a ping control frame over the socket!
The disconnect method does what you would expect and closes the socket.
et.disconnect()
Returns if the socket is connected or not.
ocket.isConnected {
do cool stuff.
You can also override the default websocket headers with your own custom ones like so:
request = URLRequest(url: URL(string: "ws://localhost:8080/")!)
est.timeoutInterval = 5
est.setValue("someother protocols", forHTTPHeaderField: "Sec-WebSocket-Protocol")
est.setValue("14", forHTTPHeaderField: "Sec-WebSocket-Version")
est.setValue("Everything is Awesome!", forHTTPHeaderField: "My-Awesome-Header")
socket = WebSocket(request: request)
Your server may use a different HTTP method when connecting to the websocket:
request = URLRequest(url: URL(string: "ws://localhost:8080/")!)
est.httpMethod = "POST"
est.timeoutInterval = 5
socket = WebSocket(request: request)
If you need to specify a protocol, simple add it to the init:
at and superchat are the example protocols here
et = WebSocket(url: URL(string: "ws://localhost:8080/")!, protocols: ["chat","superchat"])
et.delegate = self
et.connect()
et = WebSocket(url: URL(string: "ws://localhost:8080/")!, protocols: ["chat","superchat"])
t this if you want to ignore SSL cert validation, so a self signed SSL certificate can be used.
et.disableSSLCertValidation = true
SSL Pinning is also supported in Starscream.
et = WebSocket(url: URL(string: "ws://localhost:8080/")!, protocols: ["chat","superchat"])
data = ... //load your certificate from disk
et.security = SSLSecurity(certs: [SSLCert(data: data)], usePublicKeys: true)
cket.security = SSLSecurity() //uses the .cer files in your app's bundle
You load either a Data blob of your certificate or you can use a SecKeyRef if you have a public key you want to use. The usePublicKeys bool is whether to use the certificates for validation or the public keys. The public keys will be extracted from the certificates automatically if usePublicKeys is choosen.
To use an SSL encrypted connection, you need to tell Starscream about the cipher suites your server supports.
et = WebSocket(url: URL(string: "wss://localhost:8080/")!, protocols: ["chat","superchat"])
et enabled cipher suites to AES 256 and AES 128
et.enabledSSLCipherSuites = [TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256]
If you don't know which cipher suites are supported by your server, you can try pointing SSL Labs at it and checking the results.
Compression Extensions (RFC 7692) is supported in Starscream. Compression is enabled by default, however compression will only be used if it is supported by the server as well. You may enable or disable compression via the .enableCompression property:
et = WebSocket(url: URL(string: "ws://localhost:8080/")!)
et.enableCompression = false
Compression should be disabled if your application is transmitting already-compressed, random, or other uncompressable data.
A custom queue can be specified when delegate methods are called. By default DispatchQueue.main is used, thus making all delegate methods calls run on the main thread. It is important to note that all WebSocket processing is done on a background thread, only the delegate method calls are changed when modifying the queue. The actual processing is always on a background thread and will not pause your app.
et = WebSocket(url: URL(string: "ws://localhost:8080/")!, protocols: ["chat","superchat"])
eate a custom queue
et.callbackQueue = DispatchQueue(label: "com.vluxe.starscream.myapp")
Check out the SimpleTest project in the examples directory to see how to setup a simple connection to a WebSocket server.
Starscream works with iOS 7/OSX 10.9 or above. It is recommended to use iOS 8/10.10 or above for CocoaPods/framework support. To use Starscream with a project targeting iOS 7, you must include all Swift files directly in your project.
Check out Get Started tab on cocoapods.org.
To use Starscream in your project add the following 'Podfile' to your project
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!
pod 'Starscream', '~> 3.0.2'
Then run:
pod install
Check out the Carthage docs on how to add a install. The Starscream framework is already setup with shared schemes.
You can install Carthage with Homebrew using the following command:
ew update
ew install carthage
To integrate Starscream into your Xcode project using Carthage, specify it in your Cartfile:
ub "daltoniam/Starscream" >= 3.0.2
First see the installation docs for how to install Rogue.
To install Starscream run the command below in the directory you created the rogue file.
e add https://github.com/daltoniam/Starscream
Next open the libs folder and add the Starscream.xcodeproj to your Xcode project. Once that is complete, in your “Build Phases” add the Starscream.framework to your “Link Binary with Libraries” phase. Make sure to add the libs folder to your .gitignore file.
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.
Once you have your Swift package set up, adding Starscream as a dependency is as easy as adding it to the dependencies value of your Package.swift.
ndencies: [
.Package(url: "https://github.com/daltoniam/Starscream.git", majorVersion: 3)
Simply grab the framework (either via git submodule or another package manager).
Add the Starscream.xcodeproj to your Xcode project. Once that is complete, in your “Build Phases” add the Starscream.framework to your “Link Binary with Libraries” phase.
If you are running this in an OSX app or on a physical iOS device you will need to make sure you add the Starscream.framework to be included in your app bundle. To do this, in Xcode, navigate to the target configuration window by clicking on the blue project icon, and selecting the application target under the “Targets” heading in the sidebar. In the tab bar at the top of that window, open the “Build Phases” panel. Expand the “Link Binary with Libraries” group, and add Starscream.framework. Click on the + button at the top left of the panel and select “New Copy Files Phase”. Rename this new phase to “Copy Frameworks”, set the “Destination” to “Frameworks”, and add Starscream.framework respectively.
The advanced delegate acts just like the simpler delegate but provides some additional information on the connection and incoming frames.
et.advancedDelegate = self
In most cases you do not need the extra info and should use the normal delegate.
websocketDidReceiveMessage(socket: WebSocketClient, text: String, response: WebSocket.WSResponse {
print("got some text: \(text)")
print("First frame for this message arrived on \(response.firstFrame)")
websocketDidReceiveData(socket: WebSocketClient, data: Date, response: WebSocket.WSResponse) {
print("got some data it long: \(data.count)")
print("A total of \(response.frameCount) frames were used to send this data")
These methods are called when the HTTP upgrade request is sent and when the response returns.
websocketHttpUpgrade(socket: WebSocketClient, request: CFHTTPMessage) {
print("the http request was sent we can check the raw http if we need to")
wift
websocketHttpUpgrade(socket: WebSocketClient, response: CFHTTPMessage) {
print("the http response has returned.")
SSLCiphers, disableSSLCertValidation, or SSL pinning. All these values set on watchOS will do nothing.SSLCiphers either.Starscream is licensed under the Apache v2 License.