Swift on Server Tour 1: Your First Server App and Its Story

In this chapter, we will learn how to set up the development environment for Swift on Server and create our first server-side Hello, World app. Additionally, we’ll briefly discuss some technical details behind accessing the server app.

Setting up the Swift on Server Development Environment

Thanks to Swift’s open-source nature, Swift can be developed on Linux as well. With the efforts of the Swift Server Workgroup, VSCode has become a competent Swift editor. Therefore, to ensure readability for different types of users, this series of articles will use VSCode as the editor.

Installing Swift

Apple’s Download Swift provides installation guides for different platforms. Unfortunately, Swift for Linux is not available in the official repositories of major distributions. Hence, Linux users will need to explore alternative installation methods.

Configuring VSCode

Simply install the Swift Extension for Visual Studio Code plugin.

Creating Hello World

I created a folder named “1” to store the code for this chapter. You can also create it using the following command:

mkdir 1

As a Swift project, the first thing we need to do is create a Package.swift file to describe the project:

// swift-tools-version:5.8
import PackageDescription
let package = Package(
    name: "HelloWorld",
    platforms: [
       .macOS(.v12)
    ],
    dependencies: [
        .package(url: "https://github.com/vapor/vapor.git", from: "4.77.0"),
    ],
    targets: [
        .executableTarget(
            name: "App",
            dependencies: [
                .product(name: "Vapor", package: "vapor")
            ]
        ),
    ]
)

Next, create the 1/Sources/App/main.swift file:

import Vapor
let app = Application()
app.http.server.configuration.port = 8080
defer { app.shutdown() }
app.get { req async in
    "It works!"
}
try app.run()

To run the code, use swift run in the root directory of the "1" folder, or click the "Run & Debug" option in VSCode.

Usually, when you save the Package.swift file, the Swift extension for VSCode will automatically generate a .vscode/launch.json file in the project's root directory, enabling the Run & Debug functionality.

After compilation, you will see a message indicating that the server is running:

[Vapor] Server starting on http://127.0.0.1:8080

Access http://127.0.0.1:8080 in your browser, and you will see the familiar “It works!” message.

Congratulations, your first server app is up and running!

How Does the Browser Access the Server App?

To understand this question, let’s start with the URL the browser accesses: http://127.0.0.1:8080. This URL can be broken down into three parts:

• http: the desired protocol
• 127.0.0.1: the IP address to access
• 8080: the port on the machine corresponding to the IP address to access

When you press enter, the browser uses the HTTP protocol to create the following request:

GET / HTTP/1.1
Host: 127.0.0.1:8080

This request is then sent to the machine represented by the IP address 127.0.0.1, which is the loopback address for the local machine, and is delivered to the server app waiting on port 8080.

127.0.0.1 is a special reserved address that represents the local machine. When this address is used, it actually points to the machine that made the request.

Now let’s review what the server app’s code does:

// Listen on port 8080 of the local machine
app.http.server.configuration.port = 8080
// If a request arrives with a GET method and path "/"
app.get { req async in
    "It works!"
}

In reality, our server app sends back a response like this:

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
content-length: 9

It works!

When the browser receives this response, it first learns from the 200 status code that the request was successful. The content-type section indicates that the returned data is plain text encoded in UTF-8, and the content-length indicates that the length of the content is 9.

Based on this information, the browser decides to display the text “It works!” on the page.

This back-and-forth data exchange is the most basic functionality of a server app. Behind it, the TCP/IP network protocol stack supports the communication. TCP/IP is a sophisticated and complex protocol, and HTTP, as shown above, is just the topmost application layer in the TCP/IP four-layer model.

Building a simple server app doesn’t require in-depth knowledge of TCP/IP. However, as the business grows and faces more complex problems, understanding TCP/IP can help us solve many issues. However, this topic is beyond the scope of this article series. I encourage readers to explore it according to their future business needs.

The code of this chapter can be found on GitHub at https://github.com/kevinzhow/swift-on-server-tour.

Preview of the Next Chapter

In the next chapter, we will start using Vapor to connect to a database, perform CRUD operations, and explore how these operations are implemented behind the scenes.