cronwatch 0.10.0 → 0.11.0

data/lib/cronwatch/serialize.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Cronwatch
+  # @api private
   module Serialize
     module_function
 

data/lib/cronwatch/stats.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Cronwatch
+  # @api private
   module Stats
     module_function
 

data/lib/cronwatch/stores/active_record.rb

@@ -247,9 +247,10 @@ module Cronwatch
         read(:running_runs, []).map { |row| row_to_run(row) }
       end
 
+      # A state whose text does not parse, or is not an object, reads as none.
       def get_state(job)
         row = read(:get_state, [job]).first
-        row && JobState.from_h(json(row["state"]))
+        row && JobState.from_h(lenient_json(row["state"]))
       end
 
       def set_state(state)
@@ -347,7 +348,8 @@ module Cronwatch
         # The version inside a state's JSON, as Evaluate.state_version reads
         # it: a whole number from 0 to 2**53 - 1, else 0 (none, or a foreign
         # row's 1.5 or "x", which must neither fail the statement nor refuse
-        # every write for good). Each CASE tests the JSON type before any cast.
+        # every write for good; on SQLite, also text that is not JSON). Each
+        # CASE tests the JSON type before any cast.
         version = lambda do |column|
           if pg
             v = "(#{column}->>'version')::numeric"
@@ -355,7 +357,8 @@ module Cronwatch
                  "WHEN #{v} % 1 = 0 AND #{v} BETWEEN 0 AND 9007199254740991 THEN #{v}::bigint ELSE 0 END"
           end
           v = "json_extract(#{column}, '$.version')"
