couch-daemon

couch-daemon

High-level sugar for CouchDBs os_daemon. With a Highland streaming interface.

Usage

couch-daemon provides high-level interface as well as low-level streams. couch-daemon is built as a pipeline of six streams:

• dbs: Create a stream of databases, filtered via black- and white lists.
• ddocs: Fetch and emit design docs.
• changes: Create a global stream of changes.
• compile: Compile functions defined in ddocs.
• [your worker stream]
• checkpoint: Store last seq in checkpoint docs.
• logger: Print log events.

The idea is to store per database daemon configuration in design documents in an object under the daemon name. The configuration cana have functions, like filters or processors (see couchmagick and massage-couch). couch-daemon looks at those configurations and evaluates each function in a sandbox. The actual daemon code is modelled as through stream. It receives configuration as well as changes of each database it is configured for. You can do anything you want inside that stream - make http calls to the outside, query the database or run long computations. When you're done you emit the original event to have couch-daemon store the checkpoint. Do not hesitate to open a ticket if something is unclear - this was written a bit in a hussle.

When using the high-level interface you do not need to handle os_daemon communication with CouchDB, commandline option parsing nor set up the pipeline yourself. Just call couch-daemon with your (optional) defaults and a stream and you're fine:

require('couch-daemon')({ include_docs }, functions(url, options) {
  // url comes from daemon configuration,
  // as well as the options

  return function(source) {
    return source
      .filter...
      .group...
      .zip...
      .whatever...
  };
});

Configuration

The daemon is set up in the os_daemons config section:

[os_daemons]
mydaemon = mydaemon

The actual configuration is done under its own config section:

[mydaemon]
; Optional username and password, used by the workers to access the database
username = mein-user
password = secure
; Whitelist databases: only the databases above are used (seperate with comma)
; whitelist = mydb,otherdb
; Blacklist: ignore the following databases (again comma seperated list)
blacklist = _users,_replicator

Daemons in the wild

• dimensionist
• TBD: couchmagick
• TBD: massage-couch

Send me a pull to add yours.

Examples

An example daemon is included. It just prints out each change in all dbs:

./examples/logger.js --name my-daemon --blacklist _users

Contributing

Write tests with tap, then test your code with npm test.

Specify CouchDB url and credentials via COUCH environment variable:

COUCH=http://user:password@localhost:5984 npm test

License

Copyright (c) 2014 Johannes J. Schmidt, null2 GmbH
Licensed under the MIT license.