nodeRunner

nodeRunner is a Node.js server app that runs scripts every second, minute, hour or overnight, each group in its own folder.

It's the first of a series of "server snacks" that will come out in early 2015.

Dave Winer

How it works

Copy noderunner.js to a folder with a single sub-folder: scripts.

In scripts, there are four sub-folders, everySecond, everyMinute, everyHour, overnight and startup. You can use the examples in the scripts folder here as examples to help you get started.

Any file with a .js extension in those folders are loaded and run when it's their time. All other files are ignored.

The files are not cached, so you can make changes while nodeRunner is running.

They share data through a structure called localStorage, which works more or less like localStorage in browsers. It doesn't have a file size limit, but it's a good idea to keep it small, because it's potentially saved every second.

It automatically creates the folders it needs when it boots up.

Examples

1. Here's a Hello World script that runs when nodeRunner starts up.

2. RiverToConsole runs every minute and checks a JSON file produced by River4, and echoes new items to the console. It's part of a real app that I use to maintain @NYT on Twitter.

3. Snapshot archives the Scripting News feed once a day in a calendar folder structure.

Special folders

1. files contains files that are accessed through three routines provided by nodeRunner: fileExists, readWholeFile and writeWholeFile. Note, you can use any of Node's fs routines to read or write to any file on the local system.

2. prefs contains files that are managed by nodeRunner. stats.json has data that the server maintains. prefs.son allows you to control when scripts run, what port the server boots up on. localStorage.json is the contents of the localStorage object.

3. scripts has several sub-folders, startup, everySecond, everyMinute, everyHour and overnight.

The HTTP server

The server provides three endpoints: version, now and status, that tell you what version is running, what the current time is on the server, and echoes the contents of the prefs and stats structs.

Why folders?

I like file sharing software like Dropbox, Box, Google Drive, OneDrive, BT Sync. I've built a few pieces of software over the years based on the idea of storing all the data in folder structures. This means that pieces of the app can easily be distributed among a variety of machines, or moved. With folders, I can manage my scripts from any of my sharing-capable computers, which includes my desktop, laptop, tablet and smartphone.

Why did you develop it?

I needed it.

How do you know it's useful?

This is an adaptation of a core feature in Frontier, a scripting and object database environment I led the development of. Now that I'm working primarily in Node, I wanted the same ability to quickly add and edit scripts that are constantly running on net-accessible systems.

JavaScript sample code

I've iterated over the code to try to make it good sample code for JavaScript projects.

I wanted to make code that could be used for people who are just getting started with Node, to help make the process easier.

There will always be more work to do here. ;-)

Updates

v0.64 11/19/15 by DW

Added support for Amazon S3. There are new built-in routines that create and read files, set metadata, list the objects in a bucket.

v0.61 1/15/15 by DW

Code reorg. There's now a lib folder, and it contains a module called utils.js. This simplifies noderunner.js, and makes it easier for nodeRunner to share code with other projects.

v0.57 12/30/14 by DW

New environment variable, noderunnerFolderPath, lets you set the folder nodeRunner runs from, i.e. where it looks for scripts, prefs, and where it stores its data. See this blog post on this release, including general philosophy of nodeRunner.

Questions, comments?

Please post a note on the Server Snacks mail list.