Nitrogen Pumpkin Mulch

    sicarii

    1.0.5 • Public • Published

    The zero dependency http2 nodejs multithreading framework

    cd-img dep-img sz-img

    NPM Version lic-img

    SICARII Website

    SICARII Dev Wiki

    Documentation

    Installation

    npm

    stable release

    $ npm install sicarii --save

    dev release

    git

    $ git clone https://github.com/angeal185/sicarii.git

    About

    Sicarii is a nodejs http2 framework for projects of all sizes.

    • zero dependencies forever
    • multithreading by default
    • does not need or use the nodejs http2 compatibility layer api but can be extended to do so
    • non restrictive design in that you can use the sicarii api or vanilla nodejs most of the time
    • easily extendable

    Initialization

    As sicarii is built for http2, SSL certificates are required. The default path for the ssl certificates is as follows:

    • ./cert/localhost.cert
    • ./cert/localhost.key

    These options be edited in the default ./config/config.json file at config.ssl.

    • for using the key/cert/pfx/ca options, a path to the file should be provided as the arg.
    • config.server accepts all of the same default arguments as nodejs http2 server config.
    • sicarii will automatically combine config.ssl with config.server

    self signed certificates can be used for development and created as follows:

    ECDSA

     
    $ openssl ecparam -name secp384r1 -genkey -out localhost.key
    $ openssl req -new -x509 -key localhost.key -out localhost.cert -days 365
     

    RSA

     
    $ openssl req -x509 -new -x509 -sha256 -newkey rsa:4096 -nodes -keyout localhost.key -days 365 -out localhost.cert
     

    Build

    run the following line of code in any file inside your cwd to build sicarii.

     
    require('sicarii/build')();
     

    Upon first run and if no config file is found, sicarii will attempt to generate the following.

    • ./config ~ default config directory.
    • ./config/config.json ~ default config file.
    • ./config/ip_config.json ~ default ip whitelist/blacklist file.
    • ./render ~ default render/document directory.
    • ./render/index.html ~ starter html file.
    • ./static ~ default static file directory.
    • ./static/css/main.css ~ starter css file.
    • ./static/modules/main.mjs ~ starter mjs file.
    • ./uploads ~ default upload directory.
    • ./logs ~ default logs directory.
    • ./store/cache ~ default cache write dir.
    • ./store/session ~ default session write dir.
    • ./store/store ~ default store write dir.

    this action is sandboxed for security reasons. should you wish to, you can delete the associated build files:

    • /sicarii/build.js
    • /sicarii/lib/utils/init.js
     
    const { app } = require('sicarii');
     
    app.del_build()
     

    Server

    Sicarii is built to incorporate multi-threading by default. you can edit your thread count at config.cluster.workers

    Although many frameworks wrap the server object within their app, limiting your server actions to those they wish you to have access to, sicarii does not. sicarii extends the existing nodejs modules in place, leaving you full access to the nodejs server object. Most of these extensions can be either disabled, replaced, configured or extended.

    sicarii uses the modern nodejs http2 api and does not need or contain any code related to the http2 Compatibility API.

    Below is a 30 second minimal rest-api/static server example.

    const { app, cluster } = require('sicarii');
    // app is always called first
     
    if (cluster.isMaster) {
     
      const { sync, Cache, server, logs } = require('sicarii/master');
     
     
      // Cache extentions here ~ if any
     
      // server extentions here ~ if any
     
      // logs extentions here ~ if any
     
      // * spawn workers
      // * synchronize master/worker communication
      // * respawn dead workers
      // * start cache on config.cache.port cache port
      // * automatically handle cache requests
      // * automatically handle log requests
     
      sync.init().respawn().listen();
     
    } else {
     
      const { server, router, crypt } = require('sicarii/main');
     
      // serve static
      router.get('/', function(stream, headers, flags){
     
        stream.addHeaders({
          header2: 'ok2',
          header3: 'ok3'
        });
     
     
        //stream headers and and send static document
        stream.doc('index.html', 'text/html; charset=utf-8');
     
      });
     
      // json rest
      router.post('/', function(stream, headers, flags){
        let body = stream.body.json;
     
        stream.addHeader('x-Static', 'ok');
     
        // send headers & response
        stream.json({key: 'val'});
      });
     
      //start worker server at config.port
      server.listen(app.config.port);
    }

    server.log_ip()

    refer to logs for a detailed explanation

    log ip address

     
    /**
     *  @server.log_ip(ip, path)
     *
     *  @param {string} ip ~ ip address to log
     *  @param {string} path ~ path to log
     **/
     
    router.get('/login', function(stream, headers, flags){
     
      server.log_ip(stream.ip, '/login')
     
    });
     

    server.log_history()

    refer to logs for a detailed explanation

    log history

     
    /**
     *  @server.log_history(data)
     *
     *  @param {string} data ~ history data to log
     **/
     
     router.get('/login', function(stream, headers, flags){
     
       let his_log = [Date.now(), 'GET', '/login'].join('::::')
       server.log_history(his_log)
     
     });
     

    server.log_error()

    refer to logs for a detailed explanation

    log error

     
    /**
     *  @server.log_error(data)
     *
     *  @param {string} data ~ error data to log
     **/
     
     router.get('/someerror', function(stream, headers, flags){
     
       let his_log = [Date.now(), 'GET', '/someerror', '400', 'some message'].join('::::')
       server.log_error(his_log)
     
     });
     

    server.pre_cache()

    server.pre_cache() will enable you to pre-cache your static files/docs.

    • this method can only be called once and upon doing so, it will remove itself
    • this method is apart of sync although you may have many workers, it will only be called once.
    • this method is for static files/docs only, it is not intended for rendered docs
    • config.pre_cache is the path to your pre_cache config file
    • config.verbose enabled will log to console the cache status of a streamed file

    the configuration file can be configured like so:

    /* ./config/pre_cache.json */
     
    {
      "render": [{
        "ctype": "text/html", // file content-type 'only'
        "url": "/index.html"  // file path relative to render path
      }],
      "static": [{
        "ctype": "text/css",
        "url": "/css/main.css" // file path relative to static path
      },{
        "ctype": "application/javascript",
        "url": "/modules/main.mjs"
      }]
    }
     

    the method can be called like so:

    const { app, cluster } = require('sicarii');
     
     
    if(cluster.isMaster) {
     
      const { sync } = require('sicarii/master');
     
      sync.init().respawn().listen();
     
     
    } else {
     
      const { server, router } = require('sicarii/main');
     
      router.get('/', function(stream, headers, flags){
     
        // stream.doc() static files are located in the render folder
        // this file has been cached
        // [sicarii:GET] /index.html 200 [cache]
        stream.status(200).doc('index.html', 'text/html')
     
        // stream.render() files are located in the render folder but are not static
        // this has not been rendered/cached properly
        // do not pre-cache rendered files
        stream.status(200).render('index.html', {not: 'cached'})
     
      });
     
      // can be optionally called in chain
      // sync will ensure the method is only called by first worker
      server.pre_cache().listen(app.config.port);
     
    }

    server.push_handler()

    refer to push handler

    server.push_handler() will enable/disable automatic stream push of static files.

    • this method takes priority over config.push_handler.enabled
    const { app, cluster } = require('sicarii');
     
    if(cluster.isMaster) {
     
      const { sync } = require('sicarii/master');
     
      sync.init().respawn().listen();
     
    } else {
     
      const { server, router } = require('sicarii/main');
     
      router.get('/', function(stream, headers, flags){
        stream.status(200).doc('index.html', 'text/html')
      });
     
      //enable push_handler manually
      server.pre_cache().push_handler(true).listen(app.config.port);
    }
     

    Sync

    the sync object is is used to control and synchronize events between master/worker

    • sync is optionally responsible for all tasks related to the cluster module
    • sync will automatically handle spawning of new worker threads
    • sync will automatically handle respawning of crashed worker threads
    • sync will automatically handle inter-process messaging across all processes
    • sync will automatically initialize Cache and start the cache server
    • sync will handle inter-process ip/history/error logging
    • sync is a part of the master scope

    sync.init()

     
    /**
     *  sync.listen(settings)
     *  @param {object} settings // optional worker settings overrides to config.cluster.settings
     **/
     
    if (cluster.isMaster) {
      const { sync } = require('sicarii/master');
     
      // * spawn workers
      // * synchronize master/worker communication
      sync.init();
    }

    sync.respawn()

    if (cluster.isMaster) {
      const { sync } = require('sicarii/master');
     
      // * respawn dead workers
      sync.respawn()
     
      // or
      sync.init().respawn()
    }

    sync.listen()

    /**
     *  sync.listen(callback)
     *  @param {function} callback // optional callback
     **/
     
    if (cluster.isMaster) {
      const { sync } = require('sicarii/master');
     
      // * start cache on config.cache.port cache port
      sync.listen()
     
      // or
      sync.init().respawn().listen()
    }

    sync.kill()

    /**
     *  sync.kill(id)
     *  @param {number} id // id of the worker to kill
     **/
     
    if (cluster.isMaster) {
      const { sync } = require('sicarii/master');
     
      sync.init().respawn().listen()
     
      // kill worker with id 1 then worker with id 2
      // with sync.respawn() active these workers will be respawned
      setTimeout(function(){
        sync.kill(1).kill(2)
      },5000)
    }

    sync.kill_all()

    if (cluster.isMaster) {
      const { sync } = require('sicarii/master');
     
      sync.init().respawn().listen()
     
      // kill all workers
      // with sync.respawn() active these workers will be respawned
      setTimeout(function(){
        sync.kill_all(1)
      },5000)
    }

    Router

    methods

    The default allowed router methods can and should be configured at config.stream.methods.

    • config.stream.methods accepts all compatible http methods. you should only add the ones you use.

    • config.stream.method_body contains all of the router methods that accept a body.

    • config.stream.method_query contains all of the router methods that accept a query string.

    • If you are not using a method in your app, you should remove it to improve both the security and performance of your app.

    the router also accepts all of the default nodejs stream methods.

    below listed are some basic router method examples:

     
    /**
     *  router[event](path, callback)
     *  @param {string} path 
     *  @param {function} callback ~ function(stream, headers, flags)
     **/
     
    router.get('/test', function(stream, headers, flags){
      let query = stream.query; //json object
     
      // add header
      stream.addHeader('Content-Type', 'application/json');
     
      // add cookie
      stream.cookie('name', 'value',{
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Strict',
        Secure: true,
        Priority: 'High'
      })
     
      // send headers & response
      stream.json({test: 'get'});
     
      /* or using default nodejs methods */
     
      stream.respond(stream.headers);
      stream.end(JSON.stringify({test: 'get'}))
     
    });
     
     
    // head stream
    router.head('/test', function(stream, headers, flags){
      let query = stream.query;
     
    });
     
    // trace stream
    router.trace('/test', function(stream, headers, flags){
      let query = stream.query;
     
    });
     
     
     
    // post stream
    router.post('/', function(stream, headers, flags){
      let body = stream.body.text; // stream.body.buffer / stream.body.json
     
      console.log(body)
     
    });
     
    // delete stream
    router.delete('/', function(stream, headers, flags){
      let body = stream.body.text; // stream.body.buffer / stream.body.json
     
      console.log(body)
     
    });
     
    // patch stream
    router.patch('/', function(stream, headers, flags){
      let body = stream.body.text; // stream.body.buffer / stream.body.json
     
      console.log(body)
    });
     
    // put stream
    router.put('/', function(stream, headers, flags){
      let body = stream.body.text; // stream.body.buffer / stream.body.json
     
      console.log(body)
    });
     
     
    router.get('/', function(stream, headers, flags){
     
      //serve headers and serve static document
      stream.doc('/index.html', 'text/html; charset=utf-8');
     
    });
     
     
     
    // send response headers and render static document
    router.get('/', function(stream, headers, flags){
     
      stream.doc('index.html', 'text/html; charset=utf-8');
     
    });
     
    router.get('/', function(stream, headers, flags){
     
      stream.addHeader('key', 'val');
     
      stream.doc('index.html', 'text/html; charset=utf-8');
     
    });
     
     
    // send response headers and render with optional template engine installed
    router.get('/', function(stream, headers, flags){
     
      // basic ~ default
      stream.render('index.html', {title: 'basic'})
     
      // nunjucks
      stream.render('index.njk', {title: 'nunjucks'})
     
      // pug
      stream.render('index.pug', {title: 'pug'})
     
    });
     
     

    Configuration

    sicarii has a tiny but powerful list of configurations

    the configuration file at ./config/config.json is an essential part of sicarii. you MUST tweak it to your own requirements in order to maximize performance and security.

    //defaults
     
    {
      "port": 8080, // server port
      "origin": "https://localhost", // server origin
      "verbose": true, // show log to console
      "dev": true, // log errors to console
      "proxy": false, //  x-forwarded-for as ip address
      "ip_config": "/config/ip_config", // path to ip_config.json
      "pre_cache": "/config/pre_cache", // path to pre_cache.json
      "push_handler": { // automatic push handler
        "enabled": true,
        "accept": ["text/html"], // accept header document types to accept
        "path": "/config/push" // path to push config file
      },
      "cluster": {
        "workers": 2 // worker count
        "settings": { //worker settings
          "serialization": "json"
        }
      },
      "sync": {
        "respawn": true // auto-respawn dead workers
      },
      "session": {
        "path": "/store/session/db.json", //read/write dir relative to cwd
        "maxage": 1000000, //maxage of sessions in ms
        "secret": "" //optional session secret
      },
      "cache": {
        "url":"https://localhost:5000", // cache server url
        "timeout": 5000, //cache response timeout ms
        "proxy": false, // x-forwarded-for as ip address
        "authtoken": { //cache auth-token header
          "enabled": false,
          "header": "X-Authtoken",
          "token": "12345"
        },
        "whitelist": { //cache server ip whitelist
          "enabled": true,
          "ip": ["::ffff:127.0.0.1"] //cache whitelisted ip addersses
        },
        "server": {
          //cache server config ~ accepts all nodejs http2 server settings
          "rejectUnauthorized": false
        },
        "headers": {
          //cache server outbound headers
        }
      },
      "cookie_parser": {
        "enabled": true, //enable cookie parser
        "auto_parse": true, //enable auto cookie parse
        "sig": {
          "hmac": "secret", // cookie sign hmac
          "prefix": "sig" // cookie sig prefix
        }
      },
      "stream": {
        "path_limit": 100, // stream path size limit ~ false to disable check
        "case_sensitive": true, // converts url pathnames to  lowercase if false
        "param_limit": 1000, // stream url search size limit ~ false to disable check
        "body_limit": 5000, // stream body size limit ~ false to disable check
        "methods": [ // add all allowed http  methods ~ remove if unused
          "get",
          "post",
          "connect",
          "put",
          "delete",
          "head"
        ],
        "querystring": true, // enable stream.qs
        "method_body": ["post", "delete", "patch", "put"], // methods return body
        "method_query": ["get","connect", "head", "options", "trace"],// methods return query params
        "content_types": [ // accepted body content-types ~ remove if unused
          "application/json",
          "text/plain",
          "multipart/form-data",
          "application/x-www-form-urlencoded"
        ]
      },
      "blacklist": { //enable server ip blacklist
        "enabled": false,
        "msg": "your ip has been blacklisted, have a nice day" // unauth msg
      },
      "whitelist": { //enable server ip whitelist
        "enabled": false,
        "msg": "Unauthorized" // unauth msg
      },
      "authtoken": {  //enable auth token header
        "enabled": false,
        "header": "X-Authtoken",
        "token": "xxxxxx",
        "msg": "server offline" // unauth msg
      },
      "server": {
        // accepts all http2 nodejs server options
      },
      "ssl": {
        "cert": "/cert/localhost.cert", // key/cert/pfx/ca as string path to file
        "key": "/cert/localhost.key"
      },
      "store": { // sicarri store
        "path": "/store/store/db.json" // read/write path relative to cwd
      },
      "uploads": {
        "enabled": true,
        "path": "/uploads", // uploads dir, relative to cwd()
        "recursive": true, //enable recursive folder creation
        "gzip": true, // compress file using gzip
        "brotli": false, // compress file using brotli
        "deflate": false, // compress file using deflate
        "mimetypes": {
          // accepted mimetypes
        },
        "max_filename": 30, // max filename length
        "max_filesize": 50000 // max upload content length
      },
      "static": {
        "path": "/static", // default static file path
        "blocked": [],
        "etag": { // etag header
          "enabled": true, // use etags on rendered files
          "digest": "sha3-256", //etag digest hash ~ crypto.getHashes();
          "encode": "base64" //etag digest encoding hex/base64
        },
        "cache": { // static file server cache
          "enabled": true, // enable cache on static file server
          "maxage": 1000000 // cached items maxAge
        },
        "headers": {} // default headers for static file server
      },
      "render": { // render/tempate engine defaults
        "path": "/render",
        "blocked": [],
        "etag": { // etag header
          "enabled": true, // use etags on rendered files
          "digest": "sha3-256", //etag digest hash ~ crypto.getHashes();
          "encode": "base64" //etag digest encoding hex/base64
        },
        "cache": { // rendered files cache
          "enabled": true, // enable cache on rendered files
          "maxage": 1000000 // cached items maxAge
        },
        "headers": { // default headers for rendered files
          "X-Frame-Options": "DENY",
          "Referrer-Policy": "no-referrer",
          "Server": "Nodejs",
          "Access-Control-Allow-Origin": "*",
          "Access-Control-Allow-Methods": "GET",
          "X-DNS-Prefetch-Control": "on",
          "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
          "X-Content-Type-Options": "nosniff",
          "X-XSS-Protection": "1",
          "TK": "N"
        }
      },
      "compression": {
        "gzip": { // gzip compression
          "enabled": true,
          "prezipped": false, // use pre-compressed files
          "ext": ".gz", // compressed file extention
          "setting": {} // accepts all nodejs gzip compression settings
        },
        "brotli": { // brotli compression
          "enabled": false,
          "prezipped": false, // use pre-compressed files
          "ext": ".br", // compressed file extention
          "setting": {} // accepts all nodejs brotli compression settings
        },
        "deflate": { // deflate compression
          "enabled": false,
          "prezipped": false, // use pre-compressed files
          "ext": ".dfl", // compressed file extention
          "setting": {} // accepts all nodejs deflate compression settings
        }
      },
      "cors": { // default stream.cors fallback
        "origin": '',        // string  | Access-Control-Allow-Origin
        "methods": '',       // string  | Access-Control-Allow-Methods
        "allow_headers": '', // string  | Access-Control-Allow-Headers
        "expose_headers": '',// string  | Access-Control-Expose-Headers
        "credentials": true, // boolean | Access-Control-Allow-Credentials
        "maxage": 9999       // number  | Access-Control-Max-Age
      },
      "csp": { // content security policy object
        "default": "default-src 'self'"
      },
      "feature_policy": { // feature policy object
        "default": "microphone 'none'; geolocation 'none'"
      },
      "logs": {
        "path": "/logs", //path to log dir
        "separator": "|", // log separator
        "logs":["error", "history","ip"],
        "cron": 86400000, // logs cronjob interval
        "console_error": false, //log to console log-related errors
        "compression": "gzip", // backup compression ~ gzip/deflate/brotli
        "encodeURIComponent": false, // encode log entries
        "error": {
          "enabled": true, // enable auto error logs
          "max_size": 5000, // log max file size
          "base_name": "error", //log file base name
          "ext": ".txt" //log file base extension
        },
        "history": {
          "enabled": true, // enable auto history logs
          "max_size": 5000, // log max file size
          "base_name": "history", //log file base name
          "ext": ".txt" //log file base extension
        },
        "ip": {
          "enabled": true, // enable ip logging
          "max_size": 5000, // log max file size
          "base_name": "ip", //log file base name
          "ext": ".txt" //log file base extension
          "log_time": true, // add timestamp to log
          "log_path": true // add path to log
        }
      },
      "template_engine": { // template engine config
        "engines": [
          "basic", "poorboy", "nunjucks", "ejs", "pug",
          "mustache", "twig", "squirrelly", "ect", "eta",
          "liquidjs"
        ],
        "basic": {
          "enabled": true,
          "settings": {
            "pretty": false,
            "filters": {},
            "cache": false
          }
        },
        "squirrelly": {
          "enabled": false,
          "settings": {}
        },
        "eta": {
          "enabled": false,
          "settings": {}
        },
        "liquidjs": {
          "enabled": false,
          "settings": {
            "extname": ".liquid"
          }
        },
        "ect": {
          "enabled": false,
          "settings": {
            "cache": false,
            "open": "<%",
            "close": "%>"
          }
        },
        "poorboy": {
          "enabled": false,
          "settings": {
            "use_globals": false,
            "globals": {}
          }
        },
        "nunjucks": {
          "enabled": false,
          "jinjacompat": true,
          "filters": "",
          "globals": {
            "enabled": false,
            "vars": {}
          },
          "settings": {
            "autoescape": true,
            "noCache": true,
            "throwOnUndefined": false,
            "trimBlocks": false,
            "lstripBlocks": false,
            "tags": {}
          }
        },
        "ejs": {
          "enabled": false,
          "settings": {}
        },
        "pug": {
          "enabled": false,
          "settings": {
            "pretty": false,
            "filters": {},
            "cache": false
          }
        },
        "mustache": {
          "enabled": false,
          "tags": ["{{", "}}"],
          "settings": {}
        },
        "twig": {
          "enabled": false,
          "settings": {}
        }
      },
      "mimetypes": {
        // a list of all your allowed mimetypes
      },
      "crypt": {
        "jwt":{
          "secret": "secret", // jwt secret for hmac
          "digest": "sha256", // jwt digest for hmac
          "encode": "base64", // jwt encoding
          "separator": ":", // jwt token separator
          "header": { // jwt header
            "typ": "JWT",
            "alg": "HS256"
          },
          "claims": {
            "iss": "token issuer", // optional jwt issuer
            "sub": "token subject", // optional jwt subject
            "aud": "token audience", // optional jwt audience
            "exp": 5000000, // mandatory ms till expires
            "nbf": 0 // optional ms till valid
          }
        },
        "hmac": {
          "secret": "secret",  // hmac secret
          "digest": "sha3-512", // hmac hash function
          "encode": "hex" // output encode
        },
        "pbkdf2": {
          "digest": "sha3-512", // hash function
          "encode": "hex", // output encode
          "iterations": 50000 // kdf iterations
        },
        "scrypt": {
          "encode": "hex", // output encode
          "cost": 16384, // scrypt cost
          "blockSize":8, // scrypt cost
          "parallelization": 1 // scrypt parallelization
        },
        "encryption": {
          "secret": "", // encrypt/decrypt ~ app secret
          "secret_len": 32, // correct key length
          "iterations": 60000, // iterations to be used in keygen
          "digest": "sha3-512", // digest to be used in keygen
          "settings": { // THESE SETTINGS MUST BE VALID
            "cipher": "aes", // encrypt/decrypt cipher
            "bit_len": "256", // encrypt/decrypt bit
            "iv_len": 32, // encrypt/decrypt iv length
            "tag_len": 16, // encrypt/decrypt auth-tag length
            "encode": "hex", // encrypt/decrypt/keygen encoding
            "mode": "gcm" // encrypt/decrypt mode
          }
        },
        "ecdsa": {
          "curve": "secp521r1", // ecdsa curve
          "encode": "hex", // ecdsa encoding
          "hash": "sha3-512", // ecdsa hash used
          "privateKey": {  // accepts all nodejs ec privateKey settings
            "type": "sec1",
            "format": "der"
          },
          "publicKey": { // accepts all nodejs ec publicKey settings
            "type": "spki",
            "format": "der"
          }
        },
        "ecdh": { // ecdh key exchange
          "curve": "secp521r1",  // ecdh curve
          "encode": "hex"  // ecdh encoding
        },
        "rsa": { // rsa encryption
          "length": 4096, // rsa modulusLength
          "publicExponent": 65537,
          "encode": "hex",
          "oaepHash": "sha512", // rsa oeap hash used
          "publicKey": { // accepts all nodejs rsa publicKey settings
            "type": "pkcs1",
            "format": "pem"
          },
          "privateKey": { // accepts all nodejs rsa privateKey settings
            "type": "pkcs8",
            "format": "pem"
          }
        },
        "otp": { // contains the one time pad defaults
          "rounds": 1, // otp encrypt/decrypt rounds count
          "iterations": 10000, // iteration count for generating a secure pad
          "digest": "sha512", // digest used for generating a secure pad
          "encode": "hex" // encoding used for otp
        }
      },
      "bot": {
        "detect": {
          "items": ["Googlebot"] // manual detect bots via user-agent sub-string
        },
        "block": {  // automatically block bots via user-agent sub-string
          "enabled": false,
          "msg": "Unauthorized", // bot block msg
          "items": [] // blocked bots array
        }
      }
    }
     

    Stream

    accepts all nodejs methods and the following:

    stream.doc(src, content-type)

    stream doc will serve a document from the render folder

    • this method will use cache if available
    • this method will use compression if available
    • this method will stream respond headers
    • this method will send default headers from config.render.headers
    • this method will use etag settings from config.render.etag
    • this method will use cache settings from config.render.cache
    • this method will use gzip/brotli/deflate settings from config.compression
     
    /**
     *  stream.doc(path, contentType, callback)
     *  @param {string} path // file path relative to render dir
     *  @param {string} contentType // file content-type
     *  @param {function} callback ~ optional
     **/
     
      router.get('/', function(stream, headers, flags){
     
        // send response headers and render static document from the render dir
        stream.doc('index.html', 'text/html; charset=utf-8');
     
      });

    stream.render(src, data)

    stream render will serve a rendered document from the render folder. refer to template engines.

    • this method will use cache if available
    • this method will use compression if available
    • this method will stream respond headers
    • this method will send default headers from config.render.headers
    • this method will use etag settings from config.render.etag
    • this method will use cache settings from config.render.cache
    • this method will use gzip/brotli/deflate settings from config.compression
     
    /**
     *  stream.render(path, obj, callback)
     *  @param {string} path // file path relative to render dir
     *  @param {object} obj // data for rendered file
     *  @param {function} callback ~ optional
     **/
     
      router.get('/', function(stream, headers, flags){
     
        // basic ~ default: uses template literals in html documents
        stream.render('index.html', {title: 'basic'})
     
        // nunjucks ~ requires manual installation of nunjucks
        stream.render('index.njk', {title: 'nunjucks'})
     
        // pug ~ requires manual installation of pug
        stream.render('index.pug', {title: 'pug'})
     
      });
     

    stream.pushStatic(path, ctype)

    stream pushStatic will push a file or files from the static folder before requested.

    • this method can be chained to push multiple files
    • this method will use cache if available
    • this method will use compression if available
    • this method will send default headers from config.static.headers
    • this method will use etag settings from config.static.etag
    • this method will use cache settings from config.static.cache
    • this method will use gzip/brotli/deflate settings from config.compression
    • config.verbose will log the push state of a file
    • this method is asynchronous so the stream object is immediately returned
    • any errors are handled by sicarii in the same manner as the static file server
     
    /**
     *  stream.pushStatic(path, ctype) // single file
     *  @param {string} path // file path relative to static dir as it would be requested as
     *  @param {string} ctype // file content type as it would be requested as
     *
     *  stream.pushStatic(obj) // multiple files
     *  @param {object} obj // obj.path: file path, obj.ctype: content-type
     **/
     
      router.get('/', function(stream, headers, flags){
        /* push files to the browser before the browser requests them */
     
        // push a file before it has been requested
        stream
        .pushStatic('/css/main.css', 'text/css')
        .status(200)
        .doc('index.html', 'text/html')
     
        // or push multiple files before they have been requested
     
        stream
        .pushStatic([{
          path: '/css/main.css', // file path
          ctype: 'text/css' // file content type
        },{
          path: '/favicon.ico',
          ctype: 'image/x-icon'
        }])
        .status(200)
        .render('index.html', {test: 'push'}, function(err){
          if(err){return console.error(err)}
        })
     
      });
     

    stream.download(file, content-type)

    stream.download will initiate a file download upon browser navigation.

    • stream.download uses config.static settings
    • this method will use cache if available
    • this method will use compression if available
    • this method will stream respond headers
    • this method will send default headers from config.static.headers
    • this method will use etag settings from config.static.etag
    • this method will use cache settings from config.static.cache
    • this method will use gzip/brotli/deflate settings from config.compression
    • this method will Content-Disposition 'attachment; filename="the files name"' to the headers;
     
    /**
     *  stream.download(path, contentType, callback)
     *  @param {string} path // file path relative to static dir
     *  @param {string} contentType // file content-type
     *  @param {function} callback ~ optional
     **/
     
    router.get('/downloadpath', function(stream, headers, flags){
      // main.mjs will download when /downloadpath is navigated to in the browser
      stream.download('modules/main.mjs', 'application/javascript');
     
    });

    stream.upload(object, callbabk)

    stream.upload will upload a file to your uploads dir if enabled at config.uploads.enable

    • config.uploads.gzip will enable/disable gzip compression for uploads
    • config.uploads.brotli will enable/disable brotli compression for uploads
    • config.uploads.deflate will enable/disable deflate compression for uploads
    • config.uploads.path is your upload path relative to cwd()
    • config.uploads.recursive will enable recursive dir creation within config.uploads.path,
    • config.uploads.mimetypes should list all accepted upload mimetypes in the same format as config.mimetypes
    • config.uploads.max_filename max filename length
    • config.uploads.max_filesize max content length

    simple upload example:

     
    /**
     *  stream.upload(settings, callback)
     *  @param {object} settings // upload settings
     *  @param {function} callback ~  function(err,res) | optional
     **/
     
    router.post('/upload', function(stream, headers, flags){
        let ctype = headers.get('content-type');
     
        if(ctype !== 'application/json'){
          // do something
        }
     
        try {
          let body = JSON.stringify(stream.body.json);
     
          let upload_data = {
            path: '/test/index.json', // path relative to uploads dir
            ctype: ctype, // content type
            data: body, // data as string
            brotli: true, //override default brotli setting config.uploads.brotli ~ optional
            gzip: false //override default gzip setting config.uploads.gzip ~ optional
            //deflate: false //override default deflate setting config.uploads.deflate ~ optional
          }
     
          stream.upload(upload_data, function(err,res){
            if(err){
              // do something
              return;  
            }
     
            stream.json({upload: 'success'})
     
          })
        } catch (err) {
          // do something
        }
     
    });

    stream.json(data)

    stream.json() performs the following actions:

    • add content-type 'application/json' to the headers;
    • stream the headers object.
    • send stringified json
     
    /**
     *  stream.json(obj, contentType, callback)
     *  @param {array/object} obj // data to be stringified
     *  @param {function} callback ~ optional
     **/
     
    router.get('/', function(stream, headers, flags){
     
      stream.json({send: 'json'})
     
    });
     

    stream.redirect(dest)

    stream.redirect() performs the following actions:

    • add location destination to the headers;
    • stream the headers object.
    • send redirect
     
    /**
     *  stream.redirect(path)
     *  @param {string} path // redirect anywhere path
     **/
     
    router.get('/', function(stream, headers, flags){
      //redirect to url
      stream.redirect('/test')
     
    });
     

    stream.ip

    stream.ip returns the client ip address

    • enable config.proxy to return ['x-forwarded-for'] ip
     
    router.get('/', function(stream, headers, flags){
     
      console.log(stream.ip)
      // xxx.xxx.x.x.x
     
    });
     

    stream.headers

    stream.headers will return an object containing all current and default outbound headers; this is not to be mistaken with the received headers object;

    router.get('/', function(stream, headers, flags){
     
      //log default received headers to console
      console.log(headers.all())
     
      //log default outbound headers to console
      console.log(stream.headers)
     
      // add outbound header
      stream.addHeader('Content-Type', 'text/plain');
     
      stream.respond(stream.headers);
      stream.end('headers sent')
     
    })
     

    stream.addHeader()

    stream.addHeader(key,val) will add a header to stream.headers

     
    /**
     *  stream.addHeader(key, val)
     *  @param {string} key // header type
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound header
      stream.addHeader('Content-Type','text/plain');
      //stream.headers['Content-Type'] = 'text/plain';
     
      stream.respond(stream.headers);
      stream.end('headers sent')
     
    })
     

    stream.addHeaders()

    stream.addHeaders(obj) will assign an object of headers to stream.headers

     
    /**
     *  stream.addHeaders(key, val)
     *  @param {object} obj // headers object
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound header
      stream.addHeaders({
        'content-type':'text/plain',
        'content-encoding': 'gzip'
      });
     
      stream.respond(stream.headers);
      stream.end('headers sent')
     
    })
     

    stream.cors()

    stream.cors() will add the included cors options to stream.headers

    • this method will override any default cors headers in config.render.headers || config.static.headers
    • this method will fallback to config.cors if no object is provided
     
    /**
     *  stream.cors(obj)
     *  @param {object} obj // optional | cors entries || fallback to config.cors
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add all outbound cors headers
      stream.cors({
        origin: '',        // string  | Access-Control-Allow-Origin
        methods: '',       // string  | Access-Control-Allow-Methods
        allow_headers: '', // string  | Access-Control-Allow-Headers
        expose_headers: '',// string  | Access-Control-Expose-Headers
        credentials: true, // boolean | Access-Control-Allow-Credentials
        maxage: 9999       // number  | Access-Control-Max-Age
      });
     
      // or only some
      stream.cors({
        origin: '',
        methods: '',
        allow_headers: ''
      });
     
      // or use config.cors
      stream.cors();
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.ctype()

    stream.ctype(val) will add the Content-Type header to stream.headers

     
    /**
     *  stream.ctype(val)
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound Content-Type header
      stream.ctype('text/plain');
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.lang()

    stream.lang(val) will add the Content-Language header to stream.headers

     
    /**
     *  stream.lang(val)
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound Content-Language header
      stream.lang('en-US');
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.tk()

    stream.tk(val) will add the TK header to stream.headers

     
    /**
     *  stream.tk(val)
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      /*
      Tk: !  (under construction)
      Tk: ?  (dynamic)
      Tk: G  (gateway or multiple parties)
      Tk: N  (not tracking)
      Tk: T  (tracking)
      Tk: C  (tracking with consent)
      Tk: P  (potential consent)
      Tk: D  (disregarding DNT)
      Tk: U  (updated)
      */
     
      // add outbound TK header
      stream.tk('N');
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.csp()

    stream.csp(val) will add the Content-Security-Policy header to stream.headers

    • stream.csp will load the csp from config.csp;
    • this method enables you to store and use multiple pre-defined content security policies
     
    /**
     *  stream.csp(val)
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound Content-Security-Policy header from `config.csp.default`
      stream.csp('default');
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.feature()

    stream.feature(val) will add the Feature-Policy header to stream.headers

    • stream.feature will load the Feature-Policy from config.feature_policy;
    • this method enables you to store and use multiple pre-defined feature policies
     
    /**
     *  stream.feature(val)
     *  @param {string} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound Feature-Policy header from `config.feature_policy.default`
      stream.feature('default');
     
      stream.respond(stream.headers)
     
      stream.end('text')
    })
     

    stream.status()

    stream.status(val) will set the :status header to stream.headers

     
    /**
     *  stream.status(val)
     *  @param {number} val // header value
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // add outbound :status header
      stream.status(200).ctype('text/plain').respond(stream.headers);
     
      stream.end('text')
    })
     

    stream.query

    stream.query is part of body parser. if enabled, it will parse the given query to json. refer to body parses section.

    • config.stream.method_query controls the accepted router methods.
    • config.stream.content_types controls the accepted content types.
    router.get('/test', function(stream, headers, flags){
      let query = stream.query;
      console.log(query)
     
    });
     

    stream.qs

    stream.qs is similar to stream.query but returns the unparsed querystring. This method is intended for use with custom or complex querystrings;

    • config.stream.querystring enable/disable
    • the returned querystring is decoded with decodeURIComponent()
    router.get('/test', function(stream, headers, flags){
      let customquery = stream.qs;
      console.log(customquery)
     
    });

    stream.body.text

    stream.body.text is the default body parse format

    • returns string
    router.post('/', function(stream, headers, flags){
      let body = stream.body.text;
     
      console.log(body)
     
    });

    stream.body.buffer

    stream.body.buffer is part of body parser.

    • returns buffer
    router.post('/', function(stream, headers, flags){
      let buff = stream.body.buffer;
     
      console.log(buff)
     
    });

    stream.body.json

    stream.body.buffer is part of body parser. refer to body parses section.

    • returns json for supported content-types
    router.post('/', function(stream, headers, flags){
      let obj = stream.body.json;
     
      console.log(obj)
     
    });

    stream.cookies

    this method is a part of cookie parser refer to cookie parser

    stream.cookie will enable you to easily access all cookies in headers

    • this method automatically deserializes all cookies.
    • this method requires config.cookie_parser.enabled to be enabled
    • this method can be enabled/disabled at config.cookie_parser.auto_parse
    router.get('/', function(stream, headers, flags){
     
      // return cookies object ~ config.cookie_parser.auto_parse
      console.log(stream.cookies)
     
    })

    stream.cookie()

    this method is a part of cookie parser refer to cookie parser

    stream.cookie(name,val,obj) will enable you to easily add cookies to the stream.response

    • this method automatically adds the created cookie to stream.headers
    • this method can be enabled/disabled at config.cookie_parser.enabled
    • this method can create a separate signed cookie for tamper detection
    • config.cookie_parser.sig.secret is used to hmac the cookie
    • config.cookie_parser.sig.suffix is the signed cookies suffix
    • a signed cookie will be will use digest/encode settings from config.crypt.hmac
     
    /**
     *  stream.cookie(key, val, settings)
     *  @param {string} key // cookie name
     *  @param {string} val // cookie value
     *  @param {object} settings // cookie settings
     **/
     
    router.get('/', function(stream, headers, flags){
     
      //create cookie and add to outbouheaders ~ config.cookie_parser.enabled
      stream.cookie('name', 'value',{
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Lax',
        Secure: true,
        Priority: 'High',
        Signed: true // creates a separate suffixed signed cookie for validation
      })
     
      stream.respond(stream.headers);
      stream.end()
     
    })

    push handler

    the push handler will enable/disable automatic stream push of static files.

    upon stream, the server will search the accepted header for a match in config.push_handler.accepted and will push your selected files with the document

    • config.push_handler.enabled enables this method
    • this method is for static files only e.g js/css/png/jpg
    • this method is not for rendered/static documents e.g html/xhtml/xml
    • this method is for GET requests only.
    • config.push_handler.accepted should contain the requested paths content-type e.g text/html
    • config.push_handler.accepted should not contain the pushed items content-type e.g text/css
    • config.push_handler.accepted should only contain document content-types that you use
    • config.push_handler.accepted should be as small as possible
    • automatic stream push of static files is recommended only for push intensive sites

    the push configuration file can be configured like so:

    /* ./config/push.json */
     
     
    [{
      "url": "/single_push", // the url path that the file is to be pushed for
      "ctype": "text/css",   // file content-type 'only'
      "path": "/css/main.css" // file path relative to static path
    },{
      "url": "/multi_push",
      "items": [{ // push multiple items at same url
        "ctype": "text/css",
        "path": "/css/main.css"
      },{
        "ctype": "image/x-icon",
        "path": "/favicon.ico"
      }]
    }]
     
     
     
    router.get('/single_push', function(stream, headers, flags){
      // will automatically push a static file and send headers/doc
     
      stream.status(200).doc('index.html', 'text/html')
    });
     
    router.get('/multi_push', function(stream, headers, flags){
      // will automatically push multiple static files and send headers/doc
     
      stream.status(200).doc('index.html', 'text/html')
    });
     
    router.get('/manual_push', function(stream, headers, flags){
      // will not automatically push multiple static files
     
     
      stream // manually push multiple static files and send headers/doc
      .pushStatic([{
        path: '/css/main.css', // file path
        ctype: 'text/css' // file content type
      },{
        path: '/favicon.ico',
        ctype: 'image/x-icon'
      }])
      .status(200)
      .doc('index.html', 'text/html')
    });
     

    Headers

    the headers object includes the following methods:

    headers.all()

    headers.all() will return a valid json object containing all received headers

     
    router.get('/', function(stream, headers, flags){
     
      // log all received headers
      console.log(headers.all())
     
    })

    headers.get()

    headers.get() will return a header from the headers object in nodejs http2 format

     
    /**
     *  headers.get(key)
     *  @param {string} key // header name
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // return content-type header
      console.log(headers.get('content-type'))
     
    })

    headers.is()

    headers.is() will return a boolean if the header is equal to the comparison

     
    /**
     *  headers.is(key, val)
     *  @param {string} key // header name
     *  @param {string} val // value to compare
     **/
     
    router.get('/admin', function(stream, headers, flags){
     
      // check content-type
      if(!headers.is('x-token', 'secret')){
        app.blacklist(stream.ip)
      }
     
    })
     

    headers.has()

    headers.has() will return a boolean if the header exists

    • will also return true for header that exists and has a value of false or 0
     
    /**
     *  headers.has(key)
     *  @param {string} key // header name
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // check if cookie header exists
      if(headers.has('cookie')){
        console.log('cookie header exists')
      }
     
    })
     

    headers.cookies()

    headers.cookies() will return a deserialized cookies json object

     
    router.get('/', function(stream, headers, flags){
     
      // return cookies object
      console.log(headers.cookies())
     
    })
     

    headers.ctype()

    headers.ctype() will return the Content-type header if exists

     
    router.get('/', function(stream, headers, flags){
     
      console.log(headers.ctype())
      // application/json ...
     
    })
     

    headers.agent()

    headers.agent() will return the User-agent header if exists

     
    router.get('/', function(stream, headers, flags){
     
      console.log(headers.agent())
      // some browser user-agent ...
     
    })
     

    headers.bot()

    headers.bot() will return true if the user-agent detected is a bot

    • config.bot.items should contain an array of bots to check for
    • this feature could be used to perform targeted seo optimization
     
    router.get('/', function(stream, headers, flags){
     
     
      if(headers.bot()){
        // render template containing seo data only
        let useragent = headers.ua();
     
        if(useragent.includes('google')){
          stream.render('index_seo_google.html', {
            data: {
              some: 'google data',
              specifically: 'relating',
              to: 'google seo'
            }
          })
        } else if(useragent.includes('facebook')) {
          stream.render('index_seo_facebook.html', {
            data: {
              some: 'facebook data',
              specifically: 'relating',
              to: 'facebook seo'
            }
          })
        } else {
          stream.render('index_seo_default.html', {
            data: {
              some: 'default data',
              specifically: 'relating',
              to: 'default seo'
            }
          })
        }
      } else {
        // render normal template not polluted with seo
        stream.render('index.html', {title: 'basic'})
      }
     
     
    })
     

    headers.encoding()

    headers.encoding() will return the accept-encoding header if exists

    • the returned value/s will be within a trimmed array
     
    router.get('/', function(stream, headers, flags){
     
      console.log(headers.encoding())
      // ['accepted', 'encoding']
     
    })
     

    headers.lang()

    headers.lang() will return the accept-language header if exists

    • the returned value/s will be within a trimmed array
     
    router.get('/', function(stream, headers, flags){
     
      console.log(headers.lang())
      // ['accepted', 'language']
     
    })
     

    headers.accept()

    headers.accept() will return the accept header if exists

    • the returned value/s will be within a trimmed array
     
    router.get('/', function(stream, headers, flags){
     
      console.log(headers.accept())
      // ['accepted', 'content', 'types']
     
    })
     

    headers.size()

    headers.size() length of the headers object

     
    router.get('/', function(stream, headers, flags){
     
      let len = headers.size(); // headers length
      if(len > 1000){
        app.blacklist(stream.ip)
      }
     
    })
     

    headers.count()

    headers.count() will return a count of your total headers

     
    router.get('/', function(stream, headers, flags){
     
      let len = headers.count(); // headers count
      if(len > 50){
        app.blacklist(stream.ip)
      }
     
    })
     

    App

    the app object exists as a bridge between worker/master.

    • app must be accessible outside of the worker/master scope
    • all methods within app are available to the master and worker threads
    • app contains a list of helper functions that might otherwise require dependencies

    app.config

    app.config gives you access to your current configuration vars throughout your app.

     
    console.log(app.config.port)
     

    app.set()

    app.set() will set environmental variables available to the scope in which they are called

    /**
     *  app.setEnv(key, val)
     *  @param {string} key //  
     *  @param {string|object|number|buffer} val 
     **/
     
     app.set('key', 'val');
     
    console.log(app.env('key'));
    // val
     
    console.log(process.env.key);
    //val

    app.env()

    app.env() will get environmental variables available from the scope in which they are called

    /**
     *  app.env(key)
     *  @param {string} key 
     **/
     
     app.set('key', 'val');
     
    console.log(app.env('key'));
    // val
     

    app.uuid

    app.config generates a random uuidv4

     
    console.log(app.uuid())
    // 4370139d-653c-49eb-933e-a714eec14f69
     

    app.bot()

    app.bot() will return true if the user-agent detected is a bot

    • config.bot.items should contain an array of bots to check for
    • this feature could be used to perform targeted seo optimization
    • refer to headers.bot()
     
    router.get('/', function(stream, headers, flags){
     
      let useragent = headers.ua();
      if(app.bot(useragent)){
        console.log('bot detected')
      }
     
    })
     

    app.fetch()

    the app.fetch method will perform a secure http2 client request to any local or external address.

    • app.fetch uses your apps ssl certificate/s to create a secue connection

    app.fetch uses body parser to automatically parse responses for the following content-types:

    • application/json ~ response.json | data as parsed json object/array
    • multipart/form-data ~ response.text | data as string
    • application/x-www-form-urlencoded ~ response.text | data as string

    all content-types are available as:

    • * ~ response.text | data as string
    • * ~ response.buffer | data as buffer
     
    /**
     *  app.fetch(obj, callback, timeout)
     *  @param {object} obj // cookie name
     *  @param {object} callback // function(err,response)
        @param {number} timeout // milliseconds ~ optionally overrides config.fetch.tomeout
     **/
     
    /* simple json get example */
     
    let head = {
      'url': 'https://example_get_url.com', //dest url
      ':method': 'GET', // fetch method
      ':path': '/example/path', // fetch path
      'Content-Type': 'application/json'
      // your other headers ...
    }
     
    let timeout = 5000 // optional
     
    app.fetch(head, function(err,response){
      if(err){return console.error(err)}
     
      console.log(response.headers) // response headers object
      console.log(response.json) // response as json ~ if available
      console.log(response.buffer) // response as buffer
      console.log(response.text) // response as text
      console.log(response.statusText) // ok/not ok
     
    },timeout)
     
    /* simple post example */
     
    let data = JSON.stringify({test: 'body'});
     
    let head = {
      'url': 'https://example_post_url.com', //dest url
      ':method': 'POST', // fetch method
      ':path': '/example/path' // fetch path
      'body':  data// fetch body for accepted methods
      "Content-Type": "application/json"
      // ...
    }
     
    app.fetch(head, function(err,res){
      if(err){return console.error(err)}
      console.log(res.headers) // response headers object
      console.log(res.json) // response as json ~ if available
      console.log(res.buffer) // response as buffer
      console.log(res.text) // response as text
      console.log(res.statusText) // ok/not ok
    })
     

    app.etag()

    refer to stream for a more detailed explanation.

    app.etag can be used to manually create a hashed etag from data that you may use in a stream.

    the following digests are supported:

    insecure

    • md5, md5-sha1, ripemd160, rmd160, sha1

    secure

    • sha224, sha256, sha384, sha512, sha512-224, sha512-256, whirlpool

    excessive

    • sha3-224, sha3-256, sha3-384,sha3-512, blake2b512, blake2s256, shake128,shake256
    /**
     *  app.etag(digest, data, encode)
     *  @param {string} digest // hash digest
     *  @param {string} data // data to be hashed
     *  @param {string} encode // base64/hex
     **/
     
    router.get('/etagdemo', function(stream, headers, flags){
     
      // manual app.etag
      let etag = app.etag('sha3-512', 'test string', 'base64');
      stream.addHeader('Etag', etag)
     
    });
     

    app.digest()

    app.digest can be used to manually create a digest from data for the Digest header.

    the following prefixes are recommended:

    • sha-224, sha-256, sha-384, sha-512

    the following digests are supported recommended:

    • sha224, sha256, sha384, sha512

    those are the current recommended standards. you can use any equivalents from the above mentioned in app.etag if you want to implement your own standard.

    /**
     *  app.digest(prefix, encode, data, digest)
     *  @param {string} prefix // valid http digest header prefix e.g. sha-256/sha-512
     *  @param {string} digest // valid nodejs digest hash digest
     *  @param {string} data // data to be hashed
     *  @param {string} encode // base64/hex
     **/
     
    router.get('/digestdemo', function(stream, headers, flags){
     
      stream.addHeader('Digest', app.digest('sha-512', 'sha512', 'test digest', 'base64'));
     
    });
     

    app.cookie_encode()

    refer to stream for a more detailed explanation.

    app.cookie_encode can be used to manually create cookies

     
    /**
     *  app.cookie_encode(key, val, settings)
     *  @param {string} key // cookie name
     *  @param {string} val // cookie value
     *  @param {object} settings // cookie settings
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // manual create cookie and add to outbouheaders
      let new_cookie = app.cookie_encode('name', 'value',{
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Lax',
        Secure: true,
        Priority: 'High'
      })
      // add cookie to headers
      stream.addHeader('Set-Cookie', [new_cookie]);
     
      // send headers & send json response
      stream.json({msg: 'cookie created'});
     
    })

    app.cookie_sign()

    refer to cookie_parser for a more detailed explanation.

    app.cookie_sign can be used to manually create signed cookies

     
    /**
     *  app.cookie_sign(key, val, settings)
     *  @param {string} key // cookie name
     *  @param {string} val // cookie to sign value
     *  @param {object} settings // cookie settings
     **/
     
    router.get('/', function(stream, headers, flags){
     
      // manual create cookie and add to outbouheaders
      let cookie_specs = {
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Lax',
        Secure: true,
        Priority: 'High'
      }
      let new_cookie = app.cookie_encode('name', 'value', cookie_specs),
      // manual create cookie sig and add to outbouheaders
      signed_cookie = app.cookie_sign('name', 'value', cookie_specs);
      // only required for manual add
      stream.addHeader('Set-Cookie',  [new_cookie, signed_cookie]);
     
      // send headers & send json response
      stream.json({msg: 'cookies created'});
     
    })

    app.cookie_decode()

    refer to stream for a more detailed explanation.

    app.cookie_decode can be used to create a deserialized cookies object

     
    /**
     *  app.cookie_decode(key, val, settings)
     *  @param {string} settings // cookie header
     **/
     
     
    router.get('/', function(stream, headers, flags){
     
      // manual return cookies object
      console.log(app.cookie_decode(headers.get('cookie')))
     
    });
     

    app.cookie_verify()

    app.cookie_verify can be used to verify signed cookies

    • app.cookie_verify is for signed cookies only
    • app.cookie_verify will return true if the cookie is valid
     
    /**
     *  app.cookie_verify(name, obj)
     *  @param {string} name // cookie name to verify
     *  @param {object} settings // cookies object
     **/
     
    router.get('/', function(stream, headers, flags){
      // verify cookie with name=name
      console.log(
        app.cookie_verify('name', headers.get('cookie'))
      )
      // true/false
     
    })

    app.blacklist()

    refer to blacklist

    app.blacklist can be used add ip addresses to your blacklist

    • this action controlled by sync
    • this action will trigger an update of the blacklist cache for all worker threads
    • no server restart is required.
     
    /**
     *  app.blicklist(ip)
     *  @param {string|array} ip // ip address/addresses to add to blacklist
     **/
     
    router.get('/', function(stream, headers, flags){
     
      app.blacklist(stream.ip)
     
      // or add multiple in Array
     
      app.blacklist([stream.ip])
     
    });
     

    app.whitelist()

    refer to whitelist

    app.whitelist can be used add ip address to your whitelist

    • this action controlled by sync
    • this action will trigger an update of the whitelist cache for all worker threads
    • no server restart is required.
     
    /**
     *  app.whitelist(ip)
     *  @param {string|array} ip // ip address or array of address to add to whitelist
     **/
     
    router.get('/', function(stream, headers, flags){
     
      app.whitelist(stream.ip);
     
      //or multiple in array
     
      app.whitelist([stream.ip]);
     
    });
     

    app.gzip

    refer to compression for a more detailed explanation.

    gzip compression can be used anywhere via the app.gzip method:

    /**
     *  @app.gzip(data, method, options, callback)
     *
     *  @param {Buffer/TypedArray/DataView/ArrayBuffer/string} data
     *  @param {boolean} method ~ true = compress | false = decompress
     *  @param {object} options ~ optional | fallback to config.compression.gzip.settings
     *  @param {function} callback ~ function(err,res) | optional | no callback for sync
     **/
     
    let str = 'test'
    //gzipSync
    str = app.gzip(str, true);
     
    //gunzipSync
    str = app.gzip(str, false);
     
    console.log(str.toString())
    // test
     
    //gzip
    app.gzip(str, true, function(err,res){
     
      //gunzip
      app.gzip(res, false, function(err,str){
        console.log(str.toString())
        // test
      })
    })

    app.brotli

    refer to compression for a more detailed explanation.

    brotli compression can be used anywhere via the app.brotli method:

     
    /**
     *  @app.brotli(data, method, options, callback)
     *
     *  @param {Buffer/TypedArray/DataView/ArrayBuffer/string} data
     *  @param {boolean} method ~ true = compress | false = decompress
     *  @param {object} options ~ optional | fallback to config.compression.brotli.settings
     *  @param {function} callback ~ function(err,res) | optional | no callback for sync
     **/
     
    let str = 'test'
    //brotliCompressSync
    str = app.brotli(str, true);
     
    //brotliDecompressSync
    str = app.brotli(str, false);
     
    console.log(str.toString())
    // test
     
    //brotliCompress
    app.brotli(str, true, function(err,res){
     
      //brotliDecompress
      app.brotli(res, false, function(err,str){
        console.log(str.toString())
        // test
      })
    })

    app.deflate

    refer to compression for a more detailed explanation.

    deflate compression can be used anywhere via the app.deflate method:

     
    /**
     *  @app.deflate(data, method, options, callback)
     *
     *  @param {Buffer/TypedArray/DataView/ArrayBuffer/string} data
     *  @param {boolean} method ~ true = compress | false = decompress
     *  @param {object} options ~ optional | fallback to config.compression.deflate.settings
     *  @param {function} callback ~ function(err,res) | optional | no callback for sync
     **/
     
    let str = 'test'
    //deflateSync
    str = app.deflate(str, true);
     
    //inflateSync
    str = app.deflate(str, false);
     
    console.log(str.toString())
    // test
     
    //deflate
    app.deflate(str, true, function(err,res){
     
      //inflate
      app.deflate(res, false, function(err,str){
        console.log(str.toString())
        // test
      })
    })
     

    app.engine.add()

    refer to template engines

    extra template engines can be added using app.engine.add:

    • sicarii/lib/adapters will contain your new engine template.
    • config.template_engine will automatically be updated with your settings
     
    /**
     *  app.engine.add(title, obj, callback)
     *  @param {string} title // template engine title in snake_case
     *  @param {object} obj // data new engine
     *  @param {function} callback function(err)
     **/
     
    app.engine.add('test', {
      "enabled": false, // must have enabled
      "settings": {
        "use_globals": false,
        "globals":{}
      }
    }, function(err){
      if(err){return console.error(err)}
    })
     

    app.engine.del()

    refer to template engines

    extra engines can be deleted using app.engine.del:

    • sicarii/lib/adapters will have the adapter removed
    • config.template_engine will automatically remove the engine/s
    • this action should be called for production to minimize sicarii's size
    • this action cannot be undone.
     
    /**
     *  app.engine.del(items, callback)
     *  @param {array} items // template engine items to remove
     *  @param {function} callback function(err)
     **/
     
    app.engine.del(['pug','twig', 'nunjucks', 'ejs'], function(err){
      if(err){return console.error(err)}
    })
     

    app.qs()

    app.qs will return a serialized query string from valid json object

     
    /**
     *  app.qs(items, sep, eq)
     *  @param {object} items // query string object
     *  @param {string} sep // query string separetor ~ defalts to &
     *  @param {string} eq // query string equals ~ defalts to =
     **/
     
     var data = {
       test: '%^&*$#hsdacsddf',
       test2: 2345
     }
     
     console.log(app.qs(data))
     // test=%25%5E%26*%24%23hsdacsddf&test2=2345
     

    app.path()

    app.path returns a json object containing the parsed path data

     
    /**
     *  app.path(path)
     *  @param {string} path // path string
     **/
     
     let somepath = app.path('sicarii/lib/utils.js');
     
     console.log(somepath)
     // {root: '',dir: 'sicarii/lib',base: 'utils.js',ext: '.js', name: 'utils'}
     
     console.log(somepath.base)
     // utils.js
     

    app.url()

    app.url returns a json object containing the parsed url data

     
    /**
     *  app.url(path)
     *  @param {string} path // path string
     **/
     
     let someurl = app.url('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
     
     console.log(someurl)
     
     /*
       {
         protocol: 'https:',
         slashes: true,
         auth: 'user:pass',
         host: 'sub.example.com:8080',
         port: '8080',
         hostname: 'sub.example.com',
         hash: '#hash',
         search: '?query=string',
         query: { query: 'string' },
         pathname: '/p/a/t/h',
         path: '/p/a/t/h?query=string',
         href: 'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'
       }
     
     */
     

    app.dns.get()

    • perform dns lookup
    • returns json object containing results
    /**
     *  app.dns.reverse(path, cnf, callback)
     *  @param {string} path // path string
     *  @param {object} cnf // optional nodejs dns.lookup.options
     *  @param {function} callback // function(err,res)
     **/
     
     app.dns.get('example.org', function(err, data){
       if(err){return console.log(err)}
       //{address: 'someaddress', family: 'somefamily'}
     });
     

    app.dns.getService()

    • perform dns lookupService
    • returns json object containing results
    /**
     *  app.dns.getService(path,port,callback)
     *  @param {string} path // path string
     *  @param {number} port // port
     *  @param {function} callback // function(err,res)
     **/
     
     app.dns.getService('127.0.0.1', 80, function(err, data){
       if(err){return console.log(err)}
       console.log(data)
       //{ hostname: 'localhost', service: 'http' }
     });
     

    app.dns.reverse()

    • perform dns reverse
    • returns json array containing results
    /**
     *  app.dns.reverse(path, callback)
     *  @param {string} path // path string
     *  @param {function} callback // function(err,res)
     **/
     
     app.dns.reverse('208.67.222.222',function(err, hostnames){
       if(err){return cb(err)}
       console.log(hostnames)
       // [ 'resolver1.opendns.com' ]
     })
     

    app.encode()

    • convert between data encoding

    supported conversions

    • buffer|utf8|hex|base64|Uint8Array|Uint16Array|Uint32Array|Int8Array|Int16Array|Int32Array
     
    /**
     *  app.encode(data, from, to)
     *  @param {string} data // path string
     *  @param {string} from // data current encoding
     *  @param {string} to // ~ optional data to be encoded to
     **/
     
    let str = 'test string';
     
    // basic encode to buffer
    app.encode(str, 'utf8') // utf8 string to buffer
     
    // convert between
    str = app.encode(str, 'utf8', 'base64') // from utf8 string to base64
     
    str = app.encode(str, 'base64', 'hex') // base64 string to hex
     
    str = app.encode(str, 'hex', 'Uint8Array') // hex string to Uint8Array
     
    // and so on ...
     

    Body parser

    sicarii has its own built in body parser for the following content types:

    • application/json
    • multipart/form-data
    • application/x-www-form-urlencoded

    These content types can be enabled/disabled at config.stream.content_types.

    if you are not using it, remove it from config.stream.content_types to improve both security and performance.

    The correct content type headers must be sent with the request.

    multipart/form-data and application/x-www-form-urlencoded will automatically be parsed to valid json.

    for example:

    // query
    router.get('/content', function(stream, headers, flags){
      let query = stream.query; //json object
     
    })
     
    // body
    router.post('/content', function(stream, headers, flags){
      let body = stream.body.json; //json object
      body = stream.body.buffer; //nodejs buffer
      body = stream.body.text; //string
    })

    All other content types are available as text or buffer

    Etags

    sicarii has its own built in configurable in Etag generator.

    it provides separate options for render/document to static files and can also be manually overridden or manually added on a per case basis.

    • automatic render/document Etags can be configured at config.render.etag
    • automatic static file Etags can be configured at config.static.etag
    • automatic etags will use cache settings from config.render.cache or config.static.cache if available
    • etags support either base64 or hex encoding.

    the following digests are supported:

    insecure

    • md5, md5-sha1, ripemd160, rmd160, sha1

    secure

    • sha224, sha256, sha384, sha512, sha512-224, sha512-256, whirlpool

    excessive

    • sha3-224, sha3-256, sha3-384,sha3-512, blake2b512, blake2s256, shake128,shake256

    Etags can be manually added using either an app.etag or stram.etag function like so:

     
    /**
     *  stream.etag(digest, data, encode)
     *  @param {string} digest // hash digest
     *  @param {string} data // data to be hashed
     *  @param {string} encode // base64/hex
     **/
     
    router.get('/etagdemo', function(stream, headers, flags){
     
      // manual app.etag
      stream.addHeader('Etag', app.etag('sha3-512', 'test string', 'base64'));
     
      // manual stream.etag ~ will automatically add to stream.headers
      stream.etag('sha3-512', 'test string', 'base64');
     
      stream.respond(stream.headers)
     
      stream.end('test etag')
     
    });
     

    As etags are hashed from the data being sent, they can also easily double as the Digest header:

    router.get('/etagdemo', function(stream, headers, flags){
     
     
      // manual stream ~ will automatically add to stream.headers
      stream.etag('sha3-512', 'test string', 'base64');
     
      // set Digest header using hash from Etag
      stream.addHeader('Digest', 'sha-256=' + stream.headers['Etag']);
     
     
      stream.respond(stream.headers)
     
      stream.end('test etag')
     
    });
     

    Cookie parser

    sicarii has its own built in cookie parser.

    • the cookie parser can be enabled/disabled at config.cookie_parser.enabled
    • with config.cookie_parser.auto_parse enabled, inbound cookies will automatically be parsed to json.
    • if the cookie parser is disabled, cookies can still be created/parsed through app.cookie_encode()/app.cookie_decode().

    encode cookie

    sicarii has two methods for creating serialized cookies.

    • this method has support for multiple cookies
    • this method can create a separate signed cookie for tamper detection
    • config.cookie_parser.sig.secret is used to hmac the cookie
    • config.cookie_parser.sig.suffix is the signed cookies suffix
    • a signed cookie will be will use digest/encode settings from config.crypt.hmac
    • a signed cookie will be will use digest/encode settings from config.crypt.hmac
     
    /**
     *  stream.cookie(key, val, settings)
     *  app.cookie(key, val, settings)
     *  @param {string} key // cookie name
     *  @param {string} val // cookie value
     *  @param {object} settings // cookie settings
     **/
     
    router.get('/', function(stream, headers, flags){
     
      //create cookie and add to outbouheaders ~ config.cookie_parser.enabled
      stream.cookie('name', 'value',{
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Lax',
        Secure: true,
        Priority: 'High',
        Signed: true
      })
     
     
      // manual create cookie and add to outbouheaders
      let cookie_specs = {
        Domain: 'localhost',
        Path: '/',
        Expires: Date.now(),
        MaxAge: 9999,
        HttpOnly: true,
        SameSite: 'Lax',
        Secure: true,
        Priority: 'High'
      }
      let new_cookie = app.cookie_encode('name', 'value', cookie_specs),
      // manual create cookie sig and add to outbouheaders
      signed_cookie = app.cookie_sign('name', 'value', cookie_specs);
      // only required for manual add
      stream.addHeader('Set-Cookie',  [new_cookie, signed_cookie]);
     
      // send headers & send json response
      stream.json({msg: 'cookies created'});
     
    })

    decode cookie

    sicarii has three methods for returning a deserialized cookies object

     
    /**
     *  app.cookie_decode(key, val, settings)
     *  @param {string} settings // cookie header
     **/
     
     
    router.get('/', function(stream, headers, flags){
     
      // return cookies object
      console.log(headers.cookies())
     
       // return automatically parsed cookies object ~ config.cookie_parser.auto_parse
       console.log(stream.cookies)
     
      // manual return cookies object
      console.log(app.cookie_decode(headers.get('cookie')))
     
    });
     

    Template engines

    sicarii has the ability to render, cache and compress templates engine templates. refer to stream.render for further details

    • template engines can be configured at config.template_engine
    • templates are rendered with stream.render
    • templates use settings from config.render
    • templates are compresses if compression is enabled
    • templates are cached if config.render.cache is enabled
    • all sicarii template engine adapters are asynchronous.
    • automatic error handling is provided for consistency across all engines
    • each engines individual error messages are still provided in the callback
    /**
     *  stream.render(path, obj, callback)
     *  @param {string} path // file path relative to render dir
     *  @param {object} obj // data for rendered file
     *  @param {function} callback ~ optional
     **/
     
     //send headers and rendered doc
     stream.render('index.html', {title: 'basic'})
     
     //or
     
     // send headers and rendered doc
     stream.render('index.html', {title: 'basic'}, function(err){
       if(err){
         // the stream has ended and automatic error handling has been provided.
         return console.log(err)
       }
     
       // do something...
     })

    sicarii currently supports the following engines:

    default

    • default engine, renders html files with javascript template literals included
    • the default engine is ideal for single page apps or when you do not require extra features
    • the default engine does not require any additional installation
     
    router.get('/', function(stream, headers, flags){
     
      // send default headers and render index.html
      stream.render('index.html', {title: 'basic'})
     
    });
     

    index.html

    <title>${title}</title>
     

    poorboy

    • renders html from javascript
    • write your templates in plain javascript
    • poorboy engine does not require any additional installation
    • poorboy can be extended to use html parsing modules
    • poorboy can be used to render pre-compiled templates from any other engine
    • poorboy is fast
     
    router.get('/', function(stream, headers, flags){
     
      // send default headers and render index.js
      stream.render('index.js', {
        title: 'poorboy',
        people: ['bob', 'alice']
      })
     
    });
     

    basic example

    // /render/index.js
     
    module.exports = (data) => `
    <html>
      <head>
        <title>${data.title}</title>
      </head>
      <body></body>
    </html>
    `
     

    advanced example

    // /render/index.js
     
    const includes = require('./includes'); //cached
    module.exports = (data) => `
    <html>
      <head>
        ${includes.title(data.title)}
      </head>
      <body>
       ${includes.group(data.people)}
      </body>
    </html>
    `
     
    // /render/includes.js
     
    const includes = module.exports = {
      title: (i) => '<title>'+ i +'</title>',
      li: (i) => '<li>'+ i +'</li>',
      group: (i) => {
        let ul = '<ul>';
        for (let x = 0; x < i.length; x++) {
          ul += includes.li(i[x])
        }
        ul += '</ul>';
        return ul;
      }
    }
     

    extended example

    // /render/index.js
    const cheerio = require('cheerio'); // cached
    const includes = require('./includes'); //cached
     
    module.exports = (data) => {
     
      const $ = cheerio.load(includes.body(data.title))
     
      let test = $('<ul />').attr({id: 'test'})
      $(data.people).each(function(i){
        test.append(includes.li(data.people[i]))
      })
     
      $('body').append(
        $('<h1 />').text('Hello world'),
        test
      )
     
      return $.html()
     
    }
     
    // /render/includes.js
     
    const includes = module.exports = {
      body: (i) => '<html><head><title>'+ i +'</title></head><body></body></html>',
      li: (i) => '<li>'+ i +'</li>'
    }
     

    nunjucks

    • usage of nunjucks requires nunjucks to be pre installed
    • do not set nunjucks to cache templates as this will be done by sicarii
    • config.template_engine.nunjucks.filters is a path to filters file relative to cwd
    • config.template_engine.nunjucks.globals.vars are added to all renders
    • refer to nunjucks documentation for further details
     
    router.get('/', function(stream, headers, flags){
      // send default headers and render index.njk
      stream.render('index.njk', {title: 'nunjucks'})
    });
     

    index.njk

    <title>{{title}}</title>
     

    custom filters can be added like so:

    /*
    "nunjucks": {
      "enabled": true,
      "filters": "/path/to/filters.js"
    }
    */
     
     
    // filters.js
    module.exports = {
      shorten: function(str, count) {
        return str.slice(0, count || 1);
      }
    }
     

    liquidjs

    • usage of liquidjs requires liquidjs to be pre installed
    • do not set liquidjs to cache templates as this will be done by sicarii
    • refer to liquidjs documentation for further details
     
    router.get('/', function(stream, headers, flags){
     
      // send default headers and render index.liquid
      stream.render('index.liquid', {title: 'liquidjs'})
     
    });
     

    index.liquid

    <title>{{title}}</title>
     

    squirrelly

    • usage of squirrelly requires nunjucks to be pre installed
    • do not set squirrelly to cache templates as this will be done by sicarii
    • refer to squirrelly documentation for further details
     
    router.get('/', function(stream, headers, flags){
     
      // send default headers and render index.html
      stream.render('index.html', {title: 'squirrelly'})
     
    });
     

    index.html

    <title>{{it.title}}</title>
     

    twig

    • usage of twig requires twig to be pre installed
    • refer to twig documentation for further details
     
    router.get('/', function(stream, headers, flags){
     
      // send default headers and render index.twig
      stream.render('index.twig', {title: 'twig'})
     
    });
     

    index.twig

    <title>{{title}}</title>
     

    ejs

    • usage of ejs requires ejs to be pre installed
    • do not set ejs to cache templates as this will be done by sicarii
    • refer to ejs documentation for further details
     
    router.get('/', function(stream, headers, flags){
     
     // send default headers and render index.ejs
     stream.render('index.ejs', {title: 'ejs'})
     
    });
     

    index.ejs

    <title><%= title %></title>