The instructions to set up an AWS instance here is adapted from EECS 485’s tutorial.

Create an account

Create an AWS account at the AWS Registration. You should be eligible for their free tier, which means that you will be able to run an instance for free for the duration of the course.

Despite that, you will need to enter a credit card number on the account, even if you only use free tier resources. This is how Amazon charges, in case you request more resources than provided in the free tier. Do not launch any additional instances other than the one we specify in order to avoid additional charges.

Optionally, you may redeem extra benefits as a student, including $100 in AWS credits.

Start instance

Navigate to the AWS Management Console. Select the “Services” dropdown menu, then “EC2”. An EC2 “instance” is a virtual machine running on Amazon AWS hardware.

Click launch an instance. It may take a few minutes to initialize before it’s running.

Select the “Ubuntu Server 24.04.01 LTS” Amazon Machine Image (AMI).

Select the “t2.micro” instance type. You should see “free tier eligible”. When you create an instance, AWS automatically creates user “ubuntu” for you on the instance.

Create a key pair for user “ubuntu”. The private key will be automatically downloaded for you once the key pair is created. You’ll use this private key later to ssh to the instance. Click on Create new key pair:

Then enter “eecs441” as the key pair name and click Create key pair:

Allow SSH, HTTP, and HTTPS and click Edit on the top right:

Verify if three security group rules have been added. After this, Click on Add security group rule.

Edit the “Security group rule 4 (TCP, 0)” section, and add “Custom TCP” for port 8000 to allow Django traffic in and out of your instance. [Thanks to Z. Liang and R. Nagavardhan ‘23.]

Click “Launch Instance”.

Instance status

Navigate to the AWS Management Console. Select the “Services” dropdown menu, then “EC2”.

Select one of the instances and view its status and Public DNS.

In the remainder of this spec, and this term, we will refer to your “IPv4 Public IP” as YOUR_SERVER_IP (in the image it’s 52.90.192.32).

ssh to instance

On your development host (laptop):

If AWS gave you a eec441.cer instead of eecs441.pem, just use eecs441.cer everywhere you see eecs441.pem in this spec.

MacOS on Terminal:

#         👇👇👇👇👇👇👇👇👇👇
laptop$ cd YOUR*LABS*FOLDER
laptop$ mv ~/Downloads/eecs441.pem eecs441.pem
laptop$ chmod 400 eecs441.pem
laptop$ ssh -i eecs441.pem ubuntu@YOUR_SERVER_IP
#                                 👆👆👆👆👆👆👆👆👆

Windows on PowerShell [thanks to Jad Beydoun (F21) for use of icacls]:

#            👇👇👇👇👇👇👇👇👇👇
PS laptop> cd YOUR*LABS*FOLDER
PS laptop> mv ~\Downloads\eecs441.pem eecs441.pem
PS laptop> icacls eecs441.pem /grant "$($env:username):(r)" /inheritance:r
PS laptop> ssh -i eecs441.pem ubuntu@YOUR_SERVER_IP
#                                    👆👆👆👆👆👆👆👆👆

  laptop$ sudo vi /etc/wsl.conf

  [automount]
  options = "metadata"

  #          👇👇👇👇👇👇👇👇👇
  laptop$ cd YOUR*LABS*FOLDER
  #                       👇👇👇👇👇👇👇👇👇👇👇👇👇
  laptop$ mv /mnt/c/Users/YOUR_WINDOWS_USERNAME/Downloads/eecs441.pem eecs441.pem
  laptop$ chmod 400 eecs441.pem
  laptop$ ssh -i eecs441.pem ubuntu@YOUR_SERVER_IP
  #                                 👆👆👆👆👆👆👆👆👆

In both cases, what the above does:

1. change working directory to YOUR*LABS*FOLDER,
2. move the private ssh key you created and downloaded earlier into YOUR*LABS*FOLDER,
3. set its permissions to read-only, and
4. ssh to your AWS instance as user “ubuntu” using the downloaded private key. (Make sure your instance is running. See Instance status.)

Stop instance

Check your Instance status.

Right click on your instance Instance State > Stop.

You should see that your instance is stopped.

server$ sudo apt install cloud-utils awscli

server$ ec2metadata
server$ aws configure
server$ aws ec2 help

server$ aws iam list-access-keys

server$ aws ec2 authorize-security-group-ingress --group-id YOUR_GROUP_ID --ip-permissions IpProtocol=tcp,FromPort=8000,ToPort=8000,Ipv6Ranges=[{CidrIpv6=::/0}]

Google Cloud Platform has a free-tier, with free credits that are easy to qualify for.

Login to Google account

You’ll need a personal Google account to use the Google Cloud Platform. Do not use your umich email address. The following steps are adapted from Google Cloud’s Quickstart using a Linux VM, though they have been adapted to the course. For example, we choose an E2 instance that is eligible for the free-tier.

Create project

Go to the Google Cloud Platform Project Selector page and create a project. Click AGREE AND CONTINUE if you agreed to Google’s Terms of Service.

Create a project by clicking on the Create Project button.

Give your project a name unique to you and click Create.

Add billing

Add a billing method to your project.

The side menu may have additional items pre-pinned, however the two items we need Billing and Compute Engine are easily identifiable. Please consult the teaching staff if you couldn’t find any menu items referenced in this spec.

When you fill out your billing information, select “individual” as account type. Make sure you see something like this:

Add a credit or debit card. If your back end qualifies for free-tier (it should), this card will not be charged. Select START MY FREE TRIAL. Return to the project console.

Enable Compute Engine API

Visit GCP’s Compute Engine API site and select ENABLE.

Create VM instance

Return to the console. Hover over Compute Engine on the left navigation bar and select VM Instances.

Select CREATE INSTANCE.

Review the free tier options at the Google Cloud Free Program page by scrolling to the section titled “Free Tier usage limits”. Look under the “Compute Engine” section and check regions eligible for free tier. Free tier usage is governed by time used. Currently, an E2 in Oregon, Iowa, or South Carolina is eligible for free tier if used for the number of hours in a month.

Give the instance a name and carefully select the regions that are available as free tier with an e2-micro configuration.

The monthly estimate does not factor in free tier. If the steps are followed, your account should not be billed.

Scroll down until you see the **Boot disk**** section. Click “CHANGE” under Boot disk and configure it to Ubuntu 24.04.01 LTS. Be sure to select STANDARD PERSISTENT DISK. Any other Boot Disk type option will cost you.

After you’ve chosen “Ubuntu 24.04.01 LTS” and “Standard persistent disk”, click the blue SELECT button.

Back in the “Machine configuration” page, scroll down further, pass the “Boot disk” section, to get to the “Firewall” section. In the “Firewall” section, allow both HTTP and HTTPS traffic. You should see two boxes like this:

Press “CREATE” to create the instance. Wait for the instance to initialize. When the loading animations are done, write down the external IP address shown on the screen. In the remainder of this spec, and this term, we will refer to your “external IP” as YOUR_SERVER_IP (in the image it’s 34.73.108.54). You’ll never need the internal IP (and GCP doesn’t provide any public DNS for your instance).

Next select the triple dots on your E2. Select “Network Details”.

Select “Firewall”. We have to change one more firewall setting to allow us to test the web server we’ll be setting up later.

Create a firewall rule.

Give your rule a name. Scroll down to “Targets”. Enter “http-server” into the “Target tags” box. Enter 0.0.0.0/0 into the source IPv4 ranges box. Enter port 8000 into the tcp box. Press “CREATE”.

ssh to instance

The back-end specs in this course will assume that you have a user with username “ubuntu” created on your instance. The specs further assume that you’re doing all your back-end work, building your server, under user “ubuntu”. You’re free to build under a different username, e.g., your Google account name, however you will then have to map between the instructions in the specs and your setup. More importantly, we will NOT be able to help you should you need help debugging your back-end server. To build your back end as user ubuntu, please do the following:

  laptop$ sudo vi /etc/wsl.conf

  [automount]
  options = "metadata"

  #                       👇👇👇👇👇👇👇👇👇👇👇👇👇
  laptop$ ls /mnt/c/Users/YOUR_WINDOWS_USERNAME/

First generate a public/private key pair for user “ubuntu” in a safe place you can easily remember, for example YOUR*LABS*FOLDER.:

#         👇👇👇👇👇👇👇👇👇👇
laptop$ cd YOUR*LABS*FOLDER
laptop$ ssh-keygen -C ubuntu

when ssh-keygen prompts you for the file in which to save the key, enter “eecs441.pem”. It will then prompt you for a passphrase. Leave it empty. Hit return or enter, twice. Your identification (private key) would have been saved in eecs441.pem and your public key in eecs441.pem.pub. You can view the content of your public key for posting to Google below by:

laptop$ cat eecs441.pem.pub

Go to GCP Metadata page, open the SSH KEYS tab and click on EDIT.

On the edit page, click + ADD ITEM, copy and paste the content of your “eecs441.pem.pub” to the empty box that + ADD ITEM brought up, and hit the blue SAVE button.

Your SSH KEYS tab should now list “ubuntu” under Username with its corresponding public key:

To ssh to your GCP instance as user “ubuntu” using your private key, eecs441.pem, you must first set its permissions to read-only. In the following, YOUR_SERVER_IP always refers to the external IP address you’ve noted down earlier.

laptop$ chmod 400 eecs441.pem
laptop$ ssh -i eecs441.pem ubuntu@YOUR_SERVER_IP
#                                 👆👆👆👆👆👆👆👆👆

PS laptop> icacls eecs441.pem /grant "$($env:username):(r)" /inheritance:r
PS laptop> ssh -i eecs441.pem ubuntu@YOUR_SERVER_IP
#                                    👆👆👆👆👆👆👆👆👆 

Stop instance

Head to your E2 dashboard. Select “Compute Engine”.

When you are completely done with your E2, delete it to ensure you are not charged. A day or two later, ensure that there are no charges for your E2 at all.

Install Go

• ssh to your server and download the latest version of Go: Check Go’s Downloads page for the current latest version. As of the time of writing, the latest version is 1.23.4.

  server$ cd /tmp
  server$ wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz
  

  The version of Go distributed with the Ubuntu package manager apt may not be the latest version and may be incompatible with our solution, which requires Go version 1.18 or later.

• Go to Go’s download and install page.

• Skip the first section on Go download, you’ve already downloaded Go.

• Click on the Linux tab in the second (Go install) section of the instructions.

• Follow the instructions, with the following modifications to step 1 (you need to be root to modify /usr/local):

  server$ sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.23.2.linux-amd64.tar.gz
  server$ sudo chmod -R go+rX /usr/local/go
  

To update to a later version of Go, follow the instructions in Managing Go installations—which would have you manually delete the existing Go folder (usually /usr/local/go/), so don’t put any custom files in there.

chatterd module

First create and change into a directory where you want to keep your chatterd module:

