Example Rust

This repository provides a simple Hello-World example of an http-server written in rust, which in recent years has gained importance.

Requirements

• A bash terminal. Windows users can e.g. install this via https://gitforwindows.org.

• The justfile tool.

• Rust ~0.18.0 incl. the cargo package manager.

Important

We also require an installation of Zig for cross-compilation. This avoids gcc-compiler issues on your local machine, which the rust compiler requires to install some dependencies.

Ensure paths to the binaries have been set.

Tip

To verify, open a bash terminal and call.

just --version
# rust
rustup --version
rustc --version
cargo --version
# zig
zig version
# docker
docker version
docker compose version

Optional requirements

• Postman, also available as a VSCode extension.
• (necessary for docker usage) docker incl. the docker CLI.

Usage

Open a bash terminal and run:

just setup

This is only needed once. After this, adjust the values in the newly created .env files based on the template.

Direct usage

Open a bash terminal and run:

# compiles code and creates binary artefact in ./dist folder
just build
# execution
just run-binary # runs from binary
just run # runs from source code (this may involve recompiling dependencies / code)
# tests
just tests-unit
# linting
just prettify

Via docker

Start up the docker engine.

# compiles code and creates binary artefact in ./dist folder
just docker-build
# execution
just docker-run-binary # runs from binary created in container
just docker-run # runs from source code (this may involve recompiling dependencies / code)
# tests
just docker-utests # runs unit-tests within container
# linting
just prettify
# exploration
just explore {service} # service = one of build, run, run-binary, utests

Tip

Due to the volume mounting (see docker-compose.yaml), whilst "exploring" you can alter the source code and run the tests using the commands exactly as stated in Direct Usage.

Note

Changes performed whilst exploring the container will mostly be reverted (bar those performed on mounted volumes), once the container is exited.

Interaction with the Http-Server

Whilst "running" the compiled code (via either just run-binary, just run, just docker-run-binary, just docker-run; see above), the endpoints are exposed to the HTTP_PORT value set in your .env-file.

The exposed endpoints of the application can now be spoken to, e.g.

curl --request GET 'http://{HTTP_IP}:{HTTP_PORT}/api/ping'
curl --request POST 'http://{HTTP_IP}:{HTTP_PORT}/api/token' \
    --data '{"key1": value1, "key2", value2, ...}'

where {HTTP_IP} and {HTTP_PORT} are to be replaced by the values set in your .env-file. Alternatively, we recommend using Postman.

Clean up

To clean up build artefacts and dangling docker images, simply run

just clean

To be more thorough, you may wish to run

docker system prune

Warning

The latter command clears all docker images, containers, etc. not just for this project##

References

Some of the source code (see src/main.rs) was initially adapted from the code in @alfredodeza/rust-azure-function. In our repository, we refactored this and took things in a completely different direction. We wrote the task scripts (justfile), docker infrastructure, etc. completely independently.