Herman's Thought Soup

Herd Hound 2.0: The need for speed

2012-02-24T15:02:00.000-08:00

It was April 2011 when work on Herd Hound officially started. Six months later, we were finishing up a port of GAE-Bottle backend to Node.js. Less than Six months from there, we have a completely rewritten frontend and partially rewritten backend, with a reduction in total code base of almost 50%, mean and lean appearance, and very good performance. Let me just quickly recap what we did to reduce the payload and dramatically boost responsiveness, and then I'll cover the details in the following posts.

The key of the changes we introduced in v2.0 is jQX. It is a replacement for jQuery UI dialog, with many features suited for developing MDI-style single-page apps. After working with jQuery UI for a while, I realized that jQuery UI was developed primarily to enhance conventional dynamic pages (static page + dynamic components), rather than single-page web apps. It was also quite bulky (although that's mostly because it has lots of features which are useful in some scenarios), and tends to create a huge amount of markup, which possibly slows down DOM manipulation. So I looked for a good replacement, and decided there was nothing out there that would fit our needs.

jQX is based on jQuery, and weighs in at 57KB gzipped and minified. It sports a window manager (with windows, of course), smartphone-style shade, hashchange handler, keyboard shortcuts (yes, you can actually write 'ctrl+s'), and a host of other features written specifically for single-page apps like Herd Hound (which combine pinned and movable windows). It does rquire two additional dependencies, and those are es5-shim, and JSON2. Dependencies will hopefully become obsolete one of these days, but they are there just in case. The code base for this toolkit is written using the AMD modules suitable for use with RequireJS (you are using it, right?).

jQX has not yet been released because it needs cleanup, but I think it will be out under BSD or MIT license in a few months. One reason it is not released yet is that it was written specifically to handle Herd Hound workflow, so it is missing a bunch of features I'm 100% sure would be required in some other scenario. So I'm waiting to have at least one more project done with jQX before I call it ready for public.

Another library we developed has no fancy name (it's currently only known as input). Input is a library that deals with (you've guessed it right) form fields and user input. It has support for basic validation, and some other essentials, but the main reason I've written it is to make styling forms much easier. So, it does create a bit verbose markup (double-wrapper DIV around form inputs), but the end result is a possibly very sleek interface, with a bit of clever (or not so clever) CSS.

Thanks to those two libraries, the overall business logic code was also halved, and even the addition of the i18n facilities did not mean much for the total payload size. Including all images, the total payload is now around 180KB.

All in all, the changes dramatically reduce the on-load time from over 7 seconds in v1.0 to just under 4 seconds in the new version.

Apart from developing new libraries and completely rewriting all of the frontend code (yes, all of it, almost every single line), we have also made sure the frontend is now 100% decoupled from the backend. In fact, it will properly load and initialize even if the backend server is dead. Not a single line of HTML comes from the backend in this version. In the earlier version, the base HTML was quite a few lines longer than what we have now (basically, just a single div with some styling and text that reads "loading..."). It was also served by Node.js instead of a the nginx HTTP server. Because of that, we still put a little stress on the backend, and the frontend would not even load if backend were down. So we've taken care of that, and serving up even the base HTML is now super fast.

During the final stages of development, we also experimented a lot with nginx configuration, and cache-busting (which was completed today, actually), so we now take full advantage of browsers' caching functionality. As a result, the total payload when using cached contents is only 3KB, and the on-load time is 2 seconds.

To sum up, we have a reduction of the total payload from over 350KB gzipped and minified to 180KB gzipped and minified (that's 50% reduction), and reduced the on-load time from 7 to 4 seconds. We've made coding much, much more fun, and we had fun while doing all of this. Keep an eye out for juicy details of how's and what's of v2.0 optimization efforts.

Prevent text selection during mousemove

2012-02-10T14:33:00.000-08:00

Let's say you are trying to implement drag & drop action for your flashy web ~~2.0~~ 3.0 app. You are happy that it all works, and slap it onto the page. The draggable item appears over that article on the home page, and you happily proceed to test your new functionality. Alas, as you move your cursor, gripping the left mouse button, the article becomes selected, and soon enough, the whole page is marked as selected.

While working on something like the above, I've stumbled upon a nice solution to this problem. The answer is CSS3!

First of all, you can't actually prevent things from being selected on mousemove. I know it sounds crazy, but you really can't. What you can do is make things appear deselected.

This feature is supported in most A-class browsers (Firefox, Opera, Safari, Chrome, and IE), and looks something like this:

*.unselectable {
  user-select: none;
  -webkit-user-select: none;
  -khtml-user-select: none;
  -moz-user-select: none;
  -o-user-select: none;
  user-select: none;
}

What the above does is make anything with .unselectable class appear (and I stress, appear) unselectable. You can still select the text (or images), but the selection will not be rendered.

So what you do is, you add those style definitions to your stylesheet, load it up, and add the class to whatever you want to become unselectable during mousemove:

$('.draggable').on('mousedown', function(e) {
    var $this = $(this);
    e.preventDefault();

    // Make every element on page unselectable
    $('*').addClass('unselectable');

    // Some setup here, like remembering the original location, etc
    $(window).on('mousemove', function(e) {
       // Do the thing!
       $this.on('mouseup', function(e) {
           $('*').removeClass('unselectable');
           // Other clean-up tasks here
       });
    });
});

In the above example (using jQuery), we add the class to all elements on the page. The reason we add the class to all elements is that this set of CSS property only applies to individual elements and are not inherited/inheritable by child elements.

As an aside, once you start the drag action (by handling mousedown), it's best to handle the mousemove on the window object (or document if you like). The reason is that in some browsers, if the movement of the element resulting from drag action cannot keep up with the cursor, and cursor flies out of the element, the mousemove would no longer trigger until the cursor is back above the element. With the window element, you don't have to worry about this. Just make sure that propagation is not prevented.

Useful online tools for web developers

2012-02-02T06:32:00.000-08:00

We are currently working on v2.0 frontend for our service, and testing our new email interaction model (I'll write in more detail about that in upcoming posts). During development of the new features, I've come across a few tools that came in very handy.

Gradient with style

CSS3 gradients are tedious to do by hand, to say the least. I've tried a few online tools to help me out with this but most of them don't come anywhere near the versatility of the desktop tools for creating non-CSS3 gradients. One exception is worth mentioning, though.

When they say "Powerful Photoshop-like CSS3 gradient editor, guys from CollorZilla aren't lying. The Ultimate CSS Gradient Generator lives up to its name. Not only will it generate all kinds of gradients (radial, linear, etc) full with transparency, but it also stores presets for you, and allows you to load gradients by pasting bits of CSS.

I definitely recommend this tool as the only tool for gradients you'll ever need.

Sprite up your images

CSS sprites are good way to reduce the number of connections you are making to the assets server. They are a demanding task to do by hand, though, so any help is very welcome.

There are different CSS srpite tools out there, and there's a good reason for that. There are different scenarios for both sprites creation, and sprites usage, so every tool out there tends to fit one scenario. In our case, we wanted to pack all icons into a single spirte, and that's where Project Fondue's CSS Sprite Generator really shines.

The Project Fondue's sprite generator requires that you pack icons as individual images in a zip file. Once you've done that, it will create the sprites image and the matching CSS using image file names as class names. Carefully named files and well-chosen settings make a big difference for your resulting sprites. optiPNG optimization of the resulting PNG sprites image is a handy feature, too.

Email testing

If you want to test email delivery, and you don't want to create multiple accounts for that purpose, GuerillaMail is a perfect solution. It will create temporary email addresses that work for 60 minutes.

I haven't yet tried it, but it's on my list in the upcoming days. Some of us at Herd Hound do use it during QA sessions, and it seems to be working great.

Herd Hound is Live

2011-11-27T05:20:00.001-08:00

Yes, we are officially live. But live in an early-preview sort-of-way. So what does that mean? Well, it means that everything more or less works, but we are still in the refinement process. We're not just reevaluating some technical decisions, we're also in the process of completely overhauling some user-experience and business decisions. But, to reiterate, everything works just fine, so we can definitely start moving some herds. If you have an interest in going anywhere, please don't be shy.

Online Payments and Some Tricks

2011-09-29T01:04:00.000-07:00

We are finishing the final bits and pieces to make the alpha Herd Hound ready for prime time.Yesterday, we spent about half our working hours debugging the booking system,and I'd like to share our insights regarding payment processing.
I don't know a programmer that loves payment processing (except maybe thebrave guys and gals working for payment gateway providers). It's really a painpoint in most scenarios and there is surprisingly little information on what todo and how. Sure you have all kinds of APIs and matching documentations, but this is not (just) about API. It's also about the hidden stuff that apply to most payment gateways that, sadly, every integrator has to learn on her/his ownevery time.

Thing called liability

Since it's not strictly my area of expertise, I'll try to be brief here.There's this thing called 'liability'. It applies to chargebacks. Generally, the more data you provide about the card holder, the less you are liable whenit comes to chargebacks and associated fees. This is important to keep in mindfor tangible goods. I'll let Syed cover this part at some later date.

AVS: Address Verification System

Address verification system is something obviously invented by people thathave very little to do with programming. For a simple query to verify addressand zip/postal code, you get a whopping 26 response codes.
Apart from being a pain in the arse, you might also incur a fee. So thinkabout whether you really need it. If you are dealing with tangible goods, youprobably want to do AVS, as it decreases your liability in case ofchargebacks.
The response codes can be roughly divided into three categories:

Success (hooray!)
Failure (boo!)
Unsupported (dang!)

But there are nuances, too. And those nuances boil down to whether the cardwas issued in the US or not.
Generally, if you get any of the following letters you're good: D, M, J, Q, V, X, Y.
Unsupported cards will return S, but might also return G (internationalcards), E, or U. G is particularly interesting. If you get G, you will almostalways succeed if you do not use AVS (or do not send the address).
Failure can be triggered by many factors, not worth covering in detail, butit can be summarized as:

Address verification failure
Zip code verification failure
All of above

To cut to the chase, here's what I think should be general rules:

If you sell tangible goods, you need to provide the address.
If you are handling international cards, do not send the address, just the postal code.
If the issuing bank doesn't support AVS (status code S), do not send address and zip/postal code.

AVS failure may result in transaction being declined, andauthorization of (bank putting a hold on) funds on user's credit card. From myexperience, for international cards, status P will not result in transactionbeing declined.

Expiry date

Some may tell you that expiry date is not required and that banks do notcheck them. I learned yesterday that that's not true.
My bank definitely checks the expiry date for my Visa, and omitting it orsending a wrong date will fail the transaction. It turns out different bankshave different policies about the expiry date, so you should generally supplythe data and decline a card that fails to process because of bad expiry date.
Banks issue new cards automatically unless the client terminates thecontract. So, if the card's expiry date is in the past, you can generally use adate that is the supplied expiry date + 3 years, but I think it's safer todecline the card anyway. There is no guarantee someone didn't just type in arandom number because the card isn't theirs to begin with.

Don't tell the user

This is not strictly a rule. It's more like how I do things.
Do not tell the user why the card failed. Ever. Why should you? Just tellthem to review the billing data and/or contact their bank. If they have thecard, and the card is good, they should be able to tell what went wrong. On theother hand, you don't want to help a thief by providing detailed error report,do you?
I generally only check if the transaction failed for some technical reason(like the bank wasn't available, or gateway failed to respond), and disregardany card-related failures. Herd Hound doesn't sell tangible goods, so we don'tuse AVS. If we did use AVS, I would probably also special-case G and S failures, and retry the transaction with AVS disabled (Samurai will have this feature soon). You might also like to log AVS failures just in case.
The main point is, you should not let the user know the exact reason forfailure.
What you can and should do to help user out is:

Check the card number using Luhn Mod-10 check.
Check the length of the CCV code (4 for Amex, 3 for everyone else).
Warn about expiry date in the past.

That should be enough to help users spot typos early on.

Browser Cache and AJAX

2011-09-24T02:49:00.000-07:00

We've recently made log-ins more permanent by using sessions. For oursingle-page frontend application, we could have loaded the data from sessionseither by performing an extra AJAX request, or creating global variables in<script> tag. I decided to go with the former solution.After implementing the solution, I found out there was an issue with browsercaching, and successfully solved it with a rather simple trick.
The solution is neither new or exciting. However, it took me a while totroubleshoot, so I'll describe the symptoms in detail first.
Because sessions are server-side, I wanted to query the session data fromclient-side in order to determine if user is logged in. Therefore, I created a/status route, and queried it with a GET request.
The way it works is, if the user has been logged in before, GET/status returns a JSON object that contains the access token. Otherwise,it will return {"status":"ng"}. However, if I log in, and thenclose the browser, the app would not log me back in if I reopened thebrowser.
After a lot of debugging, it finally dawned on me that GET/status was being cached. Since this request is made only once atapplication boot, the last response before closing the browser was{"status":"ng"}, so that was read from the cache and fed to theapp, instead of making a new request.
The standard technique to prevent browsers from caching responses to GETrequests is to use query strings that are time-based or contain a randomstring. Point is, if URL is different each time, browser will not use thecache, because response doesn't match any previously used URL.
Here's the easy way to do it in jQuery:

$.ajax({
  url: '/status',
  // ....
  data: {t: (new Date()).getTime()}
  // ....
});

Simple as that.

New Node.js book: Node Web Development

2011-09-13T11:01:00.000-07:00

Yes, we at Herd Hound love Node.js. Come to think of it, I haveonly been using it for a bit less than two months. It feels like years, though.:) Anyway, here's areview I wrote about a book I wish I had before I got started.

node-logging 0.0.6

2011-09-12T06:33:00.000-07:00

It's busy these days in the Herd Hound camp, as we're getting ready to deploy the public Alpha soon. (If you're interested in what we're about,go to www.herdhound.com and add yourself to our Alpha release mailing list.) After detecting an attempt tosniff out potential admin exploit, I've done some more work on the loggingsystem so we get a more complete picture of the whole request-response cycle.

Here's what's new in node-logging v0.0.6.

The requestLogger middleware has been reworked a lot. The logging is now more-or-less async. As soon as middleware is started, control is passed on to handler right away, and logging is done later, after the request is finished. Believe it or not, it didn't work like that before, so there was a logger overhead before handler could run. I blame it on temporarypseudo-insanity.

A few more pieces of data are logged. This includes connection data:

remote IP
remote port
HTTP version
whether SSL was used
TCP socket type
total open connection at the time of request

Complete response headers are also logged. Memory usage isn't gone. It was just moved to the end of the log just before the 'User messages'.

Methd similar to req.log.setTimer() has been added for non-requestLogger time-based logging. Here's a simple usage scenario:

var logging = require('node-logging');

app.get('/hello_async', function(req, res, next) {
  var endTimer = logging.startTimer();

  setTimeout(function() {
    endTimer('Finished timing');
  }, 2000);
});

Unlike req.log.startTimer(), the node-logging.startTimer() doesn't require a label, and instead returns the function to stop the timer. The returned function has the same signature as other logging methods: it takes the log message, and trace flag which tells logger to output the stack trace along with the message.

Last but not least (not at all), node-logging now has the ability to disable logging of values of predefined path/url/request parameters. By default it willnot log any parameters named 'password', but the list of parameters can be customized using the node-logging.setExcludes() call:

var logging = require('node-logging');

logging.setExcludes(['password', 'card-number', 'secret']);

To disable the excludes completely, just pass this method an empty array.

Any excluded parameter will still be logged as having value '(excluded)', soyou can still tell if it was passed or not.

node-logging: pretty logging for Node and Express

2011-09-10T10:30:00.000-07:00

While this post claims that node-logging is for connect, it reallyonly works with Express. If it works with Connect, that's pure conincidence,and it's not a supported feature. I apologize for any false hopes that I causedin you, and hope you find an equally pretty logger for Connect. :)

I've looked at a few logging solutions recently. Most of them are either toocomplex, or they don't do exactly what I want, so I decided to roll my own.Usually, I'd patch an existing project, submit a pull request, and use it, butwith systems as simple as logging, I didn't feel like it would be worth it.

The node-logging module offers a simple and convenient logging facility forConnect and Connect-based apps (e.g., ones written on top of Express). Becausethe module is documented on GitHub, I will only cover it's usage with Express here.

Before you use noge-loggin with Express, you have to do just a little setting up.

Pick a logging level as you see fit. They are explained in detail in the documentation.

var logging = require('node-logging');
logging.setLevel('info');

The above sets the level to 'info'. Basically, the levels will restrict the logging to levels for greater importance. For example, 'debug' is of less importance than 'info', so it will be filtered out.

Next, add the requestLogger middleware to the stack:

app.configure(function() {
  ....
  app.use(logging.requestLogger);
  ....
});

With Express, there are a few limitation on where you can put the requestLogger. It must be after the Connect bodyParser,and before the app.router().

Now all your requests will be logged complete with request parameters, memory usage at the time request handler was called, duration of the response,and request headers. Here's a sample from the Herd Hound logs:

But this is not all. Most of the time you want to know what is going on inside the handler. There are two ways to log this information.

For simple messages, you can use req.log.push() method. This method will log your message, and the time (in milliseconds) since the moment the handler was called.

app.get('/hello', function(req, res, next) {
  req.log.push('Hi!');
});

If you have an asynchronous (or even sychronous call) in your handler, andwant to know how long it took from call to callback, you can use req.log.setTimer. This method takes a single argument which is astring label for the timer. This label is used to generate a method to end the timer and also add a message.

app.get('/hello-async', function(req, res, next) {
  req.log.startTimer('Async');
  setTimer(function() {
    // Simulated async call
    req.log.endAsync('Message');
  });
});

All messages are buffered and are added to the final request log so that messages are always grouped. Unless you have many tasks running in parallel, they will also appear in chronological order in your final log. Here is an example of the messages logged using in-handler methods.

The User messages section lists all messages logged during execution of the hander. The times in brackets represent the time from the start of the handler call, and if there is a second time in the bracket, it represents the time from the start of the handler call when the operation finished. For timed operations, the duration of the operation will also be appended at the end of the message (last item in the example above).

To install node-logging, you can use npm:

npm install node-logging

Daimyo 0.0.7

2011-08-30T09:45:00.000-07:00

Daimyo has seen 0.0.7release today. This release fixes a few of the smaller issues present in theprevious versions, and contains a small update in the documentation.

Starting with 0.0.6 release, we have started integrating Daimyo (andtherefore the Samurai paymentgateway into Herd Hound. This means that Daimyo is closer to productionstability than ever. With 0.0.7 and later releases, we will try to keep the APIas stable as possible, only adding new features. Good news is, Samurai's API isquickly maturing, and from what I've heard, they will be releasing inSeptember, so Daimyo will probably be going into feature freeze with 0.0.8.

As usual, to get the new release, just use npm:

npm install daimyo

Also, if you use the package.json file to manage dependenciesfor your project, be sure to set Daimyo's version to 0.0.7 andhigher.

node-sendgrid 0.0.3 released

2011-08-30T07:01:00.000-07:00

I've just released a v0.0.3 of node-sendgrid, utility library to generate Sendgrid's SMTP API headers in Node.js.

This is a small bugfix release that addresses issue #1, Headers constructor and a couple of methods defaulting to empty Arrray or Object if no value is supplied. This is a critical issue because if you are using the Headers constructor for your headers (by far the most convenient method), your email will be dropped by Sendgrid.

It is highly recommended to switch to 0.0.3 immediately.

Restrict text input to integers

2011-08-29T08:14:00.000-07:00

In a form used to make a purchase on Herd Hound, we needed to restrict thequantity of items. We cannot let anyone purchase more items than we have instock, and we don't want to give an impression that it can be done. So it'sbest to trap these things at an early stage (when user is typing in the value).Furthermore, we don't want emtpy values, 0 or non-numeric values.

With a bit of clever JavaScript, and some jQuery magic, I came up with a simpleimplementation that works as reliably as aplugin.

To make this work, we first need to trap the keyup event. Thisevent is triggered when you lift your finger off a key while entering text.It's important to use keyup and not keydown, becausethe latter is triggered before the text is entered into thetextbox/textarea.

$('input[name=numbers]').keyup(function() {
  /* more code goes here */
});

Once we know the key is pressed, we fist check what our text boxcontains.

$('input[name=numbers]').keyup(function() {
  var numeric = parseInt($(this).val(), 10);
});

In JavaScript, you convert a string to integer by using the built-inparseInt method. The first argument is the string, and the secondis the radix, which basically tells parseInt which base the numberis. While parseInt will be able to guess most of the time, wedon't want to take chances with a text box that can contain anything at all. Avalue of NaN (short for Not a Number) will be returned ifthe conversion cannot be performed (yes, it's a value that is as retarded as itsounds). You cannot test the truthiness of NaN, so you must usethe built-in method called isNaN (and yes, it breaks fingers whileyou type it in).

$('input[name=numbers]').keyup(function() {
  var numeric = parseInt($(this).val(), 10);

  if (isNaN(numeric)) {
    $(this).val(1); /* set default value*/
    return true;
  }
});

Return true to allow the event to propagate (keeps normalbrowser behavior.

Now we check if it's more than the number of items in stock. Let's say ourstock is 12 items.

var stock = 12;

$('input[name=numbers]').keyup(function() {
  var numeric = parseInt($(this).val(), 10);

  if (isNaN(numeric)) {
    $(this).val(1); /* set default value*/
    return true;
  }

  if (numeric > stock) {
    $(this).val(stock); /* cap at stock */
    return true;
  }
});

Finally, we check if the value is at least 1.

var stock = 12;

$('input[name=numbers]').keyup(function() {
  var numeric = parseInt($(this).val(), 10);

  if (isNaN(numeric)) {
    $(this).val(1); /* set default value*/
    return true;
  }

  if (numeric > stock) {
    $(this).val(stock); /* cap at stock */
    return true;
  }

  if (numeric < 1) {
    $(this).val(1); /* set to minimum value */
    return true;
  }
});

After all the checks, we need to make sure the good values are passed through:

var stock = 12;

$('input[name=numbers]').keyup(function() {
  var numeric = parseInt($(this).val(), 10);

  /* ....... */

  $(this).val(numeric);
  return true;
});

There is an improved version of this code on JSFiddle that keeps track of lastknown good value and uses that instead of minimum when the new value isNaN. I won't go into details of how it works, but you should beable to figure it out if you came this far without getting confused. :)

Cool stuff

2011-08-26T05:10:00.000-07:00

After surviving the heat of the Serbian summer at 50°C (122°F), Herd Hound's Belgrade outpost, that is yours truly, has got a new AC unit. Big thanks to my boss, Syed. :)

Now, doing cool stuff has a new meaning.

Client-side credit card validation using Daimyo

2011-08-20T12:46:00.000-07:00

Validate both client-side (using JavaScript) and server-side.That's a common mantra among web developers. So why do both? Well, because people hate it when they made a mistake and it took 30 seconds to find out(or more if the connection is bad). So the faster you can trap errors, the better. Same with credit cards.

Daimyo offers a simple way to validate credit card numbers using Luhn Mod-10 test, and CSC (card security code, sometimes called CVC, CVV, or CCV) via its checkmodule. Here I'll give you a quick tour.

Before we begin, you should know that check builds into anAMD-compliant module. So you should also know what AMD is. To cut the long story short, it's a cool module system for use withAMD-compliant module loaders like RequireJS. So, if you've been a good boy/girl scout and hopped on the RequireJS/AMD bandwagon early on, you will be rewarded with check-0.0.3.js, andbe able to do some easy validation of credit card data client-side.

To use this module, you first need to translate it into the AMD format.There is a target in the makefile called checkamd, and all you need to do is run make checkamd in the Daimyo directory.

Here's an example AMD module that loads jQuery and check and does some validation:

define(['jquery', 'check-0.0.3'], function($, check) {
  var cardNumber = $('input[name=cardnumber]').val();
  var csc = $('input[name=csc]').val();

  // Validate the number itself
  if (!check.mod10check(cardNumber)) {
    // It should be null if it's not valid
    alert('Bad card number!');
  }

  // Validate CSC (CCV, CVV, CVC)
  if (!check.cscCheck(cardNumber, csc)) {
    alert('Bad CCV code!');
  }

  // You can also find out what the card issuer is
  alert('Your card was issued by ' + check.getIssuer(cardNumber));

});

That's about it. It's quite simpe, so I guess I don't have to go any deeper.Happy hacking!

Secure, tamper-free configuration

2011-08-19T15:08:00.000-07:00

At Herd Hound, we have chosen to use FeeFighters' new offering, Samurai payment gateway, for processing credit cards and transactions. Samurai is still in early closed beta and it accepts join requests. We have started working on Daimyo, Node.js library for Samurai integration, and focused on security early on. In this post, I will give you an overview of one of Daimyo's features (appeared in v0.0.2): configuration locking.

Apart from Samurai credentials, which are quite a valuable asset, Daimyo's configuration contains several more options that can potentially cripple your site if modified during operation. Because of that, we decided to make configuration tamper-free, so that it cannot be easily modified even if the attacker could manipulate your application to attempt it.

All Node modules are sandboxed. That is, unless you explicitly export something from a module, other libraries in your system do not have access to things defined in it. For Daimyo, this property of Node modules was used to seal the configuration options away from the rest of your application. The configuration options are then made available in a controlled way through two methods: daimyo.configure(), and daimyo.option().

Here is a simplified version of a module with sealed configuration:

/**
 * Module demonstrating tamper-free configuration
 */

// Defaults
var configuration = {
  option1: true,
  option2: null // unset
};

var isSet = false; // not accessible to other modules

// Public-facing function that configures the module
exports.configure = function(opts) {
  if (isSet) {
    return; // Do nothing if already configured
  }
  configuration.option1 = opts.option1;
  configuration.option2 = opts.option2;
  isSet = true;
};

// Public-facing function that returns the configuration value
exports.option = function(opt) {
  return configuration[opt];
}

Step by step, we first set up an object that will hold all our configuration options. It does not have to be an object. You could add multiple variables, and that would work just fine. Objects just make it easier to organize the code. Important thing here is never to export the configuration options.

Next we set the initial value of the isSet variable which will be used to track the state of module's configuration. Again, this should never be exported. The main point here is that isSet is not accessible by other modules.

The configure() method sets the options only if isSet is false. Once it has set the options, it sets isSet to true, effectively locking the configuration.

This method makes sense for any module that does not realistically need to be configured more than once.

Be careful about setting an object as configuration option. Objects need to be cloned before returned to the outside world, or otherwise they can be tampered with. (An alternative to cloning is freezing and preventing extension.)

While it is very difficult to imagine a scenario in which the app can be compromised in a way that arbitrary code is executed, it is nevertheless not 100% impossible, and this way of configuration prevents modification of critical options at runtime, making the module more resilient to attacks.

Another variant of this method is the use of set-once setters. We will discuss this method in another article, but you can see a demo in a fiddle.