Forseti

Introduction

Forseti is the god of justice and reconciliation in Norse mythology. We use it like this for the navitia project. It aims to give jormungandr with realtime data provided by external services.
The complexity of reading is masked by this one to provide a simple output webservice. Several methods is used to catch the realtime data :

Read files on a Ftp server (Xml, json, csv, etc...)
Call an external Api

Architecture

Written in

Forseti is written in Go.

APIs

Each service is exposed like an API. The web API is powered by gin.
The API list is as follows :

/status exposes general information about the webservice
/metrics exposes metrics in the prometheus text format
/departures returns the next departures for a stop (parameter stop_id). doc
/parkings/P+R returns real time parkings data. (with an optional list parameter of ids[])
/equipments returns informations on Equipments in StopAreas. doc
/free_floatings?coord=2.37715%3B48.846781 returns informations on freefloatings within a certain radius as a crow flies from the point
/vehicle_occupancies returns occupany of a vehicles at a stop. doc

For each service, a goroutine is created to handle the refresh of the data by downloading them every refresh-interval (default: 30s) and load them. Once these data have been loaded there is swap of pointer being done so that every new requests will get the new dataset.

Options

Sometimes, options exists to active/Deactivate the periodic refresh of data for the Api.
/free_floatings and /vehicle_occupancies dispose of that:

/status?free_floatings=false deactivates the periodic refresh of data for api /free_floatings
/status?vehicle_occupancies=false deactivates the periodic refresh of data for api /vehicle_occupancies

After the deactivation the service keeps working with the last loaded data.

Build

To build this project you need at least go 1.15
Dependencies are handled by go modules as such it is recommended to not checkout this in your GOPATH.

To build the project you just need to run the following command, at the root of the project:

make build

If you want to run the tests:

make test

Run it

Forseti run with a bunch of input parameters:

./forseti -h

For each Api, you need to provide several parameters to load it. These parameters are described within the concerned Api doc. See above
As an example, for the equipment API:

./forseti --equipments-uri file:///forseti/fixtures/NET_ACCESS.XML --equipments-refresh=1s

With Docker

Use the pre-built docker image: navitia/forseti Several tags exists:

release/latest - The main tag. This is the last stable version
X.X.X - Each main version is tagged with a num
master - The current branch of development

A docker compose is available for a local run.

docker-compose --compatibility up

connect to : http://127.0.0.1:8088

You have to tweak the environment section for the occupancy Api.
The directory ~/workspace/data/forseti must contain the data necessary: extraction_courses.csv and mapping_stops.csv

Contribute

To contribute, create a Github PR from your fork, we will please to read your contribution.
Don't forget to lint and format your code before to push, otherwise the CI will be merciless with you.

Install the linter.

# Install linter
make linter-install

Now you can

# Run linter
make lint

# Run formatting
make fmt

AzHicham / forseti