Documentation

New simpleS Instance

simples([port, options, callback])

port: number

options: object

callback: function

simpleS needs only the port number and it sets up a HTTP server on this port.

var server = simples(80);

// or simpler

var server = simples(); // the server will be set on the port 80

To set up an HTTPS server the options object is needed with key and cert or pfx attributes, these will be the paths to the .pem or .pfx files, see https and tls core modules for more details, the options object is the same used there with the only difference that simpleS resolve the content of key and cert or pfx attributes, so the key and cert or pfx attributes are required. The requests on HTTPS are always listen on port 443. Automatically, with the HTTPS server an HTTP server is created which will have the same routes as the HTTPS server (see Routing). To check the protocol the connection.protocol property is used (see Connection Interface).

var server = simples(443, {
    key: 'path/to/key.pem',
    cert: 'path/to/cert.pem'
});

// or just

var server = simples({ // the server will be set on port 443
    key: 'path/to/key.pem',
    cert: 'path/to/cert.pem'
});

To redirect the client to HTTPS, use a structure like this:

server.get('/', function (connection) {
    if (connection.protocol === 'http') {
        connection.redirect('https://' + connection.url.host + connection.url.path, true);
    } else {
        // Application logic
    }
});

or try simples-redirect middleware with some more options.

The third parameter callback is used to know when the server has started running.

Server Management

Starting and Restarting

.start([port, callback])

port: number

callback: function()

Start listening for requests on the provided port. If the server is already started then simpleS will restart the server and will listen on the new provided port. Can have an optional callback. All connection in simpleS are kept alive and the restart can take few seconds for closing alive http and ws connections. While restarting, no new connection will be accepted but existing connections will be still served. This method is called automatically when a new simpleS instance is created, it is not needed to call it explicitly on server creation. The purpose of this method is to provide a way to switch port. Returns current instance, so calls can be chained.

server.start(80, function () {
    // Application logic
});

Stopping

.stop([callback])

callback: function()

Stop the server. Can have an optional callback. All connection in simpleS are kept alive and the closing can take few seconds for closing alive http and ws connections. While closing, no new connection will be accepted but existing connections will be still served. Returns current instance, so calls can be chained.

server.stop(function () {
    // Application logic
});

Server error handling

Any simpleS instance is an event emitter, all possible errors that may appear at the level of the server can be caught using the usual error event listener attached to the instance object. The same approach can be applied for HTTP and WS hosts, in this case the error listeners will catch errors to the level of the host. It is recommended to attach error event listeners to the server and all its hosts to prevent any undesired behavior.

server.on('error', function (error) {
    // Handle any fatal errors that may occur at the level of the server
});

host.on('error', function (error) {
    // Handle any error that occurs at the level of the host
});

Virtual Hosting

.host(name[, config])

config: object

simpleS can serve multiple domains on the same server and port, using .host() method it is simple to specify which host should use which routes. By default, simpleS has the main host which will route all existent routes of the simpleS instance, this is vital for one host on server or when it is needed a general behavior for incoming requests. This method will create and configure a new host or will return an existing host with a changed configuration. Returns current instance, so calls can be chained.

var host = server.host('example.com');

Host Configuration

.config(config)

config: object

Change the configuration of the host. Returns current instance, so calls can be chained. Possible attributes for the configuration:

Compression configuration:

compression: {
    enabled: true, // Activate the compression, by default the compression is enabled
    filter: /^.+$/i, // Filter content types that will be compressed, by default all kinds of file types are compressed
    options: null, // Compression options, see more on http://nodejs.org/api/zlib.html#zlib_options
    preferred: 'deflate' // The prefereed compression type, can be 'deflate' or 'gzip', by default is `deflate`
}

origins: array of strings // [] - Set the origins accepted by the host. By default, the server will accept requests only from the current host. To accept requests from any origin use '*', if this parameter is used as the first parameter then all next origins are rejected. 'null' is used for local file system origin. These limitations will work for HTTP GET and POST request and even for WebSocket requests. The current host should not be added in the list, it is accepted anyway.

