cronwatch 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5e3c0550792cfd9ba9d34f828cf099051f30b5b52cfd780373efe581e665e2
-  data.tar.gz: ba21834f9a3d3b8b641e26fa23990f34f12f2190b7ad5bbf7d9355b0bdc0685f
+  metadata.gz: 9f5d4d303ae53fd20968b2f416e805a3f840b07b152004878147c3d3c3e4e899
+  data.tar.gz: 184ac01a139983fdabc2344586a4bc6c6669b987864a8c84d7f7b8f8bd90909d
 SHA512:
-  metadata.gz: bf853e3e1f3ac6db1f74178033a1bd92a0863a182285bfe944e872a8463f9a261319b8c5c27d5c2a2acd31d54a4f328a22b6a80d1d722170414aef18785e2dc4
-  data.tar.gz: f23c2439e7b9d0fb9f9f818cc49313c15d0e35e42dcffb74aaf246a327d4318b8951293060e269cf1e01224f5986ac25090ce9ef92c4e688f0d4e7feb8614976
+  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
 
@@ -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
 
@@ -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. Puma, Unicorn, Thin and rackup set `RACK_ENV` to `development` when nothing names an environment, production included, so under one of them `RACK_ENV` alone does not count: `Rails.env`, `RAILS_ENV` or `APP_ENV` must say `development` or `test` (or `RACK_ENV` say `test`). 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

@@ -12,6 +12,7 @@ module Cronwatch
       # 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
 
@@ -45,10 +46,28 @@ module Cronwatch
       # 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 = alert.triage && !alert.triage.empty? ? "\n**Triage:** #{escape_markdown(JS.head16(alert.triage, 1000))}" : ""
-        room = DESCRIPTION_MAX - "```\n".length - "\n```".length - JS.length16(triage)
-        "```\n#{JS.head16(code_block_safe(JS.head16(alert.message, 3800)), room)}\n```#{triage}"
+        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.

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.

data/lib/cronwatch/client.rb

@@ -42,8 +42,16 @@ module Cronwatch
     SILENCE_OPTIONS = %i[for].freeze
     # Run ids that start with this belong to the pg_cron source (Sources::PgCron).
     RESERVED_RUN_ID_PREFIX = "pgcron:"
+    # The longest run id, in UTF-16 code units (JavaScript's string length):
+    # what start, resume and record_run take, and every store holds.
+    MAX_RUN_ID = 200
+    private_constant :CHANNEL_TIMEOUT_MS, :DEFAULT_OPTIONS, :FORK_LOCK, :HISTORY_MAX, :HISTORY_PAGE, :MAX_RUN_ID,
+                     :PRUNE_INTERVAL_MS, :RESERVED_RUN_ID_PREFIX, :RETRY_BUDGET_MS, :SILENCE_OPTIONS, :STATE_ATTEMPTS,
+                     :TRIAGE_TIMEOUT_MS
 
     # What execute returns: the recorded run, and the block's own outcome.
+    #
+    # @api private
     ExecuteResult = Struct.new(:run, :result, :error, :threw, keyword_init: true)
     # What a channel's call receives with each alert (the SDK's ChannelContext).
     # on_error(error) reports a problem that did not stop the alert going
@@ -73,7 +81,9 @@ module Cronwatch
     # alerts:      where alerts go: objects with #call(alert) and #name. Defaults to the console.
     # triage:      a callable taking a TriageContext and returning a short diagnosis, added to every alert but recoveries.
     # cron_secret: a second bearer Cronwatch::Web accepts for /api/check, for an outside cron. Defaults to
-    #              ENV["CRON_SECRET"]; an empty string counts as unset. Pass nil for none.
+    #              ENV["CRON_SECRET"]; an empty string or one of only whitespace, given here or in the
+    #              variable, counts as unset. Pass nil for none. Anything but a String or nil (false, a
+    #              number, a Symbol) raises TypeError.
     # retention:   how long finished runs are kept. Default "30d".
     # defaults:    grace, timeout, timezone and failures_before_alert applied to every job unless it sets its own.
     # redact:      applied to every run's output and error before it is stored, shown or sent to an alert
@@ -98,8 +108,11 @@ module Cronwatch
         raise ArgumentError, "a source must respond to sync(host)" unless source.respond_to?(:sync)
       end
       @triage = triage
