cronwatch 0.10.0 → 0.11.0

data/lib/cronwatch/environment.rb

@@ -1,14 +1,91 @@
 # frozen_string_literal: true
 
 module Cronwatch
-  # The app's environment, read one way everywhere: Rails.env when Rails is
-  # loaded, otherwise RAILS_ENV, then RACK_ENV. The SDK reads NODE_ENV.
+  # The app's environment, read as every CronWatch library reads it: the
+  # first of CRONWATCH_ENV, APP_ENV, then the app's own (Rails.env when Rails
+  # is loaded, else RAILS_ENV, then RACK_ENV) that holds more than spaces,
+  # trimmed and lowercased, with "prod" read as "production" and "dev",
+  # "local", "test" and "testing" as "development". None set is neither,
+  # which is the safe reading. The SDK reads NODE_ENV where this reads the
+  # app's own.
+  #
+  # @api private
   module Environment
-    DEVELOPMENT = %w[development test].freeze
+    # The variables read before the app's own, in order.
+    SHARED = %w[CRONWATCH_ENV APP_ENV].freeze
+    ALIASES = {
+      "prod" => "production", "dev" => "development", "local" => "development", "test" => "development",
+      "testing" => "development",
+    }.freeze
+    private_constant :SHARED, :ALIASES
 
     module_function
 
-    # "production", "development", ... or nil when nothing names one.
+    # "production", "development", "staging", ... or nil when nothing names one.
+    def environment
+      _, value = source
+      return nil if value.nil?
+
+      value = JS.trim(value).downcase
+      ALIASES.fetch(value, value)
+    end
+
+    # Where the environment was read from and its value as set:
+    # ["CRONWATCH_ENV", " dev"], ["Rails.env", "test"], or nil.
+    def source
+      SHARED.each do |variable|
+        value = ENV.fetch(variable, nil)
+        return [variable, value] if present?(value)
+      end
+      if defined?(::Rails) && ::Rails.respond_to?(:env)
+        env = ::Rails.env.to_s
+        return ["Rails.env", env] if present?(env)
+      end
+      %w[RAILS_ENV RACK_ENV].each do |variable|
+        value = ENV.fetch(variable, nil)
+        return [variable, value] if present?(value)
+      end
+      nil
+    end
+
+    def present?(value)
+      !value.nil? && !blank?(value)
+    end
+
+    # Whether a String is empty or only whitespace, as JavaScript's
+    # String.prototype.trim sees it (JS::WHITESPACE). Bytes that are not
+    # UTF-8 are not whitespace.
+    def blank?(value)
+      JS.trim(value.dup.force_encoding(Encoding::UTF_8).scrub).empty?
+    end
+
+    # A secret from the environment (CRONWATCH_TOKEN, CRON_SECRET): nil when
+    # the variable is unset, empty or only whitespace, so a blank value counts
+    # as not set and the routes fail closed. Any other value is used as it
+    # is, untrimmed.
+    def secret(variable)
+      value = ENV.fetch(variable, nil)
+      present?(value) ? value : nil
+    end
+
+    # A token or secret passed in code: a String, or nil. A String that is
+    # empty or only whitespace counts as not given (nil here; the caller
+    # tells that from nil the opt-out). Anything else (false, a number, a
+    # Symbol) raises TypeError naming the option, so it never becomes a
+    # password.
+    def secret_option(value, what)
+      return nil if value.nil?
+      unless value.is_a?(String)
+        kind = [true, false].include?(value) ? value.to_s : value.class.name
+        raise TypeError, "#{what} must be a String, or nil to opt out, not #{kind}"
+      end
+
+      blank?(value) ? nil : value
+    end
+
+    # The framework's own name for the environment, as it sets it: Rails.env
+    # when Rails is loaded, otherwise RAILS_ENV, then RACK_ENV, or nil. The
+    # section of a Solid Queue file is chosen by it, as Solid Queue does.
     def name
       if defined?(::Rails) && ::Rails.respond_to?(:env)
         env = ::Rails.env.to_s
@@ -17,30 +94,29 @@ module Cronwatch
       [ENV.fetch("RAILS_ENV", nil), ENV.fetch("RACK_ENV", nil)].find { |value| value && !value.empty? }
     end
 
-    # Development or test: Cronwatch::Web without a token serves only then.
+    # Development (including test): Cronwatch::Web without a token serves only then.
     def development?