server$ mkdir ~/441/chatterd
server$ cd ~/441/chatterd

Create a Go module called chatterd to house the Chatter back end:

server$ go mod init chatterd
# output:
go: creating new go.mod: module chatterd

Create a file called main.go:

server$ vi main.go

We will put the server and URL routing code in main.go, starting with the following import lines:

package main

import (
	"context"
	"log"
	"github.com/jackc/pgx/v4/pgxpool"
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

We next create a Route struct to hold the URL routing information needed by Echo and declare a global variable routes to hold an array of Routes. We define the routes to serve Chatter’s two APIs. We route HTTP GET requests with URL endpoint getchatts/ to the getchatts() function and we route HTTP POST requests with endpoint postchatt/ to the postchatt() function. With each route, we also specify which HTTP method is allowed for that URL endpoint:

type Route struct {
    HTTPMethod string
    URLPath    string
    URLHandler echo.HandlerFunc
}

var routes = []Route {
    {"GET", "/getchatts/", getchatts},
    {"POST", "/postchatt/", postchatt},
}

The functions getchatts() and postchatt() will be implemented in handlers.go later.

For now, staying in main.go, in our main() function, we first set up a pool of open connections to our PostgreSQL chatterdb database. Maintaining a pool of open connections avoids the cost of opening and closing a connection on every database operation. The password used in creating pgxpool must match the one you used when setting up Postgres earlier. The connection pool needs to be accessible to all the URL handlers, so we store it in a global variable chatterDB:

var background = context.Background()
var chatterDB *pgxpool.Pool

func main() {
	var err error
	chatterDB, err = pgxpool.Connect(background, "host=localhost user=chatter password=chattchatt dbname=chatterdb")
	if err != nil { panic(err) } 
  

Continuing inside the main() function, we set up the Echo server:

• disable the Echo banner printing on the console,
• load up the routes array above,
• set it to automatically reroute any URL specified without a trailing ‘/’ to one with trailing ‘/’, for example https://YOUR_SERVER_IP/getchatts will be routed to https://YOUR_SERVER_IP/getchatts/,
• bind it to the default HTTPS port (443),
• assign it the chatterd certificate and key we created earlier, and . . .

launch the server:

	server := echo.New()
  server.HideBanner = true
	for _, route := range routes {
		server.Match([]string{route.HTTPMethod}, route.URLPath, route.URLHandler)
	}
	server.Pre(middleware.AddTrailingSlash())

	log.Fatal(server.StartTLS(":443",
		"/home/ubuntu/441/chatterd.crt",
		"/home/ubuntu/441/chatterd.key"))
}

handlers.go

We implement the URL path API handlers in handlers.go:

server$ vi handlers.go

Start the file with the following imports:

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/labstack/echo/v4"
)

We define a Chatt struct to help postchatt() deserialize JSON received from clients:

type Chatt struct {
    Username  string    `json:"username"`
    Message   string    `json:"message"`
    Id        string    `json:"id"`
    Timestamp time.Time `json:"timestamp"`
}

The property names must be capitalized to be visible to the JSON deserializer.

We add a number of logging functions to print to console results of handling each HTTP request and, in case of error, prepare a corresponding JSON response to be returned to the client:

func logOk(c echo.Context) {
	log.Println("[Echo] |", http.StatusOK, `|`, c.RealIP(), `|`, c.Request().Method, c.Request().RequestURI)
}

func logServerErr(c echo.Context, err error) error {
	log.Println("[Echo] |", http.StatusInternalServerError, `|`, c.RealIP(), `|`, c.Request().Method, c.Request().RequestURI, err.Error())
	return c.JSON(http.StatusInternalServerError, err.Error())
}

func logClientErr(c echo.Context, sc int, err error) error {
	log.Println("[Echo] |", sc, `|`, c.RealIP(), `|`, c.Request().Method, c.Request().RequestURI, err.Error())
	return c.JSON(sc, err.Error())
}

The handler getchatts() uses an open connection from the connection pool to query the database for stored chatts.

func getchatts(c echo.Context) error {

    var chattArr [][]any
    var chatt Chatt

    rows, err := chatterDB.Query(background, `SELECT username, message, id, time FROM chatts ORDER BY time DESC`)
    if err != nil {
      if rows != nil { rows.Close() }
		  return logServerErr(c, err)
    }

    for rows.Next() {
        err = rows.Scan(&chatt.Username, &chatt.Message, &chatt.Id, &chatt.Timestamp)
        if err != nil {
          rows.Close()
          return logServerErr(c, err)
        }        
        chattArr = append(chattArr, []any{chatt.Username, chatt.Message, chatt.Id, chatt.Timestamp})
    }

    logOk(c)
    return c.JSON(http.StatusOK, chattArr)
}

Similarly, postchatt() receives a posted chatt in the expected JSON format, has it deserialized into the Chatt struct, and inserts it into the database, using a connection from the pool. The UUID and time stamp of each chatt are automatically generated at insertion time.

func postchatt(c echo.Context) error {
    var chatt Chatt

    if err := c.Bind(&chatt); err != nil {
      return logClientErr(c, http.StatusUnprocessableEntity, err)
    }

    _, err := chatterDB.Exec(background, `INSERT INTO chatts (username, message, id) VALUES ($1, $2, gen_random_uuid())`, chatt.Username, chatt.Message)
    if err != nil {
        return logClientErr(c, http.StatusBadRequest, err)
    }

    logOk(c)
	  return c.JSON(http.StatusOK, "")
}

Build and test run

To build your server:

server$ go get
server$ go build