-          "CASE WHEN json_type(#{column}, '$.version') NOT IN ('integer', 'real') THEN 0 " \
+          # Text that is not JSON at all (SQLite holds any) counts as 0 too, before json_type could fail on it.
+          "CASE WHEN NOT json_valid(#{column}) THEN 0 WHEN json_type(#{column}, '$.version') NOT IN ('integer', 'real') THEN 0 " \
             "WHEN #{v} = CAST(#{v} AS INTEGER) AND #{v} BETWEEN 0 AND 9007199254740991 THEN CAST(#{v} AS INTEGER) ELSE 0 END"
         end
         sql = {
@@ -425,28 +428,43 @@ module Cronwatch
         end
       end
 
-      def int(value)
-        value.nil? ? nil : Integer(value)
+      # Rows are read leniently: a foreign, hand-edited or damaged row (SQLite
+      # keeps whatever type it is given, in any column) must affect only its
+      # own job, never every read. JSON text that does not parse (or nests
+      # past JSON.parse's limit) reads as nil, which the client takes as no
+      # state, or as an unreadable definition it reports.
+      def lenient_json(value)
+        json(value)
+      rescue ::JSON::ParserError
+        nil
       end
 
-      def row_to_job(row)
-        StoredJob.new(name: row["name"], definition: JobDefinition.from_h(definition_json(row["definition"])),
-                      created_at: int(row["created_at"]), updated_at: int(row["updated_at"]))
+      # A time that must be there: one that is not a finite number reads as 0.
+      def time(value)
+        JS.finite_number(value) || 0
       end
 
-      # A definition that does not parse (nested past JSON.parse's limit, say)
-      # reads as nil, which JobDefinition.from_h marks unreadable.
-      def definition_json(value)
-        json(value)
-      rescue ::JSON::ParserError
-        nil
+      # A time or duration that may be absent: one that is not a finite number reads as nil.
+      def maybe_time(value)
+        JS.finite_number(value)
+      end
+
+      def row_to_job(row)
+        StoredJob.new(name: row["name"], definition: JobDefinition.from_h(lenient_json(row["definition"]), row["name"]),
+                      created_at: time(row["created_at"]), updated_at: time(row["updated_at"]))
       end
 
+      # A start that is not a finite number reads as 0, a finish or duration
+      # as nil; an error or output that is not text as nil; metrics that do
+      # not parse to an object as {}; a trigger that is not text as "run".
       def row_to_run(row)
-        metrics = row["metrics"].nil? ? {} : Run.metrics_from(json(row["metrics"]))
-        Run.new(id: row["id"], job: row["job"], status: row["status"].to_sym, started_at: int(row["started_at"]),
-                finished_at: int(row["finished_at"]), duration_ms: int(row["duration_ms"]), error: row["error"],
-                output: row["output"], metrics: metrics, trigger: row["trigger"])
+        error = row["error"]
+        output = row["output"]
+        trigger = row["trigger"]
+        Run.new(id: row["id"], job: row["job"], status: Run.status_from(row["status"]), started_at: time(row["started_at"]),
+                finished_at: maybe_time(row["finished_at"]), duration_ms: maybe_time(row["duration_ms"]),
+                error: error.is_a?(String) ? error : nil, output: output.is_a?(String) ? output : nil,
+                metrics: Run.metrics_from(lenient_json(row["metrics"])), trigger: trigger.is_a?(String) ? trigger : "run")
       end
     end
   end

data/lib/cronwatch/ticker.rb

@@ -6,6 +6,8 @@ module Cronwatch
   class Client
     # Calls the block after `first` seconds, then every `interval` seconds
     # counted from the start, in a background thread, until stopped.
+    #
+    # @api private
     class Ticker
       def initialize(interval, first, &tick)
         @lock = Mutex.new

data/lib/cronwatch/triage/anthropic.rb

@@ -37,6 +37,8 @@ module Cronwatch
 
       # JavaScript's /<\/?job_data/gi, spelled out: Ruby's /i folds more than ASCII.
       TAG = %r{</?[Jj][Oo][Bb]_[Dd][Aa][Tt][Aa]}
+      private_constant :DEFAULT_EFFORT, :DEFAULT_MAX_TOKENS, :DEFAULT_MODEL, :FALLBACK_BETA, :REQUEST_TIMEOUT_MS,
+                       :SYSTEM, :TAG
 
       attr_reader :model, :effort, :max_tokens, :fallbacks, :context
 

data/lib/cronwatch/types.rb

@@ -7,6 +7,8 @@ module Cronwatch
   # Ruby names are snake_case symbols; everything that leaves the process
   # (store rows, JSON, webhook bodies) uses the SDK's camelCase names and
   # string values. Each type's to_h is that JSON shape, and from_h reads it.
+  #
+  # @api private
   module Naming
     module_function
 
@@ -51,6 +53,8 @@ module Cronwatch
   end
 
   # Shared by the structs below.
+  #
+  # @api private
   module Serializable
     def as_json(*)
       to_h
@@ -78,28 +82,41 @@ module Cronwatch
 
     FIELDS.each_key { |field| define_method(field) { @fields[field] } }
 
-    # What from_h makes a stored definition that is not a JSON object from.
-    UNREADABLE = {}.freeze
+    private_constant :BY_JSON, :FIELDS
 
     def initialize(fields = {})
       @fields = {}
       fields.each { |k, v| @fields[k.is_a?(Symbol) ? k : k.to_s] = v }
       @fields.freeze
-      @unreadable = fields.equal?(UNREADABLE)
+      @unreadable = false
       freeze
     end
 
     # A stored definition that is not a JSON object (null, a string, a
-    # number, written by hand or by something else) reads as an empty one
-    # marked unreadable, so the one row does not stop every other job being
-    # listed; a check or a dashboard read reports that job and shows it as
-    # failing (see Client#evaluable).
-    def self.from_h(hash)
+    # number, an array, or text that does not parse, written by hand or by
+    # something else) reads as `{ name }` (`name` being the job's, when
+    # given) marked unreadable, so the one row does not stop every other job
+    # being listed; a check or a dashboard read reports that job and shows it
+    # as failing (see Client#evaluable). `tags` is kept only when it is a
+    # list of strings. Every other field is kept as stored.
+    def self.from_h(hash, name = nil)
       return hash if hash.is_a?(JobDefinition)
-      return new(UNREADABLE) unless hash.is_a?(Hash)
+      return unreadable(name) unless hash.is_a?(Hash)
+
+      fields = hash.each_with_object({}) { |(k, v), out| out[BY_JSON[k.to_s] || k.to_s] = v }
+      tags = fields[:tags]
+      fields.delete(:tags) if fields.key?(:tags) && !(tags.is_a?(Array) && tags.all?(String))
+      new(fields)
+    end
 
-      new(hash.each_with_object({}) { |(k, v), out| out[BY_JSON[k.to_s] || k.to_s] = v })
+    # `{ name }`, marked unreadable. See from_h.
+    def self.unreadable(name)
+      definition = allocate
+      definition.instance_variable_set(:@fields, (name.nil? ? {} : { name: name }).freeze)
+      definition.instance_variable_set(:@unreadable, true)
+      definition.freeze
     end
+    private_class_method :unreadable
 
     def [](field)
       @fields[field]
@@ -161,7 +178,7 @@ module Cronwatch
       new(
         id: Naming.fetch(hash, "id"),
         job: Naming.fetch(hash, "job"),
-        status: Naming.fetch(hash, "status")&.to_sym,
+        status: Run.status_from(Naming.fetch(hash, "status")),
         started_at: Naming.fetch(hash, "startedAt"),
         finished_at: Naming.fetch(hash, "finishedAt"),
         duration_ms: Naming.fetch(hash, "durationMs"),
@@ -174,12 +191,19 @@ module Cronwatch
 
     def to_h
       {
-        "id" => id, "job" => job, "status" => status.to_s, "startedAt" => started_at, "finishedAt" => finished_at,
+        "id" => id, "job" => job, "status" => status.is_a?(Symbol) ? status.to_s : status,
+        "startedAt" => started_at, "finishedAt" => finished_at,
         "durationMs" => duration_ms, "error" => error, "output" => output,
         "metrics" => Run.metrics_from(metrics), "trigger" => trigger,
       }
     end
 
+    # A status as read: text as a Symbol, anything else (a foreign or
+    # damaged row's) kept as it came, which matches no known status.
+    def self.status_from(value)
+      value.is_a?(String) ? value.to_sym : value
+    end
+
     # Stored metrics as a Hash with string keys. Anything else (a string or
     # an array a foreign or corrupted row holds) reads as none.
     def self.metrics_from(value)
@@ -196,9 +220,10 @@ module Cronwatch
     def self.from_h(hash)
       return hash if hash.is_a?(StoredJob)
 
+      name = Naming.fetch(hash, "name")
       new(
-        name: Naming.fetch(hash, "name"),
-        definition: JobDefinition.from_h(Naming.fetch(hash, "definition") || {}),
+        name: name,
+        definition: JobDefinition.from_h(Naming.fetch(hash, "definition"), name),
         created_at: Naming.fetch(hash, "createdAt"),
         updated_at: Naming.fetch(hash, "updatedAt"),
       )
@@ -211,6 +236,8 @@ module Cronwatch
 
   # An alert before it has a title and message. See Format.compose_alert.
   # `details` is a hash with snake_case symbol keys; its JSON is camelCase.
+  #
+  # @api private
   AlertDraft = Struct.new(:type, :run, :details, keyword_init: true) do
     include Serializable
 
@@ -241,65 +268,145 @@ module Cronwatch
       @triage_tried = true
     end
 
+    # Read leniently, since a queued alert a foreign writer left malformed
+    # must affect only its own job: a field of the wrong type is kept as it
+    # came (a `type` or `run` that is not what it should be, `details` that
+    # are not an object, an `at` that is not a number), and the retry drops
+    # such an alert as stale (Evaluate.stale_alert?).
     def self.from_h(hash)
       return hash if hash.is_a?(Alert)
 
       run = Naming.fetch(hash, "run")
-      details = Naming.from_json_value(Naming.fetch(hash, "details") || {})
-      details[:after] = details[:after].map(&:to_sym) if details[:after].is_a?(Array)
-      details[:reason] = details[:reason].to_sym if details[:reason].is_a?(String)
+      written = Naming.fetch(hash, "details") || {}
+      details = Naming.from_json_value(written)
+      if details.is_a?(Hash)
+        details[:after] = details[:after].map { |c| c.is_a?(String) ? c.to_sym : c } if details[:after].is_a?(Array)
+        details[:reason] = details[:reason].to_sym if details[:reason].is_a?(String)
+      end
+      type = Naming.fetch(hash, "type")
+      definition = Naming.fetch(hash, "definition")
       alert = new(
-        type: Naming.fetch(hash, "type")&.to_sym,
-        run: run && Run.from_h(run),
+        type: type.is_a?(String) ? type.to_sym : type,
+        run: run.is_a?(Hash) ? Run.from_h(run) : run,
         details: details,
         job: Naming.fetch(hash, "job"),
-        definition: JobDefinition.from_h(Naming.fetch(hash, "definition") || {}),
+        definition: definition.nil? || definition.is_a?(Hash) ? JobDefinition.from_h(definition || {}) : definition,
         title: Naming.fetch(hash, "title"),
         message: Naming.fetch(hash, "message"),
         at: Naming.fetch(hash, "at"),
       )
       alert.triage_result = Naming.fetch(hash, "triage") if Naming.present?(hash, "triage")
+      alert.keep_as_written(hash, written, details)
       alert
     end
 
+    # What a stored alert held that its members do not say again: the
+    # fields this version does not know (a newer release may add one), its
+    # details as written, since snake_case and back would turn a key spelled
+    # `a_b` into `aB`, and which known fields it left out. to_h writes the
+    # first two back, the details only while they are unchanged, and leaves
+    # out a field that was absent while it still holds what its absence
+    # read as, so a partial alert (a foreign row's) is written as it came,
+    # in the order it came. An alert with every field the SDK writes has
+    # them written back in the SDK's order, then the fields it does not
+    # know, since a store on Postgres jsonb gives an object's keys back in
+    # an order of its own (as JobState.sending_entry does for an entry).
+    #
+    # @api private
+    def keep_as_written(hash, written, details)
+      extra = hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v unless Alert::KNOWN.include?(k.to_s) }
+      @extra = extra.empty? ? nil : extra
+      @written_details = [Marshal.load(Marshal.dump(details)), Alert.string_keys(written)] if written.is_a?(Hash)
+      absent = (Alert::KNOWN - ["triage"]).reject { |key| Naming.present?(hash, key) }
+      @absent = absent.empty? ? nil : to_h.slice(*absent)
+      order = hash.keys.map(&:to_s)
+      @order = @absent && order.uniq == order ? order : nil
+    end
+
+    # @api private
+    def self.string_keys(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, string_keys(v)] }
+      when Array then value.map { |v| string_keys(v) }
+      else value
+      end
+    end
+
     def to_h
       out = {
-        "type" => type.to_s, "run" => run&.to_h, "details" => Naming.to_json_value(details), "job" => job,
-        "definition" => definition.respond_to?(:to_h) ? definition.to_h : definition,
+        "type" => type.is_a?(Symbol) ? type.to_s : type, "run" => run.is_a?(Run) ? run.to_h : run,
+        "details" => details_json, "job" => job,
+        "definition" => definition.is_a?(JobDefinition) ? definition.to_h : definition,
         "title" => title, "message" => message, "at" => at,
       }
+      @absent&.each { |key, value| out.delete(key) if out[key] == value }
       out["triage"] = triage if triage_tried?
-      out
+      @extra&.each { |key, value| out[key] = value unless out.key?(key) || Alert::KNOWN.include?(key) }
+      return out if @order.nil? || @order == out.keys
+
+      # The keys in the order they were read, as the object a store held
+      # keeps them; any added since go after.
+      written = @order.select { |key| out.key?(key) }
+      (written + (out.keys - written)).to_h { |key| [key, out[key]] }
+    end
+
+    private
+
+    def details_json
+      return @written_details[1] if @written_details && @written_details[0] == details
+
+      Naming.to_json_value(details)
     end
   end
 
+  # The fields this version reads from a stored alert; the rest are kept as they came.
+  # @api private
+  Alert::KNOWN = %w[type run details job definition title message at triage].freeze
+
   # `version` goes up by one on every write, so a store can refuse a write
   # made from a stale read (see Stores::Memory#compare_and_set_state). Absent
   # (nil) counts as 0.
   #
+  # from_h reads a state as stored, keeping each field as it came where it
+  # has the wrong type (Evaluate.normalize_state then reads it leniently),
+  # so a foreign, hand-edited or damaged row is written back unchanged by a
+  # read that changes nothing, and affects only its own job. A stored state
+  # that is not a JSON object reads as none (nil).
+  #
   # `sending` is the outbox (see Evaluate.hold_alerts): entries of
   # { "until" => epoch ms, "alert" => Alert }, read leniently, since an entry
   # a foreign writer left malformed must not make the whole state unreadable:
   # an entry that is not a Hash, or whose alert is not one, is kept as it
   # came. nil when there is none; it is never written empty.
