pagarme / superbowleto

:football: A microservice to issue, register and manage boletos
MIT License
5 stars 0 forks source link
acceptance boleto microservice sec-squad-gateways sec-tribo-payments

superbowleto

Build Status Quality Gate Status Security Rating Reliability Rating Bugs Maintainability Rating Vulnerabilities Code Smells Lines of Code Coverage Duplicated Lines (%) Technical Debt

:football: A microservice to issue, register and manage boletos

Table of Contents

Technology

Here's a brief overview of our technology stack:

Developing

In order to develop for this project you must have Docker and Docker Compose installed.

First Install

If you never developed in this repo before:

  1. Clone the repository:
$ git clone git@github.com:pagarme/superbowleto
  1. Build the base images:
$ docker-compose build superbowleto-web

Running the server

To run the server, you will have to start the database and run the migrations.

  1. Start database and run migrations in one command:
$ make setup-db
  1. Or start database and run migrations separately:
  1. Then finally run the server:
$ make superbowleto-web

Running tests

Tests are separate in functional, integration and unit. You can either run them separately or run them all.

For the CI purposes we have a specif command that will generate coverage report and xml test results report to be published at the CircleCI.

$ docker-compose run --entrypoint="npm run test-ci" test --abort-on-container-exit

Installing new dependencies

We install our dependencies (aka npm dependencies) inside the Docker image (see our Dockerfile to understand it better).

This gives us the advantage of caching the dependencies installation process, so when we build the image again, it's already cached by Docker and the image can be easily distributed with all its dependencies installed.

However, if you need to install any new dependency, you must rebuild the image, otherwise, your dependency will not be available inside the container.

You can install dependencies and rebuild the image by running:

$ docker-compose run test npm install --save ramda
$ docker-compose build test

Testing

Tests are found inside the test/ directory and are separate by type: functional, integration and unit. It's also common to have some helpers folders alongside the tests.

Data Flow

This project has two programs, the worker and the server.

Server

This section documents what every endpoint of the server does.

1. POST /boletos

Create a new boleto.

After creating the boleto (on our database), we will try to register the boleto withing the provider. Here, there's two possible outcomes: a) the provider could be reached, could process the boleto and gave us a status (either registered or refused); or b) the provider could not be reached or could not process the boleto (giving us an unknown/undefined/try_later status).

a) Provider could process the boleto

The following steps illustrate the case where the provider could be reached and it could process the boleto.

  1. The Client makes an HTTP request to create a boleto.
  2. We create the boleto in the Database with status issued.
  3. We try to register the boleto within the Provider.
  4. The provider returns an answer (either registered or refused).
  5. We update the boleto status in the Database.
  6. We return the response to the Client (HTTP response).

1a-post-boletos-diagram

Diagram built with mermaid.js. Check out the source code at docs/diagrams/server

b) Provider could not process the boleto

The following steps illustrate the case where the provider could be reached and it could process the boleto.

  1. The Client makes an HTTP request to create a boleto.
  2. We create the boleto in the Database with status issued.
  3. We try to register the boleto within the Provider.
  4. The provider could not be reached or could not process the boleto.
  5. We update the boleto status in the Database to pending_registration.
  6. We send the boleto (boleto_id and issuer) to an SQS queue called boletos-to-register. This queue will be processed by the worker later.
  7. We return the response to the Client (HTTP response) with the status = pending_registration.

1b-post-boletos-diagram

Diagram built with mermaid.js. Check out the source code at docs/diagrams/server

Example:

POST /boletos

Content-Type: application/json

{
  "queue_url": "http://yopa/queue/test",
  "expiration_date": "Tue Apr 18 2017 18:46:59 GMT-0300 (-03)",
  "amount": 2000,
  "instructions": "Please do not accept after expiration_date",
  "issuer": "bradesco",
  "payer_name": "David Bowie",
  "payer_document_type": "cpf",
  "payer_document_number": "98154524872"
}

201 Created

Content-Type: application/json

{
  "queue_url": "http://yopa/queue/test",
  "status": "issued | registered | refused",
  "expiration_date": "Tue Apr 18 2017 18:46:59 GMT-0300 (-03)",
  "amount": 2000,
  "instructions": "Please do not accept after expiration_date",
  "issuer": "bradesco",
  "issuer_id": null,
  "title_id": "null",
  "payer_name": "David Bowie",
  "payer_document_type": "cpf",
  "payer_document_number": "98154524872"
}

2. GET /boletos

Retrieve all boletos.

2-get-boletos-diagram

Diagram built with mermaid.js. Check out the source code at docs/diagrams/server

Example:

GET /boletos

Content-Type: application/json

{
  "count": "10",
  "page": "1"
}

200 Ok

Content-Type: application/json

[{
  "id": "bol_cj1o33xuu000001qkfmlc6m5c",
  "status": "issued",
  "queue_url": "http://yopa/queue/test",
  "expiration_date": "Tue Apr 18 2017 18:46:59 GMT-0300 (-03)",
  "amount": 2000,
  "instructions": "Please do not accept after expiration_date",
  "issuer": "bradesco",
  "issuer_id": null,
  "title_id": "null",
  "payer_name": "David Bowie",
  "payer_document_type": "cpf",
  "payer_document_number": "98154524872"
}]

3. GET /boletos/:id

Find one boleto by id.

3-get-boletos-id-diagram

Diagram built with mermaid.js. Check out the source code at docs/diagrams/server

Example:

GET /boletos/:id

Content-Type: application/json

{
  "id": "bol_cj1o33xuu000001qkfmlc6m5c"
}

200 Ok

Content-Type: application/json

{
  "id": "bol_cj1o33xuu000001qkfmlc6m5c",
  "status": "issued",
  "queue_url": "http://yopa/queue/test",
  "expiration_date": "Tue Apr 18 2017 18:46:59 GMT-0300 (-03)",
  "amount": 2000,
  "instructions": "Please do not accept after expiration_date",
  "issuer": "bradesco",
  "issuer_id": null,
  "title_id": "null",
  "payer_name": "David Bowie",
  "payer_document_type": "cpf",
  "payer_document_number": "98154524872"
}

Worker

This section documents what the worker processes.

1. Process boletos-to-register queue

This is a worker which consumes the queue which has boletos to register and effectively register them.

When a boleto can't be registered within the provider at the moment of its creation, it will be posted to a SQS Queue called boletos-to-register. This worker is responsible for processing this queue. Here are the steps:

  1. This worker consumer function is triggered when an item is on the queue
  2. Using sqs-quooler we then start to poll items from SQS (sqs.receiveMessage)
  3. Each message received has a boleto ({ id, issuer}) and a message (the raw SQS message from boletos-to-register queue).
  4. We use the boleto id to find the boleto on Database.
  5. We check if the boleto can be registered, i.e. if the status of the boleto is either issued or pending_registration.
  6. If the boleto can be registered, we try to register it within the provider.
  7. If the provider could not process the boleto, we stop executing here. The SQS Message will then go back to boletos-to-register queue and will be later processed.
  8. We update the boleto status with either registered or refused.
  9. IMPORTANT: After the boleto is updated, we notify the boleto owner by sendin an SQS message to the queue the owner specified on the boleto creation (aka: boleto.queue_url). The owner will then handle the processing of these SQS Messages. That's the only way we can notify the boleto owner that a boleto that went to boletos-to-register queue was updated. That's why it's mandatory to pass a queue at the moment of the boleto creation. 1-process-boletos-to-register-queue-diagram

Diagram built with mermaid.js. Check out the source code at docs/diagrams/worker