Awesome

Node http server with https and proxy support

Simple to use stand alone node HTTP and HTTPS Server you can spin up in seconds.

• TLDR; Quick start examples
• Server Class
• Config Class
• Basic use with cluster example

Support for building proxy servers has been added. Documentation coming in next release. For now see the node-http-server proxy examples.

npm i node-http-server

npm info : See npm trends and stats for node-http-server

GitHub info :

Package Quality :

See the code documentation on riaevangelist.github.io

cli use if you just want to test

Now you can also use the node-http-server cli if you just want to spin up a basic file server to test something out quickly or share on the local network.

$ sudo npm i -g node-http-server

//start a node-http-server from the current directory on the default port 8080
$ node-http-server

You can modify any of the config keys by passing their key value pairs as args.

//start a verbose node-http-server from the current directory on port 1942
$ node-http-server port=1942 verbose=true

quick npm script tests and examples

#node ./example/basic/basicApp.js
npm run basic

#node ./example/basic/https-ONLY-basicApp.js
npm run https

#node ./example/basic/https-basicApp.js
npm run both

#node ./example/advanced/basicTemplate.js
npm run template

#node ./example/basic/cluster-basicApp.js
npm run cluster

writing a node http or https server

The below table shows all of the methods available on the server when you require this module.

    const server=require('node-http-server');

    server.deploy();

If you want to create a custom Server or extend the Server Class you can require just the server class.

    const Server=require('node-http-server').Server;

    class MyCustomServer extends Server{
      constructor(){
        super();
      }
    }

    const server=new MyCustomServer;
    server.deploy();

Server Class

request uri, query, and, body

For handling api requests, posts, puts patches etc with body data, we are now making that available on the request as both a String and Buffer incase you need images or videos uploaded.

Server Methods

deploy

server.deploy starts the server.

server.deploy(userConfig,readyCallback)

const server=require('node-http-server');

server.deploy(
    {
        port:8000,
        root:'~/myApp/'
    },
    serverReady
);

server.deploy(
    {
        port:8888,
        root:'~/myOtherApp/'
    },
    serverReady
);

function serverReady(server){
   console.log( `Server on port ${server.config.port} is now up`);
}

onRawRequest

server.onRawRequest

server.onRawRequest(request,response,serve)

const server=require('node-http-server');
const config=new server.Config;

config.port=8000;

server.onRawRequest=gotRequest;

server.deploy(config);


function gotRequest(request,response,serve){
    console.log(request.uri,request.headers);

    serve(
        request,
        response,
        JSON.stringify(
            {
                uri:request.uri,
                headers:request.headers
            }
        )
    );

    return true;
}

onRequest

server.onRequest

server.onRequest(request,response,serve)

const server=require('node-http-server');
const config=new server.Config;

config.port=8099;
config.verbose=true;

server.onRequest=gotRequest;

server.deploy(config);


function gotRequest(request,response,serve){
    //at this point the request is decorated with helper members lets take a look at the query params if there are any.
    console.log(request.query,request.uri,request.headers);

    //lets only let the requests with a query param of hello go through
    if(request.query.hello){
       // remember returning false means do not inturrupt the response lifecycle
       // and that you will not be manually serving
       return false;
    }

    serve(
        request,
        response,
        JSON.stringify(
            {
                success:false,
                message:'you must have a query param of hello to access the server i.e. /index.html?hello'
                uri:request.uri,
                query:request.query
            }
        )
    );

    //now we let the server know we want it to kill the normal request lifecycle
    //because we just completed it by serving above. we could also handle it async style
    //and request a meme or something from the web and put that on the page (or something...)
    return true;
}

beforeServe

server.beforeServe

server.beforeServe(request,response,body,encoding,serve)

type RefString

const server=require('node-http-server');

server.beforeServe=beforeServe;

function beforeServe(request,response,body,encoding){
    //only parsing html files for this example
    if(response.getHeader('Content-Type')!=server.config.contentType.html){
        //return void||false to allow response lifecycle to continue as normal
        return;
    }

    const someVariable='this is some variable value';

    body.value=body.value.replace('{{someVariable}}',someVariable);

    //return void||false to allow response lifecycle to continue as normal
    //with modified body content
    return;
}

