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 percolate: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 schedule: function(parser) { 4 // parser is a later.parse object 5 return parser.text('every 2 hours'); 6 }, 7 job: function() { 8 var numbersCrunched = CrushSomeNumbers(); 9 return numbersCrunched; 10 } 11});
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.
Configuration
Modify the object SyncedCron.options
to set configuration entries. Defaults are:
1 SyncedCron.options = { 2 //Log job run details to console 3 log: true, 4 5 //Name of collection to use for synchronisation and logging 6 collectionName: 'cronHistory', 7 8 //Default to using localTime 9 utc: false, 10 11 //TTL in seconds for history records in collection to expire 12 //NOTE: Unset to remove expiry but ensure you remove the index from 13 //mongo by hand 14 // 15 //ALSO: SyncedCron can't use the `_ensureIndex` command to modify 16 //the TTL index. The best way to modify the default value of 17 //`collectionTTL` is to remove the index by hand (in the mongo shell 18 //run `db.cronHistory.dropIndex({startedAt: 1})`) and re-run your 19 //project. SyncedCron will recreate the index with the updated TTL. 20 collectionTTL: 172800 21 }
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
Synced Cron was developed as part of the Verso project.