Hapi for the little ones

Hapi.js is a framework for building web applications. This post contains all the essentials for a hot start. Unfortunately, the author is not a writer at all, so there will be a lot of code and few words.

• MVP
• In the wild
  
  
  • ORM sequelize
  • Inject additional modules into the request
  • Login
  • Error processing
  
  
  
• Data schemas
• Swagger / OpenAPI
• Auto Test Generation

MVP

Put a bunch of dependencies:

npm i @hapi/hapi @hapi/boom filepaths hapi-boom-decorators
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

• hapi / hapi - actually, our server
• hapi / boom - module for generating standard answers
• hapi-boom-decorators - helper for hapi / boom
• filepaths - a utility that recursively reads folders

Create a folder structure and a bunch of start files:

In ./src/routes/ we add a description of api endpoints, 1 file - 1 endpoint:

 // ./src/routes/home.js async function response() { // content-type            return { result: 'ok', message: 'Hello World!' }; } module.exports = { method: 'GET', //  path: '/', //  options: { handler: response // ,  ,  hapi > 17    } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

./src/server.js - the module that exports the server itself.

 // ./src/server.js 'use strict'; const Hapi = require('@hapi/hapi'); const filepaths = require('filepaths'); const hapiBoomDecorators = require('hapi-boom-decorators'); const config = require('../config'); async function createServer() { //   const server = await new Hapi.Server(config.server); //   await server.register([ hapiBoomDecorators ]); //      ./src/routes/ let routes = filepaths.getSync(__dirname + '/routes/'); for(let route of routes) server.route( require(route) ); //   try { await server.start(); console.log(`Server running at: ${server.info.uri}`); } catch(err) { //    ,   console.log(JSON.stringify(err)); } //      return server; } module.exports = createServer;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

In ./server.js all we do is call createServer ()

 #!/usr/bin/env node const createServer = require('./src/server'); createServer();
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

We launch

 node server.js
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And check:

 curl http://127.0.0.1:3030/ {"result":"ok","message":"Hello World!"} curl http://127.0.0.1:3030/test {"statusCode":404,"error":"Not Found","message":"Not Found"}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

In the wild

In a real project, at a minimum, we need a database, a logger, authorization, error handling, and much more.

Add sequelize

