cronwatch 0.8.0 → 0.10.0

data/lib/cronwatch/ticker.rb

@@ -39,6 +39,18 @@ module Cronwatch
         end
       end
 
+      # False once the thread has ended: stopped, or killed from outside.
+      def alive?
+        @thread.alive?
+      end
+
+      # Waits for the thread to end: once stopped, after the tick under way.
+      # Returns at once when called from the thread itself.
+      def join
+        @thread.join unless Thread.current.equal?(@thread)
+        nil
+      end
+
       private
 
       # False once stopped.

data/lib/cronwatch/types.rb

@@ -78,15 +78,25 @@ 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
+
     def initialize(fields = {})
       @fields = {}
       fields.each { |k, v| @fields[k.is_a?(Symbol) ? k : k.to_s] = v }
       @fields.freeze
+      @unreadable = fields.equal?(UNREADABLE)
       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)
       return hash if hash.is_a?(JobDefinition)
+      return new(UNREADABLE) unless hash.is_a?(Hash)
 
       new(hash.each_with_object({}) { |(k, v), out| out[BY_JSON[k.to_s] || k.to_s] = v })
     end
@@ -95,6 +105,11 @@ module Cronwatch
       @fields[field]
     end
 
+    # True for a stored definition that was not a JSON object. See from_h.
+    def unreadable?
+      @unreadable
+    end
+
     def key?(field)
       @fields.key?(field)
     end
@@ -152,7 +167,7 @@ module Cronwatch
         duration_ms: Naming.fetch(hash, "durationMs"),
         error: Naming.fetch(hash, "error"),
         output: Naming.fetch(hash, "output"),
-        metrics: (Naming.fetch(hash, "metrics") || {}).transform_keys(&:to_s),
+        metrics: Run.metrics_from(Naming.fetch(hash, "metrics")),
         trigger: Naming.fetch(hash, "trigger", "run"),
       )
     end
@@ -161,10 +176,16 @@ module Cronwatch
       {
         "id" => id, "job" => job, "status" => status.to_s, "startedAt" => started_at, "finishedAt" => finished_at,
         "durationMs" => duration_ms, "error" => error, "output" => output,
-        "metrics" => (metrics || {}).transform_keys(&:to_s), "trigger" => trigger,
+        "metrics" => Run.metrics_from(metrics), "trigger" => trigger,
       }
     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)
+      value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+    end
+
     def running? = status == :running
     def ok? = status == :ok
   end
@@ -255,8 +276,14 @@ module Cronwatch
   # `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.
+  #
+  # `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.
   JobState = Struct.new(:job, :open, :consecutive_failures, :silenced_until, :last_alert_at, :pending_recovery,
-                        :undelivered, :version, keyword_init: true) do
+                        :undelivered, :version, :sending, keyword_init: true) do
     include Serializable
 
     def self.from_h(hash)
@@ -264,6 +291,7 @@ module Cronwatch
 
       pending = Naming.fetch(hash, "pendingRecovery")
       undelivered = Naming.fetch(hash, "undelivered")
+      sending = Naming.fetch(hash, "sending")
       new(
         job: Naming.fetch(hash, "job"),
         open: (Naming.fetch(hash, "open") || {}).each_with_object({}) { |(k, v), out| out[k.to_sym] = v },
@@ -273,12 +301,34 @@ module Cronwatch
         pending_recovery: pending&.map(&:to_sym),
         undelivered: undelivered&.map { |a| Alert.from_h(a) },
         version: Naming.fetch(hash, "version"),
+        sending: sending.is_a?(Array) ? sending.map { |entry| JobState.sending_entry(entry) } : sending,
       )
     end
 
+    # One entry of `sending` as read: its alert parsed when it is a Hash
+    # that parses, anything else kept as it came. `until` and `alert` come
+    # first, in the order the SDK writes them, since a store on Postgres
+    # jsonb gives an object's keys back in an order of its own.
+    def self.sending_entry(entry)
+      return entry unless entry.is_a?(Hash)
+
+      read = entry.to_h do |key, value|
+        next [key.to_s, value] unless key.to_s == "alert" && value.is_a?(Hash)
+
+        parsed = begin
+          Alert.from_h(value)
+        rescue StandardError
+          value
+        end
+        ["alert", parsed]
+      end
+      %w[until alert].select { |key| read.key?(key) }.to_h { |key| [key, read[key]] }.merge(read)
+    end
+
     # pendingRecovery, undelivered and version are left out when unset, as in
