File Coverage

blib/lib/Mojolicious/Plugin/Cron.pm

Criterion	Covered	Total	%
statement	64	64	100.0
branch	16	20	80.0
condition	14	19	73.6
subroutine	12	12	100.0
pod	1	1	100.0
total	107	116	92.2

package Mojolicious::Plugin::Cron;
use Mojo::Base 'Mojolicious::Plugin';
use File::Spec;
use Fcntl ':flock';
use Mojo::File 'path';
use Mojo::IOLoop;
use Algorithm::Cron;

use Carp 'croak';

our $VERSION = "0.035";
use constant CRON_DIR => 'mojo_cron_';
my $crondir;

sub register {
  my ($self, $app, $cronhashes) = @_;
  croak "No schedules found" unless ref $cronhashes eq 'HASH';

# for *nix systems, getpwuid takes precedence
# for win systems or wherever getpwuid is not implemented,
# eval returns undef so getlogin takes precedence
  $crondir
    = path($app->config->{cron}{dir} // File::Spec->tmpdir)
    ->child(CRON_DIR . (eval { scalar getpwuid($<) } || getlogin || 'nobody'),
    $app->mode);
  Mojo::IOLoop->next_tick(sub {
    if (ref((values %$cronhashes)[0]) eq 'CODE') {

      # special case, plugin => 'mm hh dd ...' => sub {}
      $self->_cron($app->moniker,
        {crontab => (keys %$cronhashes)[0], code => (values %$cronhashes)[0]},
        $app);
    }
    else {
      $self->_cron($_, $cronhashes->{$_}, $app) for keys %$cronhashes;
    }
  });
}

sub _cron {
  my ($self, $sckey, $cronhash, $app) = @_;
  my $code     = delete $cronhash->{code};
  my $all_proc = delete $cronhash->{all_proc} // '';
  my $test_key
    = delete $cronhash->{__test_key};    # __test_key is for test case only
  $sckey = $test_key // $sckey;

  $cronhash->{base} //= 'local';

  ref $cronhash->{crontab} eq ''
    or croak "crontab parameter for schedule $sckey not a string";
  ref $code eq 'CODE' or croak "code parameter for schedule $sckey is not CODE";

  my $cron = Algorithm::Cron->new(%$cronhash);
  my $time = time;

  # $all_proc, $code, $cron, $sckey and $time will be part of the $task clojure
  my $task;
  $task = sub {
    $time = $cron->next_time($time);
    if (!$all_proc) {
    }
    Mojo::IOLoop->timer(
      ($time - time) => sub {
        my $fire;
        if ($all_proc) {
          $fire = 1;
        }
        else {
          my $dat = $crondir->child("$sckey.time");
          my $sem = $crondir->child("$sckey.time.lock");
          $crondir->make_path;    # ensure path exists
          my $handle_sem = $sem->open('>')
            or croak "Cannot open semaphore file $!";
          flock($handle_sem, LOCK_EX);
          my $rtime = $1
            if (-e $dat && $dat->slurp // '') =~ /(\d+)/;   # do some untainting
          $rtime //= '0';
          if ($rtime != $time) {
            $dat->spew($time);
            $fire = 1;
          }
          undef $dat;
          undef $sem;                                       # unlock
        }
        $code->($time, $app) if $fire;
        $task->();
      }
    );
  };
  $task->();
}

1;

=encoding utf8

=head1 NAME

Mojolicious::Plugin::Cron - a Cron-like helper for Mojolicious and Mojolicious::Lite projects

=head1 SYNOPSIS

  # Execute some job every 5 minutes, from 9 to 5 (4:55 actually)

  # Mojolicious::Lite

  plugin Cron => ( '*/5 9-16 * * *' => sub {
      my $target_epoch = shift;
      # do something non-blocking but useful
  });

  # Mojolicious

  $self->plugin(Cron => '*/5 9-16 * * *' => sub {
      # same here
  });

# More than one schedule, or more options requires extended syntax

  plugin Cron => (
  sched1 => {
    base    => 'utc', # not needed for local time
    crontab => '*/10 15 * * *', # at every 10th minute past hour 15 (3:00 pm to 3:50 pm)
    code    => sub {
      # job 1 here
    }
  },
  sched2 => {
    crontab => '*/15 15 * * *', # at every 15th minute past hour 15 (3:00 pm to 3:45 pm)
    code    => sub {
      # job 2 here
    }
  });

=head1 DESCRIPTION

L is a L plugin that allows to schedule tasks
 directly from inside a Mojolicious application.

The plugin mimics *nix "crontab" format to schedule tasks (see L) .

As an extension to regular cron, seconds are supported in the form of a sixth space
separated field (For more information on cron syntax please see L).

The plugin can help in development and testing phases, as it is very easy to configure and
doesn't require a schedule utility with proper permissions at operating system level.

For testing, it may be helpful to use Test::Mock::Time ability to "fast-forward"
time calling all the timers in the interval. This way, you can actually test events programmed
far away in the future.

For deployment phase, it will help avoiding the installation steps normally asociated with
scheduling periodic tasks.

=head1 BASICS

When using preforked servers (as applications running with hypnotoad), some coordination
is needed so jobs are not executed several times.

L uses standard Fcntl functions for that coordination, to assure
a platform-independent behavior.

Please take a look in the examples section, for a simple Mojo Application that you can
run on a preforked server, try hot restarts, adding / removing workers, etc, and
check that scheduled jobs execute without interruptions or duplications.

=head1 EXTENDEND SYNTAX HASH

When using extended syntax, you can define more than one crontab line, and have access
to more options

  plugin Cron => {key1 => {crontab line 1}, key2 => {crontab line 2}, ...};

=head2 Keys

Keys are the names that identify each crontab line. They are used to form a locking
semaphore file to avoid multiple processes starting the same job.

You can use the same name in different Mojolicious applications that will run
at the same time. This will ensure that not more that one instance of the cron job
will take place at a specific scheduled time.

=head2 Crontab lines

Each crontab line consists of a hash with the following keys:

=over 8

=item base => STRING

Gives the time base used for scheduling. Either C or C (default C).

=item crontab => STRING

Gives the crontab schedule in 5 or 6 space-separated fields.

=item sec => STRING, min => STRING, ... mon => STRING

Optional. Gives the schedule in a set of individual fields, if the C
field is not specified.

For more information on base, crontab and other time related keys,
 please refer to L Constructor Attributes.

=item code => sub {...}

Mandatory. Is the code that will be executed whenever the crontab rule fires.
Note that this code B be non-blocking. For tasks that are naturally
blocking, the recommended solution would be to enqueue tasks in a job
queue (like the L queue, that will play nicelly with any Mojo project).

=back

=head1 METHODS

L inherits all methods from
L and implements the following new ones.

=head2 register

  $plugin->register(Mojolicious->new, {Cron => '* * * * *' => sub {}});

Register plugin in L application.

=head1 MULTIHOST LOCKING

The epoch corresponding to the scheduled time (i.e. the perl "time" function
corresponding to the current task) is available as the first parameter for the
callback sub. This can be used as a higher level "lock" to limit the amount
of simultaneous scheduled tasks to just one on a multi-host environment.

(You will need some kind of db service accessible from all hosts).

  # Execute some job every 5 minutes, only on one of the existing hosts

  plugin Cron => ( '*/5 * * * *' => sub {
      my ($target_epoch, $app) = @_;
      my $last_epoch = some_kind_of_atomic_swap_function(
        key => "some id key for this crontab",
        value => $target_epoch
        );
      if ($target_epoch != $last_epoc) { # Only first host will get here!
        # do something non-blocking
      } else {
        # following hosts will get here. Do not call the task
      }
  });

That "atomic_swap" function B. As this is unlikely the
case because it will normally imply a remote call, you can just enqueue a job to a L queue
and then inside the task filter out already executed (by other host) tasks by this lock.
You can see a working proof of concept L, using
an L db as a resilient backend to handle the atomic swap functionality.

=head1 WINDOWS INSTALLATION

To install in windows environments, you need to force-install module
Test::Mock::Time, or installation tests will fail.

=head1 AUTHOR

Daniel Mantovani, C

=head1 COPYRIGHT AND LICENCE

Copyright (C) 2018-2024, Daniel Mantovani.

This library is free software; you may redistribute it and/or modify it under
the terms of the Artistic License version 2.0.

=head1 SEE ALSO

L, L, L, L, L

=cut