Sunday, December 16, 2012

How much a wrapper of a lib should be documented?

I was looking for a service on the npm to install my Node.js application as a Windows service.  Pretty straight forward stuff really and I came across winser which is a nice module that easily allows you us it  to do this.  The documentation even shows how to do this when you install the npm module which I must admit is very nice using the npm script feature "postinstall" to install your module as a Windows service.  

All had been going well when I was using winser but when I install it on the testing environment things suddenly took a turn for the worse.  All of a sudden the test box became unresponsive and then rebooted itself.  All of this happened only moments after I had install the module.  I knew this environment was not setup correct and my application self terminates once it can not find the correct settings/start up as expected.  Problem here which I didn't know was that the library winser relies upon to register the application as service, nssm has more configuration options.  One important one is a throttling mechanism when your application exits after a certain period of time.  This works well if you are within this time period but outside of it your application is automatically restarted.  This is the default setting of nssm library when an application exits. This default period which the throttling mechanism comes into is 1500ms.  So once your application passes 1500ms nssm assumes the application to be up and running successfully.  Unfortunately this is not the case for my application which would exit after 1500~1600ms... which lead to the application tight looping on restarts... which lead to excessive messages going to the Windows logs and CPU consumption that lead to my test server crashing.

To me this shows that sometimes important default settings/behaviours are not obvious when they should be to a developer.  If I had knew the default behaviours I would have looked to change the defaults but I had not.  After reading a lot about nssm (probably more than I should have needed too) I am now excited about the next version of nssm 3 which will allow you to control a lot of these settings without editing the Windows registry.

Even though it is easy to wrap up functionality to make it available cross programming languages.  It is important to include the documentation/usage of that library from the original in the wrapper. 

No comments: