Mobicoop V3 ad service
Go to file
Romain Thouvenin 5e449ad69a Prepare release 2.6 2024-05-07 10:42:54 +02:00
.gitlab/merge_request_templates copy file from v3 gitlab template repo 2024-02-05 19:16:00 +01:00
ci use node lts image for docker 2024-01-23 14:50:32 +01:00
prisma Add optional comment to Ad type and records #7409 2024-02-29 14:47:53 +01:00
src Listen to user.deleted events to delete the corresponding user ads 2024-04-26 12:31:16 +02:00
tests Listen to user.deleted events to delete the corresponding user ads 2024-04-26 12:31:16 +02:00
.dockerignore first commit 2023-05-03 13:43:21 +02:00
.editorconfig first commit 2023-05-03 13:43:21 +02:00
.env.dist secure broker 2023-12-18 15:31:39 +01:00
.env.test refactor 2023-06-02 09:49:19 +02:00
.eslintrc.js first commit 2023-05-03 13:43:21 +02:00
.gitignore first commit 2023-05-03 13:43:21 +02:00
.gitlab-ci.yml Use common test and build jobs 2024-04-03 08:51:29 +02:00
.prettierignore copy file from v3 gitlab template repo 2024-02-05 19:16:00 +01:00
.prettierrc first commit 2023-05-03 13:43:21 +02:00
Dockerfile use node lts image for docker 2024-01-23 14:50:32 +01:00
LICENSE first commit 2023-05-03 13:43:21 +02:00
README.md Update documentation about the delete command 2024-04-29 08:34:40 +02:00
docker-compose.ci.service.yml findAdByUuid, functional basic AdModule 2023-05-04 12:07:53 +02:00
docker-compose.ci.tools.yml findAdByUuid, functional basic AdModule 2023-05-04 12:07:53 +02:00
docker-compose.yml Expose the debugger in the dev container 2024-04-26 12:29:06 +02:00
jest-e2e.json first commit 2023-05-03 13:43:21 +02:00
nest-cli.json first commit 2023-05-03 13:43:21 +02:00
package-lock.json Prepare release 2.6 2024-05-07 10:42:54 +02:00
package.json Prepare release 2.6 2024-05-07 10:42:54 +02:00
tsconfig.build.json Fix tests path in build config 2024-04-26 10:57:45 +02:00
tsconfig.json pretty 2024-01-17 08:56:34 +01:00

README.md

Mobicoop V3 - Ad

Ad service for Mobicoop V3.

Requirements

You need Docker and its compose plugin.

You also need NodeJS installed locally : we strongly advise to install Node Version Manager and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).

The API will run inside a docker container, but the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint or Prettier with fix-on-save).

A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.

Installation

  • copy .env.dist to .env :

    cp .env.dist .env
    

    Modify it if needed.

  • install the dependencies :

    npm install
    
  • start the containers :

    docker compose up -d
    

    The app runs automatically on port 5006.

Database migration

Before using the app, you need to launch the database migration (it will be launched inside the container) :

npm run migrate

Usage

