cron window look-ahead + crontab docs (v1.0)

Model/RecoRecoModel.php

@@ -23,6 +23,7 @@ class RecoRecoModel extends Base
     public function run($now = null)
     {
         $now = $now ?: time();
+        $horizon = $this->horizon($now);
         $spawned = 0;
 
         $task_ids = $this->db->table('task_has_metadata')
@@ -31,13 +32,31 @@ class RecoRecoModel extends Base
             ->findAllByColumn('task_id');
 
         foreach ($task_ids as $task_id) {
-            $spawned += $this->processTemplate((int) $task_id, $now);
+            $spawned += $this->processTemplate((int) $task_id, $now, $horizon);
         }
 
         return $spawned;
     }
 
-    public function processTemplate($task_id, $now)
+    /**
+     * The look-ahead horizon for this run: fire everything whose fire time is before it. Computed as
+     * "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs:
+     * 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a
+     * 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are
+     * naturally included (their fire time is < now < horizon) -- that is the catch-up.
+     *
+     * @param  int $now
+     * @return int
+     */
+    private function horizon($now)
+    {
+        $startOfDay = mktime(0, 0, 0, (int) date('n', $now), (int) date('j', $now), (int) date('Y', $now));
+        $boundaryHour = (intdiv((int) date('G', $now), 6) + 1) * 6;
+
+        return $startOfDay + $boundaryHour * 3600 + 12 * 3600;
+    }
+
+    public function processTemplate($task_id, $now, $horizon)
     {
         $task = $this->taskFinderModel->getById($task_id);
 
@@ -86,11 +105,12 @@ class RecoRecoModel extends Base
             $this->setDue($task_id, $cursor);
         }
 
-        // Fire every occurrence whose fire time has arrived, advancing the cursor each time.
+        // Fire every occurrence whose fire time is before this run's horizon (this includes
+        // past-due ones -> catch-up), advancing the cursor each time.
         $spawned = 0;
         $fireTime = $cursor - $daysBefore * 86400;
 
-        while ($fireTime <= $now && $spawned < self::CATCHUP_CAP) {
+        while ($fireTime < $horizon && $spawned < self::CATCHUP_CAP) {
             $this->spawn($task, $targetColumn);
 
             $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);