ORM sequelize is connected as a module:

 ... const Sequelize = require('sequelize'); ... await server.register([ ... { plugin: require('hapi-sequelizejs'), options: [ { name: config.db.database, // identifier models: [__dirname + '/models/*.js'], //    //ignoredModels: [__dirname + '/server/models/**/*.js'], //  -     sequelize: new Sequelize(config.db), //  sync: true, // default false forceSync: false, // force sync (drops tables) - default false }, ] } ... ]);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

The database becomes available inside the route through a call:

 async function response(request) { const model = request.getModel('_', '_'); }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Inject additional modules into the request

It is necessary to intercept the "onRequest" event, inside which we will inject the config and logger into the request object:

 ... const Logger = require('./libs/Logger'); ... async function createServer(logLVL=config.logLVL) { ... const logger = new Logger(logLVL, 'my-hapi-app'); ... server.ext({ type: 'onRequest', method: async function (request, h) { request.server.config = Object.assign({}, config); request.server.logger = logger; return h.continue; } }); ... }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

After that, inside the request handler, we will have access to the config, logger, and database, without the need to additionally include something in the module body:

 // ./src/routes/home.js async function response(request) { //  request.server.logger.error('request error', 'something went wrong'); //  console.log(request.server.config); //   const messages = request.getModel(request.server.config.db.database, '_'); return { result: 'ok', message: 'Hello World!' }; } module.exports = { method: 'GET', //  path: '/', //  options: { handler: response // ,  ,  hapi > 17    } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Thus, the request handler at the input will receive everything necessary for its processing, and it will not be necessary to include the same modules each time from time to time.

Login

Authorization in hapi is made in the form of modules.

 ... const AuthBearer = require('hapi-auth-bearer-token'); ... async function createServer(logLVL=config.logLVL) { ... await server.register([ AuthBearer, ... ]); server.auth.strategy('token', 'bearer-access-token', {// 'token' -   ,  allowQueryToken: false, unauthorized: function() { //  ,  validate  isValid=false throw Boom.unauthorized(); }, validate: function(request, token) { if( token == 'asd' ) { return { //    isValid: true, credentials: {} }; } else { return { //   isValid: false, credentials: {} }; } } }); server.auth.default('token'); //    ... }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And also inside the route you need to specify which type of authorization to use:

 module.exports = { method: 'GET', path: '/', auth: 'token', //  false,     options: { handler: response } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

If several types of authorization are used:

 auth: { strategies: ['token1', 'token2', 'something_else'] },
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Error processing

By default, boom generates errors in a standard way, often these answers need to be wrapped in their own format.

 server.ext('onPreResponse', function (request, h) { //      Boom,     if ( !request.response.isBoom ) { return h.continue; } //  -     let responseObj = { message: request.response.output.statusCode === 401 ? 'AuthError' : 'ServerError', status: request.response.message } //     logger.error('code: ' + request.response.output.statusCode, request.response.message); return h.response(responseObj).code(request.response.output.statusCode); });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Data schemas

This is a small but very important topic. Data schemes allow you to check the validity of the request and the correctness of the response. How well you describe these schemes, so will swagger and autotests be of such quality.

All data schemes are described through joi. Let's make an example for user authorization:

 const Joi = require('@hapi/joi'); const Boom = require('boom'); async function response(request) { //   const accessTokens = request.getModel(request.server.config.db.database, 'access_tokens'); const users = request.getModel(request.server.config.db.database, 'users'); //     let userRecord = await users.findOne({ where: { email: request.query.login } }); //   ,     if ( !userRecord ) { throw Boom.unauthorized(); } // ,    if ( !userRecord.verifyPassword(request.query.password) ) { throw Boom.unauthorized();//  ,    ,    } // ,    let token = await accessTokens.createAccessToken(userRecord); //    return { meta: { total: 1 }, data: [ token.dataValues ] }; } //   ,      const tokenScheme = Joi.object({ id: Joi.number().integer().example(1), user_id: Joi.number().integer().example(2), expires_at: Joi.date().example('2019-02-16T15:38:48.243Z'), token: Joi.string().example('4443655c28b42a4349809accb3f5bc71'), updatedAt: Joi.date().example('2019-02-16T15:38:48.243Z'), createdAt: Joi.date().example('2019-02-16T15:38:48.243Z') }); //   const responseScheme = Joi.object({ meta: Joi.object({ total: Joi.number().integer().example(3) }), data: Joi.array().items(tokenScheme) }); //   const requestScheme =Joi.object({ login: Joi.string().email().required().example('pupkin@gmail.com'), password: Joi.string().required().example('12345') }); module.exports = { method: 'GET', path: '/auth', options: { handler: response, validate: { query: requestScheme }, response: { schema: responseScheme } } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Testing:

 curl -X GET "http://localhost:3030/auth?login=pupkin@gmail.com&password=12345"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Now send instead of mail, only login:

 curl -X GET "http://localhost:3030/auth?login=pupkin&password=12345"
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

If the answer does not match the response scheme, then the server will also fall into a 500 error.

If the project began to process more than 1 request per hour, it may be necessary to limit the verification of responses, as verification is a resource-intensive operation. There is a parameter for this: "sample"

 module.exports = { method: 'GET', path: '/auth', options: { handler: response, validate: { query: requestScheme }, response: { sample: 50, schema: responseScheme } } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

In this form, only 50% of requests will be validated responses.

It is very important to describe the default values ​​and examples, in the future they will be used to generate documentation and autotests.

Swagger / OpenAPI

We need a bunch of additional modules:

 npm i hapi-swagger @hapi/inert @hapi/vision
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

We connect them to server.js

 ... const Inert = require('@hapi/inert'); const Vision = require('@hapi/vision'); const HapiSwagger = require('hapi-swagger'); const Package = require('../package'); ... const swaggerOptions = { info: { title: Package.name + ' API Documentation', description: Package.description }, jsonPath: '/documentation.json', documentationPath: '/documentation', schemes: ['https', 'http'], host: config.swaggerHost, debug: true }; ... async function createServer(logLVL=config.logLVL) { ... await server.register([ ... Inert, Vision, { plugin: HapiSwagger, options: swaggerOptions }, ... ]); ... });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And in each route you need to put the tag "api":

 module.exports = { method: 'GET', path: '/auth', options: { handler: response, tags: [ 'api' ], //    swagger'     validate: { query: requestScheme }, response: { sample: 50, schema: responseScheme } } };
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Now at http: // localhost: 3030 / documentation a web-face with documentation will be available, and at http: // localhost: 3030 / documentation.json .json a description.

Auto Test Generation

If we have qualitatively described the request and response schemes, prepared a seed database corresponding to the examples described in the request examples, then, according to well-known schemes, you can automatically generate requests and check server response codes.

For example, in GET: / auth login and password parameters are expected, we will take them from the examples that we specified in the diagram:

 const requestScheme =Joi.object({ login: Joi.string().email().required().example('pupkin@gmail.com'), password: Joi.string().required().example('12345') });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And if the server responds with HTTP-200-OK, then we will assume that the test has passed.

Unfortunately, there was no ready-made suitable module; you have to talk a little bit:

 // ./test/autogenerate.js const assert = require('assert'); const rp = require('request-promise'); const filepaths = require('filepaths'); const rsync = require('sync-request'); const config = require('./../config'); const createServer = require('../src/server'); const API_URL = 'http://0.0.0.0:3030'; const AUTH_USER = { login: 'pupkin@gmail.com', pass: '12345' }; const customExamples = { 'string': 'abc', 'number': 2, 'boolean': true, 'any': null, 'date': new Date() }; const allowedStatusCodes = { 200: true, 404: true }; function getExampleValue(joiObj) { if( joiObj == null ) // if joi is null return joiObj; if( typeof(joiObj) != 'object' ) //If it's not joi object return joiObj; if( typeof(joiObj._examples) == 'undefined' ) return customExamples[ joiObj._type ]; if( joiObj._examples.length <= 0 ) return customExamples[ joiObj._type ]; return joiObj._examples[ 0 ].value; } function generateJOIObject(schema) { if( schema._type == 'object' ) return generateJOIObject(schema._inner.children); if( schema._type == 'string' ) return getExampleValue(schema); let result = {}; let _schema; if( Array.isArray(schema) ) { _schema = {}; for(let item of schema) { _schema[ item.key ] = item.schema; } } else { _schema = schema; } for(let fieldName in _schema) { if( _schema[ fieldName ]._type == 'array' ) { result[ fieldName ] = [ generateJOIObject(_schema[ fieldName ]._inner.items[ 0 ]) ]; } else { if( Array.isArray(_schema[ fieldName ]) ) { result[ fieldName ] = getExampleValue(_schema[ fieldName ][ 0 ]); } else if( _schema[ fieldName ]._type == 'object' ) { result[ fieldName ] = generateJOIObject(_schema[ fieldName ]._inner); } else { result[ fieldName ] = getExampleValue(_schema[ fieldName ]); } } } return result } function generateQuiryParams(queryObject) { let queryArray = []; for(let name in queryObject) queryArray.push(`${name}=${queryObject[name]}`); return queryArray.join('&'); } function generatePath(basicPath, paramsScheme) { let result = basicPath; if( !paramsScheme ) return result; let replaces = generateJOIObject(paramsScheme); for(let key in replaces) result = result.replace(`{${key}}`, replaces[ key ]); return result; } function genAuthHeaders() { let result = {}; let respToken = rsync('GET', API_URL + `/auth?login=${AUTH_USER.login}&password=${AUTH_USER.pass}`); let respTokenBody = JSON.parse(respToken.getBody('utf8')); result[ 'token' ] = { Authorization: 'Bearer ' + respTokenBody.data[ 0 ].token }; return result; } function generateRequest(route, authKeys) { if( !route.options.validate ) { return false; } let options = { method: route.method, url: API_URL + generatePath(route.path, route.options.validate.params) + '?' + generateQuiryParams( generateJOIObject(route.options.validate.query || {}) ), headers: authKeys[ route.options.auth ] ? authKeys[ route.options.auth ] : {}, body: generateJOIObject(route.options.validate.payload || {}), json: true, timeout: 15000 } return options; } let authKeys = genAuthHeaders(); let testSec = [ 'POST', 'PUT', 'GET', 'DELETE' ]; let routeList = []; for(let route of filepaths.getSync(__dirname + '/../src/routes/')) routeList.push(require(route)); describe('Autogenerate Hapi Routes TEST', async () => { for(let metod of testSec) for(let testRoute of routeList) { if( testRoute.method != metod ) { continue; } it(`TESTING: ${testRoute.method} ${testRoute.path}`, async function () { let options = generateRequest(testRoute, authKeys); if( !options ) return false; let statusCode = 0; try { let result = await rp( options ); statusCode = 200; } catch(err) { statusCode = err.statusCode; } if( !allowedStatusCodes[ statusCode ] ) { console.log('*** TEST STACK FOR:', `${testRoute.method} ${testRoute.path}`); console.log('options:', options); console.log('StatusCode:', statusCode); } return assert.ok(allowedStatusCodes[ statusCode ]); }); } });
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Do not forget about the dependencies:

 npm i request-promise mocha sync-request
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And about package.json

 ... "scripts": { "test": "mocha", "dbinit": "node ./scripts/dbInit.js" }, ...
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

We check:

 npm test
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

And if the lock is some kind of data scheme, or the answer does not match the scheme:

And do not forget that sooner or later the tests will become sensitive to the data in the database. Before running the tests, you need to at least wipe the database.

Entire Sources