-      DEVELOPMENT.include?(name)
+      environment == "development"
     end
 
     def production?
-      name == "production"
+      environment == "production"
     end
 
-    # Whether development or test was named by the app rather than by its
-    # server, for the dashboard's own token (Cronwatch::Web). Puma, Unicorn,
-    # Thin and rackup set RACK_ENV to "development" when nothing names an
+    # Whether development was named by the app rather than by its server,
+    # for the dashboard's own token (Cronwatch::Web). Puma, Unicorn, Thin
+    # and rackup set RACK_ENV to "development" when nothing names an
     # environment, so under one of them, in production too, RACK_ENV alone
-    # reads "development". There it takes Rails.env, RAILS_ENV or APP_ENV
-    # (Sinatra's) to say development; RACK_ENV "test" still counts, as no
-    # server sets it.
+    # reads "development". There it takes CRONWATCH_ENV, APP_ENV, Rails.env
+    # or RAILS_ENV to say development; any other value of RACK_ENV that reads
+    # as development ("test", "dev") still counts, as no server sets it.
     def stated_development?
       return false unless development?
-      return true if defined?(::Rails) && ::Rails.respond_to?(:env) && !::Rails.env.to_s.empty?
 
-      stated = [ENV.fetch("RAILS_ENV", nil), ENV.fetch("APP_ENV", nil)].find { |value| value && !value.empty? }
-      return DEVELOPMENT.include?(stated) unless stated.nil?
+      variable, value = source
+      return true unless variable == "RACK_ENV" && JS.trim(value).downcase == "development"
 
-      name == "test" || !defaulting_server?
+      !defaulting_server?
     end
 
     # A server that sets RACK_ENV when it is unset is running this process.

data/lib/cronwatch/evaluate.rb

@@ -4,6 +4,8 @@ module Cronwatch
   # Pure decisions about a job's health. Each function takes the current state
   # and returns the new state plus the alerts that should go out. Nothing here
   # touches a store or a network, which is what makes it testable.
+  #
+  # @api private
   module Evaluate
     DEFAULT_GRACE_MS = 10 * 60_000
     DEFAULT_TIMEOUT_MS = 60 * 60_000
@@ -69,6 +71,12 @@ module Cronwatch
       [count, MAX_DURATION_MS].min.to_i
     end
 
+    # A JSON number, as JavaScript's typeof value === "number" sees one
+    # read from JSON: an Integer or a Float (never true or false).
+    def json_number?(value)
+      value.is_a?(Integer) || value.is_a?(Float)
+    end
+
     def empty_state(job)
       JobState.new(job: job, open: {}, consecutive_failures: 0, silenced_until: nil, last_alert_at: nil,
                    pending_recovery: [], undelivered: [])
@@ -77,21 +85,35 @@ module Cronwatch
     # A stored state with every field present, or a fresh one. State written
     # by an older version lacks the newer fields. `sending` is the exception:
     # it is there only while it holds an alert (see hold_alerts).
+    #
+    # Read leniently, since a foreign, hand-edited or damaged row must affect
+    # only its own job, and the next write puts it right: a state that is not
+    # an object reads as none; `open` keeps only its entries whose value is a
+    # number (anything but an object reads as {}); `silenced_until` and
+    # `last_alert_at` that are not numbers read as nil; `pending_recovery`
+    # keeps only its conditions (strings as stored), and `undelivered` only
+    # its entries that are objects (a list of neither shape reads as []).
+    # Unknown fields are kept as written.
     def normalize_state(state, job)
+      state = JobState.from_h(state)
       return empty_state(job) if state.nil?
 
-      state = JobState.from_h(state)
       sending = state.sending
+      open = state.open.is_a?(Hash) ? state.open.select { |_, at| json_number?(at) } : {}
+      pending = state.pending_recovery.is_a?(Array) ? state.pending_recovery.grep(Symbol) : []
+      undelivered = state.undelivered.is_a?(Array) ? state.undelivered.grep(Alert) : []
       JobState.new(
         job: state.job.nil? ? job : state.job,
-        open: (state.open || {}).dup,
+        open: open,
         consecutive_failures: failure_count(state),
-        silenced_until: state.silenced_until,
-        last_alert_at: state.last_alert_at,
-        pending_recovery: (state.pending_recovery || []).dup,
-        undelivered: (state.undelivered || []).dup,
+        silenced_until: json_number?(state.silenced_until) ? state.silenced_until : nil,
+        last_alert_at: json_number?(state.last_alert_at) ? state.last_alert_at : nil,
+        pending_recovery: pending,
+        undelivered: undelivered,
         version: state.version,
         sending: sending.is_a?(Array) && !sending.empty? ? sending.dup : nil,
+        # Fields a newer release wrote, carried through every write.
+        extra: state.extra,
       )
     end
 
