doppio

Doppio is a small "server container" for Node.JS web applications that makes managing the server process more convenient and testable.

Basic Usage

npm install doppio

Doppio works by wrapping your application with an http server. This is basically what the Express documentation recommends for configuring an application with HTTPS. Doppio just makes this process easier to manage and test. In the simplest case you can wrap your app and the server will start automatically:

var doppio = require("doppio");

var server = doppio({ port: 8080 }, app);

Usage Details

doppio([options], [handler])

• options - Optional. Options to configure the server instance.
• handler - Optional. The request handler for the server. This typically something like an Express app.

Creates a new server instance. By default, the server starts listening for requests automatically. The following configuration options are available:

• autostart - Defaults to true. If true, the server will start automatically unless NODE_ENV is 'test'.
• cert - The contents of the public certificate to use for HTTPS. See the Node HTTPS documentation for more information.
• key - The contents of the private key to use for HTTPS. See the Node HTTPS documentation for more information.
• hostname - Defaults to 'localhost'. Sets the hostname that the server will be running at. This is used by server.url().
• path - Defaults to '/'. Sets the base path for all URLs computed using server.url().
• port - Defaults to 0. The default port to use if a port is not provided to server.start(). If 0 is provided, an arbitrary open port will be assigned. For cases involving a proxy, a port pair can be specified (see server.start() for more details).
• scheme - Defaults to 'http'. Must be either 'http' or 'https'. When running with 'https', a certifacate and key must also be specified. If running behind a proxy it is possible to specify a scheme pair as follows: { private: "http", public: "https" }. The public scheme will be reflected by server.url().

doppio.loadPlugin([id...])

• id - Optional. One ore more module IDs of the plugins to load (Node.JS modules).

Loads plugins to process server configuration options. When multiple plugins are loaded, they will be processed in the order specified. See the "Plugins" section for more details.

doppio.unloadPlugins()

Unloads all plugins restoring Doppio to the default behavior.

server.server()

Returns a Node HTTP API instance for the Doppio instance. This is useful for integrating with external tools like Socket.IO.

server.start([port], [callback])

• port - Optional. The port that the server should listen on. If this is not provided, the default port is used (this is typically an arbitrary open port). In the case that the server should bind to a different port than the client will connect on, a pair can be specified as follows: { private: 54321, public: 80 }. The public port will be reflected by server.url().
• callback Optional. If provided, the callback will be automatically subscribed to the ready and error events.

Starts listening on a port. It is an error to try to start a server that is already listening. Returns a chainable reference to the server.

server.stop([callback])

• callback Optional. If provided, the callback will be automatically subscribed to the stopped and error events.

Stops listening for requests. Returns a chainable reference to the server.

server.url([path])

• path Optional. Resolve the given path against the server base URL and return the fully qualified URL.

Returns the fully qualified URL of the application. An error will be thrown if server.url() is called while the server is not listening.

Event: 'error'

function (error) { }

Emitted when an error occurs with the server.

Event: 'ready'

function () { }

Emitted when the server is ready to process requests.

Event: 'stopped'

function () { }

Emitted when the server closes and finishes handling all requests.

Plugins

Doppio plugins can be used to change how server options are handled. This can be useful for things like adding runtime specific logic. A Doppio plugin is just a Node module that exports a function that takes an options hash as its only argument and returns a new options hash (see the doppio() section for more info on the available options). Each time a new server instance is created, the plugins are invoked in the order they were loaded in. Each plugin is passed the options returned from the previous plugin as its argument. For example, the default option logic is equivalent to the following plugin code:

module.exports = function (options) {
    options.autostart = "autostart" in options ? options.autostart : true;
    options.hostname  = options.hostname || "localhost";
    options.path      = options.path || "/";
    options.port      = "port" in options ? options.port : 0;
    options.scheme    = options.scheme || "http";
    return options;
};