cronwatch 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6df945edfb266ca737de6343276860554a4d3d740331091e1167d00fe93888a4
-  data.tar.gz: ec33c3140fb5f453de2cd0263b74a894b590408394f9f1aade76f1be2485e190
+  metadata.gz: 9f5d4d303ae53fd20968b2f416e805a3f840b07b152004878147c3d3c3e4e899
+  data.tar.gz: 184ac01a139983fdabc2344586a4bc6c6669b987864a8c84d7f7b8f8bd90909d
 SHA512:
-  metadata.gz: ba15e440f49e390715b9668a24c0ee2b1c0cf35dac907a461555d18181fc95572b0ba3fee50b00237893733ca5b864b9f35b6a4e30b0f0bee64e6eefa1f3c5b0
-  data.tar.gz: 71e579e3ebba4a279cfef5de79d611157dcc2fc8ad176fac77cc737e7e0750c9ecd3cfefed383b2ac51f2f7aef5a5a24a24a472b6b739e90c1bd007a5814f0f5
+  metadata.gz: 333767b7bcffda2b75c1349644c7fa870c371c9a5c1ee0491083effcdbb1030c54dfc561a36a883b8588411caa59b19ca4c36c06638c61c5652917c29f1252fa
+  data.tar.gz: 0ecbafab015195219f3dfb53e03dd202766342fc11195b7d97cdac4610821940a2e8d777898834aa8b015236b5b5a1a11eb0f1ecd424c42f52a4b84eddfb14b1

data/README.md

@@ -47,10 +47,10 @@ NIGHTLY.run do |job|
   job.metric(:cost, 1.2)             # watched against budgets and baselines
 end
 
-CW.start # checks for missed and stuck runs every minute, in a background thread
+CW.start_checking # checks for missed and stuck runs every minute, in a background thread
 ```
 
-`run` returns what the block returns and raises what it raises, after the run is recorded. A script run from crontab exits when it is done, so instead of `start`, add a second crontab line that declares the jobs and calls `CW.check` every five minutes.
+`run` returns what the block returns and raises what it raises, after the run is recorded. A script run from crontab exits when it is done, so instead of `start_checking`, add a second crontab line that declares the jobs and calls `CW.check` every five minutes.
 
 A run that starts in one call and ends in another (a job that hands work to a queue, a webhook that reports back later) is one run too:
 
@@ -64,7 +64,7 @@ run.finish                          # or run.fail(error); finish("text") and fin
 
 Neither raises for the store: failures go to `on_error`, and a finish of a run already finished, not found, or of another job records nothing and returns nil. A run is judged once, however many processes finish it at once, and a store that fails during `finish` leaves the handle active to finish again. A run never finished is marked stuck after the job's `timeout`.
 
-Client options: `store`, `alerts`, `triage`, `cron_secret`, `retention` (default `"30d"`), `defaults`, `sources` (where runs the process does not wrap come from, such as pg_cron), `redact` (default: blank values that look like secrets; `false` keeps output as logged, or pass a callable), `deliver` (`:now` by default; `:check` queues alerts for another process's check to send, for a worker that cannot reach Slack), `on_error` and `now`. Methods: `job`, `run`, `resume_run`, `record_run`, `check`, `start`/`stop`, `silence(name, for: "2h")`/`unsilence`, `forget`, `jobs`, `jobs_with_runs`, `job_summary`, `runs`, `get_run`, `defined_jobs`, `close`. [cronwatch.dev/docs/ruby](https://cronwatch.dev/docs/ruby/#api) has each one.
+Client options: `store`, `alerts`, `triage`, `cron_secret`, `retention` (default `"30d"`), `defaults`, `sources` (where runs the process does not wrap come from, such as pg_cron), `redact` (default: blank values that look like secrets; `false` keeps output as logged, or pass a callable), `deliver` (`:now` by default; `:check` queues alerts for another process's check to send, for a worker that cannot reach Slack), `on_error` and `now`. Methods: `job`, `run`, `resume_run`, `record_run`, `check`, `start_checking`/`stop`, `silence(name, for: "2h")`/`unsilence`, `forget`, `jobs`, `jobs_with_runs`, `job_summary`, `runs`, `get_run`, `defined_jobs`, `close`. [cronwatch.dev/docs/ruby](https://cronwatch.dev/docs/ruby/#api) has each one.
 
 ## Rails
 
@@ -74,7 +74,7 @@ bin/rails generate cronwatch:install    # a migration and config/initializers/cr
 bin/rails db:migrate
 ```
 
