@lucidsoftware/nodegun

Nodegun

Nailgun for Node.js

Purpose

Nodegun improve start up overhead for Node.js programs.

// helloworld.js
console.log('Hello world');

$ time node helloworld.js
Hello world
real    0m0.102s

$ time ng helloworld.js
Hello world
real    0m0.004s

Architecture

Nodegun is inspired by Nailgun, a system for reducing startup overhead of Java programs. Users invoke a small executable (written in C), which connects to a long-running JVM server where the work is actually performed.

Nodegun is a Node.js server implementation of the Nailgun protocol. Users connect with the same native client, which submits work to the server.

Nodegun can run either as a single process, as master-worker for parallelized workloads:

Getting started

1. Install the nailgun client, either from source or from your package manager. E.g. for Ubuntu,

$ apt-get install nailgun

1. Install and run nodegun.

$ npm install -g nodegun
$ nodegun

1. Create a Node.JS program to run (aka a "nail").

// example_nail.js
console.log(process.argv.slice(2).join('-'));

1. Run the client

$ ng example_nail The Fast and the Furious
$ # (or ng-nailgun ...)
The-Fast-and-the-Furious

Nails

Requirements

Most Node.JS programs should work as nails without modification. Nodegun adjusts the runtime environment, including

• process.argv
• process.env
• process.exit
• process.stdin, process.stdout, process.stderr

The most significant requirement: Nails must clean up after themselves. They must not corrupt state, create memory leaks, etc.

The root nail module and re-run each time. Modules required by the nail module are run only once. In both cases, code is cached via the standard require mechanism. The server must be restarted if nails are updated on disk.

Resolution

Nodegun resolves the requested nail

1. As node would do, i.e. relative to the current directory.
2. As require would do from nodegun process.

Concurrency

Each worker process (or the main process, if there are no workers) runs only one nail at a time.

Examples

Nodegun comes with a few built-in nails, including

• ng ./examples/hello - Print Hello World
• ng ./examples/info - Print arguments and working direcotry
• ng ./examples/echo - Copy stdin to stdout

What is this good for?

We use Nodegun in our build system. A fast CLI to Node.js amenable to in concurrent, polyglot build systems.

In this way, it is similar to Nailgun, which is used in build tools like Buck and Pants.

Server options

usage: main.js [-h] [-v] [--tcp [TCP] | --local [LOCAL]]
               [--status-tcp TCP | --status-local LOCAL] [--workers [WORKERS]]
               

Node.js server that supports the Nailgun protocol.

Optional arguments:
  -h, --help            Show this help message and exit.
  -v, --version         Show program's version number and exit.
  --workers [WORKERS]   If present, number of worker processes to start. A 
                        flag with no argument starts one per CPU.

Transport:
  Transport and address. TCP is used by default.

  --tcp [TCP]           TCP address to listen to, given as ip, port, or 
                        ip:port. IP defaults to 0.0.0.0, and port defaults to 
                        2113.
  --local [LOCAL]       Local address to listen to. Defaults to /tmp/nodegun.
                        sock.

Status:
  Optionally expose internal status information via HTTP server.

  --status-tcp TCP      TCP address to listen to for status, given as ip, 
                        port, or ip:port. IP defaults to 0.0.0.0.
  --status-local LOCAL  Local address to listen to for status.