ee-webserver

A simple webserver used by the ee framework.

- listen on any interface class or hostname
- listen on a defined or a random port
- request & response abstraction

build status


API

Constructor

var server = new Webserver(config);

The constructor accepts a config object which defines on which interfaces
to listen on. The specific interface classifiers can be obtained from the
Webserver class contructor.

var server = new Webserver({
interface: Webserver.IF_INTERNAL
, port: 80
});

The available interface classifiers are as folows:

- IF_PUBLIC: listen on all public interfaces
- IF_PRIVATE: listen on all private interfaces ( RFC 1918, 192.168.x.y, 10.x.y.z, 172.16.x.y - 172.31.x.y, fc00:: )
- IF_INTERNAL: listen on localhost ( 127.0.0.1, ::1, fe80::/7 )
- IF_ANY: listen on any interface
- IF_V4_PRIVATE: listen on private v4 interfaces
- IF_V6_PRIVATE: listen on private v6 interfaces
- IF_V4_INTERNAL: listen on 127.0.0.1
- IF_V6_INTERNAL: listen on fc00::/7, ::1
- IF_V4_PUBLIC: listen on all v4 public interfaces
- IF_V6_PUBLIC: listen on all v6 public interfaces
- IF_V4_ANY: listen on any v4 interfaces
- IF_V6_ANY: listen on any v6 interfaces

Listen Method

the lsiten method opens all configurerd server instances.

server.listen(function(err){
if (err) console.log('stuff failed. one ore more servers failed to come up. review your logs ...');
else console.log('We\'re online, yeah!');
});

Request Event

The request event is fired when any of the started webserver instances
receives a request. The event receives two arguments - the request and
the response object.

server.on('request', function(request, response){
if (request.pathname === '/what') response.send(200, 'that!');
else response.send(404);
});

Close Method

The close method closes the servers.

server.close(function(err){
if (err) console.log('stuff failed. one ore more servers failed to close. review your logs ...');
else console.log('We\'re offline :(');
});

Request Class

The request object is received via the «request» event on the server
object instance.

$3

- ip: returns either the ip set in the «x-forwarded-for» header or the ip from the request
- requestIp: returns the ip from the request
- forwardedIp: returns the ip set in the «x-forwarded-for» header
- hostname: returns the hostane header
- url: returns the url string
- querystring: returns the querstrting portion of the url

$3

- language: gets or sets the request language. Gets the language from the «accept-language» header.
- pathname: gets or sets the requests pathname
- query: gets or sets an object containing the query paramters (extracted from the url)

$3

The getCookie method extracts a cookie by name from the cookie header and returns it contents or null.

var cookieValue = request.getCookie('sid');

$3

The getHeader method returns a http header by its name. If the second argument is set to true the
method tries to parse the header content by the format «x, y;q=1, z;q=.5». Using the input
«da, en-gb;q=0.8, en;q=0.7» the function will the values as listen below

var acceptLanguage = request.getHeader('accept-language');
// da, en-gb;q=0.8, en;q=0.7

var acceptLanguageArray = request.getHeader('accept-language', true);
// [
// {
// key: "da"
// , q: 1
// , value: ""
// }, {
// key: "en"
// , q: 1
// , value: "gb"
// }, {
// key: "en"
// , q: 0.5
// , value: ""
// }
// ]

$3

The getHeaders resturns all request headers as an object.

var headers = request.getHeaders();
// {
// host: "127.0.0.1:13023"
// , connection: "keep-alive"
// }

$3

The getUri method returns the parsed url as an object.

var headers = request.getUri();

// {
// protocol: "http:"
// , slashes: true
// , auth: null
// , host: "127.0.0.1:13023"
// , port: "13023"
// , hostname: "127.0.0.1"
// , hash: null
// , search: ""
// , query: {}
// , pathname: "/"
// , path: "/"
// , href: "http://127.0.0.1:13023/"
// }

$3

The getRequest method returns the raw request object as provided by node.js.

var request = request.getRequest();

$3

