Sivy ·

The survey synchronization server for MongoDB.

How to use

Setup

Install it:

npm install @indec/sivy

Sivy requires [email protected]

And add a script to your package.json like this:

{
  "scripts": {
    "start": "sivy",
    "dev": "sivy dev"
  }
}

The sivy dev command enables the hot code reloading. No server restart is needed.

Handlers

The file-system is the main API. Every .js file becomes a handler that gets automatically processed on every sync, and the container folder is when that handler is executed. The handlers support promise.

| Folder | Input parameters | |------------------|------------------------------------------------------------------------| | dumpSurveys | (surveyDump: SurveyDump, surveys: Array<object>) | | receiveSurveys | (surveys: Array<object>, syncLog: SyncLog) | | preSaveSurvey | (surveyAddress: SurveyAddress, survey: object, syncLog: SyncLog) | | getSurveys | (surveyAddresses: Array<SurveyAddress>, syncLog: SyncLog) | | preSaveSyncLog | (syncLog: SyncLog) |

To log how many surveys we receive on a POST we can create a file into: receiveSurveys/helloWorld.js as the following:

module.exports = surveys => console.log(`Received surveys: ${surveys.length}`);

Model

By default the SurveyAddress has the following Mongoose's schema:

{
    dwellings: [{type: Mixed}],
    user: {type: ObjectId, required: true},
    address: {type: ObjectId, ref: 'Address', required: true},
    surveyAddressState: {type: Number},
    state: {type: Number},
    valid: {type: Number}
}

You can strongly type the Dwelling's schema defining a model/dwelling.js as the following:

module.exports = {
    order: {type: Number},
    dwellingCharacteristics: {
        ...
    }
};

Also, you can add additional attributes to the SurveyAddress's schema defining a model/surveyAddress.js as the following:

module.exports = {
    visits: [{
        order: {type: Number, required: true},
        date: {type: Date, required: true},
        comments: {type:String}
    }]
};

Environment variables

| Required | Variable | Description | Defaults to | |------------|----------------------|-----------------------------------------|-----------------------------| | | NODE_ENV | Defines the running environment | development | | | PORT | Port where sivy will listen | 3000 | | | MONGODB_URI | Connection string to the MongoDB server | mongodb://localhost:27017 | | | RECEIVE_ONLY | True if Sivy works on receive_only mode | false | | :bangbang: | AUTH_CLIENT_SECRET | The secret to validate the JWT. | | | | SURVEYS_COLLECTION | The surveys collection name on MongoDB | surveyAddresses | | | SURVEYS_HISTORY | Keeps a history of survey changes | true | | | SURVEYS_DUMP | Dumps every request to a collection | false | | | MORGAN_FORMAT | Log format used by Morgan package | dev on NODE_ENV=development, combined on NODE_ENV=production | | | DEBUG | Set to sivy to turn on debug logging. | |

Authentication

Sivy expects an Authorization header on the HTTP request as the following:

Authorization: Bearer <jwt>

The JWT will be verified using the AUTH_CLIENT_SECRET defined in the environment variables and the verify method in the jsonwebtoken package.

Debug

To turn on the Sivy debug mode just set the environment variable DEBUG=sivy.

Production deployment

To deploy just run the sivy command:

sivy

For example, to deploy with now a package.json like follows is recommended:

{
  "name": "my-sync",
  "dependencies": {
    "@indec/sivy": "latest"
  },
  "scripts": {
    "start": "sivy"
  }
}

Note: It’s your responsibility to set NODE_ENV=production manually!