BlueSocket
Socket framework for Swift using the Swift Package Manager. Works on iOS, macOS, and Linux.
Prerequisites
Swift
- Swift Open Source
swift-5.1-RELEASEtoolchain (Minimum REQUIRED for latest release) - Swift Open Source
swift-5.4-RELEASEtoolchain (Recommended) - Swift toolchain included in Xcode Version 12.5 (12E262) or higher.
macOS
- macOS 10.11.6 (El Capitan) or higher.
- Xcode Version 11 or higher using one of the above toolchains.
- Xcode Version 12 or higher using the included toolchain (Recommended).
iOS
- iOS 10.0 or higher
- Xcode Version 11 or higher using one of the above toolchains.
- Xcode Version 12 or higher using the included toolchain (Recommended).
Note:
If creating a UDP server on iOS, you may need to follow a few steps:
- Request multicast entitlement from Apple
- Add the Multicast Network capability to your App identifier
- For more details, see discussion in Issue 194
Linux
- Ubuntu 16.04 or 18.04
- One of the Swift Open Source toolchains listed above.
Other Platforms
- BlueSocket is NOT supported on watchOS since POSIX/BSD/Darwin sockets are not supported on the actual device although they are supported in the simulator.
- BlueSocket should work on tvOS but has NOT been tested.
Add-ins
- BlueSSLService can be used to add SSL/TLS support.
- If using this package, please note that the libssl-dev package is required to be installed when building on Linux.
Build
To build Socket from the command line:
% cd <path-to-clone>
% swift build
Testing
To run the supplied unit tests for Socket from the command line:
% cd <path-to-clone>
% swift build
% swift test
Using BlueSocket
Including in your project
Swift Package Manager
To include BlueSocket into a Swift Package Manager package, add it to the dependencies attribute defined in your Package.swift file. You can select the version using the majorVersion and minor parameters. For example:
dependencies: [
.Package(url: "https://github.com/Kitura/BlueSocket.git", majorVersion: <majorVersion>, minor: <minor>)
]
Carthage
To include BlueSocket in a project using Carthage, add a line to your Cartfile with the GitHub organization and project names and version. For example:
github "Kitura/BlueSocket" ~> <majorVersion>.<minor>
CocoaPods
To include BlueSocket in a project using CocoaPods, you just add BlueSocket to your Podfile, for example:
platform :ios, '10.0'
target 'MyApp' do
use_frameworks!
pod 'BlueSocket'
end
Before starting
The first thing you need to do is import the Socket framework. This is done by the following:
import Socket
Family, Type and Protocol Support
BlueSocket supports the following families, types and protocols:
- Families:
- IPV4:
Socket.ProtocolFamily.inet - IPV6:
Socket.ProtocolFamily.inet6 - UNIX:
Socket.ProtocolFamily.unix
- IPV4:
- Types:
- Stream:
Socket.SocketType.stream - Datagram:
Socket.SocketType.datagram
- Stream:
- Protocols:
- TCP:
Socket.SocketProtocol.tcp - UDP:
Socket.SocketProtocol.udp - UNIX:
Socket.SocketProtocol.unix
- TCP:
Creating a 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.
Setting the read buffer size.
BlueSocket allows you to set the size of the read buffer that it will use. Then, depending on the needs of the application, you can change it to a higher or lower value. The default is set to Socket.SOCKET_DEFAULT_READ_BUFFER_SIZE which has a value of 4096. The minimum read buffer size is Socket.SOCKET_MINIMUM_READ_BUFFER_SIZE which is set to 1024. Below illustrates how to change the read buffer size (exception handling omitted for brevity):
let mySocket = try Socket.create()
mySocket.readBufferSize = 32768
The example above sets the default read buffer size to 32768. This setting should be done prior to using the Socket instance for the first time.
Closing a socket.
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.
Listen on a socket (TCP/UNIX).
To use BlueSocket to listen for a connection on a socket the following API is provided:
listen(on port: Int, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG, allowPortReuse: Bool = true, node: String? = nil)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. To allow the reuse of the listening port, setallowPortReusetotrue. If set tofalse, a error will occur if you attempt to listen on a port already in use. TheDEFAULTbehavior is toallowport reuse. The last parameter,node, can be used to listen on a specific address. The value passed is an optional String containing the numerical network address (for IPv4, numbers and dots notation, for iPv6, hexidecimal strting). TheDEFAULTbehavior is to search for an appropriate interface. Ifnodeis improperly formatted a SOCKET_ERR_GETADDRINFO_FAILED error will be returned. Ifnodeis properly formatted but the address specified is not available, a SOCKET_ERR_BIND_FAILED will be returned.listen(on path: String, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG)This API can only be used with the.unixprotocol family. The first parameterpath, is the path 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.
Example:
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)
Accepting a connection from a listening socket (TCP/UNIX).
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(invokeDelegate: Bool = true)- This function accepts the connection and returns a newSocketinstance based on the newly connected socket. The instance that was listening in unaffected. IfinvokeDelegateisfalseand theSockethas anSSLServicedelegate attached, you MUST call theinvokeDelegateOnAcceptmethod using theSocketinstance that is returned by this function.invokeDelegateOnAccept(for newSocket: Socket)- If theSocketinstance has aSSLServicedelegate, this will invoke the delegates accept function to perform SSL negotiation. It should be called with theSocketinstance returned byacceptClientConnection. This function will throw an exception if called with the wrongSocketinstance, called multiple times, or if theSocketinstance does NOT have aSSLServicedelegate.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.
Connecting a socket to a server (TCP/UNIX).
In addition to the create(connectedUsing:) factory method described above, BlueSocket supports three additional instance functions for connecting a Socket instance to a server. They are:
connect(to host: String, port: Int32, timeout: UInt = 0)- This API allows you to connect to a server based on thehostnameandportyou provide. Note: anexceptionwill be thrown by this function if the value ofportis not in the range1-65535. Optionally, you can settimeoutto the number of milliseconds to wait for the connect. Note: If the socket is in blocking mode it will be changed to non-blocking mode temporarily if atimeoutgreater than zero (0) is provided. The returned socket will be set back to its original setting (blocking or non-blocking). If the socket is set to non-blocking and no timeout value is provided, an exception will be thrown. Alternatively, you can set the socket to non-blocking after successfully connecting.connect(to path: String)- This API can only be used with the.unixprotocol family. It allows you to connect to a server based on thepathyou 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.
Reading data from a socket (TCP/UNIX).
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, truncate: Bool = false)- 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, unlesstruncate = truein which case the socket will act as if onlybufSizebytes were read (unretrieved bytes will be returned in the next call). Iftruncate = false, 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.
Writing data to a Socket (TCP/UNIX).
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: UnsafeRawPointer, 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 that denotes the size of that buffer.
Listening for a datagram message (UDP).
BlueSocket supports three different ways to listen for incoming datagrams. These are (in recommended use order):
listen(forMessage data: inout Data, on port: Int, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG)- This function listens for an incoming datagram, reads it and returns it in the passedDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated.listen(forMessage data: NSMutableData, on port: Int, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG)- This function listens for an incoming datagram, reads it and returns it in the passedNSMutableDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated.listen(forMessage buffer: UnsafeMutablePointer<CChar>, bufSize: Int, on port: Int, maxBacklogSize: Int = Socket.SOCKET_DEFAULT_MAX_BACKLOG)- This function listens for an incoming datagram, reads it and returns it in the passedDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated.- Note 1: These functions will determine the appropriate socket configuration based on the
portspecified. Setting the value ofportto zero (0) will cause the function to determine a suitable free port. - Note 2: The 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.
Reading a datagram (UDP).
BlueSocket supports three different ways to read incoming datagrams. These are (in recommended use order):
readDatagram(into data: inout Data)- This function reads an incoming datagram and returns it in the passedDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated.readDatagram(into data: NSMutableData)- This function reads an incoming datagram and returns it in the passedNSMutableDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated.readDatagram(into buffer: UnsafeMutablePointer<CChar>, bufSize: Int)- This function reads an incoming datagram and returns it in the passedDataobject. It returns a tuple containing the number of bytes read and theAddressof where the data originated. If the amount of data read is more thanbufSizeonlybufSizewill be returned. The remainder of the data read will be discarded.
Writing a datagram (UDP).
BlueSocket also supplies four methods for writing datagrams to a socket. These are (in recommended use order):
write(from data: Data, to address: Address)- This function writes the datagram contained within theDataobject to the socket.write(from data: NSData, to address: Address)- This function writes the datagram contained within theNSDataobject to the socket.write(from string: String, to address: Address)- This function writes the datagram contained in theStringprovided to the socket.write(from buffer: UnsafeRawPointer, bufSize: Int, to address: Address)- This function writes the data contained within the buffer of the specified size by providing an unsafe pointer to that buffer and an integer that denotes the size of that buffer.- Note: In all four of the APIs above, the
addressparameter represents the address for the destination you are sending the datagram to.
IMPORTANT NOTE about NSData and NSMutableData
The read and write APIs above that use either NSData or NSMutableData will probably be deprecated in the not so distant future.
Miscellaneous Utility Functions
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.createAddress(host: String, port: Int32)- This class function allows for the creation ofAddressenum given ahostandport. On success, this function returns anAddressornilif thehostspecified doesn't exist.isReadableOrWritable(waitForever: Bool = false, timeout: UInt = 0)- 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.waitForeverif true, causes this routine to wait until theSocketis either readable or writable or an error occurs. If false, thetimeoutparameter specifies how long to wait. If a value of zero(0)is specified for the timeout value, this function will check the current status and immediately return. This function returns a tuple containing two booleans, the firstreadableand the second,writable. They are set to true if theSocketis either readable or writable repsectively. If neither is set to true, a timeout has occurred. Note: If you're attempting to write to a newly connected Socket, you should ensure that it's writable before attempting the operation.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.setReadTimeout(value: UInt = 0)- This instance function allows you to set a timeout for read operations.valueis aUIntthe specifies the time for the read operation to wait before returning. In the event of a timeout, the read operation will return0bytes read anderrnowill be set toEAGAIN.setWriteTimeout(value: UInt = 0)- This instance function allows you to set a timeout for write operations.valueis aUIntthe specifies the time for the write operation to wait before returning. In the event of a timeout, the write operation will return0bytes written anderrnowill be set toEAGAINfor TCP and UNIX sockets, for UDP, the write operation will succeed regardless of the timeout value.udpBroadcast(enable: Bool)- This instance function is used to enable broadcast mode on a UDP socket. Passtrueto enable broadcast,falseto disable. This function will throw an exception if theSocketinstance is not a UDP socket.
Complete Example
The following example shows how to create a relatively simple multi-threaded echo server using the new GCD based Dispatch API. What follows is code for a simple echo server that once running, can be accessed via telnet ::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 continueRunningValue = true
var connectedSockets = [Int32: Socket]()
let socketLockQueue = DispatchQueue(label: "com.kitura.serverSwift.socketLockQueue")
var continueRunning: Bool {
set(newValue) {
socketLockQueue.sync {
self.continueRunningValue = newValue
}
}
get {
return socketLockQueue.sync {
self.continueRunningValue
}
}
}
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: \(String(describing: 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...")
self.continueRunning = false
// Close all open sockets...
for socket in connectedSockets.values {
self.socketLockQueue.sync { [unowned self, socket] in
self.connectedSockets[socket.socketfd] = nil
socket.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 ::1 \(port)'")
server.run()
This server can be built by specifying the following Package.swift file using Swift 4.
import PackageDescription
let package = Package(
name: "EchoServer",
dependencies: [
.package(url: "https://github.com/Kitura/BlueSocket.git", from:"1.0.8"),
],
targets: [
.target(
name: "EchoServer",
dependencies: [
"Socket"
]),
]
)
Or if you are still using Swift 3, by specifying the following Package.swift file.
import PackageDescription
let package = Package(
name: "EchoServer",
dependencies: [
.Package(url: "https://github.com/Kitura/BlueSocket.git", majorVersion: 1, minor: 0),
],
exclude: ["EchoServer.xcodeproj"]
)
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 ::1 1337'
Listening on port: 1337
Community
We love to talk server-side Swift and Kitura. Join our Slack to meet the team!
License
This library is licensed under Apache 2.0. Full license text is available in LICENSE.
2 Feb 7, 2022
140 Mar 9, 2022
12.3k Jan 8, 2023
574 Dec 7, 2022
89 Dec 29, 2022
0 Nov 27, 2021
0 Nov 3, 2021
1.9k Dec 22, 2022
540 Dec 15, 2022
0 Dec 26, 2021
2k Dec 5, 2022
258 Oct 6, 2022
19 Sep 8, 2022
2.3k Jan 8, 2023
3.7k Dec 28, 2022
4 Oct 25, 2021
251 Jan 8, 2023
5 Nov 4, 2022
407 Nov 19, 2022