Configuration API

[fbbdev]

I'm opening this issue to summarize and discuss in one place all configuration APIs.

Things that currently are, or could be made, configurable:

• [x] Platforms
• [x] Platform priority
• [x] Platform-specific options
• [ ] Base URL

Requirements:

• Platforms:
  • [x] Registration
  • [x] Override by deployment script
• Platform priority:
  • [x] Per-platform defaults
  • [x] Override by deployment script
• Platform-specific options:
  • [ ] Override on call to serve
  • [x] Override by deployment script
• Base URL
  • [x] Per-platform defaults
  • [ ] Override by deployment script

Current APIs:

• Platform registration: autoserve.register(platform)
• Platform override: autoserve.override(platformName, object)
• Default priority: { /*platform object*/ }.priority
• Priority override: provided through autoserve.override(platformName, { priority: /* new priority */ })
• Platform-specific options override: autoserve.options[ /* platform name */ ] and autoserve.extendOptions(object)
• Base URL per-platform defaults: { /* platform object */ }.getBaseUrl(request)

[fbbdev]

While I think that platform APIs (namely, register/override and the priority mechanism) reached a good point, I believe that options and base url APIs could be improved.

For options, I propose the following changes:

• Modify the extendOptions method to have the same signature of the override method: (platformName, options). This would make it more coherent with the rest of the API.
• Rename extendOptions to configure. It's shorter, easier on the eyes, more explicative... like you observed in the comment setOptions would not be a good choice, but I find extendOptions confusing too.
• I still support adding the options argument to the main serve method. The use case I have in mind is that of an app that wants to provide custom defaults for options, or load them from a config file, from the environment or from command-line options. The autoserve call seems a good place to do that, and it would still allow deployment scripts to override options; otherwise, apps would use the extendOptions method and hide settings made by deployment scripts, since those run before the app.

For the base url system I propose the following mechanism:

• Introduce a global baseUrl property with default value = null
• When a request is received, determine the actual base url by the following logic:

if (typeof module.exports.baseUrl === 'function') {
    actualBaseUrl = module.exports.baseUrl(req);
} else {
    actualBaseUrl = module.exports.baseUrl || detectedPlatform.getBaseUrl(req);
}

• Check if the resulting base url is effectively a prefix of the url. If it is, strip it from the url, else ignore it. (I am not sure about this last point.. how an invalid base url could be handled?)

if (req.url.indexOf(actualBaseUrl) === 0) {
    req.baseUrl = actualBaseUrl;
    req.url = req.url.slice(actualBaseUrl.length);
}

These changes would allow a deployment script to handle complex cases while still providing sane defaults. See notes on cbccaf2 for a discussion of related problems.