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
Forseti is written in Go.
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 (parameterstop_id
). doc/parkings/P+R
returns real time parkings data. (with an optional list parameter ofids[]
)- /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.
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.
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
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
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
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