DEV Community: Szabolcs Toth

Hummingbird in the cloud

Szabolcs Toth — Tue, 27 Jun 2023 14:31:09 +0000

Deploying your Server side Swift application using ARM-based server with Ubuntu in Oracle Cloud

The point, when you want to access your API server not only from localhost, comes very fast. When your application is in development phase, it is very difficult to commit yourself to any paid services, that's why I will show a way how to host your API server for free.

We will deploy our previously created parkAPI on Oracle Cloud Infrastructure (OCI). It offers you an "Always Free" Tier, you can find many tutorials on the web, how to register and start with it.

Although for the first sight it looks complicated, stay with me, you will see it is easy.

Step 1 - Create an ARM-based virtual machine with Ubuntu

Before creating the VM we need to configure the network.

Step 1.1 - Create a compartment

To easily separate the different workloads and setup user access properly, it is recommended to create a separate compartment.

Go to "Identity & Security", then from "Identity", choose "Compartments".

"Create Compartment" and fill "Name" and "Description".

Step 1.2 - Create Virtual Cloud Network (VCN)

Go to "Networking", then "Virtual cloud networks"

Set "Compartment" to "parkAPI"

"Create VCN" and fill "Name" and "PIv4 CIDR Blocks"

Step 1.3 - Create Subnets

Choose "Subnets" then "Create Subnet"

Fill "Name", "Create in Compartment", "IPv4 CIDR Block", choose "Public Subnet"

Add "Default Security List for VCN for parkAPI"

Step 1.4 - Create Internet Gateway (IG)

Choose "Internet Gateways", then "Create Internet Gateway"

Fill "Name" and "Create in Compartment"

Step 1.5 - Create Route rules

Choose "Route Tables" and click on "Default Route Table for VCN for parkAPI"

Click "Add Route Rules"

Set Internet Gateway

Step 1.6 - Create VM server

"Compute" and "Instances"

Set "Compartment" to "parkAPI" then "Create Instance"

Fill "Name", change "Image" to "Canonical Ubuntu 22.04 Minimal aarch64" and the "Shape" will automatically change to Ampere.

Assign the newly created VCN at "Networking" section

At "Add SSH keys" you either "Generate a key pair for me" or "Paste public keys", but you must have to set SSH key for administration purposes.

"Create"

Step 1.7 - Test our newly created server

Step 1.7.1 - Enable `ping`

By default OCI doesn't allow ping traffic, you need to allow it.

Go to "Security Lists" then click on "Default Security List for VCN for parkAPI"

Click on "Add Ingress Rules"
Fill "Source CIDR| "IP Protocol" and "Type"

Go to "Instances" and set "Compartment" to "parkAPI" and you will see your public IP

Now you can try:

$ ping 144.24.166.181 -c 5

Step 1.7.2 - Use `ssh` to login