Go is a compiled language, like C/C++ and unlike Python, which is an interpreted language. This means you must run go build each and every time you made changes to your code, for the changes to show up in your executable.

To run your server:

server$ sudo ./chatterd
# Hit ^C to end the test

If you had Prefork enabled and wanted to prefork 3 servers, do instead:

server$ sudo GOMAXPROCS=3 ./chatterd

You can test your implementation following the instructions in the Testing Chatter APIs section.

References

• Working with Go
  • Golang tutorial series gentle and clear, though a bit out of date in parts now.
• Running multiple HTTP servers in Go
• Making a RESTful JSON API in Go
• Golang Json Marshal Example
• HTTP Status Code
• Go: Format a time or date
• pgxpool
• Effective Error Handling in Golang
• URL

Install Node.js

We will first use the apt package manager to install Node.js version 18.19.1 or later (up to version 23.2.0 tested) and its tools:

server$ sudo apt update
server$ sudo apt install npm    # will automatically install node.js also

Confirm that you’ve installed Node.js version 18.19.1 or later:

server$ node --version
# output:
v18.19.1
# or later

server$ curl -sL https://deb.nodesource.com/setup_23.x | sudo bash -
server$ sudo apt update
server$ sudo apt install nodejs # automatically install npm also

server$ sudo apt purge nodejs
server$ sudo rm /etc/apt/sources.list.d/nodesource.list

package.json and tsconfig.json

First create and change into a directory where you want to keep your chatterd package files:

server$ mkdir ~/441/chatterd
server$ cd ~/441/chatterd

Install the following packages, including the PostgreSQL adaptor and pm2 process manager:

server$ npm install express http2-express-bridge morgan postgres 
server$ npm install -D typescript @types/express @types/morgan @types/node 
server$ sudo npm install -g pm2

Your ~/441/chatterd directory should now contain the following:

node_modules/  package-lock.json  package.json

The package.json file should contain:

{
  "dependencies": {
    "express": "^4.21.1",
    "http2-express-bridge": "^1.0.7",
    "morgan": "^1.10.0",
    "postgres": "^3.4.5"
  },
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/morgan": "^1.9.9",    
    "@types/node": "^22.9.0",
    "typescript": "^5.6.3"
  }
}

The devDependencies are used in development, not deployed in production. In our case, all the devDependencies are for static type checking. The dependencies with @types prefix define the types used in their corresponding native JavaScript modules that have no static typing information. The file package-lock.json locks the dependencies to specific versions, to prevent automatically incorporating later, breaking versions. The node_modules directory contains the module files of both direct dependencies in package.json and indirect dependencies used by the direct dependencies.

Open your package.json and add the following line right below the top open brace:

  "type": "module",

Create a tsconfig.json configuration file for use by TypeScript:

server$ vi tsconfig.json

and put the following in it:

{
  "compilerOptions": {
    // https://aka.ms/tsconfig for definitions

    /* Language and Environment */
    "target": "ES2022",                   // version of emitted JavaScript and compatible library
    "module": "ES2022",                   // version of generated module code
    "moduleResolution": "bundler",        // how TypeScript looks up a file from module

    /* Interop Constraints */
    "verbatimModuleSyntax": true,         // transform and elide only imports/exports marked
                                          // "type"; the rest are emitted per the "module" setting
    "allowSyntheticDefaultImports": true, // can 'import x from y' even if y has no default export
    "esModuleInterop": true,              // can import CommonJS modules;
                                          // enables 'allowSyntheticDefaultImports'

    /* Type Checking */
    "alwaysStrict": true,                 // always enable all strict type-checking options

    /* Completeness */
    "skipLibCheck": true                  // skip type checking all .d.ts files
  }
}

Save and exit tsconfig.json.

You now have all of the packages needed by the Chatter backend.

chatterd app

Create a file called main.ts:

server$ vi main.ts

We will put the server and URL routing code in main.ts. Open and edit the file to add the following import lines:

import type { AddressInfo } from 'node:net'       // import type
import { createSecureServer } from 'node:http2'   // import function
import express from 'express'                     // import default, can't be used with import type
import http2Express from 'http2-express-bridge'
import morgan from 'morgan'
import postgres from 'postgres'
import { readFileSync } from 'node:fs'
import type { Sql } from 'postgres'
import * as handlers from './handlers.js'         // import namespace

process.on('SIGTERM', () => {
  process.exit(0)
})

process.on('uncaughtException', (err) => {
  console.error(`Uncaught exception: ${err}\n` + `Stack trace: ${err.stack}`);
  process.exit(2);
});

We also took the opportunity to register two callback functions with the process: (1) to shutdown gracefully when the process is terminated by user, and (2) to print out a stack trace and exit with an error code in the case of any uncaught exception.

With process termination events taken care of, we set up a pool of open connections to our PostgreSQL chatterdb database. Maintaining a pool of open connections avoids the cost of opening and closing a connection on every database operation. The password used in the call to postgress() must match the one you used when setting up Postgres earlier. The connection pool needs to be accessible to all the URL handlers, so we store it in a global variable chatterDB:

export let chatterDB: Sql

try {
  chatterDB = postgres('postgres://chatter:chattchatt@localhost/chatterdb')

  // the rest of main.ts will go here

} catch (error) {
  console.log(error)
  process.exit(1)
}