@@ -114,7 +136,8 @@ module Cronwatch
     # as JavaScript prints a number.
     def alert_key(alert)
       at = alert.at
-      "#{alert.type}|#{at.is_a?(Numeric) ? JS.number(at) : at}|#{alert.run&.id}"
+      run = alert.run
+      "#{alert.type}|#{at.is_a?(Numeric) ? JS.number(at) : at}|#{run.id if run.is_a?(Run)}"
     end
 
     # `alerts` added to the undelivered queue: one with the same key as a
@@ -444,11 +467,19 @@ module Cronwatch
     # is dropped rather than sent late. An alert for a condition is stale once
     # that condition has closed, or has closed and opened again (it opened at a
     # time other than the alert's). A recovery is stale when any condition it
-    # names is open again; while they all stay closed it is kept.
+    # names is open again; while they all stay closed it is kept. From a
+    # foreign or damaged row: an alert whose `at` is not a number, and a
+    # recovery whose `details.after` is not a list of conditions, are stale.
     def stale_alert?(alert, state)
-      return Array(alert.details[:after]).any? { |condition| state.open.key?(condition.to_sym) } if alert.type == :recovered
+      if alert.type == :recovered
+        # One whose details say nothing of what it recovers from cannot be judged, and goes.
+        after = alert.details.is_a?(Hash) ? alert.details[:after] : nil
+        return true unless after.is_a?(Array)
 
-      state.open[alert.type] != alert.at
+        return after.any? { |condition| !condition.is_a?(Symbol) || state.open.key?(condition) }
+      end
+      # One with no time cannot match an open condition.
+      !json_number?(alert.at) || state.open[alert.type] != alert.at
     end
 
     # How a job looks at a glance. Silence wins, then stuck, failing and late.

data/lib/cronwatch/flight.rb

@@ -3,6 +3,8 @@
 module Cronwatch
   class Client
     # One shared check: the first caller runs it, the others wait for its result.
+    #
+    # @api private
     class Flight
       # The thread running the check.
       attr_reader :owner

data/lib/cronwatch/format.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Cronwatch
+  # @api private
   module Format
     NAMED = /\A[A-Za-z_$][A-Za-z0-9_$]*: /
 

data/lib/cronwatch/http.rb

@@ -7,8 +7,15 @@ require "uri"
 module Cronwatch
   # POSTs for the alert channels. Anything with `post(url, body, headers)`
   # returning a Response can stand in for it, which is how the tests run.
+  #
+  # @api private
   module HTTP
     TIMEOUT = 10
+    # The most of an answer's body read (1 MiB): a channel reads 200
+    # characters of a refusal, and a hostile or broken endpoint could
+    # otherwise stream gigabytes into the worker within the deadline.
+    # Reading stops there. A 2xx answer's body is not read at all.
+    MAX_BODY = 1_048_576
 
     Response = Struct.new(:status, :body, keyword_init: true) do
       def ok? = status >= 200 && status < 300
@@ -33,6 +40,8 @@ module Cronwatch
       # sends. Past the deadline before an answer, raises HTTP::TimeoutError;
       # past it while the body is still arriving, returns the answer with an
       # empty body, as the SDK's channels treat a body they could not read.
+      # A 2xx answer comes back with an empty body, unread, since no channel
+      # needs it; any other with at most MAX_BODY bytes of it.
       def post(url, body, headers)
         uri = HTTP.postable(url)
         deadline = HTTP.monotonic + @timeout
@@ -46,7 +55,11 @@ module Cronwatch
           conn.read_timeout = remaining
           conn.write_timeout = remaining
           conn.request(request) do |response|
-            return Response.new(status: response.code.to_i, body: read_body(conn, response, deadline))
+            status = response.code.to_i
+            # Returning from inside the block leaves the rest unread; the connection closes after.
+            return Response.new(status: status, body: "") if status >= 200 && status < 300
+
+            return Response.new(status: status, body: read_body(conn, response, deadline))
           end
         end
       rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
