SwiftNIO tutorial – The echo server

Intoducing SwiftNIO

Should you used a excessive degree net framework, equivalent to Vapor, prior to now, you would possibly had some interplay with occasion loops or guarantees. Nicely, these basic constructing blocks are a part of a low degree community framework, referred to as SwiftNIO, which I will speak about on this tutorial.

Don’t be concerned if you have not heard about occasion loops or non-blocking IO simply but, I will attempt to clarify every thing on this information, so hopefully you may perceive every thing even in case you are a whole newbie to this matter. Let’s begin with some fundamentals about networks and computer systems.

Let’s speak about TCP/IP

It began on January 1st, 1983. The web was born (as some say) and other people began to formally use the web protocol suite (TCP/IP) to speak between units. If you do not know a lot about TCP/IP and you’re curious concerning the underlying components, you’ll be able to learn a number of different articles, however in a nutshell this mannequin permits us to speak with distant computer systems simply. 💬

As an instance that you’ve two machines, linked by the community. How do they impart with one another? Nicely, identical to once you ship a daily letter, first you need to specify the handle of the recipient. So as to ship a message to a different pc, you need to know its digital handle too. This digital handle is known as IP handle and it seems to be like this: 127.0.0.1.

So you have obtained the handle, however generally this isn’t sufficient, as a result of a constructing can have a number of flats and you need to specify the precise letterbox with a purpose to attain the precise particular person. This could occur with computer systems too, the letterbox is known as port quantity and the total handle of the goal will be created by combining the IP handle and the port quantity (we name this full handle as a community socket handle or just socket, e.g. 127.0.0.1:80). 💌

After you have specified the precise handle, you may want somebody to truly ship the letter containing your message. The postal supply service can switch your letter, there are two methods to ship it over to the recipient. The primary resolution is to easily ship it with out figuring out a lot concerning the supply standing, the digital model of this method is known as Person Datagram Protocol (UDP).

The opposite (extra dependable) methodology is to get a receipt concerning the supply, this fashion you’ll be able to be sure that the letter really arrived and the recipient obtained it. Though, the postman can open your letter and alter your message, however it’ll be nonetheless delivered and you will get a notification about this. If you talk via the community, this methodology is known as Transmission Management Protocol (TCP).

Okay, that is greater than sufficient community idea, I do know it is a excessive degree abstraction and never fully correct, however hopefully you may get the essential concept. Now let’s speak about what occurs contained in the machine and the way we will place an precise digital letterbox in entrance of the imaginary home. 📪

The fundamental constructing blocks of SwiftNIO

What do you do if you happen to anticipate a letter? Aside from the joy, most individuals continuously examine their mailboxes to see if it is already there or not. They’re listening for the noises of the postman, identical to pc packages pay attention on a given port to examine if some information arrived or not. 🤓

What occurs if a letter arrives? To start with you need to go and get it out from the mailbox. So as to get it you need to stroll via the hallway or down the steps or you’ll be able to ask another person to ship the letter for you. Anyway, ought to get the letter someway first, then based mostly on the envelope you’ll be able to carry out an motion. If it seems to be like a spam, you may throw it away, but when it is an necessary letter you may almost certainly open it, learn the contents and ship again a solution as quickly as doable. Let’s stick to this analogy, and let me clarify this once more, however this time utilizing SwiftNIO phrases.

Channel

A Channel connects the underlying community socket with the appliance’s code. The channel’s accountability is to deal with inbound and outbound occasions, occurring via the socket (or file descriptor). In different phrases, it is the channel that connects the mailbox with you, it is best to think about it because the hallway to the mailbox, actually the messages are going journey to you through a channel. 📨

ChannelPipeline

The ChannelPipeline describes a set of actions about the way to deal with the letters. One doable model is to decide based mostly on the envelope, you may throw it away if it seems to be like a spam, or open it if it seems to be like a proper letter, it is also an motion if you happen to reply to the letter. Actions are referred to as as channel handlers in SwiftNIO. Briefly: a pipeline is a predefined sequence of handlers.

ChannelHandler

The ChannelHandler is the motion which you could carry out once you open the letter. The channel handler has an enter and an output sort, which you should utilize to learn the message utilizing the enter and reply to it utilizing the output. Okay, simply two extra necessary phrases, bear with me for a second, I will present you some actual examples afterwards. 🐻

EventLoop

The EventLoop works identical to a run loop or a dispatch queue. What does this imply?

The occasion loop is an object that waits for occasions (normally I/O associated occasions, equivalent to “information acquired”) to occur after which fires some sort of callback once they do.

The fashionable CPUs have a restricted variety of cores, apps will almost certainly affiliate one thread (of execution) per core. Switching between thread contexts can be inefficient. What occurs when an occasion has to attend for one thing and a thread turns into out there for different duties? In SwiftNIO the occasion loop will obtain the incoming message, course of it, and if it has to attend for one thing (like a file or database learn) it will execute another duties within the meantime. When the IO operation finishes it will change again to the duty and it will name again to your code when it is time. Or one thing like this, however the principle takeaway right here is that your channel handler is all the time going to be related to precisely one occasion loop, this implies actions will probably be executed utilizing the identical context.

EventLoopGroup