Inside the try block, right under the call to postgres(), we next create an express instance and define routes to serve Chatter’s first two APIs: HTTP GET requests with URL endpoint getchatts/ are routed to the getchatts() function and HTTP POST requests with endpoint postchatt/ are routed to the postchatt() function. With each route, we implicit specify which HTTP method is allowed for that URL endpoint by providing only route definition with get() or post() method that will be invoked only when there is an HTTP GET or POST request for the specified endpoint:

  const app = http2Express(express)
      .use(morgan('common')) // logging
      .use(express.json())
      .get('/getchatts/', handlers.getchatts)
      .post('/postchatt/', handlers.postchatt)

We have also configured our express app with two middlewares: morgan to log each response and express.json() to automatically parse incoming requests containing JSON payload and making it available as the Request’s body to the URL handler. We also wrapped express inside the http2Express() bridge to allow interoperability with HTTP/2. This is a workaround until HTTP/2 is eventually supported natively in express. The functions getchatts() and postchatt() themselves will be implemented in handlers.ts later.

Staying inside the try block, after setting up the express app, we set up the node.js server:

• create an instace of the secure server with the chatterd certificate and key we created earlier,
• load up the app instance of express to the secure server,
• bind it to the wildcard IP address (0.0.0.0, equivalent of any) and the default HTTPS port (443), and launch it:

  const tls = {
    key: readFileSync("/home/ubuntu/441/chatterd.key"),
    cert: readFileSync("/home/ubuntu/441/chatterd.crt"),
    allowHTTP1: true
  }
  
  const server = createSecureServer(tls, app).listen({host: '0.0.0.0', port: 443}, () => {
    const address = server.address() as AddressInfo
    console.log(`chatterd on https://${address.address}:${address.port}`)
  })
  

  handlers.ts

We implement the URL path API handlers module in the handlers.rs:

server$ vi handlers.ts

Start the file with the following imports:

import { chatterDB } from './main.js'
import { createHash, randomUUID } from 'crypto'
import type { PostgresError } from 'postgres'
import type { Request, Response } from 'express'

We define a Chatt struct to help postchatt() deserialize JSON received from clients:

interface Chatt {
    username: string
    message: string
}

The handler getchatts() uses an open connection from the connection pool to query the database for stored chatts. By default, postgres.js retrieves each database row as a JSON object, whereas we want each row represented as an array of values only, without column name as tags. We achieve this by calling .values() on each retrieved row. We insert the resulting array of chatts into the response JSON object, if no exception has been raised.

export async function getchatts(req: Request, res: Response) {
    try {
        const chatts = await chatterDB`SELECT username, message, id, time FROM chatts ORDER BY time DESC`.values()
        res.json(chatts)
    } catch (error) {
        res.status(500).json(`${error as PostgresError}`)
    }
}

Similarly, postchatt() receives a posted chatt in the expected JSON format, has it deserialized into the Chatt interface, and inserts it into the database, using a connection from the pool. The UUID and time stamp of each chatt are automatically generated at insertion time.

export async function postchatt(req: Request, res: Response) {
    let chatt: Chatt
    try {
        chatt = req.body
    } catch (error) {
        res.status(422).json(error)
        return
    }
    try {
        await chatterDB`INSERT INTO chatts (username, message, id) VALUES (${chatt.username}, ${chatt.message}, ${randomUUID()})`
        res.json({})
    } catch (error) {
        res.status(400).json(`${error as PostgresError}`)
    }
}

Build and Test run

TypeScript is a compiled language, like C/C++ and unlike JavaScript and Python, which are an interpreted languages. This means you must run npx tsc each and every time you made changes to your code, for the changes to show up when you run node.

To build your server, transpile TypeScript into JavaScript:

server$ npx tsc

You should now see a .js file for each .ts file in the directory.

To run your server:

server$ sudo node main.js
# Hit ^C to end the test

tsx can run TypeScript directly, but it doesn’t perform type checking. Bun and Deno can also run TypeScript directly, but they don’t support HTTP/2 yet at the time of writing.

You can test your implementation following the instructions in the Testing Chatter APIs section.

References

• 7 Simple Steps to build your own TypeScript Node.js project
• A Complete Guide to HTTP/2 in Node.js
  • http2-express-bridge
• Postgres.js
  • Postgres Library Benchmarks for Node.js
• morgan
  • Logging in Node.js: A Comparison of the Top 8 Libraries
• Mastering Error Handling in JavaScript
  • Control flow and error handling: Exception types
  • JavaScript error reference
• Production best practices: performance and reliability
  • Why is NODE_ENV considered an antipattern?
  • Running Node.js Apps with PM2 (Complete Guide)
  • Launch PM2 in no daemon

Install Python

We will first use the apt package manager to install Python version 3.12 or later (up to version 3.13 tested) and its tools:

server$ sudo apt update
server$ sudo apt install python3-pip python3-dev python3-venv

Confirm that you’ve installed Python version 3.12 or later:

server$ python3 --version
# output:
Python 3.12 # or later

server$ sudo add-apt-repository ppa:deadsnakes/ppa
server$ sudo apt update
server$ sudo apt install python3.14 # for example

server$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3<TAB> 0 # TAB for autocompletion
server$ sudo update-alternatives --config python
# then type a selection number corresponding to the Python of choice.

Python virtual environment

Next install Python within a virtual environment for easier management.

• Create and change into a directory where you want to keep your chatterd project files:

  server$ mkdir ~/441/chatterd
  server$ cd ~/441/chatterd
  

• Within the project directory, create a Python virtual environment:

  server$ python3 -m venv venv
  

  This will create a directory called venv within your chatterd directory. Inside, it will install a local version of Python and a local version of pip. We can use this to install and configure an isolated Python environment for our project.