-      secret = cron_secret.equal?(UNSET) ? ENV.fetch("CRON_SECRET", nil) : cron_secret
-      @cron_secret = secret.nil? || secret.to_s.empty? ? nil : secret.to_s
+      # A blank secret, given or read, counts as unset; one given that is not a String raises.
+      @cron_secret =
+        if cron_secret.equal?(UNSET) then Environment.secret("CRON_SECRET")
+        else Environment.secret_option(cron_secret, "cron_secret")
+        end
       @retention_ms = Duration.parse(retention || "30d", "retention")
       @defaults = (defaults || {}).transform_keys(&:to_sym)
       unknown = @defaults.keys - DEFAULT_OPTIONS
@@ -128,7 +141,7 @@ module Cronwatch
       @registry = Mutex.new
       @ready = false
       @last_prune_at = 0
-      # Seconds before start()'s first check, and how long a channel or triage may take. Tests shorten them.
+      # Seconds before start_checking's first check, and how long a channel or triage may take. Tests shorten them.
       @first_tick_s = 1.0
       @channel_timeout_ms = CHANNEL_TIMEOUT_MS
       @triage_timeout_ms = TRIAGE_TIMEOUT_MS
@@ -158,13 +171,16 @@ module Cronwatch
       JobHandle.new(self, definition)
     end
 
-    # With a block: run a job by name without keeping a handle, declaring it
-    # on first use (or again, when options are given). Without a block: the
-    # run with this id, as get_run.
+    # Run a job by name without keeping a handle, declaring it on first use
+    # (or again, when options are given).
+    #
+    # Without a block it reads the run with this id, as get_run does: that
+    # form is deprecated (use get_run), still works through 1.x and goes in 2.0.
     def run(name_or_id, **options, &block)
       unless block
         raise ArgumentError, "run(#{name_or_id.inspect}, ...) needs a block; without one, run(id) reads a run" if options.any?
 
+        Deprecation.warn("run(id) without a block", "get_run(id)")
         return get_run(name_or_id)
       end
 
@@ -327,7 +343,12 @@ module Cronwatch
       input = run.is_a?(Run) ? run : Run.from_h(run.is_a?(Hash) ? run.to_h { |k, v| [Naming.camel(k), v] } : run)
       declared = @registry.synchronize { @definitions[input.job] }
       raise ArgumentError, "record_run: job \"#{input.job}\" is not declared; call job first" unless declared
-      if input.id.to_s.include?("\0")
+      # The longest id start takes, and every store holds.
+      unless input.id.is_a?(String) && !input.id.empty? && JS.length16(input.id) <= MAX_RUN_ID
+        got = input.id.is_a?(String) ? "#{JS.length16(input.id)} characters" : input.id.class.to_s
+        raise ArgumentError, "record_run: run ids must be 1 to #{MAX_RUN_ID} characters (got #{got}; job \"#{input.job}\")"
+      end
+      if input.id.include?("\0")
         raise ArgumentError, "record_run: run ids cannot contain a NUL character (job \"#{input.job}\")"
       end
       # Refused as JobContext#metric refuses them: a store keeps NaN and Infinity as null.
@@ -388,7 +409,7 @@ module Cronwatch
     end
 
     # Look for missed and stuck runs across every job, send alerts, retry
-    # alerts no channel accepted, and prune old runs. Call it from start(), a
+    # alerts no channel accepted, and prune old runs. Call it from start_checking, a
     # scheduled job (Cronwatch::CheckJob), or by hand. Concurrent calls share
     # one check.
     def check
@@ -456,12 +477,15 @@ module Cronwatch
 
     # Stop alerts for a job for a while. State keeps updating underneath. The
     # end is a whole millisecond, held at 2**53 - 1 (see Evaluate.silence_end).
-    #   silence("nightly-report", for: "2h")   # or silence("nightly-report", "2h")
+    #   silence("nightly-report", for: "2h")
+    # The duration as a second argument, silence("nightly-report", "2h"), is
+    # deprecated: it still works through 1.x and goes in 2.0.
     def silence(name, duration = nil, **options)
       unknown = options.keys - SILENCE_OPTIONS
       raise ArgumentError, "silence takes for:, not #{unknown.map(&:inspect).join(", ")}" if unknown.any?
       raise ArgumentError, "silence takes a duration or for:, not both" if !duration.nil? && options.key?(:for)
 