-The generator takes `--prefix` (table prefix, default `cronwatch_`) and `--database` (the database whose migrations directory gets the migration). The initializer it writes sets the ActiveRecord store, which Rails needs so web, worker and check processes see the same runs:
+The generator takes `--prefix` (table prefix, default `cronwatch_`) and `--database` (the database, from `config/database.yml`, whose migrations directory gets the migration; it also writes `app/models/cronwatch_record.rb`, an abstract class that `connects_to` that database, and names it as the store's `connection_class`, so the store reads the tables where the migration made them). The initializer it writes sets the ActiveRecord store, which Rails needs so web, worker and check processes see the same runs:
 
 ```ruby
 # config/initializers/cronwatch.rb
@@ -100,7 +100,7 @@ class NightlyReportJob < ApplicationJob
 end
 ```
 
-Every `perform` is recorded as a run with the trigger `"active_job"`. The name defaults to the class name without `Job`, dasherized, with `::` as `:` (`Reports::NightlyJob` is `reports:nightly`); pass `name:` to choose another. Jobs are declared once the app has booted, so a check knows a job that has never run. A job that raises still raises after the run is recorded, so ActiveJob retries and your error reporter see it as before.
+Every `perform` is recorded as a run with the trigger `"active-job"` (runs recorded before 1.0 carry `"active_job"`). The name defaults to the class name without `Job`, dasherized, with `::` as `:` (`Reports::NightlyJob` is `reports:nightly`); pass `name:` to choose another. Jobs are declared once the app has booted, so a check knows a job that has never run. A job that raises still raises after the run is recorded, so ActiveJob retries and your error reporter see it as before.
 
 ### Sidekiq
 
@@ -124,7 +124,7 @@ The same `cronwatch` as for ActiveJob, for classes that include `Sidekiq::Job` (
 cronwatch schedule: :from_scheduler, grace: "15m"   # ActiveJob or Sidekiq
 ```
 
-reads the class's one entry in Solid Queue's `config/recurring.yml` (the section for `Rails.env`) or sidekiq-cron's `config/schedule.yml`, so the schedule is written once. Fugit phrases such as `every day at 3am` or `every hour at minute 12` become the cron expression Fugit makes of them (`0 3 * * *`, `12 * * * *`), in the zone the scheduler reads them in. Each conversion is checked against Fugit's own next run times; anything CronWatch would not expect at exactly those times is refused at boot rather than approximated: every other week (`%`), days counted back from the month's end other than the last, random times (`~`), offsets instead of IANA zones, and a time that daylight saving skips (Fugit skips that run; CronWatch would report it missed). A class with no entry, or with two, also stops the boot.
+reads the class's one entry in Solid Queue's `config/recurring.yml` (the section for `Rails.env`) or sidekiq-cron's `config/schedule.yml`, so the schedule is written once. Fugit phrases such as `every day at 3am` or `every hour at minute 12` become the cron expression Fugit makes of them (`0 3 * * *`, `12 * * * *`), in the zone the scheduler reads them in. Each conversion is checked against Fugit's own next run times; anything CronWatch would not expect at exactly those times is refused at boot rather than approximated: every other week (`%`), days counted back from the month's end other than the last, random times (`~`), offsets instead of IANA zones, and a time that daylight saving skips (Fugit skips that run; CronWatch would report it missed). A class with no entry, or with two, also stops the boot; one scheduled only in another environment's section (Rails 8's `recurring.yml` has only `production:`) is declared without a schedule, and a process started with `SOLID_QUEUE_SKIP_RECURRING` still reads the entry.
 
 `Cronwatch.declare_from_scheduler!(grace: "10m")` in the initializer watches every enabled entry once the app has booted: classes that call `cronwatch` declare themselves, other classes are named as `cronwatch` would name them and their runs are recorded, and Solid Queue `command:` tasks are named after their key. `except:` leaves keys out. `Cronwatch::Scheduler.sources` sets where to read, when the defaults (Solid Queue's file when Solid Queue is loaded, sidekiq-cron's when sidekiq-cron is) are not right.
 
@@ -164,11 +164,11 @@ Or from a crontab: `bin/rails cronwatch:check`.
 ```ruby
 # config/routes.rb
 Rails.application.routes.draw do
-  mount Cronwatch::Web.new(Cronwatch.client) => "/cronwatch"
+  mount Cronwatch.client.routes => "/cronwatch"
 end
 ```
 
-Set `CRONWATCH_TOKEN` to a long random string and open `/cronwatch?token=<it>` once; the browser keeps a cookie. Without a token, while the environment (`Rails.env`, else `RAILS_ENV` or `RACK_ENV`) is `development` or `test`, it makes a token of its own and prints a sign-in link to standard output on its first request (open it once; unless `origin:` is set or the request's host is loopback, the link leaves the host out, since a client chooses it); anywhere else it answers 503. To rely on the app's own sign in, mount it behind that (Devise's `authenticate` block, or a routing constraint) and pass `token: nil`. The URLs, JSON shapes, headers and CSRF rules are the SDK's, so the MCP server reads it unchanged. The request's origin, which the CSRF check compares against, is what Rack reports and so already follows `X-Forwarded-Host` and `X-Forwarded-Proto`; pass `origin: "https://app.example.com"` to pin it instead. `GET /cronwatch/api/check` with a bearer (the token or `CRON_SECRET`) runs the check, for an outside cron.
+Set `CRONWATCH_TOKEN` to a long random string and open `/cronwatch?token=<it>` once; the browser keeps a cookie. Without a token, while the environment (the first of `CRONWATCH_ENV`, `APP_ENV`, then `Rails.env` (when Rails is loaded), `RAILS_ENV` or `RACK_ENV` that holds more than spaces, trimmed and lowercased) is `development`, `dev`, `local`, `test` or `testing`, it makes a token of its own and prints a sign-in link to standard output on its first request (open it once; unless `origin:` is set or the request's host is loopback, the link leaves the host out, since a client chooses it); anywhere else it answers 503. Puma, Unicorn, Thin and rackup set `RACK_ENV` to `development` when nothing names an environment, production included, so under one of them `RACK_ENV=development` alone does not count: `CRONWATCH_ENV`, `APP_ENV`, `Rails.env` or `RAILS_ENV` must say development (or `RACK_ENV` say `test`, `dev` or `local`). To rely on the app's own sign in, mount it behind that (Devise's `authenticate` block, or a routing constraint) and pass `token: nil`. The URLs, JSON shapes, headers and CSRF rules are the SDK's, so the MCP server reads it unchanged. The request's origin, which the CSRF check compares against, is what Rack reports and so already follows `X-Forwarded-Host` and `X-Forwarded-Proto`; pass `origin: "https://app.example.com"` to pin it instead. `GET /cronwatch/api/check` with a bearer (the token or `CRON_SECRET`) runs the check, for an outside cron.
 
 There is no `handler()` as in the TypeScript SDK: for a job triggered over HTTP, wrap the controller action's body in `CW.job(...).run` (declared once, at boot) and check the bearer in the controller.
 
@@ -176,10 +176,19 @@ In any other Rack app:
 
 ```ruby
 # config.ru
-require "cronwatch/web"
-map("/cronwatch") { run Cronwatch::Web.new(CW) }
+map("/cronwatch") { run CW.routes }
 ```
 
+`client.routes(**options)` (`token:`, `base_path:`, `origin:`) is the one way to build the dashboard, as `routes()` is in every language.
+
+### Public and internal
+
+Public means what this README and the docs at cronwatch.dev name. Everything else is internal and may change in any release: anything marked `@api private` in the source (`Evaluate`, `Schedule`, `Format`, `JS`, `HTTP` and the dashboard's helpers among them), and the constants made private with `private_constant`.
+
+### Deprecated
+
+These still work through every 1.x release and go in 2.0, each with a warning in Ruby's deprecation category (shown under `ruby -w` or `-W:deprecated`): `Cronwatch::Web.new(client, **options)` (use `client.routes(**options)`), `client.start(every)` (use `client.start_checking(every)`), `client.run(id)` without a block (use `client.get_run(id)`) and `client.silence(name, "2h")` (use `client.silence(name, for: "2h")`). The ActiveJob trigger is `active-job` from 1.0; runs recorded before keep `active_job`.
+
 ## Stores
 
 - `Cronwatch::Stores::Memory.new`: the default. Nothing survives a restart.
@@ -204,7 +213,7 @@ Cronwatch::Alerts::Custom.new("pagerduty") do |alert|
 end
 ```
 
-Every alert goes to every channel. A channel that raises, or takes longer than 15 seconds, goes to `on_error` and never blocks the others. Each condition alerts once when it opens and once more when a clean run closes it; there are no repeat alerts. The webhook signs its body with `X-CronWatch-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw body.
+Every alert goes to every channel. A channel that raises, or takes longer than 15 seconds, goes to `on_error` and never blocks the others. Each condition alerts once when it opens and once more when a clean run closes it; there are no repeat alerts. The webhook's body is the alert's JSON with `"schema": 1` first (its [JSON Schema](https://cronwatch.dev/schemas/webhook/1.json)); parse the fields, not `title` and `message`, whose wording may change. It signs the body with `X-CronWatch-Signature: sha256=<hex>`, the HMAC-SHA256 of the raw body, which a receiver checks with `Rack::Utils.secure_compare("sha256=#{Cronwatch::Alerts::Webhook.signature(secret, raw_body)}", header)`.
 
 ## Triage
 

data/lib/cronwatch/alerts/datadog.rb

@@ -11,6 +11,7 @@ module Cronwatch
       ALERT_TYPE = {
         missed: "error", failed: "error", stuck: "error", slow: "warning", over_budget: "warning", recovered: "success",
       }.freeze
+      private_constant :ALERT_TYPE
 
       attr_reader :name
 

data/lib/cronwatch/alerts/discord.rb

@@ -9,6 +9,11 @@ module Cronwatch
         missed: 0xb7791f, failed: 0xc62828, stuck: 0xc62828, slow: 0xb7791f, over_budget: 0xb7791f, recovered: 0x1f8a4c,
       }.freeze
 
+      # The longest embed description Discord takes. The title (under 256)
+      # and it stay well inside the embed's 6000.
+      DESCRIPTION_MAX = 4096
+      private_constant :COLOR, :DESCRIPTION_MAX
+
       attr_reader :name
 
       def initialize(webhook_url:, link: nil, http: HTTP.default)
@@ -24,8 +29,7 @@ module Cronwatch
         url = @link&.call(alert)
         embed = { "title" => alert.title }
         embed["url"] = url if url && !url.empty?
-        triage = alert.triage && !alert.triage.empty? ? "\n**Triage:** #{Discord.escape_markdown(JS.head16(alert.triage, 1000))}" : ""
-        embed["description"] = "```\n#{Discord.code_block_safe(JS.head16(alert.message, 3800))}\n```#{triage}"
+        embed["description"] = Discord.embed_description(alert)
         embed["color"] = COLOR[alert.type]
         embed["timestamp"] = JS.iso(alert.at)
         payload = {
@@ -38,6 +42,34 @@ module Cronwatch
         raise "Discord webhook answered #{response.status}: #{JS.head16(response.body.to_s, 200)}" unless response.ok?
       end
 
+      # The message in a code block, then the triage. Each part has its own
+      # cap, and escaping can grow both, so the whole is held to
+      # DESCRIPTION_MAX (in UTF-16 units) by cutting the message's block,
+      # never the triage: Discord refuses a longer one on every retry.
+      #
+      # Where a cap cuts a surrogate pair the high half is kept, as the SDK's
+      # slice keeps it, and written as JSON.stringify writes it (see
+      # JS.lone_surrogate). The cut of the block to the room left leaves out
+      # a pair or a lone half, as the SDK's cut does.
+      def self.embed_description(alert)
+        triage = ""
+        triage_units = 0
+        if alert.triage && !alert.triage.empty?
+          head, lone = JS.slice16(alert.triage, 1000)
+          triage = "\n**Triage:** #{escape_markdown(head)}"
+          triage_units = JS.length16(triage)
+          if lone
+            triage += JS.lone_surrogate(lone)
+            triage_units += 1
+          end
+        end
+        room = DESCRIPTION_MAX - "```\n".length - "\n```".length - triage_units
+        head, lone = JS.slice16(alert.message, 3800)
+        block = code_block_safe(head)
+        block = lone && JS.length16(block) + 1 <= room ? block + JS.lone_surrogate(lone) : JS.head16(block, room)
+        "```\n" + block + "\n```" + triage
+      end
+
       # Breaks up ``` so text inside a code block cannot close it.
       def self.code_block_safe(text)
         text.gsub("```", "`\u200b`\u200b`")

data/lib/cronwatch/alerts/email.rb

@@ -11,6 +11,8 @@ module Cronwatch
     #   to:             one address or several
     #   subject_prefix: put in front of the title in the subject, "[prod]" say
     #   link:           ->(alert) { "https://app.example.com/cronwatch/jobs/#{alert.job}" }
+    #
+    # @api private
     module Email
       Message = Struct.new(:from, :to, :subject, :text, :html, keyword_init: true)
 

data/lib/cronwatch/alerts/honeybadger.rb

@@ -11,6 +11,7 @@ module Cronwatch
         missed: "CronWatch::Missed", failed: "CronWatch::Failed", stuck: "CronWatch::Stuck", slow: "CronWatch::Slow",
         over_budget: "CronWatch::OverBudget", recovered: "CronWatch::Recovered",
       }.freeze
+      private_constant :CLASS
 
       attr_reader :name
 

data/lib/cronwatch/alerts/postmark.rb

@@ -7,6 +7,7 @@ module Cronwatch
     # defaults to "outbound", the transactional stream.
     class Postmark
       ENDPOINT = "https://api.postmarkapp.com/email"
+      private_constant :ENDPOINT
 
       attr_reader :name
 

data/lib/cronwatch/alerts/provider.rb

@@ -10,6 +10,8 @@ module Cronwatch
     # SDK's alerts/shared.ts: the POST that names the provider and the URL's
     # origin on failure with every secret cut out, the stable alert id, and
     # the run summary trackers attach. Standard library only.
+    #
+    # @api private
     module Provider
       module_function
 

data/lib/cronwatch/alerts/resend.rb

@@ -9,6 +9,7 @@ module Cronwatch
     #                                 from: "CronWatch <alerts@example.com>", to: "ops@example.com")
     class Resend
       ENDPOINT = "https://api.resend.com/emails"
+      private_constant :ENDPOINT
 
       attr_reader :name
 

data/lib/cronwatch/alerts/rollbar.rb

@@ -8,6 +8,7 @@ module Cronwatch
     # `recovered: false`.
     class Rollbar
       ENDPOINT = "https://api.rollbar.com/api/1/item/"
+      private_constant :ENDPOINT
 
       attr_reader :name
 

data/lib/cronwatch/alerts/sentry.rb

@@ -13,6 +13,7 @@ module Cronwatch
     # Envelopes: https://develop.sentry.dev/sdk/data-model/envelopes/
     # Event payload: https://develop.sentry.dev/sdk/data-model/event-payloads/
     class Sentry
+      # @api private
       Dsn = Struct.new(:endpoint, :public_key, keyword_init: true)
 
       attr_reader :name

data/lib/cronwatch/alerts/sigv4.rb

@@ -9,6 +9,8 @@ module Cronwatch
     # alerts/sigv4.ts. Spec:
     # https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
     # Checked against the AWS SigV4 test suite (test/provider_channels_test.rb).
+    #
+    # @api private
     module SigV4
       SPACES = Regexp.new("[#{JS::WHITESPACE}]+")
 

data/lib/cronwatch/alerts/slack.rb

@@ -11,6 +11,7 @@ module Cronwatch
         missed: ":hourglass_flowing_sand:", failed: ":x:", stuck: ":no_entry:", slow: ":turtle:",
         over_budget: ":moneybag:", recovered: ":white_check_mark:",
       }.freeze
+      private_constant :EMOJI
 
       attr_reader :name
 

data/lib/cronwatch/alerts/twilio.rb

@@ -31,6 +31,7 @@ module Cronwatch
       MAX_SEGMENTS = 10
       # Twilio refuses a Body longer than this.
       MAX_BODY = 1600
+      private_constant :GSM, :GSM_EXTENDED, :MAX_BODY, :MAX_SEGMENTS
 
       attr_reader :name
 

data/lib/cronwatch/alerts/webhook.rb

@@ -4,10 +4,11 @@ require "openssl"
 
 module Cronwatch
   module Alerts
-    # POSTs the alert as JSON to any URL. The body is the alert's JSON:
-    # { type, run, details, job, definition, title, message, at, triage }.
+    # POSTs the alert as JSON to any URL. The body is `"schema": 1` and then
+    # the alert's JSON: { schema, type, run, details, job, definition, title,
+    # message, at, triage }, described by https://cronwatch.dev/schemas/webhook/1.json.
     # With a secret, each request carries `X-CronWatch-Signature: sha256=<hex>`,
-    # the HMAC-SHA256 of the raw body, so the receiver can verify it. Header
+    # the HMAC-SHA256 of the raw body (Webhook.signature), so the receiver can verify it. Header
     # values are trimmed. A redirect is an error, not followed (the headers
     # and the signature would go with it): point the url at where the
     # receiver really is.
@@ -24,13 +25,25 @@ module Cronwatch
         @http = http
       end
 
+      # The version of the body's shape, its first key. It goes up only in a
+      # major release; fields are added within one.
+      SCHEMA = 1
+      private_constant :SCHEMA
+
+      # The HMAC-SHA256 of `body` with `secret`, as lowercase hex, without the
+      # `sha256=` the header puts before it. A receiver compares it with the
+      # header in constant time (Rack::Utils.secure_compare).
+      def self.signature(secret, body)
+        OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, body.to_s)
+      end
+
       def call(alert)
-        body = JS.json(alert.to_h)
+        body = JS.json({ "schema" => SCHEMA }.merge(alert.to_h))
         headers = { "content-type" => "application/json", "user-agent" => "cronwatch" }
         # A pasted Authorization value often carries a stray space or newline, which a header would refuse.
         @headers.each { |name, value| headers[name.to_s] = value.is_a?(String) ? JS.trim(value) : value }
         if @secret && !@secret.empty?
-          headers["x-cronwatch-signature"] = "sha256=#{OpenSSL::HMAC.hexdigest("SHA256", @secret, body)}"
+          headers["x-cronwatch-signature"] = "sha256=#{Webhook.signature(@secret, body)}"
         end
         response = @http.post(@url, body, headers)
         # Only the origin: a webhook URL's path or query often is the credential.