• Activate your virtual environment:

    server$ source venv/bin/activate
  

  Your prompt should change to indicate that you are now operating within a Python virtual environment. It will look something like this: (venv) ubuntu@YOUR_SERVER_IP:~/441/chatterd$.

  Henceforth we will represent the prompt as just (venv):chatterd$ to indicate being inside the Python virtual environment.

• Within your activated virtual environment, install the following packages, including the PostgreSQL adaptor, using the local instance of pip:

  (env):chatter$ pip install -U pip
  (env):chatterd$ pip install -U granian starlette fastapi 'psycopg[binary,pool]'
  

You now have all of the software packages needed by the Chatter backend.

chatterd app

Create a file called main.py:

(venv):chatterd$ vi main.py

We will put the server and URL routing code in main.py. Open and edit the file to add the following import lines:

from contextlib import asynccontextmanager
import handlers
from psycopg_pool import AsyncConnectionPool
from starlette.applications import Starlette
from starlette.routing import Route

In the lifespan() function, we set up a pool of open connections to our PostgreSQL chatterdb database. Maintaining a pool of open connections avoids the cost of opening and closing a connection on every database operation. The password used in creating AsyncConnectionPool must match the one you used when setting up Postgres earlier.

@asynccontextmanager
async def lifespan(server):
    server.pool = AsyncConnectionPool("dbname=chatterdb user=chatter password=chattchatt host=localhost", open=False)
    await server.pool.open()
    yield
    await server.pool.close()

We declare the routes global array to hold the URL routing information needed by Starlette server and define routes to serve Chatter’s first two APIs: HTTP GET requests with URL endpoint getchatts/ are routed to the getchatts() function and HTTP POST requests with endpoint postchatt/ are routed to the postchatt() function. With each route, we also specify which HTTP method is allowed for that URL endpoint:

# must include the trailing '/'
routes = [
    Route('/getchatts/', handlers.getchatts, methods=['GET']),
    Route('/postchatt/', handlers.postchatt, methods=['POST']),
]

Finally, construct the web server, server, providing it with the routes array and lifespan function defined above:

# must come after route definitions
server = Starlette(routes=routes, lifespan=lifespan)

handlers.py

We implement the URL path API handlers in handlers.py:

(venv):chatterd$ vi handlers.py

Start the file with the following imports:

from dataclasses import dataclass
from datetime import datetime
from fastapi.encoders import jsonable_encoder
import main
from psycopg.errors import StringDataRightTruncation
from starlette.responses import JSONResponse
from typing import Optional
from uuid import UUID

We define a Chatt class to help postchatt() deserialize JSON received from clients:

@dataclass
class Chatt:
    username: str
    message: str

The @dataclass annotations, among other things, automatically provides it with a replace() constructor, allowing us to deserialize incoming JSON object into the Chatt dataclass directly.

The handler getchatts() uses an open connection from the connection pool to query the database for stored chatts. We obtain and use the connection with its context manager that automatically commits all transactions if no exception has been raised. In the case of the cursor, its context manager releases any resources used. Once all the rows from the database are retrieved, we insert the resulting array of chatts into the response JSON object. We use jsonable_encoder() from the fastapi package to convert UUIDs present in the chatts into strings for JSONResponse(). Python’s built-in json.dumps() method cannot serialize UUIDs.

async def getchatts(request):
    try:
        async with main.server.pool.connection() as connection:
            async with connection.cursor() as cursor:
                await cursor.execute('SELECT username, message, id, time FROM chatts ORDER BY time DESC;')
                return JSONResponse(jsonable_encoder(await cursor.fetchall()))
    except Exception as err:
        print(f'{err=}')
        return JSONResponse(f'{type(err).__name__}: {str(err)}', status_code = 500)

Similarly, postchatt() receives a posted chatt in the expected JSON format, has it deserialized into the Chatt class, and inserts it into the database, using a connection from the pool. The UUID and time stamp of each chatt are automatically generated at insertion time.

async def postchatt(request):
    try:
        # loading json (not multipart/form-data)
        chatt = Chatt(**(await request.json()))
    except Exception as err:
        print(f'{err=}')
        return JSONResponse(f'Unprocessable entity: {str(err)}', status_code=422)

    try:
        async with main.server.pool.connection() as connection:
            async with connection.cursor() as cursor:
                await cursor.execute('INSERT INTO chatts (username, message, id) VALUES '
                    '(%s, %s, gen_random_uuid());', (chatt.username, chatt.message))
        return JSONResponse({})
    except StringDataRightTruncation as err:
        print(f'Message too long: {str(err)}')
        return JSONResponse(f'Message too long: {str(err)}', status_code = 400)
    except Exception as err:
        print(f'{err=}')
        return JSONResponse(f'{type(err).__name__}: {str(err)}', status_code = 500)

For more Python-PostgreSQL interaction, see Passing parameters to SQL queries.

Test run

To test run your server, launch your server from the command line:

(venv):chatterd$ sudo su
# You are now root, note the command-line prompt changed from '$' or '%' to '#'.
# You can do a lot of harm with all of root's privileges, so be very careful what you do.
server# source venv/bin/activate
(venv):chatterd# granian --host 0.0.0.0 --port 443 --interface asgi --ssl-certificate /home/ubuntu/441/chatterd.crt --ssl-keyfile /home/ubuntu/441/chatterd.key --access-log main:server
# Hit ^C to end the test
(venv):chatterd# exit
# So that you're no longer root.
server$