['null', 'localhost', 'example.com'] // Will accept requests only from these 3 hosts

['*', 'example.com'] // Will accept requests from all hosts except 'example.com'

referers: array of strings // [] - Set the referers that can use the static resources of the host. By default, the server will response to all referers. To accept all referers except some specific the first parameter should be *. The current host should not be added in the list, it is served anyway. The server will respond with error 404 to unacceptable referers.

['*', 'example.com'] // will respond to all referers except 'example.com'

['example.com', 'test.com'] // Will respond only to these 2 referers

Session configuration:

session: {
    enabled: false, // Activate the session, by default sessions are disabled
    store: simples.store(3600), // Session store, the default is simples memcached store with 1 hour timeout
}

Sessions are stored by default inside an memcached container, to define another container for them it is needed an object instance with the next methods:

.get(id, callback) - should return inside the callback function the session container if it is found, if the session defined by the id parameter is not found then the callback function should return null;

.set(id, session, callback) - should add the session container defined by the first two paramters and execute the callback function when the session container is saved to the sessions storage.

Note: The third party session store also have to implement its own technique for cleaning up expired sessions.

Middlewares

.middleware(callback[, remove])

callback: function(connection, next)

remove: boolean

Each host accepts middlewares to be implemented, which allow to add some additional implementations with a global behavior which are not available out of the box. The middlewares can manipulate the connection object and to call the next middleware or the internal simpleS functional. The order in which middlewares are defined has importance because they will be executed in the same way. simpleS will prevent the same middleware to be attached. To remove a middleware from the list its reference should be provided as the first parameter and the second parameter should be a true value. Returns current instance, so calls can be chained.

host.middleware(function (connection, next) {
    if (connection.path = '/restricted' && !connection.session.user) {
        connection.end('You do not have right to be here');
        next(true); // Will stop the middleware chain and connection routing
    } else {
        next(); // Will continue to the next middleware if it exists or will continue to connection routing
    }
});

// another example to set X-Powered-By Header for all connections

host.middleware(function (connection, next) {
    connection.header('X-Powered-By', 'simpleS');
    next();
});

Templating

.engine(engine)

engine: object

To render templates it is necessary to define the needed template engine which has a .render() method. The rendering method should accept 1, 2 or 3 parameters, source, imports and/or callback, source should be a string that defines the path to the templates, imports may be an optional parameter and should be an object containing data to be injected in the templates, callback is a function that is called if the result is generated asynchronously. The templates are rendered using the .render() method of the Connection Interface. If the template engine does not correspond to these requirements then a wrapper object should be applied. This method is applicable on each host independently (see Virtual Hosting). Returns current instance, so calls can be chained. Recommended template engine: simpleT.

var noopEngine = {
    render: function (source) {
        console.log(source);
        return source;
    }
};

host.engine(noopEngine);

// Wrapped unsupported template engine example
var unsupportedEngine = {
    renderFile: function (imports, source) {
        console.log(source);
        return source;
    }
};

host.engine({
    render: function (source, imports) {
        unsupportedEngine.renderFile(imports, source);
    }
});

Routing

All the methods described below are applicable on each host independently (see Virtual Hosting). All route paths are case sensitive and should contain only paths without queries to exclude possible unexpected behavior and to ensure improved performance, undesired data will be cut off. All routes are relative to the host root and may not begin with /, simpleS will ignore it anyway. The routes may be fixed or can contain named parameters. Fixed routes are fast and simple, while the second ones are more flexible and handy in complex applications. The named parameters in the advanced routes are mandatory, if at least one component of the route is absent in the url then the url is not routed.

'user/john/action/thinking'; // Fixed route

'user/:user/action/:action'; // Advanced routing with named parameters

/*
    This route will match this request url:

    /user/mary/action/cooking

    with parameters:

    {
        user: 'mary',
        action: 'cooking'
    }
*/

'user/:user/*'; // Advanced routing that can match anything

/*
    This route will match these request urls:

    /user/mary/home
    /user/mary/friends/john
*/