juttle-service

juttle-service

juttle-service is an API-based execution engine for juttle programs.

It exposes an API for executing and managing a set of running juttle jobs. Each job executes in a separate node.js subprocess and either returns the results immediately or creates a websocket over which results are streamed using the JSDP protocol.

Getting Started

Installation

Make sure you have node (with npm) installed.

Use npm to install juttle and juttle-service:

$ npm install juttle
$ npm install juttle-service

We've tested with nodejs 4.2.3 and npm 2.14.17. Other combinations of nodejs and npm likely work, but we haven't tested all combinations.

Options and Configuration

Here are the full command line options supported by the daemon:

juttle-service

usage: [--port <port>] [--root <path>]
       [--config <juttle-config-path>] [--daemonize]
       [--output <logfile>] [--log-config <log4js-config-path>]
       [--log-level <level] [--help]
       -p, --port <port>:                     Run juttle-service on the specified port
       -r, --root <path>:                     Use <path> as the root directory for juttle programs
       -c, --config <juttle-config-path>:     Read juttle config from <juttle-config-path>
       -d, --daemonize:                       Daemonize juttle-service and log to configured log file
       -o, --output <logfile>:                Log to specififed file when daemonized
       -L, --log-config <log4js-config-path>: Configure logging from <log4js-config-path>. Overrides any value of -o
       -l, --log-level <level>:               Use a default log level of <level>. Overridden by any log level specified in -L
       -h, --help:                            Print this help and exit

juttle-service uses log4js for logging and by default logs to log/juttle-service.log.

Juttle config file

The Juttle compiler and runtime within juttle-service are also configured via the juttle configuration file, typically at $(HOME)/.juttle/config.json. For more information on the juttle configuration file, see the juttle configuration documentation.

The Juttle Service configuration options (default values shown):

// config.json
{
    "juttle-service": {
        // Whether HTTP responses should be compressed when
        // the client supports it.
        "compress_response": true,

        // Time (in ms) a finished job should wait for the first websocket
        // to connect before disposing of the results.       
        "delayed_job_cleanup": 10000,

        // The number messages job should buffer for sending to
        // websockets that join after the job has started.
        "max_saved_messages": 1024
    },
    "adapters": { ... }
}

Module resolution

When juttle-service resolves module references in juttle programs while creating program bundles, it searches the following locations:

• The configured root directory.
• The same location as the current juttle program. For example, if a program is at /home/user/program.juttle and refers to a module module.juttle, juttle-service looks in /home/user for module.juttle.
• Any locations in the environment variable JUTTLE_MODULE_PATH (colon-separated list of directories).

Testing

To run unit tests:

npm test

Both are run automatically by Travis.

Changelog

0.2.0

Released 2016-02-10

Major Changes

NOTICE: This release includes breaking changes to the configuration file and wire format.

• Refactored the service module to be more easily embeddable as part of another express project. [#13, #28, #32]
• Removed the watch, push, and browser commands from the client since they will be implemented in juttle-engine. [#30, #22]
• Removed references to "juttled" in code and the configuration file, replacing with "juttle-service". [#15]
• Changed the output format when running jobs with wait=true to be less verbose. [#14]

Minor Changes

• Added CORS headers. [#29]
• Exposed the getLogger function from log4js to enable an embedding application to share the same instance. [#34]
• Added support for setting debug logging targets using the DEBUG environment variable [#23]
• Refactored the client script to be more modular and extendable as part of another project. [#22]
• Added compression middleware to improve the wire efficiency. [#12]

Bug Fixes

• Improved error handling to send more useful information to the client. [#20]
• Fixed a bug in the directory listing that would fail if a dangling symlink was present. [#24]