+      Deprecation.warn("silence(name, duration)", "silence(name, for: duration)") unless duration.nil?
       duration = options[:for] if duration.nil?
       ms = Duration.parse(duration, "silence duration")
       patch_state(name) { |state| state.silenced_until = Evaluate.silence_end(now, ms) }
@@ -489,8 +513,9 @@ module Cronwatch
     # processes. Default every minute; the first check comes after a second.
     # Calling it again while it runs does nothing, and a different interval
     # is reported to on_error and ignored: stop first to change it. A forked
-    # child (Puma, Unicorn, Sidekiq) has no thread, so call start there.
-    def start(every = "1m")
+    # child (Puma, Unicorn, Sidekiq) has no thread, so call start_checking
+    # there. (A job's start opens a run; this starts the checks.)
+    def start_checking(every = "1m")
       after_fork_check
       ms = [5_000, Duration.parse(every, "check interval")].max
       @ticker_lock.synchronize do
@@ -498,8 +523,8 @@ module Cronwatch
         @ticker = nil if @ticker && !@ticker.alive?
         if @ticker
           unless @ticker_ms == ms
-            report(ArgumentError.new("start(#{every.inspect}) ignored: already checking every #{Duration.format(@ticker_ms)}; " \
-                                     "call stop first to change it"), "start")
+            report(ArgumentError.new("start_checking(#{every.inspect}) ignored: already checking every #{Duration.format(@ticker_ms)}; " \
+                                     "call stop first to change it"), "start_checking")
           end
           return nil
         end
@@ -507,7 +532,7 @@ module Cronwatch
         @ticker_ms = ms
         if @defer_delivery && !@warned_deferred_start
           @warned_deferred_start = true
-          warn '[cronwatch] start() was called with deliver: "check", so these checks send no alerts. ' \
+          warn '[cronwatch] start_checking was called with deliver: "check", so these checks send no alerts. ' \
                'Another process must run checks with deliver: "now" (the default) to send them.'
         end
         @ticker = Ticker.new(ms / 1000.0, @first_tick_s) do
@@ -522,6 +547,26 @@ module Cronwatch
       nil
     end
 
+    # start_checking, under its former name. Deprecated, since a job's start
+    # opens a run: it still works through 1.x and goes in 2.0.
+    def start(every = "1m")
+      Deprecation.warn("client.start(every)", "client.start_checking(every)")
+      start_checking(every)
+    end
+
+    # The dashboard and JSON API for this client, as a Rack app to mount:
+    #
+    #   mount Cronwatch.client.routes => "/cronwatch"   # config/routes.rb
+    #   run CW.routes                                    # config.ru
+    #
+    # Options: token:, base_path: and origin: (see Cronwatch::Web). Needs the
+    # rack gem, which every Rails app has.
+    def routes(**options)
+      require_relative "web"
+      Web.build(self, **options)
+    end
+
+    # Stop the checks start_checking began.
     def stop
       stop_ticker
       nil
@@ -1076,9 +1121,9 @@ module Cronwatch
 
     # Raises for a run id no store could hold, or one reserved for the pg_cron source.
     def check_run_id(job, id, method)
-      unless id.is_a?(String) && !id.empty? && JS.length16(id) <= 200
+      unless id.is_a?(String) && !id.empty? && JS.length16(id) <= MAX_RUN_ID
         got = id.is_a?(String) ? "#{JS.length16(id)} characters" : id.class.to_s
-        raise ArgumentError, "job \"#{job}\": #{method}() needs a run id of 1 to 200 characters (got #{got})"
+        raise ArgumentError, "job \"#{job}\": #{method}() needs a run id of 1 to #{MAX_RUN_ID} characters (got #{got})"
       end
       # Postgres refuses NUL in text, so no store could hold such an id.
       raise ArgumentError, "job \"#{job}\": #{method}() cannot take a run id containing a NUL character" if id.include?("\0")
@@ -1123,6 +1168,8 @@ module Cronwatch
 
     # Alerts written with the state that opened their conditions, and how
     # many older ones the queue let go.
