Server Namespace Reference

wilton/Server
HTTP server. More...

Functions
Undefined	broadcastWebSocket (Object options, Function|Undefined callback)
	Broadcast a message to WebSocket clients.
Undefined	getTcpPort (Function|Undefined callback)
	Find out server TCP port.
Object	Server (Object options, Function|Undefined callback)
	Start HTTP server.
Undefined	stop (Function|Undefined callback)
	Stop HTTP server.

Detailed Description

This module allows to start HTTP servers and handle incoming requests using specified modules/functions.

Each value specified in views parameter, is used both as a name of the module to handle the requests and as an URL path to route the requests to this module.

GET, POST, PUT, DELETE and OPTIONS (for CORS support) methods are used inside the handler modules to handle incoming requests with the corresponding HTTP method.

Additionally WSOPEN, WSMESSAGE and WSCLOSE WebSocket event names can be used inside hanler modules to handle incoming WebSocket events.

Server can also serve static files (from file-system or from ZIP files) specifying documentRoots configuration parameter.

Server supports HTTPS (certificates must be specified) and can be configured to require client X.509 certificates.

Server can be stopped to release system resources using stop() method, otherwise it will be stopped during the shutdown.

Usage example:

// inside "index.js"

// start server
var server = new Server({
    tcpPort: 8080,
    views: [
        "server/views/hi",
        "server/views/bye"
    ]
});

// active URLS:
// http://127.0.0.1:8080/server/views/hi
// http://127.0.0.1:8080/server/views/bye

// wait for Ctrl+C (in console app)
misc.waitForSignal();

// stop server
server.stop();


// inside "server/views/hi.js"

GET: function(req) {
    req.sendResponse("hello from GET handler");
},

POST: function(req) {
    req.sendResponse({
        msg: "hello from POST handler"
    });
}

Function Documentation

Undefined Server::broadcastWebSocket	(	Object	options,
		Function|Undefined	callback
	)

Broadcasts the message to all the WebSocket clients currently connected on the specified path.

May cause the broadcast message to interleave with other frames (put in the middle of continuation sequence, or in the middle to TCP fragmented sequence), if target connection is used for outbound traffic at the the time of broadcast.

List of clients to include into broadcast may be specified directly using idList option.

Parameters

options	Object configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Undefined

Options

• path String WebSocket path to broadcast on
• message String|Object message to send, specified Object will be converted to JSON
• idList Array|Undefined optional list of WebSocket client IDs to include into the broadcast

Undefined Server::getTcpPort

(

Function|Undefined

callback

)

Retuns a TCP port number that this server instance is bound to.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined

Object Server::Server	(	Object	options,
		Function|Undefined	callback
	)

Starts HTTP server binding the connection on a specified TCP port. Server worker threads are run in background.

Parameters

options	Object configuration object, see possible options below
callback	Function|Undefined callback to receive result or error

Returns

Object Serial instance

Options

• views Array list of module names that will be used to handle incoming request; the same module names are also used as URL paths for requiests routing; functions with following names are used inside the handler module to handle the requests:GET, POST, PUT, DELETE and OPTIONS; the following method names can be used for WebSocket events: WSOPEN, WSMESSAGE and WSCLOSE; each handler function receives Request instance as an only parameter and must use sendResponse(), sendTempFile(), sendMustache() or sendWebSocket() methods to return the response to client;
• filters Array list of module names that will be called on the incoming request, each module must return a function(req, doFilter), and can either call doFilter(req) to proceed to the next filter (and eventually - to the request view), or handle the request with sendResponse()
• numberOfThreads Number|Undefined number of background threads to start, default value: 2
• tcpPort Number|Undefined TCP port to bind to, default value: 8080
• ipAddress String|Undefined IP address to bind to, default value: 0.0.0.0
• ssl Object|Undefined HTTPS configuration
  • keyFile String path to SSL certificate file that must also contain a private key
  • keyPassword String SSL server certificate (private key) password
  • verifyFile String|Undefined path to SSL CA certificate to use for validation of client X.509 certificate
  • verifySubjectSubstr String|Undefined substring of the client X.509 certificate subject that will be checked during the client certificate check
• documentRoots Array|Undefined configuration for serving static files
  • resource String URL path for this entry
  • dirPath String|Undefined path to file-system directory to serve files from
  • zipPath String|Undefined path to ZIP file to server files from
  • zipInnerPrefixString|Undefined prefix to strip from ZIP paths when serving files from ZIP
  • useResourceLoaderBoolean|Undefined whether to load response resources through wilton_loader; default value: false
  • resourceLoaderPrefixString|Undefined prefix (absolute path to WLIB file and optional internal path) to prepend to resources paths
  • cacheMaxAgeSeconds Number|Undefined value for Cache-Control's max-age field to use for files server from this documentRoot, in seconds, default value: 604800
  • mimeTypes Array|Undefined list of MIME types mapping for this documentRoot
    • extension String file extension (CSS, JS etc)
    • mime String MIME type for this extension
• requestPayload Object|Undefined configuration for handling requests payload
  • tmpDirPath String path to the directory where temporary files with requests payloads will be stored
  • tmpFilenameLen Number|Undefined length of the generated random names for temporary files, default value: 32
  • memoryLimitBytes Number|Undefined max size of the request payload that is allowed to process in-memory without dumping it into file, in bytes, default value: 1048576
• mustache Object configuration for mustache responses
  • partialsDirs Array list of directories to use for loading mustache partial templates when returning rendered mustache templates using Request.sendMustache()
• handle Number|Undefined handle to access Server instance from another thread

Undefined Server::stop

(

Function|Undefined

callback

)

Stops HTTP server releasing system resources, active servers will be stopped automatically on shutdown.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Undefined