Skip to content

Latest commit

 

History

History
179 lines (131 loc) · 5.18 KB

README.md

File metadata and controls

179 lines (131 loc) · 5.18 KB

primost

http server that catch sending emails requets, put them in a prioritized queue, and treat them in a separate process.

Principal packages used

Prerequisities

You must have a redis instance available. A docker-compose.yml file is includeed if you need it.

Primost must be configured with a config.js file placed at the projet root. There is a file named config.sample.json to help you do that.

You should copy this file with cp config.sample.js config.js and edit it with your favorite text editor.

Configuration

The following steps will all be a part of the config.js file.

Application configuration

key value description default required
NODE_ENV developement or production developement yes
PORT Number http server port 3000 yes
END_POINT String Server endpoint where you'll post requests / yes
JWT_SECRET String Secret that will be used by JWT to decrypt data shhhh yes
EMAIL_DELAY Number Time in ms the process has to wait before sending another email. AWS SES have some limitations, like 12 emails/sec 100 yes
DELAY_ON_ACKNOWLEDGE Boolean When true, waits for SES response before waiting EMAIL_DELAY between 2 jobs. When false, a job is executed every EMAIL_DELAY. false increses significantly sending rate false yes
RETRY_ON_THROTTLE Boolean When true, if maximum sending rate per day is exceeded, put the job back in the queue with a RETRY_DELAY delay. false yes
RETRY_DELAY Number Time in ms 1000 * 60 * 60 (1 hour) yes

Logger configuration

key value description default required
LOG_IN_CONSOLE Boolean Api calls will be logged in console true yes
LOG_IN_FILE Boolean Api calls will be logged in file in ./LOG_DIRECTORY/consumer.log true yes
LOG_DIRECTORY String Directory where the log files will be stored. The path is relative to project root directory. log yes (if LOG_IN_FILE === true)

Email configuration

key value description default required
EMAIL_KEYS_MAPPING Object See Fields mapping -- yes
ATTACHMENTS_KEYS_MAPPING Object See Fields mapping -- yes

Redis configuration

Since Primost uses bull wich uses redis, we need to provide redis configuration.

key value description default required
REDIS_HOST Number 6379 yes
REDIS_PORT String localhost yes
REDIS_PASSWORD String false no

AWS SES configuration

Since Primost uses AWS SES to send emails, we need to provide AWS configuration.

key value description default required
AWS_ACCESS_KEY_ID Number none yes
AWS_SECRET_ACCESS_KEY String none yes
AWS_REGION String none yes

Fields mapping

For emails to be formated in the right way, you must provide data to certain keys. I believe that every project is different, and those keys might be different as well.

For example the bcc field in french is cci, as well for attachments that could be named pj.

Primost can adapt to these differences and propose a mapping tables, described in objects :

// config.js
const config = {
  EMAIL_KEYS_MAPPING: {
    // 'your term': 'primost term'
    priority: 'priority',
    sujet: 'subject',
    from: 'from',
    fromName: 'fromName',
    replyto: 'replyTo',
    returnPath: 'returnPath',
    to: 'to',
    msg_raw: 'text',
    msg_html: 'html',
    cc: 'cc',
    bcc: 'cci',
    pj: 'attachments',
  },
  ATTACHMENTS_KEY_MAPPING: {
    // 'your term': 'primost term'
    nom: 'filename',
    url: 'path',
    contentType: 'contentType',
  }
}

Note : All fields must be provided, even if there is no mapping to setup

Usage

To use Primost, you will have to make a POST call to the endpoint END_POINT.

The token that will have to be sent is the email data set JWT encrypted with the JWT_SECRET.

Ex:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

The minimum required fields are :

const REQUIRED_FIELDS = [
  'subject',
  'from',
  'to',
  'text',
  'html',
];

Start production

# create config file frome the sample
cp config.sample.js config.js

#edit your config file
nano config.js 

# run redis
docker-compose up redis -d 

# install dependencies
yarn

# start producer and consumer
yarn start:producer:prod
yarn start:consumer:prod

# or stop them
yarn stop:producer:prod
yarn stop:consumer:prod

Start dev

# create config file frome the sample
cp config.sample.js config.js

#edit your config file
nano config.js 

# run redis
docker-compose up redis -d 

# install dependencies
yarn

# yarn dev builds and start all process
yarn dev