server.deploy(
    {
        port:8000,
        root:`${__dirname}/appRoot/`
    }
);

afterServe

server.afterServe

server.afterServe(request)

const server=require('node-http-server');

server.afterServe=afterServe;

function afterServe(request){
    console.log(`just served ${request.uri}`);
}

server.deploy(
    {
        port:8075,
        root:`${__dirname}/appRoot/`
    }
);

Examples

To see the node http server in action run npm start from the root of this repo and then visit localhost:8000.

To start only an https example server npm run https from the root of this repo and then visit localhost:4433.

To spin up both an http and an https server npm run both from the root of this repo and then visit localhost:4433 or localhost:8000.

Detailed examples can be found in the example folder or under the example folder on the node-http-server example docs The basic example directory is static http and https file servers and the advanced directory has dynamic server side rendering http and https examples including a benchmark example. The proxy examples show manual serving and response modification examples.

Basic http server example

    const server=require('node-http-server');

    server.deploy(
        {
            port:8000,
            root:'~/myApp/'
        }
    );

Basic https only server example

    const server=require('node-http-server');

    server.deploy(
        {
            port:8000,
            root:'~/myApp/',
            https:{
                privateKey:`/path/to/your/certs/private/server.key`,
                certificate:`/path/to/your/certs/server.pub`,
                port:4433,
                only:true
            }
        }
    );

Basic server running both http and https

    const server=require('node-http-server');

    server.deploy(
        {
            port:8000,
            root:'~/myApp/',
            https:{
                privateKey:`/path/to/your/certs/private/server.key`,
                certificate:`/path/to/your/certs/server.pub`,
                port:4433
            }
        }
    );

Basic cluster server

//import the `node-http-server` module
//` const server=require(‘node-http-server’); `
const server=require('../../server/Server.js');

//import cluster
const cluster = require('cluster');
const numCPUs = require('os').cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Fork node-http-server cluster workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on(
    'exit',
    (worker, code, signal) => {
      console.log(`worker ${worker.process.pid} died`);
    }
  );
} else {
  server.afterServe=(request)=>{
    console.log(`${process.pid} served ${request.uri.path}`);
  }

  //start server in clustered children
  server.deploy(
      {
          verbose: false,
          port: 8000,
          root:__dirname+'/appRoot/'
      }
  );

  console.log(`Worker ${process.pid} started listening on ${server.config.port}`);
}

Template filling

    const server=require('node-http-server');

    server.beforeServe=beforeServe;

    function beforeServe(request,response,body,encoding){
        //only parsing html files for this example
        if(response.getHeader('Content-Type')!=server.config.contentType.html){
            return;
        }

        const someVariable='this is some variable value';

        body.value=body.value.replace('{{someVariable}}',someVariable);
    }

    server.deploy(
        {
            port:8000,
            root:`${__dirname}/appRoot/`
        }
    );

Custom configuration

for http :

    const server=require('node-http-server');

    const config=new server.Config;
    config.errors['404']    = 'These are not the files you are looking for...';
    config.contentType.mp4  = 'video/mp4';
    config.port             = 8005;
    config.verbose          = true;
    config.root             = '~/myApp/'

    server.deploy(config);

for https :

    const server=require('node-http-server');

    const config=new server.Config;
    config.errors['404']    = 'These are not the files you are looking for...';
    config.contentType.mp4  = 'video/mp4';
    config.port             = 8005;
    config.verbose          = true;
    config.root             = '~/myApp/'
    config.https.privateKey = `/path/to/your/certs/private/server.key`;
    config.https.certificate= `/path/to/your/certs/server.pub`;
    config.https.port       = 4433;
    config.https.only       = true;

    server.deploy(config);

Multiple domains or subdomains

    const server=require('node-http-server');

    const config={
        port:8010,
        root:__dirname + '/www/myApp/',
        domain:'myapp.com',
        domains:{
            'a.myapp.com':__dirname+'/www/a-myApp/',
            'yourapp.com':__dirname+'/someFolder/yourApp/'
        }
    }

    server.deploy(config);    

Config Class

Default node HTTP server configuration

All of these can be modified and passed into new server.Server(myConfigs) or server.deploy(myConfigs)

const myConfig=new server.Config;
myConfig.verbose=true;
myConfig.port=9922;