You can test your implementation following the instructions in the Testing Chatter APIs section.

References

• Python Modules can import each other cyclically
• Connection pools
• Handling UUID Serialization Error In Python 3
  • Integrating jsonable_encoder with JSONResponse
• PEP 557 – Data Classes
• Asynchronous Postgres with Python, FastAPI, and Psycopg 3
  • Creating an async connection with psycopg3
  • with statement
• SQL
• Granian
• Starlette
• FastAPI
  • JSON Compatible Encoder
• Exceptions

Install Rust

Note that GCP gives you 2 GB more disk space than AWS, which allows Rust to build dependencies without complaining of running out of space.

ssh to your server and install Rust:

server$ sudo apt install gcc          # cargo depends on gcc's linker
server$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
server$ rustup update

If you see:

rustup: Command not found.

try to logout from your server and ssh back to it again. If the problem persisted and you need help updating your PATH shell environment variable, please see a teaching staff.

The command rustup update is also how you can subsequently update your installation of Rust to a new version.

Cargo.toml

First create and change into a directory where you want to keep your chatterd package:

server$ cd ~/441
server$ cargo new chatterd
# output:
     Created binary (application) `chatterd` package   

This will create the ~/441/chatterd/ directory for you. Change to this directory and edit the file Cargo.toml to list all the 3rd-party libraries (crates in Rust-speak) we will be using.

server$ cd chatterd
server$ vi Cargo.toml

In Cargo.toml, add the following below the [dependencies] tag:

axum = "0.8.0-alpha.1"
axum-server = { version = "0.7.1", features = ["tls-rustls"] }
bb8 = "0.8.6"
bb8-postgres = "0.8.1"
chrono = { version = "0.4.38", features = ["serde"] }
postgres = { version = "0.19.9", features = ["with-chrono-0_4", "with-uuid-1"] }
serde = { version = "1.0.214", features = ["derive"] }
serde_json = "1.0.132"
tokio = { version = "1.41.1", features = ["full"] }
tokio-postgres = "0.7.12"
tower-http = { version = "0.6.1", features = ["trace"] }
tracing = "0.1.40"
tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }
uuid = { version = "1.11.0", features = ["v4", "macro-diagnostics", "serde"] }

chatterd package

In ~/441/chatterd/src/ the file main.rs has also been created for you. Edit the file:

server$ vi src/main.rs

and replace the existing lines in main.rs with the server and URL routing code, starting with the following use lines::

#![allow(non_snake_case)]
use axum::{
    handler::HandlerWithoutStateExt,
:    routing::{ get, post },
    Router,
};
use axum_server::tls_rustls::RustlsConfig;
use bb8::Pool;
use bb8_postgres::PostgresConnectionManager;
use std::{ net::SocketAddr, process };
use tokio_postgres::NoTls;
use tower_http::trace::{ DefaultMakeSpan, DefaultOnFailure, TraceLayer };
use tracing::Level;

pub mod handlers;

After listing all our imports, we export our module handlers, which we will define later.

In main(), we enable logging (tracing) and set up a pool of open connections to our PostgreSQL chatterdb database. Maintaining a pool of open connections avoids the cost of opening and closing a connection on every database operation. The password used in creating pgmanager must match the one you used when setting up Postgres earlier:

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt()
        .with_level(false)
        .with_target(false)
        .compact()
        .init();

    // setup connection pool for PostgreSQL
    let pgmanager = PostgresConnectionManager::new_from_stringlike(
        "host=localhost user=chatter password=chattchatt dbname=chatterdb",
        NoTls,
    )
    .map_err(|err| { eprintln!("{:?}", err); process::exit(1) })
    .unwrap();

    let pgpool = Pool::builder()
        .build(pgmanager)
        .await
        .map_err(|err| { eprintln!("{:?}", err); process::exit(1) })
        .unwrap();

Continuing inside the main() function, we next create a Router struct to hold the URL routing information needed by axum_server. We define routes to serve Chatter’s first two APIs: HTTP GET requests with URL endpoint getchatts/ are routed to the getchatts() function and HTTP POST requests with endpoint postchatt/ are routed to the postchatt() function. With each route, we implicit specify which HTTP method is allowed for that URL endpoint by providing handler only with the get(), post(), or other MethodRouter. The database connection pool, pgpool, is passed to all the URL handlers as Router’s State:

    let router = Router::new()
        .route("/getchatts/", get(handlers::getchatts))
        .route("/postchatt/", post(handlers::postchatt))
        .layer(
            // must be after all handlers to be traced
            TraceLayer::new_for_http()
                .make_span_with(DefaultMakeSpan::new().level(Level::INFO))
                .on_failure(DefaultOnFailure::new().level(Level::INFO)),
        )         
        .with_state(pgpool); // must always be last line in Router set up

The functions getchatts() and postchatt() will be implemented in handlers.rs later.

For now, staying in main.rs, in our main() function, we set up the axum_server:

• assign it the chatterd certificate and key we created earlier,
• bind it to the wildcard IP address (0.0.0.0, equivalent of any) and the default HTTPS port (443), and
• launch it (serve()) with the router struct instance above:

    // certificate and private key used with HTTPS
    let certkey = RustlsConfig::from_pem_file(
        "/home/ubuntu/441/chatterd.crt",
        "/home/ubuntu/441/chatterd.key",
    )
    .await
    .map_err(|err| { eprintln!("{:?}", err); process::exit(1) })
    .unwrap();

    // bind HTTPS server to wildcard IP address and default port number:
    let addr = SocketAddr::from(([0, 0, 0, 0], 443));
    tracing::info!("chatterd on https://{}", addr);
    // run the HTTPS server
    axum_server::bind_rustls(addr, certkey)
        .serve(router.into_make_service_with_connect_info::<SocketAddr>())
        .await
        .map_err(|err| { eprintln!("{:?}", err); process::exit(1) })
        .unwrap();
}