-    # state written before they existed. The version comes last, where the
-    # SDK's spread of a normalized state puts it.
+    # state written before they existed. The version comes after them, where
+    # the SDK's spread of a normalized state puts it, and `sending` last, and
+    # only while it holds an entry.
     def to_h
       out = {
         "job" => job, "open" => (open || {}).transform_keys(&:to_s), "consecutiveFailures" => consecutive_failures,
@@ -287,6 +337,11 @@ module Cronwatch
       out["pendingRecovery"] = pending_recovery.map(&:to_s) unless pending_recovery.nil?
       out["undelivered"] = undelivered.map(&:to_h) unless undelivered.nil?
       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
       out
     end
   end

data/lib/cronwatch/version.rb

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

data/lib/cronwatch/web/app.rb

@@ -20,9 +20,11 @@ module Cronwatch
   #            or open the dashboard once with `?token=<token>` and a cookie is set.
   #            Defaults to ENV["CRONWATCH_TOKEN"]; an empty string counts as unset.
   #            With no token while Cronwatch::Environment is development or
-  #            test, the app makes a random one and prints a sign-in link to
-  #            stdout on its first request; with no token otherwise it answers
-  #            503. Pass `token: nil` to opt out and serve it open everywhere,
+  #            test (Environment.stated_development?: under Puma, Unicorn,
+  #            Thin or rackup, which set RACK_ENV=development by default,
+  #            RACK_ENV alone does not count), the app makes a random one and
+  #            prints a sign-in link to stdout on its first request; with no
+  #            token otherwise it answers 503. Pass `token: nil` to opt out and serve it open everywhere,
   #            for example behind your own auth. /api/check also accepts the
   #            client's cron_secret as a bearer, for a platform cron.
   # base_path: where the app is mounted, so links resolve. Defaults to the
@@ -79,7 +81,7 @@ module Cronwatch
       # (proxies, tunnels and a server bound to every interface all look
       # alike), so development gets a token too: made here, and shown only in
       # the server log.
-      @generated = @token.nil? && !@opted_out && Client.development?
+      @generated = @token.nil? && !@opted_out && Environment.stated_development?
       @token = Web.development_token if @generated
       @announced = false
       @announce_lock = Mutex.new

data/lib/cronwatch/web/html.rb

@@ -242,7 +242,7 @@ module Cronwatch
 
       # Object.entries: integer-like keys first, ascending, then the rest in insertion order.
       def entries(hash)
-        return [] if hash.nil?
+        return [] unless hash.is_a?(Hash)
 
         JS.object_keys(hash).map { |k| [k.to_s, hash[k]] }
       end
@@ -456,7 +456,8 @@ module Cronwatch
             truthy?(run.error) ? %(<details class="out error" open><summary>error</summary><pre>#{h(run.error)}</pre></details>) : "",
             truthy?(run.output) ? %(<details class="out"#{run.status.to_s == "ok" ? "" : " open"}><summary>output</summary><pre>#{h(run.output)}</pre></details>) : "",
           ].join
-          metrics = entries(run.metrics).map do |k, v|
+          # A foreign row may hold a metric that is no finite number (null, text); it is left out.
+          metrics = entries(run.metrics).select { |_, v| v.is_a?(Numeric) && v.real? && JS.finite?(v) }.map do |k, v|
             %(<span><span class="k">#{h(k)}</span> #{h(JS.integer?(v) ? v : to_fixed(v, 4))}</span>)
           end.join
           took = run.duration_ms.nil? ? %(<span class="muted">running</span>) : h(Duration.format(run.duration_ms))

data/lib/generators/cronwatch/install/install_generator.rb

@@ -11,8 +11,11 @@ module Cronwatch
     # Writes a migration for the three tables the ActiveRecord store uses
     # (created with the SDK's own DDL, so a Node process can share them) and
     # config/initializers/cronwatch.rb, then prints how to schedule
-    # Cronwatch::CheckJob and mount the dashboard. The templates live in this
-    # file so the gem ships nothing but Ruby.
+    # Cronwatch::CheckJob and mount the dashboard. With --database, the
+    # migration goes to that database and app/models/cronwatch_record.rb, an
+    # abstract class connected to it, is the store's connection_class, so the
+    # store reads the tables where the migration made them. The templates
+    # live in this file so the gem ships nothing but Ruby.
     class InstallGenerator < ::Rails::Generators::Base
       include ::ActiveRecord::Generators::Migration
 
@@ -21,7 +24,10 @@ module Cronwatch
       class_option :prefix, type: :string, default: Cronwatch::Stores::ActiveRecord::DEFAULT_PREFIX,
                             desc: "Table name prefix: lowercase letters, digits and underscores"
       class_option :database, type: :string, aliases: %i[--db],
-                              desc: "The database for the migration, in an app with several"
+                              desc: "The database for the tables, in an app with several (from config/database.yml)"
+
+      # The abstract class --database writes, which the store connects through.
+      RECORD_CLASS = "CronwatchRecord"
 
       def check_prefix
         Cronwatch::Stores::ActiveRecord.table_prefix(options[:prefix])
@@ -41,6 +47,12 @@ module Cronwatch
         create_file File.join(dir, "#{number}_#{migration_name}.rb"), migration
       end
 
+      def create_connection_class
+        return unless database_name
+
+        create_file "app/models/cronwatch_record.rb", connection_class
+      end
+
       def create_initializer
         create_file "config/initializers/cronwatch.rb", initializer
       end
@@ -60,9 +72,33 @@ module Cronwatch
         "create_cronwatch_#{prefix.squeeze("_").delete_prefix("_").delete_suffix("_")}_tables"
       end
 
+      # The --database name, or nil.
+      def database_name
+        name = options[:database].to_s
+        name.empty? ? nil : name
+      end
+
       def store_args
         prefix = options[:prefix]
-        prefix == Cronwatch::Stores::ActiveRecord::DEFAULT_PREFIX ? "" : "(prefix: #{prefix.inspect})"
+        args = []
+        args << "prefix: #{prefix.inspect}" unless prefix == Cronwatch::Stores::ActiveRecord::DEFAULT_PREFIX
+        # Named, not referenced, so the initializer does not load an app class at boot.
+        args << "connection_class: #{RECORD_CLASS.inspect}" if database_name
+        args.empty? ? "" : "(#{args.join(", ")})"
+      end
+
+      def connection_class
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # The #{database_name} database, where CronWatch keeps its tables. The store in
+          # config/initializers/cronwatch.rb connects through this class.
+          class #{RECORD_CLASS} < ActiveRecord::Base
+            self.abstract_class = true
+
+            connects_to database: { writing: :#{database_name} }
+          end
+        RUBY
       end
 
       def migration
@@ -102,7 +138,7 @@ module Cronwatch
           #
           # and run Cronwatch::CheckJob every few minutes to catch the runs that never happen.
           Cronwatch.configure do |c|
-            # Jobs, runs and alert state, in this app's database.
+            # Jobs, runs and alert state, in #{database_name ? "the #{database_name} database (see app/models/cronwatch_record.rb)" : "this app's database"}.
             c.store = Cronwatch::Stores::ActiveRecord.new#{store_args}
 
             # Where alerts go. With none set, they are written to standard error.
@@ -127,14 +163,22 @@ module Cronwatch
         RUBY
       end
 
+      # What the next steps say about --database after the migrate line, or "".
+      def database_step
+        return "" unless database_name
+
+        "\n\n   The store connects through #{RECORD_CLASS} (app/models/cronwatch_record.rb),\n   " \
+          "which connects_to the #{database_name} database named in config/database.yml."
+      end
+
       def next_steps
         <<~TEXT
 
           CronWatch is installed. Next:
 
-          1. Create the tables:
+          1. Create the tables#{database_name ? " in the #{database_name} database" : ""}:
 
-               bin/rails db:migrate
+               bin/rails db:migrate#{database_step}
 
           2. Monitor a job:
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cronwatch
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Jon C. Phillips