$ ssh -i oci ubuntu@144.24.166.181`

where oci is your private SSH key.

Step 2. - Install Swift

Install developer tools

$ sudo apt install clang libpython2.7 libpython2.7-dev

Download the Swift release for aarch64 platform

$ wget https://download.swift.org/swift-5.8.1-release/ubuntu2204-aarch64/swift-5.8.1-RELEASE/swift-5.8.1-RELEASE-ubuntu22.04-aarch64.tar.gz

Unpack it

$ tar xzf swift-5.8.1-RELEASE-ubuntu22.04-aarch64.tar.gz

Move the unpacked Swift folder under /usr

$ sudo mv swift-5.8.1-RELEASE-ubuntu22.04-aarch64 /usr/share/swift

Add it to your PATH

$ echo "export PATH=/usr/share/swift/usr/bin:$PATH" >> ~/.bashrc

Reload your SHELL with the updated PATH

$ source ~/.bashrc

Test your Swift version

$ swift -v

Step 3 - Install `git`

$ sudo apt install git

Step 4 - Install and configure NGINX

Install NGINX server

$ sudo apt install nginx

Start the service

$ sudo systemctl start nginx.service

Add a rule at the top of the INPUT and OUTPUT chain to ACCEPT connexions to port 80. Try again after adding these rules:

$ sudo iptables -I INPUT -p tcp --dport 80 -m conntrack --ctstate NEW,ESTABLISHED -j ACCEPT

$ sudo iptables -I OUTPUT -p tcp --sport 80 -m conntrack --ctstate ESTABLISHED -j ACCEPT

Before you can check your web server, you need to open the port: 80 on OCI side as well.

Under the Networking / Virtual cloud networks / Virtual Cloud / Network Details / Security Lists click on "Default Security List for VCN for parkAPI".

"Add Ingress Rules" and fill it.

Now, you will see your web server running.

Step 5 - Clone and run our API server

Clone our Hummingbird app from Github:

$ git clone https://github.com/kicsipixel/parkAPI

Run your app

$ swift run parkAPI

To be able to reach your API server you need to configure NGINX to serve as reverse proxy and connect localhost:8080 to www: 80.

Step 5 - NGINX as reverse proxy

Remove the default NGINX config

$ sudo unlink /etc/nginx/sites-enabled/default

Create your own parkAPI.conf file under /etc/nginx/sites-available/

server {
    listen 80;
    listen [::]:80;    

    server_name 144.24.166.181 www.144.24.166.181;    

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Create a symlink to sites-enabled

$ sudo ln -s /etc/nginx/sites-available/parkAPI.conf /etc/nginx/sites-enabled/parkAPI.conf

Restart the server

$ sudo systemctl reload nginx

Test your server in the browser.

Congratulations, your Hummingbird server is running in the cloud.

Park API - Using PostgreSQL instead of SQLite

Szabolcs Toth — Fri, 09 Jun 2023 15:13:19 +0000

Server side Swift with Hummingbird

In the previous part of the article we built our first API server based on Swift using Hummingbird framework. That time we stored our data in SQLite database, which is perfect for rapid prototyping but for production we need something more robust.

Feather Database Component allows us to use PostgreSQL database as well. We need to make small modifications on our code.

Step 1. - Run PostgreSQL database as container

I prefer to use containers if I know that the development and the production environment most probably are different.

I have created this simple docker-compose.yml :

version: '3.7'

services:
  database:
    image: postgres:15-alpine
    restart: always
    env_file:
      - .env/development/database
    ports:
      - 5432:5432
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

The POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment variables are moved to a separate file under .env/development folder.

The database file:

POSTGRES_USER = hummingbird
POSTGRES_PASSWORD = hummingbird_password
POSTGRES_DB = hb-parks

Run start the container:

docker-compose up

Step 2. - Add PostgreSQL database dependency to your `Package.swift` file

We need to replace the SQLite component: .product(name: "HummingbirdSQLiteDatabase", package: "hummingbird-db") to PostgreSQL.

 // Database dependencies
                .product(name: "HummingbirdDatabase", package: "hummingbird-db"),
                .product(name: "HummingbirdPostgresDatabase", package: "hummingbird-db"),

Step 3. - Configure PostgreSQL database in the `DatabaseSetup.swift` file

Creating and connecting to a PostgreSQL database needs more configuration than SQLite. So these changes need to be applied:

import Hummingbird
import HummingbirdPostgresDatabase

extension HBApplication {
    func setupDatabase() async throws {
        services.setUpPostgresDatabase(
            configuration: .init(
                host: "localhost",
                port: 5432,
                username: "hummingbird",
                password: "hummingbird_password",
                database: "hb-parks",
                tls: .disable
            ),
            eventLoopGroup: eventLoopGroup,
            logger: logger
        )

        try await db.execute(
            .init(unsafeSQL:
                                   """
                                   CREATE TABLE IF NOT EXISTS parks (
                                       "id" uuid PRIMARY KEY,
                                       "latitude" double precision NOT NULL,
                                       "longitude" double precision NOT NULL,
                                       "name" text NOT NULL
                                   );
                                   """
                 )
        )
    }
}

Obviously the .env/development/database file variables and setUpPostgresDatabase init values must be identical.

PostgreSQL database uses double precision instead of double as data type.

Step 4. - That's all. You can run your server.

Once the PostgreSQL database is running in a container and you start you server as:

swift run parkAPI

you are able to connect.

Tools - you can use to make your development process easier

Working with databases is not always easy, specially if you don't have client to test.

For basic CRUD operations I use RaidAPI for Mac
For checking SQLite database - Base 2
For checking PostgreSQL - TablePlus

Park API - Server side Swift with Hummingbird

Szabolcs Toth — Fri, 02 Jun 2023 15:27:10 +0000

Special thanks to Tibor Bödecs for his patience and guidence during the writing of this tutorial.

Server side Swift has been available since end of 2015. The idea was behind the development that you can use the same language for RESTful APIs, desktop and mobile applications. With the evolution of the Swift language, the different Swift web frameworks got more robust and complex.

That's why I was happy to read Tib's excellent article about a new HTTP server library written in Swift, Hummingbird. I immediately liked the concept of modularity, so decided to create a tutorial to show its simplicity.

We will build a swift server running on SQLite database, which will store playgrounds around the city with name and coordinates. A simple JSON response will look like this:

[
    {
        "latitude": 50.105848999999999,
        "longitude": 14.413999,
        "name": "Stromovka"
    },
    {
        "latitude": 50.0959721,
        "longitude": 14.4202892,
        "name": "Letenské sady"
    }, {
        "latitude": 50.132259369,
        "longitude": 14.46098423,
        "name": "Žernosecká - Čumpelíkova"
    }
]

The project will use FeatherCMS's own Database Component.

Step 1. - Init the project

mkdir parkAPI && cd $_
swift package init --type executable

This creates the backbones of our project. One of the most important file and initial point of our project is the Package.swift, the Swift manifest file. Here you can read more about it.

Step 2. - Create the folder structure

We need to follow a certain guidelines about folder structure, otherwise the compiler won't be able to handle our project. On the picture below, you can find the simplest structure, which follow the Hummingbird template.

.
├── Package.swift
├── README.md
└── Sources
    └── parkAPI
        ├── App.swift
        └── Application+configure.swift

We will add the Tests folder later, when we will have something to test.

Step 3. - Run the server

Before we are able to run our server, we need to add two packages to the Package.swift file:

Hummingbird
Swift Argument Parser

Using .executableTarget the @main will be the enrty point of our application and we can rename main.swift to App.swift. Paul Hudson wrote a short article about it.

import PackageDescription

let package = Package(
    name: "parkAPI",
    platforms: [
        .macOS(.v12),
    ],
    dependencies: [
        .package(url: "https://github.com/hummingbird-project/hummingbird", from: "1.5.0"),
        .package(url: "https://github.com/apple/swift-argument-parser",from: "1.2.0"),
    ],
    targets: [
        .executableTarget(
            name: "parkAPI",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "Hummingbird", package: "hummingbird"),
                .product(name: "HummingbirdFoundation", package: "hummingbird"),
            ],
            swiftSettings: [
                .unsafeFlags(
                    ["-cross-module-optimization"],
                    .when(configuration: .release)
                )
            ]
        )
    ]
)

Define the hostname and port in the App.swift.

import ArgumentParser
import Hummingbird

@main
struct App: ParsableCommand {

    @Option(name: .shortAndLong)
    var hostname: String = "127.0.0.1"

    @Option(name: .shortAndLong)
    var port: Int = 8080

    func run() throws {
        let app = HBApplication(
            configuration: .init(
                address: .hostname(hostname, port: port),
                serverName: "parkAPI"
            )
        )

        try app.configure()
        try app.start()
        app.wait()
    }
}

One last thing remained before we can run our application is to define the route in the Application+configuration.swift.

import Hummingbird
import HummingbirdFoundation

public extension HBApplication {

    func configure() throws {
         router.get("/") { _ in
            "The server is running...🚀"
        }
    }
}

Run out first Hummingbird server by typing:

swift run parkAPI

Step 4. Create API response

Our server will be accessible on the following routes, using different HTTP methods.

GET - http://hostname/api/v1/parks: Lists all the parks in the database
GET - http://hostname/api/v1/parks/:id: Shows a single park with given id
POST - http://hostname/api/v1/parks: Creates a new park
PATCH - http://hostname/api/v1/parks/:id: Updates the park with the given id
DELETE - http://hostname/api/v1/parks/:id: Removes the park with id from database

Step 4.1 Add database dependency

Our server will use SQLite database to store all data, so we need to add the database dependency to our manifest file. This will allow the server to communicate to the database.

The updated Package.swift file will look like this:

import PackageDescription

let package = Package(
    name: "parkAPI",
    platforms: [
        .macOS(.v12)
    ],
    dependencies: [
        .package(url: "https://github.com/hummingbird-project/hummingbird", from: "1.5.0"),
        .package(url: "https://github.com/apple/swift-argument-parser",from: "1.2.0"),
        // Database dependency
        .package(url: "https://github.com/feathercms/hummingbird-db", branch: "main")
    ],
    targets: [
        .executableTarget(
            name: "parkAPI",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "Hummingbird", package: "hummingbird"),
                .product(name: "HummingbirdFoundation", package: "hummingbird"),
                // Database dependencies
                .product(name: "HummingbirdDatabase", package: "hummingbird-db"),
                .product(name: "HummingbirdSQLiteDatabase", package: "hummingbird-db"),
            ],
            swiftSettings: [
                .unsafeFlags(
                    ["-cross-module-optimization"],
                    .when(configuration: .release)
                )
            ]
        )
    ]
)

Step 4.2 Use concurrency in `App.swift`

Add async to function run() and await to app.configure.

import ArgumentParser
import Hummingbird

@main
struct App: AsyncParsableCommand, AppArguments {

    @Option(name: .shortAndLong)
    var hostname: String = "127.0.0.1"

    @Option(name: .shortAndLong)
    var port: Int = 8080

    func run() async throws {
        let app = HBApplication(
            configuration: .init(
                address: .hostname(hostname, port: port),
                serverName: "Hummingbird"
            )
        )

        try await app.configure()
        try app.start()
        app.wait()
    }
}

We need to use AsyncParsableCommand and AppArguments protocols.

Step 4.3 Create a database configuration file

Add a new file, with name DatabaseSetup.swift file under a new Database folder under Source/parkAPI/.

import Hummingbird
import HummingbirdSQLiteDatabase

extension HBApplication {
    func setupDatabase() async throws {
        services.setUpSQLiteDatabase(
            storage: .file(path: "./hb-parks.sqlite"),
            threadPool: threadPool,
            eventLoopGroup: eventLoopGroup,
            logger: logger
        )

        // Create the database table
        try await db.execute(
            .init(unsafeSQL:
                           """
                           CREATE TABLE IF NOT EXISTS parks (
                               "id" uuid PRIMARY KEY,
                               "latitude" double NOT NULL,
                               "longitude" double NOT NULL,
                               "name" text NOT NULL
                           );
                           """
                 )
        )
    }
}

Step 4.4 Call the `setupDatabase` function

Add try await setupDatabase() to Application+configure.swift.

import Hummingbird
import HummingbirdFoundation


public protocol AppArguments {}

public extension HBApplication {

    func configure() async throws {

        // Setup the database
        try await setupDatabase()

        // Set encoder and decoder
        encoder = JSONEncoder()
        decoder = JSONDecoder()

        // Logger
        logger.logLevel = .debug

        // Middleware
        middleware.add(HBLogRequestsMiddleware(.debug))
        middleware.add(HBCORSMiddleware(
            allowOrigin: .originBased,
            allowHeaders: ["Content-Type"],
            allowMethods: [.GET, .OPTIONS, .POST, .DELETE, .PATCH]
        ))

        router.get("/") { _ in
            "The server is running...🚀"
        }

        // Additional routes are defined in the controller
        // We want our server to respond on "api/v1/parks"
        ParkController().addRoutes(to: router.group("api/v1/parks"))
    }
}

Step 4.5 Create the park model

Add the Park.swift under /Source/parkAPI/Models.

import Foundation
import Hummingbird

struct Park: Codable {
    let id: UUID
    let latitude: Double
    let longitude: Double
    let name: String

    init(id: UUID, latitude: Double, longitude: Double, name: String) {
        self.id = id
        self.latitude = latitude
        self.longitude = longitude
        self.name = name
    }
}

extension Park: HBResponseCodable {}

Step 4.6 Create the park controller

The Controller receives an input from the users, then processes the user's data with the help of Model and passes the results back. Add ParkController.swift to a new Controllers folder under Source/parkAPI/.

import Foundation
import Hummingbird
import HummingbirdDatabase

extension UUID: LosslessStringConvertible {

    public init?(_ description: String) {
        self.init(uuidString: description)
    }
}

struct ParkController {
    // Define the table in the databse
    let tableName = "parks"

    // The routes for CRUD operations
    func addRoutes(to group: HBRouterGroup) {
        group
            .get(use: list)
    }

    // Return all parks
    func list(req: HBRequest) async throws -> [Park] {
        let sql = """
                SELECT * FROM parks
        """
        let query = HBDatabaseQuery(unsafeSQL: sql)

        return try await req.db.execute(query, rowType: Park.self)
    }
}

In the controller file, define the table of the database you want to use, ideally it is the same as you defined in the DatabaseSetup.swift file.

Use HBRouterGroup to collect all routes under single path.

GET - all parks

Start with listing all elements: .get(use: list) Where get refers to GET method and use to the function where you describe what supposed to happen, if you call that endpoint.

The list() function returns with the array of Park model.

GET - park with {id}

Show park with specified id: .get(":id", use: show).

 func show(req: HBRequest) async throws -> Park? {
        let id = try req.parameters.require("id", as: UUID.self)
        let sql = """
                SELECT * FROM parks WHERE id = :id:
        """
        let query = HBDatabaseQuery(
            unsafeSQL: sql,
            bindings: ["id": id]
        )
        let rows = try await req.db.execute(query, rowType: Park.self)

        return rows.first
    }

POST - create park

Create new park: .post(options: .editResponse, use: create).

    func create(req: HBRequest) async throws -> Park {
        struct CreatePark: Decodable {
            let latitude: Double
            let longitude: Double
            let name: String
        }

        let park = try req.decode(as: CreatePark.self)
        let id = UUID()
        let row = Park(
            id: id,
            latitude: park.latitude,
            longitude: park.longitude,
            name: park.name
        )
        let sql = """
                INSERT INTO
                    parks (id, latitude, longitude, name)
                VALUES
                    (:id:, :latitude:, :longitude:, :name:)
                """

        try await req.db.execute(.init(unsafeSQL: sql, bindings: row))
        req.response.status = .created

PATCH - update park with {id}

Update park with specified id: ‌.patch(":id", use: update)

   func update(req: HBRequest) async throws -> HTTPResponseStatus {
        struct UpdatePark: Decodable {
            var latitude: Double?
            var longitude: Double?
            var name: String?
        }
        let id = try req.parameters.require("id", as: UUID.self)
        let park = try req.decode(as: UpdatePark.self)
        let sql = """
                    UPDATE
                        parks
                      SET
                          "latitude" = CASE WHEN :1: IS NOT NULL THEN :1: ELSE "latitude" END,
                          "longitude" = CASE WHEN :2: IS NOT NULL THEN :2: ELSE "longitude" END,
                          "name" = CASE WHEN :3: IS NOT NULL THEN :3: ELSE "name" END
                      WHERE
                          id = :0:
                    """
        try await req.db.execute(
            .init(
                unsafeSQL:
                    sql,
                bindings:
                    id, park.latitude, park.longitude, park.name
            )
        )
        return .ok
    }

As in the DatabaseSetup.swift file we defined that none of table columns can be NULL, we need to check that the request contains all values of only some of them and update the columns respectively.

DELETE - delete park with {id}

Delete park with specified id: .delete(":id", use: deletePark)

    func deletePark(req: HBRequest) async throws -> HTTPResponseStatus {
        let id = try req.parameters.require("id", as: UUID.self)
        let sql = """
                    DELETE FROM parks WHERE id = :0:
                """
        try await req.db.execute(
            .init(
                unsafeSQL: sql,
                bindings: id
            )
        )
        return .ok
    }
}

Our final folder structure looks like this:

.
├── Package.swift
├── README.md
└── Sources
    └── parkAPI
        ├── App.swift
        ├── Application+configure.swift
        ├── Controllers
        │   └── ParkController.swift
        ├── Database
        │   └── DatabaseSetup.swift
        └── Models
            └── Park.swift

Step 5: Run the API server:

swift run parkAPI

You can reach the server on: http://127.0.0.1:8080

Summary

I was impressed how easily and quickly I could build a working API server using Hummingbird and FeatherCMS's Database Component. Building and running the project took very minimal time comparing to Vapor. I highly recommend to try Hummingbird project in case you want something light and modular on Server side Swift.

You can find the source code here.

Original article was published here.

NSWindow without Storyboard but...

Szabolcs Toth — Mon, 08 Jun 2020 08:27:25 +0000

Earlier this year I wrote a short article about creating NSWindow without Storyboard with code only. While collecting information, I read several opinions why it was a tedious job, and it could be done better...

Maybe the easiest way to mix Storyboard and coding approach. As I pointed out, recreation of NSMenu is a real pain/mess. So, what about keeping Main.storyboard for NSMenu only and code the rest of the components?

Step 1.
Create a new macOS app.

Step 2.
Delete:

Window Controller Scene
View Controller Scene

This way we can keep NSMenu and need to recreate NSWindow and NSView with their Controllers.

Step 3.
Add a new Cocoa (NSWindow) class with the following code:

Probably, the most important part of NSWindow init method is the StyleMask.

I added these four constants:

titled: The window displays a title bar
closable: The window displays a close button
miniaturizable: The window displays a minimize button
resizable: The window can be resized by the user

It's worth checking the documentation to find out more about NSWindow StyleMask.

Step 4.
Add a new Cocoa class, an NSWindowController.

In the Controller file we need to define the size and position of our new window. Beside these we need to prepare the window to hold a view too as content.

Note: the convinience init method is required as NSWindowController cannot load the relevant xib file, unless NSViewController. Since we don't want to use any xib files, so we set empty string there.

Step 5.
Add a new Cocoa class, an NSViewController.

As I mentioned above, NSViewController will try to use xib file with the same name, we override this to set it to nil.

It's important not to forget that NSViewController is not enough alone. We need an NSView to show the content, which size is the same as defined for NSWindow.

Run the application. Everything seems to be fine but... we have no error and no window. Why? We have never told our application that it has an NSWindow.

Step 6.
Go to AppDelegate.swift and define our newly created NSWindow. Once we have it as variable, we need to show in applicationDidFinishLaunching method.

Run the application now, and you'll see the window.

Step 7.
Add 'Hello, World' label as NSTextField to the View using Constraints.

Note: We'll align the label to the center of the View, not important to give other x and y coordinates than 0. You use sizeToFit() method, so width and height of the NSTextfield are irrelevant as well.

Your final app:

Source code: Github

You can find more macOS programming tutorial on my blog.

NSWindow without Storyboard

Szabolcs Toth — Sun, 12 Jan 2020 19:41:43 +0000

Time to time the debate restarts whether using Storyboard is the proper way of interface desing. On iPhone it is quite simple and you can find several articles or tutorials.
I wanted to try it on macOS and hardly found anything up-to-date information. Hereby I share what I found, maybe it can help others.

At the end of the article I indicated all the sources I used.

Step 1.
Create a new Swift project with Storyboard.

Step 2.
Remove the Main.Storyboard and ViewController.swift, then delete "Main Interface".

Step 3.
Add a new swift file called: main.swift.

Add the following code to it, this is require to execute AppDelegate.swift.

Step 4.
Insert the following into

AppDelegate.swift

and comment out

// @NSApplicationMain

Run our app now.

Looks good but we need to add a NSViewController to show some content.

Step 5.
Add MyViewController.swift as NSViewController.

Connect our new NSWindow with the new MyViewController:

window?.contentViewController = MyViewController()

Color the background of the NSViewController to see if we managed to add to NSWindow.

Step 6.
Add some more code to MyViewController.swift to show a label.

There is only one big issue with our new app, there is no Menu as we deleted it with the Main.Storyboard.

Step 7.
Go back to

AppDelegate.swift

and insert the code for menu.

Now, you can quit from menu.