avy

[![coverage report](https://gricad-gitlab.univ-grenoble-alpes.fr/OSUG/RESIF/avy/badges/main/coverage.svg)](https://gricad-gitlab.univ-grenoble-alpes.fr/OSUG/RESIF/avy/-/commits/main)

# Avy

This is an implementation of the FDSN availability web service following the specifications at https://www.fdsn.org/webservices/fdsnws-availability-1.0.pdf

It is intended to work with a database table populated with the [mseedindex](https://github.com/EarthScope/mseedindex/) tool.

# Usage

## Environment variables
The service is configured by environment variables:
### Mandatory

  * `AVY_DB_USER`: the user connecting to the postgres database
  * `AVY_DB_PASS`: Password for connecting to the postgres database
  * `AVY_DB_HOST`: Hostname of the postgres service
  * `AVY_DB_NAME`: Name of the database
  
### Optional
  * `AVY_POST_MAX_LINES`: Maximum lines accepted in the POST requests (default: 300)
  * `AVY_LIMIT`: If the number of channels x days exceeds this limit, Avy will reply a 419 too much data.
  * `AVY_URL_PREFIX`: The URL prefix where the service is accessible (default: "fdsnws/availability/1/").

### Reporting to Sentry

  * `SENTRY_DSN`: The DSN of the sentry server with application token
  * `SENTRY_ENVIRONMENT`: The deployment name (for instance "production")

## Running

A docker container is provided, you can get the image at ''gricad-registry.univ-grenoble-alpes.fr/osug/resif/avy/avy''

To build it yourself, clone the repository and run:

    MIX_ENV=prod mix release
    
The executable is available at `_build/avy/prod/avy`

# Developers

All contributions are welcome. Clone the project, create merge requests.

## Conception

The availability system relies on a database populated by miniseed data indexation and metadata ingestions. The database is managed by the project osug/resif/sigma> 

### Database schema

Avy has all migration schemas embedded, but in production, avy should not manage the schema, as there should be another application responsible for data ingestion, which should be responsible for the schema management.

Database migration schemas are here in order to make sure tests will pass seamlessly.

### Run the tests

For the local tests to succeed you need a running postgresql instance (example with podman).

    podman run -d -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres
    mix coverall
    
### Build 

    MIX_ENV=dev mix release

## Code presentation

Based on the Phoenix framework, almost all the logic lies in two files:

  * `lib/avy_web/controllers/avy_controller.ex` : It is the controller part that will manipulate the user's request. It fetches the information from `Avy.Repo` and does the merging logic.
  * `lib/avy/avy_repo.ex`: this is the interface with the relational database backend. It has basically one function that creates the SQL request and returns a list of "contents".
  
Others important parts:

  * the data model is in `lib/avy/data` and `lib/avy/metadata`
  * the analyse of the user's request is made through the external library osug/resif/fdsn_plugs>
  
# Special thanks

  * Chad Trabant from EarthScope for the [mseedindex](https://github.com/EarthScope/mseedindex/) tool
  * Sentry.io for providing the full features account "OSUG" for free because this is an academic project
  * Developers and maintainers of the external libraries this tool relies on:
    - Phoenix,
    - Postgrex,
    - Ecto, 
    - Bandit,
    
    See mix.exs for an exhausive list.