The parseHeader method is used to parse headers. Its used by the «getHeader» method.

var parsedHeader = request.parseHeader(request.getHeader('accept-language'));

$3

The abort method aborts the request with the statuscode 500 or the code provided by the caller.
It closes the request without waiting for any more data.

request.abort(statusCode || 500);

Response Class

The response object is received via the «request» event on the server
object instance.

$3

- isSent: returns true when the response was closed an no more data can be written to it.

$3

- headers: the response headers. do not manipulate this object directly. Use the «setHeader» or «setHeaders» method instead.
- statusCode: the response statuscode. defaults to 500. the statuscode can be set using the «send» mthod
- query: gets or sets an object containing the query paramters (extracted from the url)

$3

The setContentType method sets the contentype header for the response

response.setContentType('Application/JSON');

$3

The setCookie method sets a cookie header. You can set as many cookies with the same name as you want.

response.setCookie('sid', '654A564B654E55D4C5F5FF54FF...');

$3

The setHeader method sets a header on the response. If you set one header mutiple times it will also be sent multiple times.

response.setHeader('Contet-Type', 'Application/JSON');

$3

The setHeaders method sets multiplle headers at once on the response. If you set one header mutiple times it will also be sent multiple times.

response.setHeader({
'Contet-Type': 'Application/JSON'
, 'Date': new Date()
});

$3

The removeHeader method removes any instance of the specified header.

response.removeHeader('Content-Type');

$3

The getRequest method returns the native node http response object

var res = response.getResponse();

$3

the send methos can be used to send data to the client. it accepts its parameter in any order. If it encounters a paramater with the type «number» it
will interpret it as the statuscode to use (if not provided the code 500 will be used). If it encounters a string or a buffer it will send it as the
body of the response. if it finds an argument of the type «object» it will set every key of that object as response header.

the method compresses the contents and sends them to the client. it ends the response when done.

// send an empty http status 500 response
response.send();

// send an string with the http status 200
response.send(200, 'hi there :)');

// send a JSON response
response.send({'Content-Type': 'Application/JSON'}, JSON.stringify({any: 'data'}), 200);

// sends a 201 created response
response.send(201, {Location: '/u..'});

$3

The write method can be used to send data i nchunks to the client

response.write(Buffer);

$3

the end method will end the response.

response.end();

example

var Webserver = require('ee-webserver');

new Webserver({
interface: Webserver.IF_INTERNAL
, port: 12001
}
, on: {
request: function(request, response){
response.send('hi ;)');
}
}
} ).listen(function(err){
// the server listens now on 127.0.0.1 and [::1]
});

#testing
To simplify testing for other applications the internal Request and Response can now be filled with
mock objects found in the testing sub. Consider the following options:

var EEWebserver = require('ee-webserver');
var requestOptions = {
host: 'some.test.com'
, headers: {
"accept-language": 'de',
"accept": 'application/json;q=1, application/xml;q=0.8, /;q=0.1'
}
, remoteAddress: '127.0.0.2'
, url: '/some/path/var/?varOne=1&varTwo=salee'
, method: 'POST'
}
, responseOptions = {
headers:{'content-type':'text/plain'}
, status: 404
};

These options can be inserted into the mock objects:

var mockRequest = new EEWebserver.testing.MockRequest(requestOptions)
, testRequest = new EEWebserver.Request(mockRequest)

, mockResponse = new EEWebserver.testing.MockResponse(responseOptions)
, testResponse = new EEWebserver.Response({
request: testRequest
, response: mockResponse
});

This now allows you to inject Request/Response pairs e.g. into your middleware and inspect their state, or the state
of the wrapped HTTPRequests. For instance, we could check if the response status and content is correct:

mockResponse.on('end', function(content){
assert.equal(this.status, 200);
assert.equal(content.toString(), '

some html

');
assert.equal(this.headers['content-type'], 'text/html');
}.bind(mockResponse));
myapplication.request(testRequest, testResponse);

For more information please consult the tests in test/MockObjectsTests.js.