handlers module

We implement the URL path API handlers module in the handlers.rs:

server$ vi src/handlers.rs

Start the file with the following use imports:

#![allow(non_snake_case)]
use axum::{
    extract::{ ConnectInfo, Json, State },
    http::StatusCode,
};
use bb8::Pool;
use bb8_postgres::PostgresConnectionManager;
use chrono::{ DateTime, Local };
use serde::{ Deserialize, Serialize };
use serde_json::{ json, Value };
use std::{ net::SocketAddr };
use tokio_postgres::NoTls;
use uuid::Uuid;

type PGPool = Pool<PostgresConnectionManager<NoTls>>;

The type alias PGPool will be used as a short hand in the following.

We define a Chatt struct to help postchatt() deserialize JSON received from clients:

#[derive(Debug, Serialize, Deserialize)]
pub struct Chatt {
    username: String,
    message: String,
    id: Option<String>,    
    timestamp: Option<DateTime<Local>>,    
}

We add a number of logging functions to print to console results of handling each HTTP request and, in case of error, return a tuple of HTTP status code and error message:

fn logOk(clientIP: SocketAddr) {
    tracing::info!("{:?} | {:?} |", StatusCode::OK, clientIP);
}

fn logServerErr(clientIP: SocketAddr, errmsg: String) -> (StatusCode, String) {
    tracing::info!("{:?} | {:?} |", StatusCode::INTERNAL_SERVER_ERROR, clientIP);
    (StatusCode::INTERNAL_SERVER_ERROR, errmsg)
}

fn logClientErr(clientIP: SocketAddr, errcode: StatusCode, errmsg: String) -> (StatusCode, String) {
    tracing::info!("{:?} | {:?} |", errcode, clientIP);
    (errcode, errmsg)
}

The handler getchatts() uses an open connection from the connection pool to query the database for stored chatts.

pub async fn getchatts(
    State(pgpool): State<PGPool>,
    ConnectInfo(clientIP): ConnectInfo<SocketAddr>,
) -> Result<Json<Value>, (StatusCode, String)> {

    let chatterDB = pgpool
        .get()
        .await
        .map_err(|err| logServerErr(clientIP, err.to_string()))?;

    let mut chattArr: Vec<Vec<Option<String>>> = Vec::new();

    for row in chatterDB
        .query(
            "SELECT username, message, id, time FROM chatts ORDER BY time DESC",
            &[],
        )
        .await
        .map_err(|err| logServerErr(clientIP, err.to_string()))?
    {
        chattArr.push(vec![
            row.get(0),
            row.get(1),
            Some(row.get::<usize, Uuid>(2).to_string()),
            Some(row.get::<usize, DateTime<Local>>(3).to_string()),
        ]);
    }

    logOk(clientIP);
    Ok(Json(json!(chattArr)))
}

Similarly, postchatt() receives a posted chatt in the expected JSON format, has it deserialized into the Chatt struct, and inserts it into the database, using a connection from the pool. The UUID and time stamp of each chatt are automatically generated at insertion time.

pub async fn postchatt(
    State(pgpool): State<PGPool>,
    ConnectInfo(clientIP): ConnectInfo<SocketAddr>,
    Json(chatt): Json<Chatt>,
) -> Result<Json<Value>, (StatusCode, String)> {
    let chatterDB = pgpool
        .get()
        .await
        .map_err(|err| logServerErr(clientIP, err.to_string()))?;

    chatterDB
        .execute(
            "INSERT INTO chatts (username, message, id) VALUES ($1, $2, gen_random_uuid())",
            &[&chatt.username, &chatt.message],
        )
        .await
        .map_err(|err| logClientErr(clientIP, StatusCode::NOT_ACCEPTABLE, err.to_string()))?;

    logOk(clientIP);
    Ok(Json(json!({})))
}

Build and test run

To build your server:

server$ cargo build --release
server$ ln -s target/release/chatterd chatterd

  error: linking with cc failed: exit status: 1
  note: collect2: fatal error: ld terminated with signal 9 [Killed]

The first time around, it will take some time to download and build all the 3rd-party crates. Be patient.

Rust is a compiled language, like C/C++ and unlike Python, which is an interpreted language. This means you must run cargo build each and every time you made changes to your code, for the changes to show up in your executable.

To run your server:

server$ sudo ./chatterd
# Hit ^C to end the test

You can test your implementation following the instructions in the Testing Chatter APIs section.

References

• The Rust Programming Language the standard and best intro to Rust.
• axum
• axum_server
• axum_server::tls_rustls
• axum examples
• http::StatusCode see the list of Associated Constants on the left menu.
• axum::extract
• axum::Extension
• Serde JSON
• bb8 Pool
• Postgres with Rust
• postgres::types::FromSql
• chrono::DateTime
• http::Uri
• Loggin in Rust - How to Get Started

  • [Adding logging and tracing to an Axum App

    Rust](https://carlosmv.hashnode.dev/adding-logging-and-tracing-to-an-axum-app-rust)

  • Tracing .. a deep dive
• Error Handling in Rust
  • Recoverable Erros with Result
  • std::option::Option
  • std::result::Result