cronwatch 0.9.0 → 0.11.0

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,23 +82,51 @@ module Cronwatch
 
     FIELDS.each_key { |field| define_method(field) { @fields[field] } }
 
+    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 = false
       freeze
     end
 
-    def self.from_h(hash)
+    # A stored definition that is not a JSON object (null, a string, a
+    # 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 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]
     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
@@ -146,25 +178,38 @@ 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"),
         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
 
     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" => (metrics || {}).transform_keys(&:to_s), "trigger" => trigger,
+        "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)
+      value.is_a?(Hash) ? value.transform_keys(&:to_s) : {}
+    end
+
     def running? = status == :running
     def ok? = status == :ok
   end
@@ -175,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"),
       )
@@ -190,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
 
@@ -220,77 +268,201 @@ 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, 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,
       )
     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,
-        "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.9.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]

data/lib/cronwatch/web/app.rb

@@ -10,19 +10,29 @@ module Cronwatch
   # (routes/index.ts) with the same URLs, JSON, auth, CSRF rules and headers,
   # so @cronwatch/mcp works against a Ruby app as it does against a Node one.
   #
+  # Made by Client#routes, the one way to mount it:
+  #
   #   # config/routes.rb
-  #   mount Cronwatch::Web.new => "/cronwatch"
+  #   mount Cronwatch.client.routes => "/cronwatch"
   #
   #   # config.ru, standalone
-  #   run Cronwatch::Web.new(CW)
+  #   run CW.routes
+  #
+  # Cronwatch::Web.new(client, **options) makes the same app and is
+  # deprecated: it still works through 1.x and goes in 2.0.
   #
   # token:     required to reach anything. Send it as `Authorization: Bearer <token>`,
-  #            or open the dashboard once with `?token=<token>` and a cookie is set.
-  #            Defaults to ENV["CRONWATCH_TOKEN"]; an empty string counts as unset.
+  #            or open the dashboard once with `?token=<token>` (or sign in with the
+  #            form, which posts it to <base>/signin) and a cookie is set.
+  #            Defaults to ENV["CRONWATCH_TOKEN"]; an empty string or one of only
+  #            whitespace, given here or in the variable, counts as unset, and
+  #            anything but a String or nil (false, a number, a Symbol) raises TypeError.
   #            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
@@ -64,22 +74,48 @@ module Cronwatch
     SECURITY_HEADERS = {
       "x-content-type-options" => "nosniff", "referrer-policy" => "same-origin", "x-robots-tag" => "noindex",
     }.freeze
-    BEARER = Regexp.new("\\ABearer[#{JS::WHITESPACE}]+", Regexp::IGNORECASE)
-    DECIMAL = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\z/
-    RADIX = { "x" => 16, "o" => 8, "b" => 2 }.freeze
+    # A bearer is what follows the scheme when the scheme is Bearer (any case)
+    # and whitespace follows it. Any other Authorization header (a proxy's
+    # Basic auth) is no bearer at all.
+    BEARER = Regexp.new("\\ABearer[#{JS::WHITESPACE}]+(.*)\\z", Regexp::IGNORECASE | Regexp::MULTILINE)
+    # What GET <base>/api names, so a client such as @cronwatch/mcp can tell
+    # what it is talking to. API_VERSION goes up only with a change that is
+    # not additive, in a major release.
+    LIBRARY = "cronwatch"
+    LANGUAGE = "ruby"
+    API_VERSION = 1
+    private_constant :API_VERSION, :ASSET_CSP, :BEARER, :BOARD_PAGE_RUNS, :COOKIE, :COOKIE_MAX_AGE, :CSP,
+                     :DEFAULT_RUNS, :LANGUAGE, :LIBRARY, :MAX_RUNS, :SECURITY_HEADERS
+
+    # Deprecated: use client.routes(**options). Still works through 1.x; a
+    # Web made without a client serves Cronwatch.client, read on each request.
+    def self.new(client = nil, **options)
+      Deprecation.warn("Cronwatch::Web.new(client, ...)", "client.routes(...)")
+      build(client, **options)
+    end
+
+    # The app Client#routes returns, without the warning.
+    #
+    # @api private
+    def self.build(client = nil, **options)
+      app = allocate
+      app.send(:initialize, client, **options)
+      app
+    end
 
     def initialize(client = nil, token: UNSET, base_path: nil, origin: nil)
       @client = client
       @origin = Web.configured_origin(origin)
       @opted_out = token.nil?
-      given = token.equal?(UNSET) ? nil : token
-      @token = @opted_out ? nil : [given, ENV.fetch("CRONWATCH_TOKEN", nil)].map(&:to_s).find { |t| !t.empty? }
+      # A blank token, given or read, counts as unset; one given that is not a String raises.
+      given = token.equal?(UNSET) ? nil : Environment.secret_option(token, "routes: token")
+      @token = @opted_out ? nil : given || Environment.secret("CRONWATCH_TOKEN")
       @base_path = base_path&.to_s&.sub(%r{/+\z}, "")
       # A Rack app cannot reliably tell a local caller from a remote one
       # (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
@@ -181,7 +217,7 @@ module Cronwatch
 
       # No token outside development: fail closed.
       if !@token && !@opted_out
-        return wants_html ? html(HTML.message_page("CronWatch routes are locked", "Set CRONWATCH_TOKEN (or pass token: to Cronwatch::Web.new), or pass token: nil to serve them open behind your own auth.", base), 503) : api({ ok: false, error: "CRONWATCH_TOKEN is not set" }, 503)
+        return wants_html ? html(HTML.message_page("CronWatch routes are locked", "Set CRONWATCH_TOKEN (or pass token: to routes), or pass token: nil to serve them open behind your own auth.", base), 503) : api({ ok: false, error: "CRONWATCH_TOKEN is not set" }, 503)
       end
 
       if method != "GET" && method != "HEAD" && cross_site?(request)
@@ -189,7 +225,18 @@ module Cronwatch
       end
 
       authorization = request.header("authorization")
-      bearer = authorization&.sub(BEARER, "")
+      bearer = authorization && BEARER.match(authorization)&.[](1)
+
+      # The sign-in form posts the token here, in the body, so it stays out of
+      # the URL and every access log. Cross-site posts were refused above.
+      if @token && method == "POST" && path == "/signin"
+        sent = read_body(request)["token"]
+        return sign_in_page(base) if sent.nil? || !HTTP.constant_time_equal?(sent, @token)
+
+        return redirect(sign_in_return(request.header("referer"), public_origin(request), base),
+                        "set-cookie" => sign_in_cookie(request, base))
+      end
+
       if @token
         # ?token= is only the sign-in that moves the token into a cookie.
         query = wants_html && method == "GET" ? request.query("token") : nil
@@ -202,16 +249,18 @@ module Cronwatch
           else !cookie.nil? && HTTP.constant_time_equal?(cookie, cookie_value(@token))
           end
         unless cron_secret_ok || token_ok
+          return sign_in_page(base) if wants_html
           if @generated
-            return wants_html ? html(HTML.message_page("Sign in", "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server log: open it once and this browser stays signed in.", base, sign_in: true), 401) : api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401)
+            return api({ ok: false, error: "Unauthorized: CRONWATCH_TOKEN is not set, so this development server made a token; it is in the server log" }, 401)
           end
-          return wants_html ? html(HTML.message_page("Sign in", "Open this page with ?token=<your CRONWATCH_TOKEN> once and it will stay signed in.", base, sign_in: true), 401) : api({ ok: false, error: "Unauthorized" }, 401)
+
+          return api({ ok: false, error: "Unauthorized" }, 401)
         end
         unless query.nil?
-          # Move the token from the URL into a cookie so it is not in history or logs.
-          secure = public_origin(request).start_with?("https:") ? "; Secure" : ""
-          return redirect(request.pathname + request.search_without("token"),
-                          "set-cookie" => "#{COOKIE}=#{cookie_value(@token)}; Path=#{base.empty? ? "/" : base}; HttpOnly; SameSite=Lax; Max-Age=#{COOKIE_MAX_AGE}#{secure}")
+          # Move the token from the URL into a cookie, so it is not left in the
+          # browser's history. The request line that carried it may still be in
+          # an access log, which is why the sign-in form posts instead.
+          return redirect(request.pathname + request.search_without("token"), "set-cookie" => sign_in_cookie(request, base))
         end
       end
 