The EventLoopGroup manages threads and occasion loops. The MultiThreadedEventLoopGroup goes to steadiness out consumer over the out there threads (occasion loops) this fashion the appliance goes to be environment friendly and each thread will deal with nearly the identical quantity of shoppers.

Different parts

There are another SwiftNIO parts, we may speak extra about Futures, Guarantees and the ByteBuffer sort, however I suppose this was greater than sufficient idea for now, so I am not going to dive into these sort of objects, however spare them for upcoming articles. 😇

Constructing an echo server utilizing SwiftNIO

You can begin by creating a brand new executable Swift bundle, utilizing the Swift Bundle Supervisor. Subsequent you need to add SwiftNIO as a bundle dependency contained in the Bundle.swift file.

import PackageDescription

let bundle = Bundle(
    identify: "echo-server",
    platforms: [
       .macOS(.v10_15),
    ],
    dependencies: [
        .package(
            url: "https://github.com/apple/swift-nio",
            from: "2.0.0"
        ),
    ],
    targets: [
        .executableTarget(
            name: "Server",
            dependencies: [
                .product(
                    name: "NIO",
                    package: "swift-nio"
                )
            ]
        ),
    ]
)

The subsequent step is to change the principle mission file, we will simply create the SwiftNIO based mostly TCP server by utilizing the ServerBootstrap object. First we now have to instantiate a MultiThreadedEventLoopGroup with quite a few threads, utilizing the CPU cores within the system.

Then we configure the server by including some channel choices. You do not have to know a lot about these simply but, the fascinating half is contained in the childChannelInitializer block. We create the precise channel pipeline there. Our pipeline will include two handlers, the primary one is the built-in BackPressureHandler, the second goes to be our customized made EchoHandler object.

If you’re within the out there ChannelOptions, you’ll be able to check out the NIO supply code, it additionally comprises some excellent docs about these items. The ultimate step is to bind the server bootstrap object to a given host and port, and look forward to incoming connections. 🧐

import NIO

@primary
public struct Server {
    
    public static func primary() throws {
        let eventLoopGroup = MultiThreadedEventLoopGroup(
            numberOfThreads: System.coreCount
        )

        defer {
            strive! eventLoopGroup.syncShutdownGracefully()
        }

        let serverBootstrap = ServerBootstrap(
            group: eventLoopGroup
        )
        .serverChannelOption(
            ChannelOptions.backlog,
            worth: 256
        )
        .serverChannelOption(
            ChannelOptions.socketOption(.so_reuseaddr),
            worth: 1
        )
        .childChannelInitializer { channel in
            channel.pipeline.addHandlers([
                BackPressureHandler(),
                EchoHandler(),
            ])
        }
        .childChannelOption(
            ChannelOptions.socketOption(.so_reuseaddr),
            worth: 1
        )
        .childChannelOption(
            ChannelOptions.maxMessagesPerRead,
            worth: 16
        )
        .childChannelOption(
            ChannelOptions.recvAllocator,
            worth: AdaptiveRecvByteBufferAllocator()
        )

        let defaultHost = "127.0.0.1" 
        let defaultPort = 8888

        let channel = strive serverBootstrap.bind(
            host: defaultHost,
            port: defaultPort
        )
        .wait()

        print("Server began and listening on (channel.localAddress!)")
        strive channel.closeFuture.wait()
        print("Server closed")
    }
}

As I discussed this, with a purpose to deal with an occasion occurring on the channel we now have can create a customized ChannelInboundHandler object. Contained in the channelRead perform it’s doable to unwrap the inbound information right into a ByteBuffer object and write the enter message onto the output as a wrapped NIOAny object.

Problem: write a server that may print colourful messages. Trace: constructing a textual content modifying server.

import NIO

remaining class EchoHandler: ChannelInboundHandler {

    typealias InboundIn = ByteBuffer
    typealias OutboundOut = ByteBuffer

    func channelRead(
        context: ChannelHandlerContext,
        information: NIOAny
    ) {
        let enter = self.unwrapInboundIn(information)
        guard
            let message = enter.getString(at: 0, size: enter.readableBytes)
        else {
            return
        }
        
        var buff = context.channel.allocator.buffer(capability: message.rely)
        buff.writeString(message)
        context.write(wrapOutboundOut(buff), promise: nil)
    }


    func channelReadComplete(
        context: ChannelHandlerContext
    ) {
        context.flush()
    }

    func errorCaught(
        context: ChannelHandlerContext,
        error: Error
    ) {
        print(error)

        context.shut(promise: nil)
    }
}

Should you run the app and connect with it utilizing the telnet 127.0.0.1 8888 command you’ll be able to enter some textual content and the server will echo it again to you. Remember that it is a quite simple TCP server, with out HTTP, however it’s doable to write down express-like HTTP servers, JSON API servers, even a recreation backend and plenty of different cool and loopy performant stuff utilizing SwiftNIO. I hope this tutorial will show you how to to get began with SwiftNIO, I am additionally studying lots concerning the framework recently, so please forgive me (and even appropriate me) if I missed / tousled one thing. 😅

So once more: SwiftNIO a (low-level) non-blocking event-driven community software framework for top efficiency protocol servers & shoppers. It is like Netty, however written for Swift.