README.md

WeeSVC Gorilla

Implementation of the WeeSVC application using Go and the Gorilla Mux web toolkit.

Ingredients

The following external libraries were directly utilized in this project.

Package	Link	Description
Go	https://golang.org/	Well...it's obvious isn't it?!
Gorilla Mux	https://www.gorillatoolkit.org/pkg/mux	Web Toolkit providing HTTP server and routing
GORM	https://gorm.io/	Database ORM
SQLite	https://www.sqlite.org/index.html	The lightweight database
Postgres	https://www.postgresql.org/	An advanced opensource relational database
Cobra	https://github.com/spf13/cobra	Command-line library
Viper	https://github.com/spf13/viper	Awesome configuration library for settings
UUID	https://github.com/google/uuid	Implementation for generation of universally unique identifiers (UUIDs)

Build

Builds are performed using the Makefile provided in the project root.

CLI

In order to build the CLI, you will need to have Go (1.22+) installed on your system.

The default target for the Makefile will perform several tasks:

• organize imports using goimports
• format code using gofmt
• vet code for errors using go vet
• compile binary for the current platform

Note

To initially build the project, you may need to run the make setup command to install the tools utilized for builds.

Once built using make, you can migrate the database scripts and run the application:

bin/weesvc migrate; bin/weesvc serve

Once started, you can even access the new user interface via http://localhost:9092/.

Docker

For those who do not have Go available, Docker is an option to build the application and run the application within a container. Using the make build-docker command will build the application within a Linux container, then copy the resulting binary into a slim docker image to utilize for execution.

Once the image is available, you can simply run the provided script which will open a browser to access the service at http://localhost:9092/api/hello .

./docker-run.sh

Caution

The docker-run.sh script will not maintain state between executions. This means each time you start the container, you will be starting with a freshly created sqlite3 database.

Using the Application

Update the DatabaseURI setting in your config.yaml for the absolute path to the base project directory, i.e. the path for the directory containing this README.

Tip

Use the very cool HTTPie application for testing locally from the command-line.

Execute a GET command to retrieve the available places from the database.

http GET :9092/api/places

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: application/json
Date: Sat, 25 Jan 2020 05:33:57 GMT

[]

Add a place into the database using a POST command.

http POST :9092/api/places name=NISC description="NISC Lake St. Louis Office" latitude:=38.7839 longitude:=90.7878

HTTP/1.1 200 OK
Content-Length: 8
Content-Type: application/json
Date: Sat, 25 Jan 2020 05:34:08 GMT

{
    "id": 1
}

Run the GET command again to retrieve places which now include your newly added place!

http GET :9092/api/places/1

HTTP/1.1 200 OK
Content-Length: 217
Content-Type: application/json
Date: Sat, 25 Jan 2020 05:34:18 GMT

[
    {
        "created_at": "2020-01-24T23:34:08.491999-06:00",
        "description": "NISC Lake St. Louis Office",
        "id": 1,
        "latitude": 38.7839,
        "longitude": 90.7878,
        "name": "NISC",
        "updated_at": "2020-01-24T23:34:08.491999-06:00"
    }
]

Use the PATCH command to update a specific value. For example, we'll update the Description as follows:

http PATCH :9092/api/places/1 description="Lake St. Louis"

HTTP/1.1 200 OK
Content-Length: 203
Content-Type: application/json
Date: Sat, 25 Jan 2020 18:13:13 GMT

{
    "created_at": "2020-01-24T23:34:08.491999-06:00",
    "description": "Lake St. Louis",
    "id": 1,
    "latitude": 38.7839,
    "longitude": 90.7878,
    "name": "NISC",
    "updated_at": "2020-01-25T12:13:13.351201-06:00"
}

This returns the newly "patched" version of the place. Next we'll remove the row using the DELETE method.

http DELETE :9092/api/places/1

HTTP/1.1 200 OK
Content-Length: 21
Content-Type: application/json
Date: Sat, 25 Jan 2020 18:15:16 GMT

{
    "message": "removed"
}

API Compliance

A core requirement for all WeeSVC implementations is to implement the same API which are utilized for benchmark comparisons. To ensure compliance with the required API, k6 is utilized within the Workbench project.

To be a valid service, the following command MUST pass at 100%:

k6 run -e PORT=9092 https://raw.githubusercontent.com/weesvc/workbench/main/scripts/api-compliance.js

User Interface Development

To experiment with Templ and HTMX, we incorporated a user interface into this implementation.

In order to work on the UI, run the make develop target to start the server in "live reload"-mode.

If you'd like to hear more about this addition, check out the presentation about it: