doppio
v0.3.3
Published
A small server container to make managing and testing server processes easier.
Downloads
26
Readme
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 (seeserver.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 byserver.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 byserver.url()
. - callback Optional. If provided, the callback will be automatically
subscribed to the
ready
anderror
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
anderror
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;
};