Mobicoop V3 - Matcher

Mobility matching 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 5005.

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 :

• Match : find matching ads corresponding to the given criteria

  For example, as a passenger, to search for drivers for a punctual carpool :

  {
      "driver": false,
      "passenger": true,
      "frequency": "PUNCTUAL",
      "algorithmType": "PASSENGER_ORIENTED",
      "fromDate": "2024-06-05",
      "toDate": "2024-06-05",
      "schedule": [
          {
              "time": "07:30"
          }
      ],
      "waypoints": [
          {
              "houseNumber": "23",
              "street": "rue de viller",
              "postalCode": "54300",
              "locality": "Lunéville",
              "lon": 6.490527,
              "lat": 48.590119,
              "country": "France",
              "position": 0
          },
          {
              "houseNumber": "3",
              "street": "rue du passage",
              "postalCode": "67117",
              "locality": "Ittenheim",
              "lon": 7.594361,
              "lat": 48.603004,
              "country": "France",
              "position": 1
          }
      ]
  }
  

  As a passenger, to search for drivers for a recurrent carpool :

  {
      "driver": false,
      "passenger": true,
      "frequency": "RECURRENT",
      "algorithmType": "PASSENGER_ORIENTED",
      "fromDate": "2024-01-02",
      "toDate": "2024-06-30",
      "strict": true,
      "page": 1,
      "perPage": 5,
      "schedule": [
          {
              "day": 1,
              "time": "07:30"
          },
          {
              "day": 2,
              "time": "07:45"
          },
          {
              "day": 4,
              "time": "07:30"
          },
          ,
          {
              "day": 5,
              "time": "07:30"
          }
      ],
      "waypoints": [
          {
              "houseNumber": "298",
              "street": "Aveue de la liberté",
              "postalCode": "86180",
              "locality": "Buxerolles",
              "lon": 0.364394,
              "lat": 46.607501,
              "country": "France",
              "position": 0
          },
          {
              "houseNumber": "1",
              "street": "place du 8 mai 1945",
              "postalCode": "47310",
              "locality": "Roquefort",
              "lon": 0.559606,
              "lat": 44.175994,
              "country": "France",
              "position": 1
          }
      ]
  }
  

  The list of possible criteria :

  • id (optional): the id of a previous matching result (as a uuid)

  • driver (boolean, optional): to search for passengers (default : false)

  • passenger (boolean, optional): to search fo drivers (default : true)

  • frequency: the frequency of the search (PUNCTUAL or RECURRENT)

  • strict (boolean, optional): if set to true, allow matching only with similar frequency ads (default : false)

  • 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 optional array of schedule items, a schedule item containing :

    • the week day as a number, from 0 (sunday) to 6 (saturday) if the ad is recurrent (default to fromDate day for punctual search)

    • the departure time (as HH:MM)

    • the margin around the departure time in seconds (optional) (default : 900)

      If the schedule is not set, the driver departure time is guessed to be the ideal departure time to reach the passenger, and the passenger departure time is guessed to be the ideal pick up time for the driver

  • seatsProposed (integer, optional): number of seats proposed as driver (default : 3)

  • seatsRequested (integer, optional): number of seats requested as passenger (default : 1)

  • 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

  • excludedAdId (optional): the id of an ad to be excluded from the results (useful to avoid self-matchings)

  • algorithmType (optional): the type of algorithm to use (as of 2023-09-28, only the default PASSENGER_ORIENTED is accepted)

  • remoteness (integer, optional): an integer to indicate the maximum flying distance (in metres) between the driver route and the passenger pick-up / drop-off points (default : 15000)

  • useProportion (boolean, optional): a boolean to indicate if the matching algorithm will compare the distance of the passenger route against the distance of the driver route (default : 1). Works in combination with proportion parameter

  • proportion (float, optional): a fraction (float between 0 and 1) to indicate minimum proportion of the distance of the passenger route against the distance of the driver route (default : 0.3). Works in combination with use_proportion parameter

  • useAzimuth (boolean, optional): a boolean to indicate if the matching algorithm will use the azimuth of the driver and passenger routes (default : 1)

  • azimuthMargin (integer, optional): an integer (representing the number of degrees) to indicate the range around the opposite azimuth to consider the candidate route excluded (default : 10)

  • maxDetourDistanceRatio (float, optional): a fraction (float between 0 and 1) of the driver route distance to indicate the maximum detour distance acceptable for a passenger (default : 0.3)

  • maxDetourDurationRatio (float, optional): a fraction (float between 0 and 1) of the driver route duration to indicate the maximum detour duration acceptable for a passenger (default : 0.3)

  • page (integer, optional): the page of results to display (default : 1)

  • perPage (integer, optional): the number of results to display per page (default : 10)

If the matching is successful, you will get a result, containing :

• id: the id of the matching; as matching is a time-consuming process, results are cached and thus accessible later using this id (pagination works as well !)
• total: the total number of results
• page: the number of the page that is returned (may be different than the number of the required page, if number of results does not match with perPage parameter)
• perPage: the number of results per page (as it may not be specified in the request)
• data: an array of the results themselves, each including:
  • adId: the id of the ad that matches
  • role: the role of the ad owner in that match
  • distance: the distance in metres of the resulting carpool
  • duration: the duration in seconds of the resulting carpool
  • initialDistance: the initial distance in metres for the driver
  • initialDuration: the initial duration in seconds for the driver
  • distanceDetour: the detour distance in metres
  • durationDetour: the detour duration in seconds
  • distanceDetourPercentage: the detour distance in percentage of the original distance
  • durationDetourPercentage: the detour duration in percentage of the original duration
  • journeys: the possible journeys for the carpool (one journey for punctual carpools, one or more journeys for recurrent carpools), each including:
    • day: the week day for the journey, as a number, from 0 (sunday) to 6 (saturday)
    • firstDate: the first possible date for the journey
    • lastDate: the last possible date for the journey
    • steps: the steps of the journey (coordinates with distance, duration and actors implied), each including:
      • distance: the distance to reach the step in metres
      • duration: the duration to reach the step in seconds
      • lon: the longitude of the point for the step
      • lat: the longitude of the point for the step
      • time: the driver time at that step
      • actors: the actors for that step:
        • role: the role of the actor (DRIVER or PASSENGER)
        • target: the meaning of the step for the actor:
          • START for the first point of the actor
          • FINISH for the last point of the actor
          • INTERMEDIATE for a driver intermediate point
          • NEUTRAL for a passenger point from the point of view of a driver

Results caching

Matching is a time-consuming process, so the results of a matching request are stored in cache before being paginated and returned to the requester. An id is attributed to the overall results of a request : on further requests (for example to query for different pages of results), the requester can provide this id and get in return the cached data, avoiding another longer process of computing the results from scratch. Obviously, new computing must be done periodically to get fresh new results !

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 - Matcher Service is AGPL licensed.