Add Api::PeriodicJob to query periodic job history and broadcast execution events

Expose periodic job last-execution timestamps through the public API
via Api::PeriodicJob and Api.list_periodic_jobs. Add Observability::PeriodicJob
to broadcast events when periodic jobs are enqueued or skipped.

https://claude.ai/code/session_01QNAYckqy4eKc6EvTdDNLU7

Author: claude

spec/mosquito/api/periodic_job_spec.cr

@@ -0,0 +1,65 @@
+require "../../spec_helper"
+
+describe Mosquito::Api::PeriodicJob do
+  getter interval : Time::Span = 2.minutes
+
+  describe "publish context" do
+    it "includes the periodic job name" do
+      clean_slate do
+        Mosquito::Base.register_job_interval PeriodicTestJob, interval: interval
+        job_run = Mosquito::Base.scheduled_job_runs.first
+        observer = job_run.observer
+        assert_equal "periodic_job:PeriodicTestJob", observer.publish_context.context
+        assert_equal "mosquito:periodic_job:PeriodicTestJob", observer.publish_context.originator
+      end
+    end
+  end
+
+  it "can fetch a list of periodic jobs" do
+    clean_slate do
+      Mosquito::Base.register_job_interval PeriodicTestJob, interval: interval
+      periodic_jobs = Mosquito::Api::PeriodicJob.all
+      assert_equal 1, periodic_jobs.size
+      assert_equal "PeriodicTestJob", periodic_jobs.first.name
+      assert_equal interval, periodic_jobs.first.interval
+    end
+  end
+
+  it "returns nil for last_executed_at when never run" do
+    clean_slate do
+      Mosquito::Base.register_job_interval PeriodicTestJob, interval: interval
+      periodic_jobs = Mosquito::Api::PeriodicJob.all
+      assert_nil periodic_jobs.first.last_executed_at
+    end
+  end
+
+  it "returns the last executed time after a job runs" do
+    now = Time.utc.at_beginning_of_second
+    clean_slate do
+      Mosquito::Base.register_job_interval PeriodicTestJob, interval: interval
+      job_run = Mosquito::Base.scheduled_job_runs.first
+
+      Timecop.freeze(now) do
+        job_run.try_to_execute
+      end
+
+      periodic_jobs = Mosquito::Api::PeriodicJob.all
+      assert_equal now, periodic_jobs.first.last_executed_at
+    end
+  end
+
+  it "publishes an event when a periodic job is enqueued" do
+    now = Time.utc.at_beginning_of_second
+    clean_slate do
+      Mosquito::Base.register_job_interval PeriodicTestJob, interval: interval
+
+      eavesdrop do
+        Timecop.freeze(now) do
+          Mosquito::Base.scheduled_job_runs.first.try_to_execute
+        end
+      end
+
+      assert_message_received /enqueued/
+    end
+  end
+end

src/mosquito/api.cr

@@ -15,6 +15,10 @@ module Mosquito::Api
     JobRun.new id
   end
 
+  def self.list_periodic_jobs : Array(PeriodicJob)
+    PeriodicJob.all
+  end
+
   def self.list_queues : Array(Observability::Queue)
     Mosquito.backend.list_queues
       .map { |name| Observability::Queue.new name }

src/mosquito/api/periodic_job.cr

@@ -0,0 +1,64 @@
+module Mosquito
+  # An interface for inspecting the state of periodic jobs.
+  #
+  # This class provides read-only access to periodic job metadata,
+  # including the last time each periodic job was executed.
+  #
+  # ```
+  # Mosquito::Api::PeriodicJob.all.each do |job|
+  #   puts "#{job.name} last ran at #{job.last_executed_at}"
+  # end
+  # ```
+  class Api::PeriodicJob
+    # The name of the periodic job class.
+    getter name : String
+
+    # The configured run interval for this periodic job.
+    getter interval : Time::Span | Time::MonthSpan
+
+    private getter metadata : Metadata
+
+    # Returns a list of all registered periodic jobs.
+    def self.all : Array(self)
+      Base.scheduled_job_runs.map do |job_run|
+        new job_run.class.name, job_run.interval
+      end
+    end
+
+    def initialize(@name : String, @interval : Time::Span | Time::MonthSpan)
+      @metadata = Metadata.new(
+        Mosquito.backend.build_key("periodic_jobs", @name),
+        readonly: true
+      )
+    end
+
+    # The last time this periodic job was executed, or nil if it has never run.
+    def last_executed_at : Time?
+      if timestamp = metadata["last_executed_at"]?
+        Time.unix(timestamp.to_i)
+      end
+    end
+  end
+
+  class Observability::PeriodicJob
+    include Publisher
+
+    getter log : ::Log
+    getter publish_context : PublishContext
+
+    def initialize(periodic_job_run : Mosquito::PeriodicJobRun)
+      @name = periodic_job_run.class.name
+      @publish_context = PublishContext.new [:periodic_job, @name]
+      @log = Log.for(@name)
+    end
+
+    def enqueued(at time : Time)
+      log.info { "Enqueued periodic job at #{time}" }
+      publish({event: "enqueued", executed_at: time.to_unix})
+    end
+
+    def skipped
+      log.trace { "Not yet due for execution" }
+    end
+  end
+end

src/mosquito/periodic_job_run.cr

@@ -5,6 +5,7 @@ module Mosquito
     property class : Mosquito::PeriodicJob.class
     property interval : Time::Span | Time::MonthSpan
     getter metadata : Metadata { Metadata.new(Mosquito.backend.build_key("periodic_jobs", @class.name)) }
+    getter observer : Observability::PeriodicJob { Observability::PeriodicJob.new(self) }
 
     # The last executed timestamp for this periodicjob tracked by the backend.
     def last_executed_at?
@@ -56,8 +57,10 @@ module Mosquito
         end
 
         self.last_executed_at = now
+        observer.enqueued(at: now)
         true
       else
+        observer.skipped
         false
       end
     end