new FATAL state

Author: patoi

README.md

@@ -43,8 +43,20 @@ Changing application state.
 const appState = require('@vanioinformatika/appstate')()
 appState.init()
 appState.running()
-appState.error()
 appState.stopped()
+appState.error()
+appState.fatal()
+```
+
+Checking application state (recommended).
+
+```javascript
+const appState = require('@vanioinformatika/appstate')()
+appState.isInit()
+appState.isRunning()
+appState.isStopped()
+appState.isError()
+appState.isFatal()
 ```
 
 Reading application state.
@@ -54,17 +66,55 @@ const appState = require('@vanioinformatika/appstate')()
 let applicationState = appState.get()
 ```
 
-**Application state values are 'INIT', 'ERROR', 'RUNNING', 'STOPPED'**
+Listing state values.
 
-## Best practice
+```javascript
+const appState = require('@vanioinformatika/appstate')()
+let applicationStateValues = appState.list()
+```
+
+**Application state values are 'INIT', 'ERROR', 'RUNNING', 'STOPPED', 'FATAL'**
 
-Using state:
+## Debug
 
+Turn on debugging with env. variable: ```DEBUG=appState```
+
+Debug messages are:
+
+```javascript
+debug('info: appState has already set: ' + newAppState)
+debug('warn: invalid state changes from ' + appState + ' to ' + newAppState)
+debug('warn: unknow appState: ' + newAppState)
+```
+
+## State machine
+
+States:
+
+* **INIT** - Default state, application is starting, initialization: starting phase (app doesn't handle request)
 * **RUNNING** - application is running
 * **STOPPED** - application is running, but programmatically stopped
-* **ERROR** - application is running, but has a critical error (e.g.: DB connection error): app doesn't serves requests
-* **INIT** - Default state, application is starting, initialization: starting phase (app doesn't handle request)
+* **ERROR** - application is running, but has a critical error (e.g.: DB connection error): app doesn't serve requests
+* **FATAL** - application doesn't serve request, and never comes to RUNNING state, all other state changes ignored
+
+State machine:
+
+* INIT icon:arrow-right[] [INIT, RUNNING, STOPPED, ERROR, FATAL]
+
+* RUNNING icon:arrow-right[] [INIT, RUNNING, STOPPED, ERROR, FATAL]
+
+* STOPPED icon:arrow-right[] [INIT, RUNNING, STOPPED, ERROR, FATAL]
+
+* ERROR icon:arrow-right[] [INIT, RUNNING, STOPPED, ERROR, FATAL]
+
+* FATAL icon:arrow-right[] [FATAL]
+
+## Best practice
+
+Turn on DEBUG on test environment and check debug messages.
+
+Invalid state changes doesn't throw error, but ignored and logged.
 
-Use a /health endpoint for load-balancers, and set to UP, if ```appState.get() === 'RUNNING'```, else DOWN.
+Use a /health endpoint for load-balancers, and set to UP, if ```appState.isRunning()```, else DOWN.
 
 You can change anytime the application state, for example under initialization process: persistent DB connection error => appState.error()

appState.js

@@ -1,3 +1,4 @@
+const debug = require('debug')('appState')
 /**
  * Application state handler.
  */
@@ -19,18 +20,37 @@ module.exports = (cb) => {
   const state = {
     INIT: 'INIT',
     RUNNING: 'RUNNING',
+    STOPPED: 'STOPPED',
     ERROR: 'ERROR',
-    STOPPED: 'STOPPED'
+    FATAL: 'FATAL'
+  }
+  const stateMachine = {
+    INIT: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+    RUNNING: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+    STOPPED: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+    ERROR: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+    FATAL: [state.FATAL]
   }
   /**
    * Set application state to new state and loging it,
    * if state has changed.
    * @param String newAppState
    */
   function changeAppState (newAppState) {
-    if (appState !== newAppState) {
-      if (cb) cb(appState, newAppState)
-      appState = newAppState
+    if (state[newAppState]) {
+      if (stateMachine[appState].includes(newAppState)) {
+        // valid state changes
+        if (appState !== newAppState) {
+          if (cb) cb(appState, newAppState)
+          appState = newAppState
+        } else {
+          debug('info: appState has already set: ' + newAppState)
+        }
+      } else {
+        debug('warn: invalid state changes from ' + appState + ' to ' + newAppState)
+      }
+    } else {
+      debug('warn: unknow appState: ' + newAppState)
     }
   }
 
@@ -47,7 +67,9 @@ module.exports = (cb) => {
   function stopped () {
     changeAppState(state.STOPPED)
   }
-
+  function fatal () {
+    changeAppState(state.FATAL)
+  }
   function isInit () {
     return appState === state.INIT
   }
@@ -60,6 +82,13 @@ module.exports = (cb) => {
   function isStopped () {
     return appState === state.STOPPED
   }
+  function isFatal () {
+    return appState === state.FATAL
+  }
+
+  function getStateMachine () {
+    return stateMachine
+  }
 
   function get () {
     return appState
@@ -68,5 +97,25 @@ module.exports = (cb) => {
   function list () {
     return state
   }
-  return {init, running, error, stopped, get, list, isInit, isRunning, isError, isStopped}
+
+  function reset () {
+    appState = state.INIT
+  }
+
+  return {
+    init,
+    running,
+    error,
+    stopped,
+    fatal,
+    get,
+    getStateMachine,
+    list,
+    isInit,
+    isRunning,
+    isError,
+    isStopped,
+    isFatal,
+    reset
+  }
 }

appState.spec.js

@@ -6,6 +6,7 @@ const shouldSinon = require('should-sinon') // eslint-disable-line
 describe('appState', () => {
   it('handling undefined logger callback function', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.get().should.equal('INIT')
     appState.running()
     appState.get().should.equal('RUNNING')
@@ -14,16 +15,19 @@ describe('appState', () => {
   it('handling logger callback function, logging changes', () => {
     const loggerCB = sinon.spy()
     const appState = require('./appState')(loggerCB)
+    appState.reset()
     appState.init()
+    appState.running()
     loggerCB.should.be.calledOnce()
     // appState hasn't changed: called one
-    appState.init()
+    appState.running()
     loggerCB.should.be.calledOnce()
   })
 
   it('changed: logged', () => {
     const loggerCB = sinon.spy()
     const appState = require('./appState')(loggerCB)
+    appState.reset()
     appState.running()
     loggerCB.should.be.calledOnce()
     appState.stopped()
@@ -36,68 +40,149 @@ describe('appState', () => {
       info (appState, newAppState) { console.log(`App state has changed from ${appState} to ${newAppState}`) }
     }
     const appState = require('./appState')(logger.info)
-    appState.init()
+    appState.reset()
+    appState.running()
     console.log.should.be.calledOnce()
-    console.log.should.be.calledWith('App state has changed from STOPPED to INIT')
+    console.log.should.be.calledWith('App state has changed from INIT to RUNNING')
     console.log.restore()
   })
 
   it('is INIT', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.init()
     appState.get().should.be.equal('INIT')
   })
 
   it('is RUNNING', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.running()
     appState.get().should.be.equal('RUNNING')
   })
 
   it('is STOPPED', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.stopped()
     appState.get().should.be.equal('STOPPED')
   })
 
   it('is ERROR', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.error()
     appState.get().should.be.equal('ERROR')
   })
 
   it('isInit ok', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.init()
     appState.isInit().should.be.true()
   })
 
   it('isRunning ok', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.running()
     appState.isRunning().should.be.true()
   })
 
   it('isStopped ok', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.stopped()
     appState.isStopped().should.be.true()
   })
 
   it('isError ok', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.error()
     appState.isError().should.be.true()
   })
 
   it('list state values', () => {
     const appState = require('./appState')()
+    appState.reset()
     appState.error()
     appState.list().should.be.eql({
       INIT: 'INIT',
       RUNNING: 'RUNNING',
+      STOPPED: 'STOPPED',
       ERROR: 'ERROR',
-      STOPPED: 'STOPPED'
+      FATAL: 'FATAL'
     })
   })
+
+  it('get state machine values', () => {
+    const appState = require('./appState')()
+    const state = appState.list()
+    appState.reset()
+    appState.error()
+    appState.getStateMachine().should.be.eql({
+      INIT: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+      RUNNING: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+      STOPPED: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+      ERROR: [state.INIT, state.RUNNING, state.STOPPED, state.ERROR, state.FATAL],
+      FATAL: [state.FATAL]
+    })
+  })
+
+  it('invalid state change FATAL to INIT', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.reset()
+    appState.get().should.equal('INIT')
+    appState.running()
+    loggerCB.should.be.calledOnce()
+    appState.get().should.equal('RUNNING')
+    appState.fatal()
+    loggerCB.should.be.calledTwice()
+    appState.init()
+    loggerCB.should.be.calledTwice() // not called
+  })
+
+  it('invalid state change FATAL to RUNNING', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.reset()
+    appState.get().should.equal('INIT')
+    appState.running()
+    loggerCB.should.be.calledOnce()
+    appState.get().should.equal('RUNNING')
+    appState.fatal()
+    loggerCB.should.be.calledTwice()
+    appState.running()
+    loggerCB.should.be.calledTwice() // not called
+  })
+
+  it('invalid state change FATAL to STOPPED', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.reset()
+    appState.get().should.equal('INIT')
+    appState.running()
+    loggerCB.should.be.calledOnce()
+    appState.get().should.equal('RUNNING')
+    appState.fatal()
+    loggerCB.should.be.calledTwice()
+    appState.stopped()
+    loggerCB.should.be.calledTwice() // not called
+  })
+
+  it('invalid state change FATAL to ERROR', () => {
+    const loggerCB = sinon.spy()
+    const appState = require('./appState')(loggerCB)
+    appState.reset()
+    appState.get().should.equal('INIT')
+    appState.running()
+    loggerCB.should.be.calledOnce()
+    appState.get().should.equal('RUNNING')
+    appState.fatal()
+    loggerCB.should.be.calledTwice()
+    appState.error()
+    loggerCB.should.be.calledTwice() // not called
+  })
 })