README.md

iracelog-service-manager-go

This repository contains the service backend for processing gRPC messages of the iRacelog project.

This project is the replacement of Python implementation of iracelog-service-manager in the iRacelog project

Initial Setup

This section is intended to help developers and contributors get a working copy of iracelog-service-manager-go on their end

Clone this repository

git clone https://github.com/mpapenbr/iracelog-service-manager-go
cd iracelog-service-manager-go

Option: Devcontainer with VS Code (recommended)

After cloning the repository you already changed into the project dir iracelog-service-manager-go.

Enter

code .

to fire up VS Code. VS Code will detect the Devcontainer configuration and ask wheter to restart the folder using the devcontainer. Please confirm. After downloading and configuring the container with the required tools and VS code plugins you're (almost) ready to go.

Option: Do you own setup

Install golangci-lint from the official website for your OS

Local Development

This section will guide you to setup a fully-functional local copy of iracelog-service-manager-go on your end and teach you how to use it! Make sure you have installed golangci-lint before following this section!

Note: This section relies on the usage of Makefile. If you can't (or don't) use Makefile, you can follow along by running the internal commands from iracelog-service-manager-go's Makefile (most of which are OS-independent)!

Installing dependencies

To install all dependencies associated with iracelog-service-manager-go, run the command

make install

Setting up pre-commit

For a watered-down explanation, pre-commit hooks are an abstraction over git-hooks, allowing you to define a series of commands (or checks), that would be automatically run every time you use the git commit command.

The pre-commit hooks used by iracelog-service-manager-go are located within the .pre-commit-config.yml file. These hooks are configured to run;

• Series of basic checks (JSON, YAML, XML file schema validation)
• Checks for merge conflicts, and possible leaks of private keys
• File formatters - whitespace trimming, end-of-file fixers
• Checks for executable scripts
• JSON formatters
• Code Formatters
• Test-suite

To install pre-commit, simply use the Makefile command

make local-setup

Note: To install (and use) pre-commit, make sure you have the latest stable versions of Python and pip installed!

The Makefile command will install pre-commit on your PC, and attach it to git hooks -- ensuring pre-commit checks are run every time you use the git commit command!

Using pre-commit

The previous section guided you to install pre-commit, ensuring pre-commit runs implicitly *before every commit*.

However, if needed, you can use the run command to forcibly run pre-commit on all staged files (i.e. files in staging area in git).

To manually run pre-commit on all files (including unstaged files), use

pre-commit run --all-files

Using Code Formatters

Code formatters format your code to match pre-decided conventions. To run automated code formatters, use the Makefile command

make codestyle

Using Code Linters

Linters are tools that analyze source code for possible errors. This includes typos, code formatting, syntax errors, calls to deprecated functions, potential security vulnerabilities, and more!

To run pre-configured linters, use the command

make lint

Running Tests

Tests in iracelog-service-manager-go are classified as fast and slow - depending on how quick they are to execute.

To selectively run tests from either test group, use the Makefile command

make fast-test

OR

make slow-test

Alternatively, to run the complete test-suite -- i.e. fast and slow tests at one go, use the command

make test

Running the Test-Suite

The test-suite is simply a wrapper to run linters, stylecheckers and all tests at once!

To run the test-suite, use the command

make test-suite

In simpler terms, running the test-suite is a combination of running linters and all tests one after the other!

Additional Resources

TLS management

In general the app is designed to run behind a proxy. The proxy takes care about the TLS termination. In the productive environment this is done by Traefik using Let's encrypt certificates.

There is another entry point available bypassing the proxy. This entry point is dedicated for the racelogger and can be used with self signed certificates or by using the Let's encrypt certs.

Param	Description	Usage
--tls-server-addr	gRPC server listen address (TLS)	Traefik + Self-signed
--tls-ca	file containing the root certificate	Self-signed
--tls-key	file containing the server key	Self-signed
--tls-cert	file containing the server cert	Self-signed
--traefik-certs	file containing LE-cert managed by Traefik	Traefik
--traefik-cert-domain	the domain containing the cert	Traefik

Self signed

The createCerts.sh script shows an example for creating the required files for both server and client certs to be used for localhost. The generated rootCA.pem needs to configured on both sides, server and client.

Note: You have to adjust the localhost value to the destination host when generating the cert.

Makefile help

Tap for a list of Makefile commands

Command	Description	Prerequisites
help	Generate help dialog listing all Makefile commands with description	NA
local-setup	Setup development environment locally	python, pip
install	Fetch project dependencies	NA
codestyle	Run code-formatters	golangci-lint
lint	Check codestyle and run linters	golangci-lint
test	Run all tests	NA
fast-tests	Selectively run fast tests	NA
slow-tests	Selectively run slow tests	NA
test-suite	Check codestyle, run linters and all tests	golangci-lint
run	Run iracelog-service-manager-go	NA

Optionally, to see a list of all Makefile commands, and a short description of what they do, you can simply run

make

Which is equivalent to;

make help

Both of which will list out all Makefile commands available, and a short description of what they do!

Generating Binaries

To generate binaries for multiple OS/architectures, simply run

goreleaser build

The command will generate binaries for Linux, Windows and Mac targetting multiple architectures at once! The binaries, once generated will be stored in the dist directory inside the project directory.

Adjust the .goreleaser.yml to fit your needs.

See goreleaser for details.

Generating Images

goreleaser is also used to create archives and docker images. This can be done by

goreleaser release

The current .goreleaser.yml is target for creating docker images and artefacts to be created by Github actions.

Running iracelog-service-manager-go

To run iracelog-service-manager-go, use the command

make run

Additionally, you can pass any additional command-line arguments (if needed) as the argument "q". For example;

make run q="--help"

OR

make run q="--version"

Releases

You can check out a list of previous releases on the Github Releases page.

Semantic versioning with Release Drafter

What is Semantic Versioning?

Semantic versioning is a versioning scheme aimed at making software management easier. Following semantic versioning, version identifiers are divided into three parts;

    <major>.<minor>.<patch>

MAJOR version when you make incompatible API changes [breaking changes]
MINOR version when you add functionality in a backwards compatible manner [more features]
PATCH version when you make backwards compatible bug fixes [bug fixes and stuff]

For a more detailed description, head over to semver.org

Release Drafter automatically updates the release version as pull requests are merged.

Labels allowed;

• major: Affects the <major> version number for semantic versioning
• minor, enhancement, update, feature: Affects the <minor> version number for semantic versioning
• all other labels affect the <patch> version number

Whenever a pull request with one of these labels is merged to the main branch, the corresponding version number will be bumped by one digit!

List of Labels

Pull requests once merged, will be classified into categories by release-drafter based on pull request labels

This is managed by the release-drafter.yml config file.

Label	Title in Releases
security	🔒 Security
enhancement, feature, update	🚀 Updates
bug, bugfix, fix	🐛 Bug Fixes
documentation, docs	📝 Documentation
wip, in-progress, incomplete, partial, hotfix	🚧 Work in Progress
dependencies, dependency	📦 Dependencies
refactoring, refactor, tests, testing	🧪 Tests and Refactor
build, ci, pipeline	🤖 CI/CD and Pipelines

The labels bug, enhancement, and documentation are automatically created by Github for repositories. Dependabot will implicitly create the dependencies label with the first pull request raised by it.

The remaining labels can be created as needed!

Credits

iracelog-service-manager-go is powered by a template generated using cookiecutter-go which is based on go-template