drcontacts:timezoned-synced-cron

A fork of percolate:synced-cron and trever:synced-cron. Timezone implementation that successfully defaults to UTC and is backwards compatible to percolate:synced-cron. A simple cron system for Meteor. It supports syncronizing jobs between multiple processes. In other words, if you add a job that runs every hour and your deployment consists of multiple app servers, only one of the app servers will execute the job each time (whichever tries first).

Installation

$ meteor add drcontacts:timezoned-synced-cron

API

Basics

To write a cron job, give it a unique name, a schedule an a function to run like below. SyncedCron uses the fantastic later.js library behind the scenes. A Later.js parse object is passed into the schedule call that gives you a huge amount of flexibility for scheduling your jobs, see the documentation.

1SyncedCron.add({
2  name: 'Crunch some important numbers for the marketing department',
3  timezone: 'Australia/Sydney',
4  // Optionally set a positive offset if you wish to 'snooze' a schedule
5  offset: 30 * 60 * 100,
6  context: {
7    userID: 'xyz'
8  },
9  schedule: function(parser) {
10    this.magic = true // Context is accesible here as this context.
11    // parser is a later.parse object
12    return parser.text('every 2 hours');
13  },
14  job: function() {
15    console.log(this.userID) // Context Object becomes this argument
16    console.log(this.magic) /
17    var numbersCrunched = CrushSomeNumbers();
18    return numbersCrunched;
19  }
20});

To start processing your jobs, somewhere in your project add:

1SyncedCron.start();

Advanced

SyncedCron uses a collection called cronHistory to syncronize between processes. This also serves as a useful log of when jobs ran along with their output or error. A sample item looks like:

1{ _id: 'wdYLPBZp5zzbwdfYj',
2  intendedAt: Sun Apr 13 2014 17:34:00 GMT-0700 (MST),
3  finishedAt: Sun Apr 13 2014 17:34:01 GMT-0700 (MST),
4  name: 'Crunch some important numbers for the marketing department',
5  startedAt: Sun Apr 13 2014 17:34:00 GMT-0700 (MST),
6  result: '1982 numbers crunched'
7}

Call SyncedCron.nextScheduledAtDate(jobName) to find the date that the job referenced by jobName will run next.

Call SyncedCron.remove(jobName) to remove and stop running the job referenced by jobName.

Call SyncedCron.stop() to remove and stop all jobs.

Call SyncedCron.pause() to stop all jobs without removing them. The existing jobs can be rescheduled (i.e. restarted) with SyncedCron.start().

Capturing user timezones

Use em0ney:jstz to capture your user's timezone string. Save this to their user profile and even allow them to edit it using joshowens:timezone-picker. Good blog post by Josh Owens on timezones in meteor.

1SyncedCron.add({
2  name: 'User Defined Job',
3  timezone: 'Australia/Sydney',
4  ...

Then use this timezone configuration in your jobs, wherever their schedules are set by a user.

Configuration

You can configure SyncedCron with the config method. Defaults are:

1  SyncedCron.config({
2    // Log job run details to console
3    log: true,
4
5    // Use a custom logger function (defaults to Meteor's logging package)
6    logger: null
7
8    // Name of collection to use for synchronisation and logging
9    collectionName: 'cronHistory',
10
11    // Default to localTime
12    // Options: 'utc', 'localtime', or specific timezones 'America/New_York'
13    // Will be applied to jobs with no timezone defined
14    timezone: 'utc',
15
16    /*
17      TTL in seconds for history records in collection to expire
18      NOTE: Unset to remove expiry but ensure you remove the index from
19      mongo by hand
20
21      ALSO: SyncedCron can't use the `_ensureIndex` command to modify
22      the TTL index. The best way to modify the default value of
23      `collectionTTL` is to remove the index by hand (in the mongo shell
24      run `db.cronHistory.dropIndex({startedAt: 1})`) and re-run your
25      project. SyncedCron will recreate the index with the updated TTL.
26    */
27    collectionTTL: 172800
28  });

Logging

SyncedCron uses Meteor's logging package by default. If you want to use your own logger (for sending to other consumers or similar) you can do so by configuring the logger option.

SyncedCron expects a function as logger, and will pass arguments to it for you to take action on.

1var MyLogger = function(opts) {
2  console.log('Level', opts.level);
3  console.log('Message', opts.message);
4  console.log('Tag', opts.tag);
5}
6
7SyncedCron.config({
8  logger: MyLogger
9});
10
11SyncedCron.add({ name: 'Test Job', ... });
12SyncedCron.start();

The opts object passed to MyLogger above includes level, message, and tag.

level will be one of info, warn, error, debug.
message is something like Scheduled "Test Job" next run @Fri Mar 13 2015 10:15:00 GMT+0100 (CET).
tag will always be "SyncedCron" (handy for filtering).

Caveats

Beware, SyncedCron probably won't work as expected on certain shared hosting providers that shutdown app instances when they aren't receiving requests (like Heroku's free dyno tier or Meteor free galaxy).

Contributing

Write some code. Write some tests. To run the tests, do:

$ meteor test-packages ./

License

MIT. (c) Percolate Studio, maintained by Zoltan Olah (@zol).

Synced Cron was developed as part of the Verso project.