Documentation

simpleS is under active development, the API may change from version to version, it is highly recommended to read the documentation of the current version as there may me be some radical changes

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
    }
});

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.

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.

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

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.

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

Host Configuration

.config(config)

config: object

Change the configuration of the host. Possible attributes:

Compression configuration:

compression: {
    enabled: true, // Activate the compression, by default the compression is enabled
    options: null, // Set compression options, see more on http://nodejs.org/api/zlib.html#zlib_options
    preferred: 'deflate' // Set the prefereed compression type, can be `deflate` or `gzip`, by default is `deflate`
}

limit: number // 1048576 - Set the limit of the request body in bytes, default is 1MB.

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
    store: simples.store(), // Session store, default is simples memcached store
    timeout: 3600 // Set the time to live of a session in seconds, default is 1 hour, zero for infinite 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.

.clean() - should remove the sessions that are expired by comparing the current time with the .expires attribute of the session containers.

Note: The API is unstable at the moment, can be made some changes in the future releases

Middlewares

.middleware(callback[, remove])

callback: function(connection, next)

remove: boolean

Each host accepts middlewares to be implemented, which allow to add some additional implementations 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.

host.middleware(function (connection, next) {
    if (connection.path = '/restricted') {
        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
    }
});

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). 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
*/