@@ -65,17 +78,20 @@ module Cronwatch
 
       private
 
-      # The body, read in chunks until the deadline; "" when it passes first.
+      # The body, read in chunks until it ends or MAX_BODY bytes have come,
+      # whichever is first; "" when the deadline passes first.
       def read_body(conn, response, deadline)
-        chunks = []
+        body = "".b
         conn.read_timeout = HTTP.remaining(deadline)
         response.read_body do |chunk|
           raise TimeoutError if HTTP.monotonic >= deadline
 
-          chunks << chunk
+          body << chunk.b.byteslice(0, MAX_BODY - body.bytesize)
+          break if body.bytesize >= MAX_BODY
+
           conn.read_timeout = HTTP.remaining(deadline)
         end
-        chunks.join.b
+        body
       rescue Net::ReadTimeout, TimeoutError
         ""
       end

data/lib/cronwatch/job.rb

@@ -95,6 +95,8 @@ module Cronwatch
   end
 
   # Collects a run's output and metrics while its block runs.
+  #
+  # @api private
   class RunRecorder
     # Lines are dropped from the front once the output is well past the cap;
     # Output.redact_and_cap trims it exactly at the end.

data/lib/cronwatch/js.rb

@@ -6,6 +6,8 @@ module Cronwatch
   # webhook bodies, so the gem reproduces them byte for byte: Math.round,
   # String(number), JSON.stringify, String.prototype.trim and lengths counted
   # in UTF-16 code units.
+  #
+  # @api private
   module JS
     # What JavaScript's \s and trim() treat as whitespace.
     WHITESPACE = "\\t\\n\\v\\f\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff"
@@ -40,8 +42,10 @@ module Cronwatch
       value - floor >= 0.5 ? floor + 1 : floor
     end
 
+    # Number.isFinite of the number as JavaScript would hold it: an Integer
+    # past a double's range is Infinity there, so it is not finite here.
     def finite?(value)
-      value.is_a?(Integer) || (value.is_a?(Numeric) && value.real? && value.to_f.finite?)
+      value.is_a?(Numeric) && value.real? && value.to_f.finite?
     end
 
     # Number.isInteger.
@@ -159,12 +163,44 @@ module Cronwatch
     end
 
     def quote(text)