+  #
+  # `extra` holds the fields this version does not know, written by a newer
+  # one, as the JSON they came as (string keys): every write carries them
+  # back unchanged, after the known fields, so a process sharing the store
+  # with a newer release never erases what that release keeps there. nil
+  # when there are none. An open condition this version does not know stays
+  # in `open` the same way, under its own name.
   JobState = Struct.new(:job, :open, :consecutive_failures, :silenced_until, :last_alert_at, :pending_recovery,
-                        :undelivered, :version, :sending, keyword_init: true) do
+                        :undelivered, :version, :sending, :extra, keyword_init: true) do
     include Serializable
 
     def self.from_h(hash)
       return hash if hash.is_a?(JobState)
+      return nil unless hash.is_a?(Hash)
 
+      open = Naming.fetch(hash, "open") || {}
       pending = Naming.fetch(hash, "pendingRecovery")
       undelivered = Naming.fetch(hash, "undelivered")
       sending = Naming.fetch(hash, "sending")
+      extra = hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v unless JobState::KNOWN.include?(k.to_s) }
       new(
+        extra: extra.empty? ? nil : extra,
         job: Naming.fetch(hash, "job"),
-        open: (Naming.fetch(hash, "open") || {}).each_with_object({}) { |(k, v), out| out[k.to_sym] = v },
+        open: open.is_a?(Hash) ? open.to_h { |k, v| [k.to_sym, v] } : open,
         consecutive_failures: Naming.fetch(hash, "consecutiveFailures", 0),
         silenced_until: Naming.fetch(hash, "silencedUntil"),
         last_alert_at: Naming.fetch(hash, "lastAlertAt"),
-        pending_recovery: pending&.map(&:to_sym),
-        undelivered: undelivered&.map { |a| Alert.from_h(a) },
+        pending_recovery: pending.is_a?(Array) ? pending.map { |c| c.is_a?(String) ? c.to_sym : c } : pending,
+        undelivered: undelivered.is_a?(Array) ? undelivered.map { |a| a.is_a?(Hash) ? Alert.from_h(a) : a } : undelivered,
         version: Naming.fetch(hash, "version"),
         sending: sending.is_a?(Array) ? sending.map { |entry| JobState.sending_entry(entry) } : sending,
       )
