Repository navigation
Documentation
var simples = require('simples');simples(port)
port: number
simpleS needs only the port number and it sets up a HTTP server on this port.
var server = simples(80);or
var server = new simples(80);.start(port[, callback])
port: number
callback: function(0)
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.
server.start(80, function () {
// Application logic
});.stop([callback])
callback: function(0)
Stop the server. Can have an optional callback.
server.stop(function () {
// Application logic
});.accept(origins)
origins: array of strings
simpleS provide a very simple way to accept cross-origin requests. It will automatically check the origin of the request and if it is in the list then it will response positively. By default the server will accept requests only from the host and local file system origins. To accept requests from any origin use ['*']. These limitations will work for HTTP GET and POST request and even for WebSocket requests. Example:
server.accept(['null', 'localhost', 'www.example.com']);.get(route, callback)
route: string
callback: function(2)
Listen for get requests and uses the callback function with request and response as parameters. Warning: route is case sensitive.
server.get('/', function (request, response) {
// Application logic
});.post(route, callback)
route: string
callback: function(2)
Listen for post requests and uses the callback function with request and response as parameters. Warning: route is case sensitive.
server.post('/', function (request, response) {
// Application logic
});.all(route, callback)
route: string
callback: function(2)
Listen for both GET and POST requests and uses the callback function with request and response as parameters. Warning: route is case sensitive.
server.all('/', function (request, response) {
// Application logic
});.serve(path)
path: string
path is the local path to a folder that contains static files (for example: css and js files), this folder will serve as the root folder for the server. simpleS will return response status 304 (Not Modified) if the files have not been changed since last visit of the client. Only one folder should be used to server static files, if more .serve() methods will be called only the last will be used to serve static files. The folder with static files can contain other folders, their content will be also served. The provided path must be relative to the current working directory. Warning: the names of static files are case sensitive.
server.serve('root');.error(code, callback)
code: number
callback: function(2)
Use the callback function with request and response as parameters for errors that can have place. Only one callback function can be used for a specific error code, if more .error() methods will be called for the same error code only the last will be used for routing. Possible values for error codes are: 404 (Not Found), 405 (Method Not Allowed) and 500 (Internal Server Error).
server.error(404, function (request, response) {
// Application logic
});The first parameter provided in callbacks for routing requests is an object that contains data about the current request. Example:
{
body: '',
connection: {
ip: '127.0.0.1',
port: 50505
},
cookies: {
user: 'me',
pass: 'password'
},
files: {},
headers: {
host: 'localhost',
'user-agent': 'myBrowser',
accept: 'text/html',
'accept-language': 'ro;q=0.8,en;q=0.6',
'accept-encoding': 'gzip, deflate',
cookie: 'user=me; pass=password'
},
langs: [
'ro',
'en'
],
method: 'GET',
query: {},
session: {},
url: {
search: '',
query: {},
pathname: '/',
path: '/',
href: '/'
}
}The content of the body of the request, for GET requests it is empty, for POST request it will contain plain data, parsed data is contained in request.query.
Data about the current connection, object containing the remote ip address and the port.
An object that contains the cookies provided by the client.
An object that contains files send using POST method with multipart/form-data content type.
An object that contains the HTTP headers of the request.
An array of strings that represents languages accepted by the client in the order of their relevance.
The HTTP method of the request.
The object that contains queries from both GET and POST methods.
A container used to keep important data on the server-side, the clients have access to this data using the _session cookie.
The url of the request split in components like href, path, pathname, query as object and query as string (search).
The second parameter provided in callbacks for routing requests is a writable stream that defines the data sent to the client. It has the next methods:
name: string
value: string
config: object
Sets the cookies sent to the client, providing a name, a value and an object to configure the expiration time, to limit the domain and the path and to specify if the cookie is http only. Can be used multiple times, but before .write() method. Example:
response.cookie('user', 'me', {
expires: new Date(new Date().valueOf() + 3600000), // or maxAge: 3600000, default is undefined
path: '/path/', // Default is the root of the server
domain: 'localhost', // Default is the domain of the server
httpOnly: false, // Default is true
});language: string
Sets the language of the response. Should be used before the .write() method. Should be used only once. Example:
response.lang('ro');path: string
Redirects the client to the provided path. Should not be used with the other methods. Example:
response.redirect('/index');type: string
override: boolean
Sets the type of the content of the response. Default is 'html'. By default uses one of 100 content types defined in mime.json, which can be edited to add mode content types. Should be used only once and before the .write() method. If the content type header is not set correctly or the exact value of the type is known it is possible to override using the second parameter with true value of this method and setting the first parameter as a valid content type. The second parameter is optional. Example:
response.type('html');data: buffer or string
Writes data to the response stream. Should be ended with .end() method. Example:
response.write('Hello');data: buffer, string or empty
If data is provided it calls the .write() method and ends the response. Example:
response.end('World');data: any value except undefined
Writes preformatted data to the response stream and ends the response, usually very useful for sending file content or JSON format. Arrays, booleans, numbers and objects are stringified. Should not be used with .write() or .end() methods, but .write() method can be used before. Should be used only once. Example:
response.send(['Hello', 'World']);.ws(path, config, callback)
path: string
config: object
callback: function(1)
Create WebSocket host and listen for WebSocket connections. For security reasons only requests from the current host or local file system origins are accepted, to accept requests from another locations the .accept() method from the simpleS instance should be used. Also, for additional security or logic separation, protocols should be provided in the config parameter, by default no protocols are required, the length of the message can be limited too, default is 1MiB, the value is defined in bytes. The callback function comes with the connection as parameter.
server.ws('/', {
length: 1024,
protocols: ['', 'echo']
}, function (connection) {
// Application logic
});The object that represents the current WebSocket connection. The WebSocket connection is an event emitter. It has the next attributes and methods:
The array of protocols of the WebSocket connection.
The request interface, same as for GET and POST requests, which is described above.
data: any value except undefined
Sends a message to the client. If data is a buffer then the sent message will be of binary type, else - text type, arrays, booleans, numbers and objects are stringified.
data: string or buffer
filter: function(3)
Sends a message to all connected clients. Clients can be filtered by providing the second parameter, equivalent to Array.filter(). Example:
connection.broadcast('HelloWorld', function (element, index, array) {
return element.getProtocols().indexOf('chat') >= 0; // Will send the message to clients that use "chat" as a subprotocol
});The WebSocket connection has the next events:
Emitted when the server receives a message from the client.
Emitted when the connection is closed.