cronwatch 0.10.0 → 0.11.1

data/lib/cronwatch/web/app.rb

@@ -10,15 +10,23 @@ 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 (Environment.stated_development?: under Puma, Unicorn,
   #            Thin or rackup, which set RACK_ENV=development by default,
@@ -66,16 +74,42 @@ 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
@@ -183,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)
@@ -191,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
@@ -204,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
 
@@ -259,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
@@ -273,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
@@ -301,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
@@ -350,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}")
@@ -448,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)
@@ -508,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
 

data/lib/cronwatch/web/html.rb

@@ -3,7 +3,7 @@
 module Cronwatch
   class Web
     # The dashboard's pages, markup for markup the SDK's routes/html.ts. The
-    # one script, app.js, only registers the service worker: the pages refresh
+    # one script, app.js, registers the service worker and toggles the theme: the pages refresh
     # themselves and the forget button confirms with a <details>.
     #
     # Set like cronwatch.dev: a printed sheet on grey paper, a serif for what a
@@ -21,10 +21,13 @@ module Cronwatch
     # Motion is CSS only and says something: marks arrive in time order, the
     # now line drops in last, and open problems (a missed slot, a running bar)
     # breathe slowly. prefers-reduced-motion turns all of it off.
+    #
+    # @api private
     module HTML
       CSS = "\n" + <<~'CSS'
         :root{color-scheme:light dark;--paper:#f4f4f5;--sheet:#fff;--sunk:#fafafa;--rule:#e4e4e7;--rule-2:#d4d4d8;--tick:#909098;--ink:#000;--body:#18181b;--muted:#71717a;--ok:#15803d;--warn:#a16207;--bad:#b91c1c;--serif:"Newsreader",ui-serif,Georgia,Cambria,"Times New Roman",serif;--mono:"IBM Plex Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--who:200px}
-        @media(prefers-color-scheme:dark){:root{--paper:#09090b;--sheet:#111113;--sunk:#18181b;--rule:#27272a;--rule-2:#3f3f46;--tick:#66666f;--ink:#fff;--body:#e4e4e7;--muted:#a1a1aa;--ok:#4ade80;--warn:#fbbf24;--bad:#f87171}}
+        @media(prefers-color-scheme:dark){:root:not([data-theme=light]){--paper:#09090b;--sheet:#111113;--sunk:#18181b;--rule:#27272a;--rule-2:#3f3f46;--tick:#66666f;--ink:#fff;--body:#e4e4e7;--muted:#a1a1aa;--ok:#4ade80;--warn:#fbbf24;--bad:#f87171}}
+        :root[data-theme=light]{color-scheme:light}:root[data-theme=dark]{color-scheme:dark;--paper:#09090b;--sheet:#111113;--sunk:#18181b;--rule:#27272a;--rule-2:#3f3f46;--tick:#66666f;--ink:#fff;--body:#e4e4e7;--muted:#a1a1aa;--ok:#4ade80;--warn:#fbbf24;--bad:#f87171}
         *{box-sizing:border-box}html{-webkit-text-size-adjust:100%}
         body{margin:0;background:var(--paper);color:var(--ink);font:400 16px/1.55 var(--serif);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}
         a{color:inherit;text-decoration:underline;text-decoration-thickness:1px;text-underline-offset:.16em;text-decoration-color:var(--rule-2)}a:hover{text-decoration-color:currentColor}
@@ -249,7 +252,7 @@ module Cronwatch
 
       # A page. `base` is where the dashboard is mounted ("" at the root): the
       # head links the web app manifest, the icons and app.js, the one script,
-      # which only registers the service worker (Web::PWA). Everything works
+      # which registers the service worker and toggles the theme (Web::PWA). Everything works
       # without it.
       def layout(title, body, base, refresh: nil)
         b = h(base)
@@ -564,13 +567,14 @@ module Cronwatch
         layout("#{job.name}: CronWatch", body, base, refresh: 60)
       end
 
-      # A page with one message. With `sign_in`, a form under it takes the
-      # token and sends it as ?token=, which the app moves into the cookie:
+      # A page with one message. With `sign_in`, a form under it posts the
+      # token to <base>/signin in the body, keeping it out of the URL and
+      # access logs, and the app sets the cookie:
       # the way in where there is no address bar to open a link with, such as
       # an app on an iPhone's home screen, which keeps its cookies apart from
       # Safari's.
       def message_page(title, message, base, sign_in: false)
-        form = sign_in ? %(<form class="signin" method="get" action="#{h(base)}/"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>) : ""
+        form = sign_in ? %(<form class="signin" method="post" action="#{h(base)}/signin"><label for="token">Token</label><input id="token" name="token" type="password" autocomplete="current-password" autocapitalize="off" spellcheck="false" required><button class="primary" type="submit">Sign in</button></form>) : ""
         layout(title, %(<header class="top">#{brand(base)}</header><main class="message"><h1>#{h(title)}</h1><p>#{h(message)}</p>#{form}</main>), base)
       end
     end

data/lib/cronwatch/web/origin.rb

@@ -10,6 +10,8 @@ module Cronwatch
     # ignored, the host is lowercased (percent escapes decoded, IPv4 numbers
     # written out, IPv6 compressed, a non-ASCII host converted to punycode)
     # and a default port is left out. A port outside 1 to 65535 is refused.
+    #
+    # @api private
     module Origin
       ABSOLUTE = "routes: origin must be an absolute URL such as \"https://app.example.com\", got %s"
       FORBIDDEN_HOST = /[\x00-\x20#%\/:<>?@\[\\\]^|\x7F]/

data/lib/cronwatch/web/pwa.rb

@@ -7,6 +7,8 @@ module Cronwatch
     # that registers it and a page to show offline. None of it says anything
     # about the jobs, so it is served without the token (a browser fetches the
     # manifest and icons without cookies in some flows).
+    #
+    # @api private
     module PWA
       # The page colours the app's window takes: the paper behind the sheet,
       # and the sheet the header sits on.
@@ -14,11 +16,27 @@ module Cronwatch
       THEME_COLOR = "#ffffff"
       THEME_COLOR_DARK = "#111113"
 
-      # Registers the service worker, and does nothing else. The page works
-      # the same without it. Its own URL gives the base, so it is the same
+      # Registers the service worker, and switches between light and dark on
+      # Cmd+Shift+D (Ctrl+Shift+D elsewhere), keeping the choice in
+      # localStorage. The page works the same without it. Its own URL gives the base, so it is the same
       # text wherever the dashboard is mounted.
       APP_JS = <<~'JS'
         "use strict";
+        (function () {
+          var root = document.documentElement;
+          try {
+            var stored = localStorage.getItem("cronwatch-theme");
+            if (stored === "light" || stored === "dark") root.setAttribute("data-theme", stored);
+          } catch (e) {}
+          document.addEventListener("keydown", function (event) {
+            if (!(event.metaKey || event.ctrlKey) || !event.shiftKey || event.altKey || event.code !== "KeyD") return;
+            event.preventDefault();
+            var shown = root.getAttribute("data-theme") || (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
+            var next = shown === "dark" ? "light" : "dark";
+            root.setAttribute("data-theme", next);
+            try { localStorage.setItem("cronwatch-theme", next); } catch (e) {}
+          });
+        })();
         (function () {
           var script = document.currentScript;
           if (!script || !("serviceWorker" in navigator)) return;

data/lib/cronwatch/web/timeline.rb

@@ -15,6 +15,8 @@ module Cronwatch
     # open, and a visually hidden list says the same things in words.
     #
     # Every time is UTC: without script the page cannot know the viewer's zone.
+    #
+    # @api private
     module Timeline
       HOUR = 3_600_000
       DAY = 24 * HOUR

data/lib/cronwatch/web.rb

@@ -3,8 +3,7 @@
 # The dashboard and JSON API, as a Rack app. Needs the rack gem; the Rails
 # integration loads this file itself.
 #
-#   require "cronwatch/web"
-#   run Cronwatch::Web.new(CW)
+#   run CW.routes # Client#routes requires this file itself
 begin
   require "rack"
 rescue LoadError => e

data/lib/cronwatch/zone.rb

@@ -5,6 +5,8 @@ require "fugit"
 module Cronwatch
   # IANA zones through TZInfo (which Fugit brings, by way of et-orbi), or the
   # process's own zone when none is named, as JavaScript's Date does.
+  #
+  # @api private
   module Zone
     @zones = {}
     @names = nil

data/lib/cronwatch.rb

@@ -4,6 +4,7 @@ require "json"
 
 require_relative "cronwatch/version"
 require_relative "cronwatch/js"
+require_relative "cronwatch/deprecation"
 require_relative "cronwatch/types"
 require_relative "cronwatch/duration"
 require_relative "cronwatch/stats"
@@ -49,6 +50,7 @@ module Cronwatch
   # The options Cronwatch.configure sets. Anything left unset takes the client's default.
   class Configuration
     OPTIONS = %i[store alerts triage cron_secret retention defaults redact deliver now on_error sources].freeze
+    private_constant :OPTIONS
 
     attr_accessor(*OPTIONS)
 

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

@@ -207,7 +207,7 @@ module Cronwatch
 
           4. Mount the dashboard in config/routes.rb:
 
-               mount Cronwatch::Web.new(Cronwatch.client) => "/cronwatch"
+               mount Cronwatch.client.routes => "/cronwatch"
 
              Outside development it needs CRONWATCH_TOKEN set to sign in. In
              development, without one, the server prints a sign-in link on

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cronwatch
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Jon C. Phillips
@@ -57,6 +57,7 @@ files:
 - lib/cronwatch/alerts/webhook.rb
 - lib/cronwatch/client.rb
 - lib/cronwatch/cron_pattern.rb
+- lib/cronwatch/deprecation.rb
 - lib/cronwatch/duration.rb
 - lib/cronwatch/environment.rb
 - lib/cronwatch/evaluate.rb