@@ -257,7 +306,7 @@ module Cronwatch
           rescue ArgumentError => e
             return html(HTML.message_page("Not silenced", e.message, base), 400)
           end
-          cw.silence(name, duration)
+          cw.silence(name, for: duration)
         else
           cw.unsilence(name)
         end
@@ -271,6 +320,9 @@ module Cronwatch
 
     def serve_api(request, method, rest, bearer)
       cw = client
+      if method == "GET" && rest.empty?
+        return api({ ok: true, library: LIBRARY, language: LANGUAGE, version: VERSION, api: API_VERSION })
+      end
       return api({ ok: true, jobs: cw.jobs }) if method == "GET" && rest[0] == "jobs" && rest.length == 1
 
       if rest[0] == "jobs" && rest.length == 2
@@ -299,9 +351,13 @@ module Cronwatch
           rescue ArgumentError => e
             return api({ ok: false, error: e.message }, 400)
           end
-          return api({ ok: true, state: cw.silence(name, duration) })
+          cw.silence(name, for: duration)
+          return api({ ok: true, job: cw.job_summary(name) })
+        end
+        if rest[2] == "unsilence"
+          cw.unsilence(name)
+          return api({ ok: true, job: cw.job_summary(name) })
         end
-        return api({ ok: true, state: cw.unsilence(name) }) if rest[2] == "unsilence"
       end
       if rest[0] == "check" && rest.length == 1
         # A page cannot send an Authorization header cross-site, so a GET
@@ -348,6 +404,37 @@ module Cronwatch
       $stdout.flush
     end
 
+    # The 401 sign-in page, with the form that posts the token to <base>/signin.
+    def sign_in_page(base)
+      message =
+        if @generated
+          "CRONWATCH_TOKEN is not set, so this development server made a token. The sign-in link is in the server " \
+            "log: open it once, or enter the token from it below, and this browser stays signed in."
+        else
+          "Enter your CRONWATCH_TOKEN and this browser stays signed in."
+        end
+      html(HTML.message_page("Sign in", message, base, sign_in: true), 401)
+    end
+
+    # The cookie a sign-in sets, by ?token= or by the form.
+    def sign_in_cookie(request, base)
+      secure = public_origin(request).start_with?("https:") ? "; Secure" : ""
+      "#{COOKIE}=#{cookie_value(@token)}; Path=#{base.empty? ? "/" : base}; HttpOnly; SameSite=Lax; Max-Age=#{COOKIE_MAX_AGE}#{secure}"
+    end
+
+    # Where a sign-in through the form goes next: the page it was posted from
+    # (the Referer) when that is on the public origin and its query has no
+    # `token` parameter, else the dashboard. A Referer that starts with the
+    # origin and "/" always parses as a URL; its query is read as
+    # URLSearchParams reads it, after the tabs and newlines a URL parser drops.
+    def sign_in_return(referer, origin, base)
+      return "#{base}/" if referer.nil? || !referer.start_with?("#{origin}/")
+
+      url = referer.delete("\t\n\r").split("#", 2).first.to_s
+      query = url.include?("?") ? url.split("?", 2).last : ""
+      Request.parse_query(query).any? { |key, _| key == "token" } ? "#{base}/" : referer
+    end
+
     # The cookie holds a digest of the token, so a leaked cookie does not reveal the bearer token itself.
     def cookie_value(token)
       Digest::SHA256.hexdigest("cronwatch-cookie:#{token}")
@@ -446,19 +533,7 @@ module Cronwatch
 
     # Number(string): decimal, 0x/0o/0b, Infinity, or NaN.
     def js_number(value)
-      text = JS.trim(value)
-      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
+      JS.to_number(value)
     end
 
     def whole(number)
@@ -506,6 +581,8 @@ module Cronwatch
     end
 
     # What the routes need from a Rack env, read the way the SDK reads a fetch Request.
+    #
+    # @api private
     class Request
       attr_reader :env