@@ -331,21 +438,31 @@ module Cronwatch
     # only while it holds an entry.
     def to_h
       out = {
-        "job" => job, "open" => (open || {}).transform_keys(&:to_s), "consecutiveFailures" => consecutive_failures,
-        "silencedUntil" => silenced_until, "lastAlertAt" => last_alert_at,
+        "job" => job, "open" => open.is_a?(Hash) ? open.transform_keys(&:to_s) : (open || {}),
+        "consecutiveFailures" => consecutive_failures, "silencedUntil" => silenced_until, "lastAlertAt" => last_alert_at,
       }
-      out["pendingRecovery"] = pending_recovery.map(&:to_s) unless pending_recovery.nil?
-      out["undelivered"] = undelivered.map(&:to_h) unless undelivered.nil?
+      unless pending_recovery.nil?
+        out["pendingRecovery"] =
+          pending_recovery.is_a?(Array) ? pending_recovery.map { |c| c.is_a?(Symbol) ? c.to_s : c } : pending_recovery
+      end
+      unless undelivered.nil?
+        out["undelivered"] = undelivered.is_a?(Array) ? undelivered.map { |a| a.is_a?(Alert) ? a.to_h : a } : undelivered
+      end
       out["version"] = version unless version.nil?
       if sending.is_a?(Array) && !sending.empty?
         out["sending"] = sending.map do |entry|
           entry.is_a?(Hash) ? entry.transform_values { |v| v.is_a?(Alert) ? v.to_h : v } : entry
         end
       end
+      extra&.each { |key, value| out[key] = value unless out.key?(key) || JobState::KNOWN.include?(key) }
       out
     end
   end
 
+  # The fields this version reads from a stored state; the rest are kept in `extra`.
+  # @api private
+  JobState::KNOWN = %w[job open consecutiveFailures silencedUntil lastAlertAt pendingRecovery undelivered version sending].freeze
+
   JobStats = Struct.new(:runs, :ok_rate, :p50_ms, :p95_ms, keyword_init: true) do
     include Serializable
 

data/lib/cronwatch/version.rb

@@ -2,5 +2,5 @@
 
 module Cronwatch
   # Kept in step with @cronwatch/sdk.
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/cronwatch/walker.rb

@@ -6,6 +6,8 @@ module Cronwatch
     # the next match, a field at a time, spilling into the next month or year
     # as croner does (including its habit of stepping into a day the month
     # does not have and letting the date roll over). Month is 0 based.
+    #
+    # @api private
     class Walker
       DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31].freeze
       # [field, the field above it, offset from a field value to its pattern index]