The app exposes the following gRPC services :

  • FindById : find an ad by its id

    {
        "id": "80126a61-d128-4f96-afdb-92e33c75a3e1"
    }
    
  • FindAllByIds : find all ads for the given ids

    {
        "ids": [
            "80126a61-d128-4f96-afdb-92e33c75a3e1",
            "80126a61-d128-4f96-afdb-92e33c75a3e2",
            "80126a61-d128-4f96-afdb-92e33c75a3e3"
        ]
    }
    
  • FindAllByUserId : find all ads for the given user id

    {
        "id": "80c9bb02-0931-4a1d-bea6-22d358992245"
    }
    
  • Create : create an ad

    Punctual driver ad :

    {
        "userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
        "driver": true,
        "passenger": false,
        "seatsProposed": 3,
        "frequency": "PUNCTUAL",
        "fromDate": "2023-01-15",
        "toDate": "2023-01-15",
        "schedule": [
            {
                "day": 0,
                "time": "09:00",
                "margin": 900
            }
        ],
        "waypoints": [
            {
                "position": 0,
                "lon": 48.689445,
                "lat": 6.17651,
                "houseNumber": "5",
                "street": "Avenue Foch",
                "locality": "Nancy",
                "postalCode": "54000",
                "country": "France"
            },
            {
                "position": 1,
                "lon": 48.8566,
                "lat": 2.3522,
                "locality": "Paris",
                "postalCode": "75000",
                "country": "France"
            }
        ],
        "comment": "I'm flexible with the departure time"
    }
    

    Punctual driver and passenger ad :

    {
        "userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
        "driver": true,
        "passenger": true,
        "seatsProposed": 3,
        "seatsRequested": 1,
        "frequency": "PUNCTUAL",
        "fromDate": "2023-01-15",
        "toDate": "2023-01-15",
        "schedule": [
            {
                "day": 0,
                "time": "09:00",
                "margin": 900
            }
        ],
        "waypoints": [
            {
                "position": 0,
                "lon": 48.689445,
                "lat": 6.17651,
                "houseNumber": "5",
                "street": "Avenue Foch",
                "locality": "Nancy",
                "postalCode": "54000",
                "country": "France"
            },
            {
                "position": 1,
                "lon": 48.8566,
                "lat": 2.3522,
                "locality": "Paris",
                "postalCode": "75000",
                "country": "France"
            }
        ],
        "comment": "I'm flexible with the departure time"
    }
    

    Recurrent passenger ad :

    {
        "userId": "80c9bb02-0931-4a1d-bea6-22d358992245",
        "passenger": true,
        "seatsRequested": 1,
        "frequency": "RECURRRENT",
        "fromDate": "2023-01-15",
        "toDate": "2023-12-31",
        "schedule": [
            {
                "day": 1,
                "time": "07:00",
                "margin": 600
            },
            {
                "day": 2,
                "time": "07:05",
                "margin": 600
            },
            {
                "day": 5,
                "time": "07:10",
                "margin": 600
            }
        ],
        "waypoints": [
            {
                "position": 0,
                "lon": 48.689445,
                "lat": 6.17651,
                "houseNumber": "5",
                "street": "Avenue Foch",
                "locality": "Nancy",
                "postalCode": "54000",
                "country": "France"
            },
            {
                "position": 1,
                "lon": 48.8566,
                "lat": 2.3522,
                "locality": "Paris",
                "postalCode": "75000",
                "country": "France"
            }
        ],
        "comment": "I'm flexible with the departure time"
    }
    

    The list of possible options when creating an ad :

    • userId: the user id (as a uuid)
    • driver (boolean): if the ad is a driver ad. Note that at least a role must be set to true (driver and/or passenger).
    • passenger (boolean): if the ad is a passenger ad. Note that at least a role must be set to true (driver and/or passenger).
    • frequency: PUNCTUAL or RECURRENT
    • fromDate: start date for recurrent ad, carpool date for punctual ad
    • toDate: end date for recurrent ad, same as fromDate for punctual ad
    • schedule: an array of schedule items, a schedule item containing :
      • the week day as a number, from 0 (sunday) to 6 (saturday)
      • the departure time (as HH:MM)
      • the margin around the departure time in seconds
    • seatsProposed: number of seats proposed as driver (required if driver is true)
    • seatsRequested: number of seats requested as passenger (required if passenger is true)
    • strict (boolean): if set to true, allow matching only with similar frequency ads
    • waypoints: an array of addresses that represent the waypoints of the journey (only first and last waypoints are used for passenger ads). Note that positions are required and must be consecutives
    • comment: optional freetext comment / description about the ad
  • Delete : Delete permanently an ad

    {
        "id": "80126a61-d128-4f96-afdb-92e33c75a3e1"
    }
    

Messages

Handled

The service listens to these RabbitMQ messages:

  • user.deleted (to delete the associated ads)

Emitted

As mentionned earlier, RabbitMQ messages are sent after these events :

  • ad.created (message: the created ad informations)
  • ad.deleted (message: the id of the deleted ad)

Tests / ESLint / Prettier

Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone). The integration tests use a dedicated database (see db-test section of docker-compose.yml).

# run all tests (unit + integration)
npm run test

# unit tests only
npm run test:unit

# integration tests only
npm run test:integration

# coverage
npm run test:cov

# ESLint
npm run lint

# Prettier
npm run pretty

License

Mobicoop V3 - Ad Service is AGPL licensed.