slower 1.1.12 → 1.1.13

package/lib/router.js

@@ -1,6 +1,6 @@
 const http = require('http');
 const fs = require('fs');
-const { noop, slugify, isSparseEqual, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders } = require('./utils');
+const { clone, noop, slugify, isSparseEqual, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders } = require('./utils');
 
 class Route {
     constructor (path, type, callback) {
@@ -37,7 +37,7 @@ class SlowerRouter {
         this.routes = [];
         this.middleware = [noop];
         this.fallback = noop;
-        this.allowedMethods = [];
+        this.allowedMethods = clone(SlowerRouter.http_methods);
         this.blockedMethodCallback = noop;
     }
 
@@ -72,7 +72,7 @@ class SlowerRouter {
     setRoute = function (path = '/', type = 'GET', callback) {
         let stat = new Route(path, type, callback);
         this.routes.push(stat);
-        return stat;
+        return this;
     }
 
     /**
@@ -82,13 +82,10 @@ class SlowerRouter {
      * @returns {Array} The used middlewares list
     */
     setMiddleware = function (callback) {
-        return this.middleware.push((typeof callback == 'function' ? callback : noop));
+        this.middleware.push((typeof callback == 'function' ? callback : noop));
+        return this;
     }
     
-    // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
-    // Use app.setStatic('/*', __dirname+'/') for serving all local files. 
-    // or use app.setStatic('/*', __dirname+'/public/') for serving files in a specific folder (public). 
-    // This is a one-liner for the setRoute function, when the route responds with a simple page or document
     /**
      * Defines a route for a determined request method 
      * @category Router
@@ -97,8 +94,6 @@ class SlowerRouter {
      * @param {String} mime The file's mime type
      * @param {Object} replacementData The replacement data map for the dynamic HTML rendering
      * @returns {Object} An Route object already configured
-     * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
     */
     /**
     * Dynamic rendering example:
@@ -117,7 +112,7 @@ class SlowerRouter {
         *   age: 29
         * }));
     */
-    setDynamic = function (path, file = '', mime = '', replacementData) {
+    setDynamic = function (path, file = '', mime = '', replacementData = null) {
         let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
         let stat = new Route(path, 'GET', (req, res) => {
             let data, targetFile, extension, targetMime, targetEncoding;
@@ -143,7 +138,7 @@ class SlowerRouter {
             res.end();
         });
         this.routes.push(stat);
-        return stat;
+        return this;
     }
     
     // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
@@ -156,10 +151,9 @@ class SlowerRouter {
      * @param {String} path The route that will be defined
      * @param {String} file The file path that will be used to respond to the route
      * @param {String} mime The file's mime type
-     * @param {String} encoding The file's encoding (defaults to UTF-8)
      * @returns {Object} An Route object already configured
      * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
+     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html');
     */
     setStatic = function (path, file = '', mime = '') {
         let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
@@ -184,7 +178,7 @@ class SlowerRouter {
             res.end(); 
         });
         this.routes.push(stat);
-        return stat;
+        return this;
     }
 
     /**
@@ -192,10 +186,8 @@ class SlowerRouter {
      * @category Router
      * @param {String} callback The function to execute for unhandled routes
      * @returns {undefined}
-     * @example <caption> Defining a simple GET route:</caption>
-     * setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html', 'utf8');
     */
-    setFallback = function (callback) { this.fallback = callback; }
+    setFallback = function (callback) { this.fallback = callback; return this; }
 
     // SERVES FILES FOR SPECIFIC PATHS. WILDCARS ALLOWED. BE CAREFUL - PATH TRAVERSAL MAY BE POSSIBLE
     // Use app.setStatic('/*', __dirname+'/') for serving all local files. 
@@ -229,7 +221,7 @@ class SlowerRouter {
         *   age: 29
         * }));
     */
-    setFallbackFile = function (file = '', mime = '', replacementData) {
+    setFallbackFile = function (file = '', mime = '', replacementData = null) {
         this.fallback = function fb (req,res) {
             let encoding = (mime === SlowerRouter.mime_table['default'] ? undefined : 'utf-8')
             let data, targetFile, extension, targetMime, targetEncoding;
@@ -254,6 +246,7 @@ class SlowerRouter {
             res.write(data);
             res.end();
         }
+        return this;
     }
 
     // Sets the methods that the application will respond to. The rest is simply discarded with empty responses.
@@ -282,7 +275,7 @@ class SlowerRouter {
             res.writeHead(405); // sends the meme error 418 'i am a teapot'
             res.end();
         };
-        return this.allowedMethods;
+        return this;
     }
 
     // Starts the server - listening at <host>:<port>
@@ -290,10 +283,8 @@ class SlowerRouter {
      * @category Router
      * @param {Number} port The port number the server will listen to.
      * @param {String} host The host's network interface address the server will listen into (use a falsy value or '0.0.0.0' for listening on all).
-     * @param {Function} methods The methods that are allowed by the application. Methods that do not conform with standards are ignored.
-     * @returns {Object} The AllowedMethods Array object.
-     * @example <caption> Allowing only GET and POST:</caption>
-     * app.setAllowedMethods(['GET', 'POST']);
+     * @param {Function} callback The function to execute after starting the server.
+     * @returns {Object<http.Server>} The server instance 
     */
     start = function (port = 8080, host = undefined, callback = () => {}) {
         let routes = this.routes;
@@ -339,7 +330,8 @@ class SlowerRouter {
         });
         callback(server);
         if (!host) host = undefined; // Turn falsy values into undefined, for default behaviour
-        return server.listen(port, host);
+        // return server.listen(port, host);
+        return this;
     }
 }
 

package/lib/utils.js

@@ -141,4 +141,6 @@ const setSocketSecurityHeaders = (req) => {
 
 const toBool = [() => true, () => false];
 
-module.exports = { noop, slugify, isSparseEqual, toBool, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders };
+const clone = (object) => JSON.parse(JSON.stringify(object));
+
+module.exports = { clone, noop, slugify, isSparseEqual, toBool, last, renderDynamicHTML, setSocketLocals, setSocketSecurityHeaders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slower",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "A package for simple HTTP server routing.",
   "main": "index.js",
   "directories": {

package/readme.md

@@ -3,6 +3,106 @@
 Slower is a small web framework, express-like, but simpler and limited.
 It allows for generic route-declaration, fallback pages, and multiple middleware functions.
 
+### API Methods:
+
+```
+app.enableStrictHeaders(): this
+
+> Enables the use of the set of 'Strict Headers'.
+> These headers increase security levels, and are a good practice to apply.
+> However, using these headers in testing scenarios are not a need, 
+  and may have buggy or negative effects. So, apply those to simulate scenarios only.
+> Headers configured:
+    > Content-Security-Policy
+    > Cross-Origin-Opener-Policy
+    > Cross-Origin-Resource-Policy 
+    > Origin-Agent-Cluster
+    > Referrer-Policy 
+    > X-DNS-Prefetch-Control (disabled)
+    > X-Download-Options
+    > X-Frame-Options
+    > X-XSS-Protection (disabled)
+    > X-Powered-By (removed)
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.disableStrictHeaders(): this
+
+> Disables the use of the set of 'Strict Headers'.
+> See 'enableStrictHeaders()' for more information.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setRoute(string: path = '/', string: type = 'GET', function: callback): this
+
+> Creates a new route for path defined in 'path', responding to the HTTP verb defined in 'type' argument.
+> The callback is executed when the route is accessed.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setMiddleware(function: callback): this
+
+> Sets a new middleware function: callback function will be accessed for every server access.
+> Many middlewares can be defined, and will be applied in the order they are defined.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setDynamic(string: path, string: file = '', string: mime = '', object: replacementData = null): this
+
+> Creates a new GET route for path defined in 'path'. 
+> This is a custom file-response route, configured for template rendering just before response.
+> Providing an object as 'replacementData' in this format { valueToBeReplaced: valueToReplace },
+  allows for template rendering. The value to replace in the file, uses this notation: '<{content}>'.
+> Example:
+  Responding a route for '/custom' with file 'custom.html':
+    app.setDynamic('/custom', './templates/custom.html', 'text/html', { smile: ':)' })
+  In file './templates/custom.html':
+    "<h2> This is a custom thing:        <{smile}>      </h2>"
+  Rendered in browser:
+    <h2> This is a custom thing:        :)      </h2>
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setStatic(string: path, string: file = '', string: mime = ''): this
+
+> Creates a new GET route for path defined in 'path', responding with the specified file and MIME type.
+> Example: A route for '/login' page, responding with 'login.html' file
+    setStatic('/login', __dirname+'/public/static/views/login.html', 'text/html');
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setFallback(function: callback): this
+
+> Creates a function for fallback state. When no other routes intercept the route, this will be used.
+> Special use for 'page not found' fallback pages or highly customized routes and situations.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setFallbackFile (string: file = '', string: mime = '', object: replacementData = null): this
+
+> Creates a function for fallback state. When no other routes intercept the route, this will be used.
+> Equivalent to setFallback, but responds with a file. Allows for template rendering.
+> See 'setDynamic' for more information about template rendering.
+> Special use for 'page not found' fallback pages, ex: './e404.html'.
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.setAllowedMethods(array: methods = []): this
+
+> Sets a list of methods to respond to.
+> By using this, it is possible to restrict the application to avoid
+  responding to dangerous HTTP verbs, such as 'DELETE'.
+> By default, all methods are allowed (see Slower.constructor.http_methods)
+> Calling this function without parameters is an easy way to block responses to all requests (lock server). 
+> Returns the own object instance, so that methods can be chained.
+```
+```
+app.start(number|string: port = 8080, string: host = undefined, function: callback = ()=>{}): this
+
+> Starts the server, at a specific host and port, then calling the callback function.
+> Not defining a specific port or host will start the server at '0.0.0.0:8080'.
+> Returns the own object instance, so that methods can be chained.
+```
 
 Example usage:
 ```
@@ -46,6 +146,7 @@ app.start(port, null, () => {
     console.log(`Running on localhost:${port}`);
     console.log(app);
 });
+
 ```
 ### API modifications on 'net.Socket' instances:
  - The API modifies every ```net.Socket``` instance BEFORE it is passed 
@@ -71,6 +172,7 @@ So, considering the common callback of ```(req, res)```, the session container w
    methods do exacly that. The strict headers are disabled by default, as some resources are too strict, 
    but it is also possible to enable them all, and then set a middleware to override any header.
  - Headers set by 'enableStrictHeaders':
+```
     Content-Security-Policy: default-src=none; script-src=self; connect-src=self; img-src=self;
         style-src=self; frame-ancestors=none; form-action=self;
     Cross-Origin-Opener-Policy:  same-origin
@@ -84,3 +186,4 @@ So, considering the common callback of ```(req, res)```, the session container w
     X-Frame-Options: DENY
     X-Powered-By: (This header is removed if a response includes it)
     X-XSS-Protection: 0 
+```