const myServer=new server.Server(config);
myServer.deploy();

//or more basically
server.deploy({port:9922,verbose:true});

defaults description

    {
        verbose     : (args.verbose=='true')||false,
        port        : args.port||defaults.port,
        root        : args.root||defaults.root,
        domain      : args.domain||defaults.domain,
        https       :{
            ca:'',
            privateKey:'',
            certificate:'',
            port:443,
            only:false
        },
        log         : false,
        logFunction : serverLogging,
        domains   : {
            /*******************\
             * domain  : /that/domains/root/dir
             *
             * for sub domains, specify the whole host i.e. "my.sub.domain"
             * you may need to edit your hosts file, cnames or iptable
             * domain or my.domain etc. goes to 127.0.0.1 for local development
             * *****************/
        },
        server      : {
            index   : args.index||defaults.index,
            noCache : args.noCache=='false' ? false : true,
            timeout : 30000 //30 second timeout
        },
        contentType : {
            html    : 'text/html',
            css     : 'text/css',
            js      : 'text/javascript',
            json    : 'application/json',
            xml     : 'text/xml',
            txt     : 'text/plain',
            jpeg    : 'image/jpeg',
            jpg     : 'image/jpeg',
            png     : 'image/png',
            gif     : 'image/gif',
            ico     : 'image/x-icon',
            svg     : 'image/svg+xml',
            appcache: 'text/cache-manifest',
            eot     : 'application/vnd.ms-fontobject',
            otf     : 'font/otf',
            ttf     : 'font/ttf',
            woff    : 'font/woff',
            woff2   : 'font/woff2'
        },
        restrictedType: {

        },
        errors:{
            headers : {
                'Content-Type' : 'text/plain'
            },
            404: '404 MIA',
            415: '415 File type not supported',
            403: '403 Access Denied',
            500: '500 {{err}}'
        }
    };

Local and Production domains

node yourServer.js local

const server=require('node-http-server');

server.deploy(
  {
    domain:(process.argv[2]=='local')?'0.0.0.0' : 'my.awesome.domain'
  }
);

const server=require('node-http-server');
const config=new server.Config;

config.domain = (process.argv[2]=='local')?'0.0.0.0' : 'my.awesome.domain';

server.deploy(config);

config.domains.*

Use this object for sub domains, or hosting multiple domains on the same port. Specify the whole host i.e. "my.sub.domain.com" or "amazing-domain.com".

You may need to edit your hosts file, cnames, iptable to get this to work on your server or development environment.

You can add the below example to your hosts file to run some of the examples from the /example/basic directory which use multiple domains on occasion.

#node-http-server examples
127.0.0.1 myapp
127.0.0.1 a.myapp
127.0.0.1 yourapp.com

   const server=require('node-http-server');

   const config={
       port:8000,
       root:__dirna\me+'/appRoot/',
       domain:'myapp',
       domains:{
            //subdomain
            'a.myapp':`${__dirname}/appSubDomainRoot/`,
            //totally different domain, but also on port 8000
            'yourapp.com':`${__dirname}/appOtherDomainRoot/`
       }
   }

   server.deploy(config);

Extending the Server

If you wish to make a reusable Server Class of your own to share or for some internal use you can always extend the server class and make your own module too.

    const os=require('os');
    const Server=require('node-http-server').Server;

    class MyAwesomeServer extends Server(){
        constructor(){
            super();
        }

        IP(){
            const networkInterfaces = os.networkInterfaces();
            const serverIPs={};
            const interfaceKeys=Object.keys(networkInterfaces);
            for(let i in interfaceKeys){
                serverIPs[
                    interfaceKeys[i]
                ]={};

                const interface=networkInterfaces[
                    interfaceKeys[i]
                ];

                for(let j in interface){
                    serverIPs[
                        interfaceKeys[i]
                    ][
                        interface[j].family
                    ]=interface[j].address;
                }
            }

            return serverIPs;
        }
    }

    module.exports=MyAwesomeServer;

    const AwesomeServer=require('MyAwesomeServer');

    const server=new AwesomeServer;

    server.deploy(
        {
            port:8000,
            root:'~/myAwesomeApp'
        }
    );

    console.log(server.IP);