Added automatic tracking of trackable jobs via queueing event listener

Author: fulopattila122

README.md

@@ -37,7 +37,7 @@ class MyJob implements \Konekt\History\Contracts\TrackableJob
 
     public function handle()
     {
-        $tracker = JobTracker::of($this);
+        $tracker = $this->jobTracker();
         $tracker->setProgressMax(count($this->dataToProcess));
         $tracker->started();
         try {
@@ -53,11 +53,7 @@ class MyJob implements \Konekt\History\Contracts\TrackableJob
     }
 }
 
-$job = new MyJob();
-$job->generateJobTrackingId();
-
-JobTracker::createFor($job);
-Bus::dispatch($job);
+MyJob::dispatch($myDataToProcess);
 ```
 
 ## Features

docs/README.md

@@ -1,11 +1,16 @@
-# Eloquent Model History Documentation
+# Eloquent Model History + Laravel Job History Documentation
 
-History is a Laravel package to manage the history of changes of Eloquent models.
+History is a Laravel package to manage the history of:
+
+1. Changes, diff and comments of Eloquent models;
+2. Track and log the execution history of Laravel background jobs;
 
 !> This library **DOES NOT automatically hook into the model's lifecycle events**, but allows the developer to manually register history events at arbitrary places in the application code.
 
 ## Features
 
+### Eloquent Model History
+
 - Record model creation, update, delete, and retrieval
 - Add optional comments to events
 - Add comment-only history events
@@ -15,6 +20,8 @@ History is a Laravel package to manage the history of changes of Eloquent models
 - Define included/excluded fields on a per-model basis
 - Has a diff of the changed fields (old/new values)
 
+### Eloquent Model History
+
 ## Alternatives
 
 If you need a strict audit tool for Laravel, that can automatically record changes, wherever they happen,

src/Concerns/CanBeTracked.php

@@ -15,12 +15,15 @@
 namespace Konekt\History\Concerns;
 
 use Illuminate\Support\Str;
+use Konekt\History\JobTracker;
 
 trait CanBeTracked
 {
-    public string $job_tracking_id;
+    private ?JobTracker $jobTracker = null;
 
-    public function getJobTrackingId(): string
+    public ?string $job_tracking_id = null;
+
+    public function getJobTrackingId(): ?string
     {
         return $this->job_tracking_id;
     }
@@ -40,4 +43,19 @@ public function generateJobTrackingId(): static
     {
         return $this->setJobTrackingId(Str::ulid()->toBase58());
     }
+
+    public function hasTrackingId(): bool
+    {
+        return null !== $this->job_tracking_id;
+    }
+
+    public function doesNotHaveTrackingIdYet(): bool
+    {
+        return null === $this->job_tracking_id;
+    }
+
+    protected function jobTracker(): JobTracker
+    {
+        return $this->jobTracker ??= JobTracker::of($this);
+    }
 }

src/Contracts/TrackableJob.php

@@ -16,5 +16,13 @@
 
 interface TrackableJob
 {
-    public function getJobTrackingId(): string;
+    public function getJobTrackingId(): ?string;
+
+    public function setJobTrackingId(string $trackingId): static;
+
+    public function generateJobTrackingId(): static;
+
+    public function hasTrackingId(): bool;
+
+    public function doesNotHaveTrackingIdYet(): bool;
 }

src/JobTracker.php

@@ -60,6 +60,13 @@ public static function of(TrackableJob $job): static
      */
     public static function createFor(TrackableJob $job, int $maxProgress = 100): JobExecution
     {
+        if ($job->doesNotHaveTrackingIdYet()) {
+            // We could generate a tracking ID here, but that would mean
+            // that the tracking ID may or may not be persisted along
+            // with the job to the queue and lead to inconsistency
+            throw new \LogicException('The job to be tracked does not have a tracking ID yet.');
+        }
+
         $result = JobExecutionProxy::create(array_merge([
             'queued_at' => Carbon::now(),
             'progress_max' => $maxProgress,

src/Listeners/StartJobTracking.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Konekt\History\Listeners;
+
+use Illuminate\Queue\Events\JobQueueing;
+use Konekt\History\Contracts\TrackableJob;
+use Konekt\History\JobTracker;
+
+class StartJobTracking
+{
+    public function handle(JobQueueing $event)
+    {
+        if ($event->job instanceof TrackableJob && $event->job->doesNotHaveTrackingIdYet()) {
+            $event->job->generateJobTrackingId();
+            JobTracker::createFor($event->job);
+        }
+    }
+}

src/Models/JobExecution.php

@@ -15,6 +15,7 @@
  */
 
 use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\HasMany;
@@ -51,6 +52,8 @@
  *
  * @property-read Model|Authenticatable $user
  * @property-read Collection $logs
+ *
+ * @method static Builder ofJobClass(string $jobClass)
  */
 class JobExecution extends Model implements JobExecutionContract
 {
@@ -72,6 +75,20 @@ public static function findByTrackingId(string $id): ?self
         return static::where('tracking_id', $id)->first();
     }
 
+    public static function byJobClass(string $jobClass, bool $activeOnesOnly = false, ?int $limit = null): Collection
+    {
+        $query = static::ofJobClass($jobClass)->orderBy('queued_at', 'desc');
+        if ($activeOnesOnly) {
+            $query->whereNull('failed_at')->whereNull('completed_at');
+        }
+
+        if (null !== $limit) {
+            $query->take($limit);
+        }
+
+        return $query->get();
+    }
+
     public function user(): BelongsTo
     {
         return $this->belongsTo(config('konekt.history.user_model', Auth::getProvider()->getModel()));
@@ -174,6 +191,11 @@ public function getUser(): ?Authenticatable
         return $this->user;
     }
 
+    protected function scopeOfJobClass(Builder $query, string $jobClass): Builder
+    {
+        return $query->where('job_class', $jobClass);
+    }
+
     protected function log(string $message, string $level, array $context): JobExecutionLogContract
     {
         return $this->logs()->create([

src/Providers/ModuleServiceProvider.php

@@ -16,9 +16,12 @@
 
 use Illuminate\Queue\Events\JobProcessed;
 use Illuminate\Queue\Events\JobProcessing;
+use Illuminate\Queue\Events\JobQueueing;
 use Illuminate\Support\Facades\App;
+use Illuminate\Support\Facades\Event;
 use Illuminate\Support\Facades\Queue;
 use Konekt\Concord\BaseModuleServiceProvider;
+use Konekt\History\Listeners\StartJobTracking;
 use Konekt\History\Models\JobExecution;
 use Konekt\History\Models\JobExecutionLog;
 use Konekt\History\Models\JobStatus;
@@ -46,6 +49,8 @@ public function boot(): void
         parent::boot();
         App::bind(JobInfo::SERVICE_NAME, fn () => null);
 
+        Event::listen(JobQueueing::class, StartJobTracking::class);
+
         Queue::before(function (JobProcessing $event) {
             App::instance(
                 JobInfo::SERVICE_NAME,

src/resources/database/migrations/2024_11_12_120632_create_job_executions_table.php

@@ -28,6 +28,7 @@ public function up(): void
             $table->timestamps();
 
             $table->index('queued_at');
+            $table->index('job_class');
 
             $table->foreign('user_id')
                 ->references('id')

tests/Dummies/SampleTrackableJob.php

@@ -37,7 +37,7 @@ public function plantLogForTesting(string $level, string $message, array $contex
 
     public function handle(): void
     {
-        $tracker = JobTracker::of($this);
+        $tracker = $this->jobTracker();
         $tracker->started();
 
         foreach ($this->logs as $log) {

tests/JobExecutionTest.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Konekt\History\Tests;
+
+use Illuminate\Support\Facades\Bus;
+use Konekt\History\JobTracker;
+use Konekt\History\Models\JobExecution;
+use Konekt\History\Models\JobStatus;
+use Konekt\History\Tests\Dummies\SampleTask;
+use Konekt\History\Tests\Dummies\SampleTrackableJob;
+
+class JobExecutionTest extends TestCase
+{
+    /** @test */
+    public function it_can_find_and_entry_by_tracking_id()
+    {
+        $job = new SampleTrackableJob(new SampleTask());
+        $job->generateJobTrackingId();
+        JobTracker::createFor($job);
+
+        $execution = JobExecution::findByTrackingId($job->getJobTrackingId());
+
+        $this->assertInstanceOf(JobExecution::class, $execution);
+        $this->assertEquals($job->getJobTrackingId(), $execution->tracking_id);
+    }
+
+    /** @test */
+    public function it_can_return_the_entries_of_a_given_job_class()
+    {
+        foreach (range(1, 10) as $i) {
+            $job = new SampleTrackableJob(new SampleTask());
+            $job->generateJobTrackingId();
+            JobTracker::createFor($job);
+        }
+
+        $entries = JobExecution::byJobClass(SampleTrackableJob::class);
+        $this->assertCount(10, $entries);
+    }
+
+    /** @test */
+    public function it_can_return_the_active_entries_of_a_given_job_class()
+    {
+        foreach (range(1, 4) as $i) {
+            $job = new SampleTrackableJob(new SampleTask(), JobStatus::COMPLETED());
+            $job->generateJobTrackingId();
+            JobTracker::createFor($job);
+
+            Bus::dispatch($job);
+        }
+
+        foreach (range(1, 2) as $i) {
+            $job = new SampleTrackableJob(new SampleTask());
+            $job->generateJobTrackingId();
+            JobTracker::createFor($job);
+
+            Bus::dispatch($job);
+        }
+
+        $entries = JobExecution::byJobClass(SampleTrackableJob::class, true);
+        $this->assertCount(2, $entries);
+    }
+
+    /** @test */
+    public function it_can_return_the_entries_of_a_given_job_class_and_limit_the_record_count()
+    {
+        foreach (range(1, 10) as $i) {
+            $job = new SampleTrackableJob(new SampleTask());
+            $job->generateJobTrackingId();
+            JobTracker::createFor($job);
+        }
+
+        $entries = JobExecution::byJobClass(SampleTrackableJob::class, false, 5);
+        $this->assertCount(5, $entries);
+    }
+}

tests/JobTrackerTest.php

@@ -5,6 +5,7 @@
 namespace Konekt\History\Tests;
 
 use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Queue\Events\JobQueueing;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Bus;
@@ -17,6 +18,7 @@
 use Konekt\History\Events\TrackableJobLogCreated;
 use Konekt\History\Events\TrackableJobStarted;
 use Konekt\History\JobTracker;
+use Konekt\History\Listeners\StartJobTracking;
 use Konekt\History\Models\JobExecution;
 use Konekt\History\Models\JobStatus;
 use Konekt\History\Tests\Dummies\SampleTask;
@@ -133,6 +135,16 @@ public function it_can_log_during_execution()
         $this->assertCount(3, $logs);
     }
 
+    /** @test */
+    public function the_start_job_tracking_listener_is_active()
+    {
+        // I wanted to test here whether the listener works well
+        // and that the tracking id was initialized correctly
+        // but during tests queue listeners aren't invoked
+        Event::fake();
+        Event::assertListening(JobQueueing::class, StartJobTracking::class);
+    }
+
     /** @test */
     public function it_emits_a_created_event_when_creating_via_the_tracker()
     {