+    #
+    # @api private
     Outbox = Struct.new(:alerts, :dropped)
 
     # An evaluation as it is written: its drafts composed into alerts and held
@@ -1309,6 +1356,8 @@ module Cronwatch
     end
 
     # The wall-clock milliseconds one check has spent retrying, across its jobs.
+    #
+    # @api private
     RetryBudget = Struct.new(:spent_ms)
 
     # Send the alerts that no channel accepted last time, once each, oldest

data/lib/cronwatch/cron_pattern.rb

@@ -7,6 +7,8 @@ require_relative "walker"
 module Cronwatch
   # A cron expression's fields, and the next time they match. What is
   # accepted, and which times match, follow croner; Fugit parses the values.
+  #
+  # @api private
   class CronPattern
     NICKNAMES = {
       "@yearly" => "0 0 1 1 *", "@annually" => "0 0 1 1 *", "@monthly" => "0 0 1 * *", "@weekly" => "0 0 * * 0",
@@ -27,14 +29,15 @@ module Cronwatch
 
     def initialize(text)
       fields, dom, dow = croner_fields(text)
-      cron = begin
-        Fugit::Cron.parse(fields.each_with_index.map { |f, i| i == 3 ? dom : (i == 5 ? dow : f) }.join(" "))
-      rescue StandardError
-        nil
-      end
+      # Fugit refuses a date no month has ("30 2"), and drops a month the
+      # days cannot fall in ("31 2,3" reads as March alone). Croner keeps
+      # both, so the days are read with every month and the months with
+      # every day, and a date no month has is a cron that never fires.
+      cron = fugit(fields.each_with_index.map { |f, i| i == 3 ? dom : (i == 4 ? "*" : (i == 5 ? dow : f)) })
+      months = fugit(["0", "0", "0", "*", fields[4], "*"])
       # Croner accepts a few forms Fugit does not read (a range with #, a day of
-      # the month with L after it, a date no month has). Those are refused.
-      raise ArgumentError, "CronPattern: '#{text}' uses a form the Ruby port does not read" unless cron
+      # the month with L after it). Those are refused.
+      raise ArgumentError, "CronPattern: '#{text}' uses a form the Ruby port does not read" unless cron && months
 
       @seconds = flags(cron.seconds, 60, 0)
       @minutes = flags(cron.minutes, 60, 0)
@@ -45,7 +48,7 @@ module Cronwatch
       else
         cron.monthdays.each { |d| @days[d - 1] = true if d.positive? }
       end
-      @months = flags(cron.months, 12, 1)
+      @months = flags(months.months, 12, 1)
       @weekdays = Array.new(7, 0)
       if cron.weekdays.nil?
         @weekdays.fill(ANY_NTH)
@@ -75,6 +78,12 @@ module Cronwatch
 
     private
 
+    def fugit(fields)
+      Fugit::Cron.parse(fields.join(" "))
+    rescue StandardError
+      nil
+    end
+
     def flags(values, size, base)
       return Array.new(size, true) if values.nil?
 

data/lib/cronwatch/deprecation.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cronwatch
+  # Warns that a name is deprecated: it still works through 1.x and goes in
+  # 2.0. The warning is Ruby's own deprecation category, so it shows where
+  # Ruby's deprecation warnings show (`ruby -w`, `-W:deprecated`, or
+  # `Warning[:deprecated] = true`) and points at the caller's line.
+  #
+  # @api private
+  module Deprecation
+    module_function
+
+    def warn(old, replacement, uplevel: 2)
+      Kernel.warn("[cronwatch] #{old} is deprecated and goes in 2.0; use #{replacement}",
+                  uplevel: uplevel, category: :deprecated)
+    end
+  end
+end

data/lib/cronwatch/duration.rb

@@ -2,6 +2,8 @@
 
 module Cronwatch
   # "15m", "1h30m", "90s", "2d", or a number of milliseconds.
+  #
+  # @api private
   module Duration
     UNIT_MS = { "ms" => 1, "s" => 1000, "m" => 60_000, "h" => 3_600_000, "d" => 86_400_000, "w" => 604_800_000 }.freeze
     PART = Regexp.new("(\\d+(?:\\.\\d+)?)[#{JS::WHITESPACE}]*(ms|s|m|h|d|w)")