1 package Catalyst::Plugin::Scheduler;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
7 use DateTime::Event::Cron;
8 use DateTime::TimeZone;
12 use Storable qw/lock_store lock_retrieve/;
15 our $VERSION = '0.05';
17 __PACKAGE__->mk_classdata( '_events' => [] );
18 __PACKAGE__->mk_accessors('_event_state');
21 my ( $class, %args ) = @_;
23 unless ( $args{event} ) {
24 Catalyst::Exception->throw(
25 message => 'The schedule method requires an event parameter' );
28 my $conf = $class->config->{scheduler};
31 trigger => $args{trigger},
32 event => $args{event},
33 auto_run => ( defined $args{auto_run} ) ? $args{auto_run} : 1,
38 # replace keywords that Set::Crontab doesn't support
39 $args{at} = _prepare_cron( $args{at} );
41 # parse the cron entry into a DateTime::Set
43 eval { $set = DateTime::Event::Cron->from_cron( $args{at} ) };
45 Catalyst::Exception->throw(
46 "Scheduler: Unable to parse 'at' value "
51 $event->{at} = $args{at};
56 push @{ $class->_events }, $event;
62 $c->NEXT::dispatch(@_);
64 $c->_get_event_state();
68 # check if a minute has passed since our last check
69 # This check is not run if the user is manually triggering an event
70 if ( time - $c->_event_state->{last_check} < 60 ) {
71 return unless $c->req->params->{schedule_trigger};
73 my $last_check = $c->_event_state->{last_check};
74 $c->_event_state->{last_check} = time;
75 $c->_save_event_state();
77 my $conf = $c->config->{scheduler};
78 my $last_check_dt = DateTime->from_epoch(
80 time_zone => $conf->{time_zone}
82 my $now = DateTime->now( time_zone => $conf->{time_zone} );
85 for my $event ( @{ $c->_events } ) {
88 if ( $event->{trigger}
89 && $event->{trigger} eq $c->req->params->{schedule_trigger} )
92 # manual trigger, run it now
93 next EVENT unless $c->_event_authorized;
97 next EVENT unless $event->{set};
98 $next_run = $event->{set}->next($last_check_dt);
101 if ( $next_run <= $now ) {
103 # do some security checking for non-auto-run events
104 if ( !$event->{auto_run} ) {
105 next EVENT unless $c->_event_authorized;
108 # make sure we're the only process running this event
109 next EVENT unless $c->_mark_running($event);
111 my $event_name = $event->{trigger} || $event->{event};
112 $c->log->debug("Scheduler: Executing $event_name")
113 if $c->config->{scheduler}->{logging};
116 local $c->{error} = [];
121 # do not allow the event to modify the response
122 local $c->res->{body};
123 local $c->res->{cookies};
124 local $c->res->{headers};
125 local $c->res->{location};
126 local $c->res->{status};
128 if ( ref $event->{event} eq 'CODE' ) {
129 $event->{event}->($c);
132 $c->forward( $event->{event} );
135 my @errors = @{ $c->{error} };
136 push @errors, $@ if $@;
139 'Scheduler: Error executing ' . "$event_name: $_" )
143 $c->_mark_finished($event);
151 # initial configuration
152 $c->config->{scheduler}->{logging} ||= ( $c->debug ) ? 1 : 0;
153 $c->config->{scheduler}->{time_zone} ||= $c->_detect_timezone();
154 $c->config->{scheduler}->{state_file} ||= $c->path_to('scheduler.state');
155 $c->config->{scheduler}->{hosts_allow} ||= '127.0.0.1';
156 $c->config->{scheduler}->{yaml_file} ||= $c->path_to('scheduler.yml');
164 return ( $c->NEXT::dump_these(@_) ) unless @{ $c->_events };
166 # for debugging, we dump out a list of all events with their next
169 my $conf = $c->config->{scheduler};
170 my $now = DateTime->now( time_zone => $conf->{time_zone} );
172 my $last_check = $c->_event_state->{last_check};
173 my $last_check_dt = DateTime->from_epoch(
174 epoch => $last_check,
175 time_zone => $conf->{time_zone}
179 for my $event ( @{ $c->_events } ) {
181 for my $key ( qw/at trigger event auto_run/ ) {
182 $dump->{$key} = $event->{$key} if $event->{$key};
185 if ( $event->{set} ) {
186 my $next_run = $event->{set}->next($last_check_dt);
189 . q{ } . $next_run->hms
190 . q{ } . $next_run->time_zone_short_name;
193 push @{$event_dump}, $dump;
197 $c->NEXT::dump_these(@_),
198 [ 'Scheduled Events', $event_dump ],
202 # check and reload the YAML file with schedule data
206 # each process needs to load the YAML file independently
207 if ( $c->_event_state->{yaml_mtime}->{$$} ||= 0 ) {
208 return if ( time - $c->_event_state->{last_check} < 60 );
211 return unless -e $c->config->{scheduler}->{yaml_file};
214 my $mtime = ( stat $c->config->{scheduler}->{yaml_file} )->mtime;
215 if ( $mtime > $c->_event_state->{yaml_mtime}->{$$} ) {
216 $c->_event_state->{yaml_mtime}->{$$} = $mtime;
217 $c->_save_event_state();
219 # wipe out all current events and reload from YAML
222 my $yaml = YAML::LoadFile( $c->config->{scheduler}->{yaml_file} );
224 foreach my $event ( @{$yaml} ) {
225 $c->schedule( %{$event} );
228 $c->log->info( "Scheduler: PID $$ loaded "
230 . ' events from YAML file' )
231 if $c->config->{scheduler}->{logging};
235 $c->log->error("Error reading YAML file: $@");
239 # Detect the current time zone
240 sub _detect_timezone {
244 eval { $tz = DateTime::TimeZone->new( name => 'local' ) };
247 'Scheduler: Unable to autodetect local time zone, using UTC')
248 if $c->config->{scheduler}->{logging};
253 'Scheduler: Using autodetected time zone: ' . $tz->name )
254 if $c->config->{scheduler}->{logging};
259 # Check for authorized users on non-auto events
260 sub _event_authorized {
263 # this should never happen, but just in case...
264 return unless $c->req->address;
266 my $hosts_allow = $c->config->{scheduler}->{hosts_allow};
267 $hosts_allow = [$hosts_allow] unless ref($hosts_allow) eq 'ARRAY';
268 my $allowed = Set::Scalar->new( @{$hosts_allow} );
269 return $allowed->contains( $c->req->address );
272 # get the state from the state file
273 sub _get_event_state {
276 if ( -e $c->config->{scheduler}->{state_file} ) {
278 lock_retrieve $c->config->{scheduler}->{state_file} );
282 # initialize the state file
284 { last_check => time,
288 $c->_save_event_state();
292 # Check the state file to ensure we are the only process running an event
294 my ( $c, $event ) = @_;
296 $c->_get_event_state();
298 return if $c->_event_state->{ $event->{event} };
300 # this is a 2-step process to prevent race conditions
301 # 1. write the state file with our PID
302 $c->_event_state->{ $event->{event} } = $$;
303 $c->_save_event_state();
305 # 2. re-read the state file and make sure it's got the same PID
306 $c->_get_event_state();
307 if ( $c->_event_state->{ $event->{event} } == $$ ) {
314 # Mark an event as finished
316 my ( $c, $event ) = @_;
318 $c->_event_state->{ $event->{event} } = 0;
319 $c->_save_event_state();
322 # update the state file on disk
323 sub _save_event_state {
326 lock_store $c->_event_state, $c->config->{scheduler}->{state_file};
329 # Set::Crontab does not support day names, or '@' shortcuts
333 return $cron unless $cron =~ /\w/;
359 'yearly' => '0 0 1 1 *',
360 'annually' => '0 0 1 1 *',
361 'monthly' => '0 0 1 * *',
362 'weekly' => '0 0 * * 0',
363 'daily' => '0 0 * * *',
364 'midnight' => '0 0 * * *',
365 'hourly' => '0 * * * *',
368 if ( $cron =~ /^\@/ ) {
370 return $replace_at{ $cron };
373 for my $name ( keys %replace ) {
374 my $value = $replace{$name};
375 $cron =~ s/$name/$value/i;
376 last unless $cron =~ /\w/;
388 Catalyst::Plugin::Scheduler - Schedule events to run in a cron-like fashion
392 use Catalyst qw/Scheduler/;
394 # run remove_sessions in the Cron controller every hour
395 __PACKAGE__->schedule(
397 event => '/cron/remove_sessions'
400 # Run a subroutine at 4:05am every Sunday
401 __PACKAGE__->schedule(
406 # A long-running scheduled event that must be triggered
407 # manually by an authorized user
408 __PACKAGE__->schedule(
409 trigger => 'rebuild_search_index',
410 event => '/cron/rebuild_search_index',
412 $ wget -q http://www.myapp.com/?schedule_trigger=rebuild_search_index
416 This plugin allows you to schedule events to run at recurring intervals.
417 Events will run during the first request which meets or exceeds the specified
418 time. Depending on the level of traffic to the application, events may or may
419 not run at exactly the correct time, but it should be enough to satisfy many
420 basic scheduling needs.
424 Configuration is optional and is specified in MyApp->config->{scheduler}.
428 Set to 1 to enable logging of events as they are executed. This option is
429 enabled by default when running under -Debug mode. Errors are always logged
430 regardless of the value of this option.
434 The time zone of your system. This will be autodetected where possible, or
435 will default to UTC (GMT). You can override the detection by providing a
436 valid L<DateTime> time zone string, such as 'America/New_York'.
440 The current state of every event is stored in a file. By default this is
441 $APP_HOME/scheduler.state. This file is created on the first request if it
442 does not already exist.
446 The location of the optional YAML event configuration file. By default this
447 is $APP_HOME/scheduler.yml.
451 This option specifies IP addresses for trusted users. This option defaults
452 to 127.0.0.1. Multiple addresses can be specified by using an array
453 reference. This option is used for both events where auto_run is set to 0
454 and for manually-triggered events.
456 __PACKAGE__->config->{scheduler}->{hosts_allow} = '192.168.1.1';
457 __PACKAGE__->config->{scheduler}->{hosts_allow} = [
464 =head2 AUTOMATED EVENTS
466 Events are scheduled by calling the class method C<schedule>.
470 event => '/cron/remove_sessions',
473 package MyApp::Controller::Cron;
475 sub remove_sessions : Private {
476 my ( $self, $c ) = @_;
478 $c->delete_expired_sessions;
483 The time to run an event is specified using L<crontab(5)>-style syntax.
485 5 0 * * * # 5 minutes after midnight, every day
486 15 14 1 * * # run at 2:15pm on the first of every month
487 0 22 * * 1-5 # run at 10 pm on weekdays
488 5 4 * * sun # run at 4:05am every Sunday
497 month 0-12 (or names, see below)
498 day of week 0-7 (0 or 7 is Sun, or use names)
500 Instead of the first five fields, one of seven special strings may appear:
504 @yearly Run once a year, "0 0 1 1 *".
505 @annually (same as @yearly)
506 @monthly Run once a month, "0 0 1 * *".
507 @weekly Run once a week, "0 0 * * 0".
508 @daily Run once a day, "0 0 * * *".
509 @midnight (same as @daily)
510 @hourly Run once an hour, "0 * * * *".
514 The event to run at the specified time can be either a Catalyst private
515 action path or a coderef. Both types of event methods will receive the $c
516 object from the current request, but you must not rely on any request-specific
517 information present in $c as it will be from a random user request at or near
518 the event's specified run time.
520 Important: Methods used for events should be marked C<Private> so that
521 they can not be executed via the browser.
525 The auto_run parameter specifies when the event is allowed to be executed.
526 By default this option is set to 1, so the event will be executed during the
527 first request that matches the specified time in C<at>.
529 If set to 0, the event will only run when a request is made by a user from
530 an authorized address. The purpose of this option is to allow long-running
531 tasks to execute only for certain users.
535 event => '/cron/rebuild_search_index',
539 package MyApp::Controller::Cron;
541 sub rebuild_search_index : Private {
542 my ( $self, $c ) = @_;
544 # rebuild the search index, this may take a long time
547 Now, the search index will only be rebuilt when a request is made from a user
548 whose IP address matches the list in the C<hosts_allow> config option. To
549 run this event, you probably want to ping the app from a cron job.
551 0 0 * * * wget -q http://www.myapp.com/
555 To create an event that does not run on a set schedule and must be manually
556 triggered, you can specify the C<trigger> option instead of C<at>.
558 __PACKAGE__->schedule(
559 trigger => 'send_email',
560 event => '/events/send_email',
563 The event may then be triggered by a standard web request from an authorized
564 user. The trigger to run is specified by using a special GET parameter,
565 'schedule_trigger'; the path requested does not matter.
567 http://www.myapp.com/?schedule_trigger=send_email
569 By default, manual events may only be triggered by requests made from
570 localhost (127.0.0.1). To allow other addresses to run events, use the
571 configuration option L</hosts_allow>.
573 =head1 SCHEDULING USING A YAML FILE
575 As an alternative to using the schedule() method, you may define scheduled
576 events in an external YAML file. By default, the plugin looks for the
577 existence of a file called C<schedule.yml> in your application's home
578 directory. You can change the filename using the configuration option
581 Modifications to this file will be re-read once per minute during the normal
582 event checking process.
584 Here's an example YAML configuration file with 4 events. Each event is
585 denoted with a '-' character, followed by the same parameters used by the
586 C<schedule> method. Note that coderef events are not supported by the YAML
591 event: /cron/delete_sessions
592 - event: /cron/send_email
598 event: /cron/rebuild_search_index
602 All events are run inside of an eval container. This protects the user from
603 receiving any error messages or page crashes if an event fails to run
604 properly. All event errors are logged, even if logging is disabled.
606 =head1 PLUGIN SUPPORT
608 Other plugins may register scheduled events if they need to perform periodic
609 maintenance. Plugin authors, B<be sure to inform your users> if you do this!
610 Events should be registered from a plugin's C<setup> method.
616 if ( $c->can('schedule') ) {
626 The time at which an event will run is determined completely by the requests
627 made to the application. Apps with heavy traffic may have events run at very
628 close to the correct time, whereas apps with low levels of traffic may see
629 events running much later than scheduled. If this is a problem, you can use
630 a real cron entry that simply hits your application at the desired time.
632 0 * * * * wget -q http://www.myapp.com/
634 Events which consume a lot of time will slow the request processing for the
635 user who triggers the event. For these types of events, you should use
636 auto_run => 0 or manual event triggering.
640 The plugin only checks once per minute if any events need to be run, so the
641 overhead on each request is minimal. On my test server, the difference
642 between running with Scheduler and without was only around 0.02% (0.004
645 Of course, when a scheduled event runs, performance will depend on what's
646 being run in the event.
652 Schedule is a class method for adding scheduled events. See the
653 L<"/SCHEDULING"> section for more information.
655 =head1 INTERNAL METHODS
657 The following methods are extended by this plugin.
663 The main scheduling logic takes place during the dispatch phase.
667 On the Catalyst debug screen, all scheduled events are displayed along with
668 the next time they will be executed.
680 Andy Grundman, <andy@hybridized.org>
684 This program is free software, you can redistribute it and/or modify it
685 under the same terms as Perl itself.