Socket framework for Swift using the Swift Package Manager. Works on macOS and Linux.
- Socket: Generic low level socket framework. Pure Swift.
- Swift Open Source
swift-3.0-RELEASEtoolchain (Minimum REQUIRED for latest release) - Swift Open Source
swift-DEVELOPMENT-SNAPSHOT-2016-11-01-atoolchain (Recommended)
- macOS 10.11.6 (El Capitan) or higher
- Xcode Version 8.0 (8A218a) or higher using one of the above toolchains (Recommended)
- Ubuntu 15.10 (or 14.04 but only tested on 15.10)
- One of the Swift Open Source toolchain listed above
- BlueSSLService can be used to add SSL/TLS support.
To build Socket from the command line:
% cd <path-to-clone>
% swift build
Important Note:
Testing on both macOS and Linux requires a working Dispatch in the toolchain.
THIS ONLY APPLIES TO TESTING.
To run the supplied unit tests for Socket from the command line:
% cd <path-to-clone>
% swift build
% swift test
The first you need to do is import the Socket framework. This is done by the following:
import Socket
BlueSocket provides four different factory methods that are used to create an instance. These are:
create()- This creates a fully configured default socket. A default socket is created withfamily: .inet,type: .stream, andproto: .tcp.create(family family: ProtocolFamily, type: SocketType, proto: SocketProtocol)- This API allows you to create a configuredSocketinstance customized for your needs. You can customize the protocol family, socket type and socket protocol.create(connectedUsing signature: Signature)- This API will allow you create aSocketinstance and have it attempt to connect to a server based on the information you pass in theSocket.Signature.create(fromNativeHandle nativeHandle: Int32, address: Address?)- This API lets you wrap a native file descriptor describing an existing socket in a new instance ofSocket.
To close the socket of an open instance, the following function is provided:
close()- This function will perform the necessary tasks in order to cleanly close an open socket.
To use BlueSocket to listen for an connection on a socket the following API is provided:
listen(on port: Int, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG)The first parameterport, is the port to be used to listen on. The second parameter,maxBacklogSizeallows you to set the size of the queue holding pending connections. The function will determine the appropriate socket configuration based on theportspecified. For convenience on macOS, the constantSocket.SOCKET_MAX_DARWIN_BACKLOGcan be set to use the maximum allowed backlog size. The default value for all platforms isSocket.SOCKET_DEFAULT_MAX_BACKLOG, currently set to 50. For server use, it may be necessary to increase this value.
The following example creates a default Socket instance and then immediately starts listening on port 1337. Note: Exception handling omitted for brevity, see the complete example below for an example of exception handling.
var socket = try Socket.create()
try socket.listen(on: 1337)When a listening socket detects an incoming connection request, control is returned to your program. You can then either accept the connection or continue listening or both if your application is multi-threaded. BlueSocket supports two distinct ways of accepting an incoming connection. They are:
acceptClientConnection()- This function accepts the connection and returns a newSocketinstance based on the newly connected socket. The instance that was listening in unaffected.acceptConnection()- This function accepts the incoming connection, replacing and closing the existing listening socket. The properties that were formerly associated with the listening socket are replaced by the properties that are relevant to the newly connected socket.
In addition to the create(connectedUsing:) factory method described above, BlueSocket supports two additional instance functions for connecting a Socket instance to a server. They are:
connect(to host: String, port: Int32)- This API allows you to connect to a server based on thehostnameandportyou provide.connect(using signature: Signature)- This API allows you specify the connection information by providing aSocket.Signatureinstance containing the information. Refer toSocket.Signaturein Socket.swift for more information.
BlueSocket supports four different ways to read data from a socket. These are (in recommended use order):
read(into data: inout Data)- This function reads all the data available on a socket and returns it in theDataobject that was passed.read(into data: NSMutableData)- This function reads all the data available on a socket and returns it in theNSMutableDataobject that was passed.readString()- This function reads all the data available on a socket and returns it as anString. Anilis returned if no data is available for reading.read(into buffer: UnsafeMutablePointer<CChar>, bufSize: Int)- This function allows you to read data into a buffer of a specified size by providing an unsafe pointer to that buffer and an integer the denotes the size of that buffer. This API (in addition to other types of exceptions) will throw aSocket.SOCKET_ERR_RECV_BUFFER_TOO_SMALLif the buffer provided is too small. You will need to call again with proper buffer size (seeError.bufferSizeNeededin Socket.swift for more information).- Note: All of the read APIs above except
readString()can return zero (0). This can indicate that the remote connection was closed or it could indicate that the socket would block (assuming you've turned off blocking). To differentiate between the two, the propertyremoteConnectionClosedcan be checked. Iftrue, the socket remote partner has closed the connection and thisSocketinstance should be closed.
In addition to reading from a socket, BlueSocket also supplies four methods for writing data to a socket. These are (in recommended use order):
write(from data: Data)- This function writes the data contained within theDataobject to the socket.write(from data: NSData)- This function writes the data contained within theNSDataobject to the socket.write(from string: String)- This function writes the data contained in theStringprovided to the socket.write(from buffer: UnsafePointer<Void>, bufSize: Int)- This function writes the data contained within the buffer of the specified size by providing an unsafe pointer to that buffer and an integer the denotes the size of that buffer.
The read and write APIs above that use either NSData or NSMutableData will probably be deprecated in the not so distant future.
hostnameAndPort(from address: Address)- This class function provides a means to extract the hostname and port from a givenSocket.Address. On successful completion, a tuple containing thehostnameandportare returned.checkStatus(for sockets: [Socket])- This class function allows you to check status of an array ofSocketinstances. Upon completion, a tuple containing twoSocketarrays is returned. The first array contains theSocketinstances are that have data available to be read and the second array containsSocketinstances that can be written to. This API does not block. It will check the status of eachSocketinstance and then return the results.wait(for sockets: [Socket], timeout: UInt, waitForever: Bool = false)- This class function allows for monitoring an array ofSocketinstances, waiting for either a timeout to occur or data to be readable at one of the monitoredSocketinstances. If a timeout of zero (0) is specified, this API will check each socket and return immediately. Otherwise, it will wait until either the timeout expires or data is readable from one or more of the monitoredSocketinstances. If a timeout occurs, this API will returnnil. If data is available on one or more of the monitoredSocketinstances, those instances will be returned in an array. If thewaitForeverflag is set to true, the function will wait indefinitely for data to become available regardless of the timeout value specified.isReadableOrWritable()- This instance function allows to determine whether aSocketinstance is readable and/or writable. A tuple is returned containing twoBoolvalues. The first, if true, indicates theSocketinstance has data to read, the second, if true, indicates that theSocketinstance can be written to.setBlocking(shouldBlock: Bool)- This instance function allows you control whether or not thisSocketinstance should be placed in blocking mode or not. Note: AllSocketinstances are, by default, created in blocking mode.
The following example shows how to create a relatively simple multi-threaded echo server using the new GCD based Dispatch API. The Dispatch API was incorporated into the toolchain using the following sequence of commands where <Path to> is the path where you've installed the required toolchain. In this example, the swift-DEVELOPMENT-SNAPSHOT-2016-08-18-a-ubuntu15.10 toolchain is being used. Important note: clang-3.8 or clang-3.9 (recommended) is REQUIRED to successfully build libdispatch. This is only required if using the 8/18 toolchain, Dispatch is built-in to the subsequently released toolchains.
$ git clone --recursive git@github.com:apple/swift-corelibs-libdispatch.git
$ cd swift-corelibs-libdispatch
$ export CC=/usr/bin/clang-3.9
$ export CXX=/usr/bin/clang-3.9
$ sh ./autogen.sh
$ ./configure --with-swift-toolchain=<Path to>/swift-DEVELOPMENT-SNAPSHOT-2016-08-18-a-ubuntu15.10/usr --prefix=<Path to>/swift-DEVELOPMENT-SNAPSHOT-2016-08-18-a-ubuntu15.10/usr
$ make
$ make install
What follows is the code for a simple echo server that once running, can be accessed via telnet 127.0.0.1 1337.
import Foundation
import Socket
import Dispatch
class EchoServer {
static let quitCommand: String = "QUIT"
static let shutdownCommand: String = "SHUTDOWN"
static let bufferSize = 4096
let port: Int
var listenSocket: Socket? = nil
var continueRunning = true
var connectedSockets = [Int32: Socket]()
let socketLockQueue = DispatchQueue(label: "com.ibm.serverSwift.socketLockQueue")
init(port: Int) {
self.port = port
}
deinit {
// Close all open sockets...
for socket in connectedSockets.values {
socket.close()
}
self.listenSocket?.close()
}
func run() {
let queue = DispatchQueue.global(qos: .userInteractive)
queue.async { [unowned self] in
do {
// Create an IPV6 socket...
try self.listenSocket = Socket.create(family: .inet6)
guard let socket = self.listenSocket else {
print("Unable to unwrap socket...")
return
}
try socket.listen(on: self.port)
print("Listening on port: \(socket.listeningPort)")
repeat {
let newSocket = try socket.acceptClientConnection()
print("Accepted connection from: \(newSocket.remoteHostname) on port \(newSocket.remotePort)")
print("Socket Signature: \(newSocket.signature?.description)")
self.addNewConnection(socket: newSocket)
} while self.continueRunning
}
catch let error {
guard let socketError = error as? Socket.Error else {
print("Unexpected error...")
return
}
if self.continueRunning {
print("Error reported:\n \(socketError.description)")
}
}
}
dispatchMain()
}
func addNewConnection(socket: Socket) {
// Add the new socket to the list of connected sockets...
socketLockQueue.sync { [unowned self, socket] in
self.connectedSockets[socket.socketfd] = socket
}
// Get the global concurrent queue...
let queue = DispatchQueue.global(qos: .default)
// Create the run loop work item and dispatch to the default priority global queue...
queue.async { [unowned self, socket] in
var shouldKeepRunning = true
var readData = Data(capacity: EchoServer.bufferSize)
do {
// Write the welcome string...
try socket.write(from: "Hello, type 'QUIT' to end session\nor 'SHUTDOWN' to stop server.\n")
repeat {
let bytesRead = try socket.read(into: &readData)
if bytesRead > 0 {
guard let response = String(data: readData, encoding: .utf8) else {
print("Error decoding response...")
readData.count = 0
break
}
if response.hasPrefix(EchoServer.shutdownCommand) {
print("Shutdown requested by connection at \(socket.remoteHostname):\(socket.remotePort)")
// Shut things down...
self.shutdownServer()
return
}
print("Server received from connection at \(socket.remoteHostname):\(socket.remotePort): \(response) ")
let reply = "Server response: \n\(response)\n"
try socket.write(from: reply)
if (response.uppercased().hasPrefix(EchoServer.quitCommand) || response.uppercased().hasPrefix(EchoServer.shutdownCommand)) &&
(!response.hasPrefix(EchoServer.quitCommand) && !response.hasPrefix(EchoServer.shutdownCommand)) {
try socket.write(from: "If you want to QUIT or SHUTDOWN, please type the name in all caps. 😃\n")
}
if response.hasPrefix(EchoServer.quitCommand) || response.hasSuffix(EchoServer.quitCommand) {
shouldKeepRunning = false
}
}
if bytesRead == 0 {
shouldKeepRunning = false
break
}
readData.count = 0
} while shouldKeepRunning
print("Socket: \(socket.remoteHostname):\(socket.remotePort) closed...")
socket.close()
self.socketLockQueue.sync { [unowned self, socket] in
self.connectedSockets[socket.socketfd] = nil
}
}
catch let error {
guard let socketError = error as? Socket.Error else {
print("Unexpected error by connection at \(socket.remoteHostname):\(socket.remotePort)...")
return
}
if self.continueRunning {
print("Error reported by connection at \(socket.remoteHostname):\(socket.remotePort):\n \(socketError.description)")
}
}
}
}
func shutdownServer() {
print("\nShutdown in progress...")
continueRunning = false
// Close all open sockets...
for socket in connectedSockets.values {
socket.close()
}
listenSocket?.close()
DispatchQueue.main.sync {
exit(0)
}
}
}
let port = 1337
let server = EchoServer(port: port)
print("Swift Echo Server Sample")
print("Connect with a command line window by entering 'telnet 127.0.0.1 \(port)'")
server.run()This server can be built by specifying the following Package.swift file.
import PackageDescription
let package = Package(
name: "EchoServer",
dependencies: [
.Package(url: "https://github.com/IBM-Swift/BlueSocket.git", majorVersion: 0, minor: 10),
],
exclude: ["EchoServer.xcodeproj", "README.md", "Sources/Info.plist"]The following command sequence will build and run the echo server on Linux. If running on macOS or with any toolchain NEWER than the 8/18 toolchain, you can omit the -Xcc -fblocks switch as it's no longer needed.
$ swift build -Xcc -fblocks
$ .build/debug/EchoServer
Swift Echo Server Sample
Connect with a command line window by entering 'telnet 127.0.0.1 1337'
Listening on port: 1337