+      if text.encoding == Encoding::UTF_8 && !text.valid_encoding? && text.b.match?(LONE)
+        # A lone surrogate (see lone_surrogate), written as JSON.stringify writes one.
+        parts = text.b.split(LONE_SPLIT).each_with_index.map do |part, i|
+          next quote(part.force_encoding(Encoding::UTF_8))[1...-1] if i.even?
+
+          bytes = part.bytes
+          format("\\u%04x", ((bytes[0] & 0x0F) << 12) | ((bytes[1] & 0x3F) << 6) | (bytes[2] & 0x3F))
+        end
+        return "\"#{parts.join}\""
+      end
       text = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless text.encoding == Encoding::UTF_8 && text.valid_encoding?
       text = text.scrub unless text.valid_encoding?
       escaped = text.gsub(/["\\\u0000-\u001f]/) { |c| ESCAPES[c] || format("\\u%04x", c.ord) }
       "\"#{escaped}\""
     end
 
+    # A surrogate code unit on its own, in the bytes UTF-8 would give it.
+    # They make the string invalid UTF-8, which Ruby's own methods refuse, so
+    # one is only ever the last thing added to text about to be written:
+    # quote writes it as \udXXX, as JSON.stringify does.
+    LONE = /\xED[\xA0-\xBF][\x80-\xBF]/n
+    LONE_SPLIT = /(\xED[\xA0-\xBF][\x80-\xBF])/n
+
+    def lone_surrogate(unit)
+      [0xED, 0x80 | ((unit >> 6) & 0x3F), 0x80 | (unit & 0x3F)].pack("C*").force_encoding(Encoding::UTF_8)
+    end
+
+    # String.prototype.slice(0, units) as JavaScript gives it: the first
+    # `units` UTF-16 code units, and the high surrogate of a pair the cut
+    # splits. Returns the head Ruby can hold (head16) and that surrogate's
+    # code unit, or nil when the cut splits no pair.
+    def slice16(text, units)
+      head = head16(text, units)
+      return [head, nil] if text.ascii_only? || head.length == text.length || length16(head) == units
+
+      [head, 0xD800 + ((text[head.length].ord - 0x10000) >> 10)]
+    end
+
     # Property order: array-index keys ascending, then the rest as inserted.
     def object_keys(hash)
       keys = hash.keys
@@ -184,5 +220,42 @@ module Cronwatch
     def parse(text)
       ::JSON.parse(text)
     end
+
+    DECIMAL = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\z/
+    RADIX = { "x" => 16, "o" => 8, "b" => 2 }.freeze
+
+    # Number(string): decimal, 0x/0o/0b, Infinity, or NaN; 0 for a string
+    # of only whitespace.
+    def to_number(value)
+      text = trim(value.dup.force_encoding(Encoding::UTF_8).scrub)
+      return 0 if text.empty?
+      # Ruby's Float() wants a digit on both sides of the point; JavaScript does not.
+      return Float(text.sub(/\A([+-]?)\./, "\\10.").sub(/\.(?=[eE]|\z)/, ".0")) if DECIMAL.match?(text)
+      return text.start_with?("-") ? -Float::INFINITY : Float::INFINITY if /\A[+-]?Infinity\z/.match?(text)
+
+      if (m = /\A0([xXoObB])([0-9a-fA-F]+)\z/.match(text))
+        return Integer(m[2], RADIX.fetch(m[1].downcase))
+      end
+
+      Float::NAN
+    rescue ArgumentError
+      Float::NAN
+    end
+
+    # A time or a count of milliseconds as a SQL column holds it: an Integer
+    # or a Float kept, a String that is not blank read as Number() reads it
+    # (Postgres hands BIGINT over as text), and nil when the result is not a
+    # finite number. A whole number in a Float comes back an Integer.
+    def finite_number(value)
+      n =
+        case value
+        when Integer, Float then value
+        when String then trim(value.dup.force_encoding(Encoding::UTF_8).scrub).empty? ? nil : to_number(value)
+        end
+      return nil unless finite?(n)
+      return n.to_i if n.is_a?(Float) && n == n.floor && n.abs <= MAX_SAFE_INTEGER
+
+      n
+    end
   end
 end

data/lib/cronwatch/monitored.rb

@@ -6,6 +6,8 @@ module Cronwatch
   # declared on Cronwatch.client. Needs nothing beyond the core, so Sidekiq
   # without Rails can use it. Loaded by cronwatch/scheduler, which schedule:
   # :from_scheduler and declare_from_scheduler! need.
+  #
+  # @api private
   module Monitored
     # What `cronwatch` is outside a monitored run: it takes log and metric
     # calls and drops them, so the job's code runs the same either way.
@@ -51,7 +53,10 @@ module Cronwatch
         client = Cronwatch.client
         @lock.synchronize do
           current = @registration
-          return current if current && current[0].equal?(client)
+          # Kept while the client still holds the job: one forgotten since
+          # (the dashboard's forget) is declared again, with its schedule,
+          # as the other ports' bridges declare it again before a check.
+          return current if current && current[0].equal?(client) && client.defined_jobs.any? { |d| d.name == @name }
 
           handle = client.job(@name, **resolve_locked)
           @registration = [client, handle].freeze

data/lib/cronwatch/output.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Cronwatch
+  # A run's output and error on their way to the store: redaction, the cap,
+  # NUL and encoding. `redact_secrets` is public, the default `redact:` and
+  # the one to call from a redact of your own; the rest is @api private.
   module Output
     # Output is capped so a chatty job cannot fill the store. The tail is kept.
     # Counted in UTF-16 code units, as the SDK counts it.

data/lib/cronwatch/pg_cron.rb

@@ -26,6 +26,8 @@ module Cronwatch
     # A job that is renamed, unscheduled or no longer picked keeps its old
     # name's runs and history, and that name is declared again without a
     # schedule, so it is never reported missed. Its description says why.
+    # Forgetting that old name from the dashboard while a run of it is still
+    # open lets the run go: it is not recorded, and no error is reported.
     #
     #   require "cronwatch/pg_cron"
     #   Cronwatch.configure do |c|
@@ -86,6 +88,8 @@ module Cronwatch
       # The options of a definition that are declared again, without its schedule, for a name no longer in use.
       UNSCHEDULED = %i[description tags grace timeout max_duration budget failures_before_alert].freeze
       DESCRIBED = /\Apg_cron job (\d+) in /
+      private_constant :BACKFILL, :COLUMNS, :DESCRIBED, :JOBS_SQL, :MAX_PAGES, :NEWEST_SQL, :PAGE, :REBOOT, :RUNS_SQL,
+                       :SCHEDULE_ONLY, :SECONDS, :SETTING_SQL, :UNSCHEDULED, :UTC
 
       attr_reader :name
 
@@ -111,6 +115,8 @@ module Cronwatch
         @declared = {}
         # Names declared again without a schedule by retire, whose open runs are still read.
         @retired = Set.new
+        # The names the host declares, read on each sync after the retires (nil for a host without defined_jobs).
+        @declared_now = nil
         @scanned = false
         @warned = Set.new
         # Jobids whose callback failed, reported once until it works again.
@@ -204,6 +210,8 @@ module Cronwatch
       end
 
       # Queries through the pg gem's PG::Connection#exec_params.
+      #
+      # @api private
       class PGConnection
         def initialize(connection)
           @connection = connection
@@ -217,6 +225,8 @@ module Cronwatch
 
       # Queries through an ActiveRecord connection's exec_query, checking one
       # out of the pool for each query when given a class or a pool.
+      #
+      # @api private
       class ActiveRecordConnection
         def initialize(source)
           @source = source
@@ -278,6 +288,10 @@ module Cronwatch
         retire_unused(host, names, definitions, all)
         return [] if !recording || names.empty?
 
+        # The names declared now, after the retires above. A run copied under
+        # a retired name that was then forgotten (the dashboard's forget) has
+        # no job to go to: it is let go, never recorded and never read again.
+        @declared_now = host.respond_to?(:defined_jobs) ? host.defined_jobs.to_set(&:name) : nil
         alerts = []
         start_cursors(host, names, alerts, now)
         read_new(host, names, alerts, now)
@@ -451,10 +465,13 @@ module Cronwatch
           visible = all.map(&:jobid).to_set
           host.store.list_jobs.each do |stored|
             definition = stored.definition
+            # A foreign or damaged definition (not an object, tags not a list) is not one of ours.
+            next if !definition.is_a?(JobDefinition) || definition.unreadable? || !definition.tags.is_a?(Array)
             next if !stored.name.start_with?(@prefix) || in_use.include?(stored.name)
-            next if definition.schedule.nil? || definition.schedule.to_s.empty? || !Array(definition.tags).include?("pg_cron")
+            next if definition.schedule.nil? || definition.schedule.to_s.empty? || !definition.tags.include?("pg_cron")
 
-            match = DESCRIBED.match(definition.description.to_s)
+            description = definition.description
+            match = DESCRIBED.match(description.is_a?(String) ? description : "")
             next unless match
 
             jobid = match[1].to_i
@@ -477,8 +494,10 @@ module Cronwatch
         runid = Integer(row["runid"])
         jobid = Integer(row["jobid"])
         name = @pending[runid] || names[jobid]
-        unless name
+        if name.nil? || (@declared_now && !names.value?(name) && !@declared_now.include?(name))
+          @pending.delete(runid)
           @held.delete(runid)
+          @retired.delete(name) if name
           return
         end
         if row["start_time"].nil? && !PgCron.finished_status?(row["status"])

data/lib/cronwatch/rails/active_job.rb

@@ -7,7 +7,7 @@ require_relative "../scheduler"
 
 module Cronwatch
   # Monitors an ActiveJob class. Each perform is a recorded run with the
-  # trigger "active_job"; `cronwatch` in the job is the run's context, for
+  # trigger "active-job"; `cronwatch` in the job is the run's context, for
   # log and metric. A perform that raises is recorded as failed and then
   # raises as before, so retry_on, discard_on and error reporters see it
   # unchanged.
@@ -34,7 +34,7 @@ module Cronwatch
     extend ActiveSupport::Concern
     include Cronwatch::Monitored
 
-    TRIGGER = "active_job"
+    TRIGGER = Scheduler::ACTIVE_JOB_TRIGGER
 
     included do
       around_perform :cronwatch_perform

data/lib/cronwatch/schedule.rb

@@ -11,6 +11,8 @@ module Cronwatch
   # is accepted and how a fire lands on a clock that jumps (daylight saving),
   # so both are ported here and a Node and a Ruby process sharing one store
   # agree on every due time.
+  #
+  # @api private
   module Schedule
     # How early a run may start and still count for the fire it was meant for.
     EARLY_SLACK_MS = 60_000
@@ -29,6 +31,8 @@ module Cronwatch
 
       # The compiled cron fields, kept out of the public shape.
       attr_accessor :pattern
+      # Whether the cron names a date no month has ("0 0 30 2 *"), and so never fires.
+      attr_accessor :never
 
       def cron? = kind == :cron
       def interval? = kind == :interval
@@ -47,12 +51,21 @@ module Cronwatch
       def to_h = { "dueAt" => due_at, "deadline" => deadline }
     end
 
+    # Where a cron is asked once whether it ever fires: more than a 400-year
+    # cycle of the calendar before the year 3000, as in schedule.ts.
+    PROBE_FROM_MS = 946_684_800_000 # 2000-01-01T00:00:00Z
+    # Text that starts like an ISO date and time, which croner would take for a one-time date.
+    ONE_TIME_DATE = /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/
+
     @cache = {}
     @lock = Mutex.new
 
     module_function
 
-    # Parsed once per (schedule, timezone) pair and cached. Without a timezone
+    # Text with a colon after its first character, which croner would take
+    # for a one-time date, is refused. A cron that names a date no month has
+    # ("0 0 30 2 *") is read, and never fires: nothing is ever due, so it is
+    # never missed. Parsed once per (schedule, timezone) pair and cached. Without a timezone
     # the expression is read in the process timezone, like crontab. Vercel and
     # GitHub Actions run their crons in UTC, so pass timezone: "UTC" for those.
     def parse(schedule, timezone = nil)
@@ -68,6 +81,13 @@ module Cronwatch
 
         parsed = Parsed.new(kind: :interval, source: text, every_ms: every_ms)
       else
+        # croner reads text with a colon after its first character as a
+        # one-time date to fire at, not as a cron expression. A cron monitor
+        # has no use for one, so every such text is refused, as in the SDK.
+        if text[1..].to_s.include?(":")
+          reason = ONE_TIME_DATE.match?(text) ? "CronPattern: a one-time date is not supported" : "Invalid ISO8601 passed to timezone parser."
+          raise ArgumentError, "schedule \"#{schedule}\" is not a cron expression or \"every <duration>\": #{reason}"
+        end
         begin
           pattern = CronPattern.compile(text)
         rescue ArgumentError => e
@@ -75,6 +95,8 @@ module Cronwatch
         end
         parsed = Parsed.new(kind: :cron, source: text, timezone: timezone.nil? || timezone == "" ? nil : timezone)
         parsed.pattern = pattern
+        # The calendar alone decides it, so it is asked in UTC.
+        parsed.never = pattern.next_after(PROBE_FROM_MS, "UTC").nil?
       end
       parsed.freeze
       @lock.synchronize { @cache[key] = parsed }
@@ -88,6 +110,7 @@ module Cronwatch
     # stepped over an hour at a time. Ported from fireAfter in schedule.ts.
     def fire_after(parsed, from)
       raise ArgumentError, "schedule \"#{parsed.source}\" was not made by Schedule.parse" unless parsed.pattern
+      return nil if parsed.never
 
       start = count_from(from)
       return nil if start.nil?
@@ -111,6 +134,7 @@ module Cronwatch
     # any that do not move forward (see fire_after).
     def fires_between(parsed, from, to, limit)
       raise ArgumentError, "schedule \"#{parsed.source}\" was not made by Schedule.parse" unless parsed.pattern
+      return [] if parsed.never
 
       out = []
       start = count_from(from)

data/lib/cronwatch/scheduler.rb

@@ -40,6 +40,11 @@ module Cronwatch
       end
     end
 
+    # The trigger of a run an ActiveJob perform records, through
+    # Cronwatch::ActiveJob or a scheduler's entry. Runs recorded before 1.0
+    # carry "active_job".
+    ACTIVE_JOB_TRIGGER = "active-job"
+
     # How far ahead the daylight saving check looks, and how far either side
     # of each clock change it compares the scheduler's runs with CronWatch's.
     HORIZON_YEARS = 5
@@ -622,7 +627,7 @@ module Cronwatch
         ::ActiveJob::Base.around_perform do |job, block|
           declaration = Cronwatch::Scheduler.declaration_for_active_job(job)
           if declaration
-            Cronwatch::Monitored.record(declaration, "active_job", job) { block.call }
+            Cronwatch::Monitored.record(declaration, ACTIVE_JOB_TRIGGER, job) { block.call }
           else
             block.call
           end