cronwatch 0.12.4 → 0.13.0

data/lib/cronwatch/web/app.rb

@@ -3,11 +3,12 @@
 require "base64"
 require "digest"
 require "securerandom"
+require "stringio"
 require "uri"
 
 module Cronwatch
   # The dashboard and the small JSON API, as a Rack app: the SDK's routes
-  # (routes/index.ts) with the same URLs, JSON, auth, CSRF rules and headers,
+  # (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:
@@ -24,12 +25,13 @@ module Cronwatch
   # token:     required to reach anything. Send it as `Authorization: Bearer <token>`,
   #            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
+  #            Defaults to ENV["CRONWATCH_TOKEN"]. It is trimmed of the whitespace
+  #            around it; 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,
+  #            With no token while Cronwatch::Environment is development
+  #            (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,
@@ -39,18 +41,24 @@ module Cronwatch
   #            mount point (SCRIPT_NAME), which is right under Rails' `mount`.
   # origin:    the public origin the dashboard is served from, such as
   #            "https://app.example.com". By default the request's own origin
-  #            is used, as Rack reads it (Rack::Request#base_url, which follows
-  #            X-Forwarded-Proto and X-Forwarded-Host the way Rails does). Set
-  #            this to pin it, for an app behind a proxy that does not set
-  #            those headers or one that should not trust them. Used in place
-  #            of the request's origin for the cross-site check on writes, the
-  #            sign-in cookie's Secure flag, the Referer the redirect back after
-  #            a form follows, and the development sign-in line. Read as
+  #            is used: rack.url_scheme and the Host header, or the forwarded
+  #            ones under trust_proxy. Set this to pin it. Used in place of the
+  #            request's origin for the cross-site check on writes, the sign-in
+  #            cookie's Secure flag, the Referer the redirect back after a form
+  #            follows, and the development sign-in line. Read as
   #            `new URL(value).origin` reads it (Web::Origin) and normalised to
   #            scheme://host[:port]; anything that is not an absolute http or
   #            https URL, or has a port outside 1 to 65535, raises
-  #            ArgumentError here. "" counts as unset. Behind more than one
-  #            proxy set it: Rack takes the last of several forwarded values.
+  #            ArgumentError here. "" counts as unset. Takes precedence over
+  #            trust_proxy.
+  # trust_proxy: take the public origin from X-Forwarded-Proto and
+  #            X-Forwarded-Host (the first value of each, falling back to the
+  #            request's own scheme or host for whichever is missing) when a
+  #            request carries either, as the SDK's trustProxy does. Only for
+  #            an app whose proxy sets or overwrites both headers: a client can
+  #            send them too. Defaults to true when Rails is loaded, since Rails
+  #            itself trusts them (ActionDispatch::Request#base_url), and to
+  #            false otherwise, as in the SDK.
   class Web
     # Tells "token not given" (read CRONWATCH_TOKEN) from "token: nil" (open on purpose).
     UNSET = Object.new.freeze
@@ -62,7 +70,7 @@ module Cronwatch
     COOKIE_MAX_AGE = 60 * 60 * 24 * 30
 
     # 'self' only for what the app shell needs: app.js (which registers the
-    # service worker and nothing else), the manifest, the worker and the icons.
+    # service worker and nothing else), the manifest, the worker, and the icons.
     # No inline script, and the pages work without any.
     CSP = "default-src 'none'; script-src 'self'; style-src 'unsafe-inline'; img-src 'self' data:; " \
           "manifest-src 'self'; worker-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"
@@ -103,24 +111,41 @@ module Cronwatch
       app
     end
 
-    def initialize(client = nil, token: UNSET, base_path: nil, origin: nil)
+    def initialize(client = nil, token: UNSET, base_path: nil, origin: nil, trust_proxy: UNSET)
       @client = client
       @origin = Web.configured_origin(origin)
+      @trust_proxy = trust_proxy.equal?(UNSET) ? Web.rails? : trust_proxy == true
       @opted_out = token.nil?
       # 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
+      # (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 && Environment.stated_development?
       @token = Web.development_token if @generated
+      Web.warn_short_token(@token) unless @generated
       @announced = false
       @announce_lock = Mutex.new
     end
 
+    # Under this many characters a token could be guessed one request at a
+    # time, since nothing slows down wrong guesses.
+    SHORT_TOKEN = 32
+    private_constant :SHORT_TOKEN
+
+    # Warns, once per app, when the dashboard's token is short enough to guess.
+    #
+    # @api private
+    def self.warn_short_token(token)
+      return if token.nil? || token.length >= SHORT_TOKEN
+
+      warn "[cronwatch] the dashboard token is #{token.length} characters; use #{SHORT_TOKEN} or more random characters, " \
+           "such as the output of `ruby -rsecurerandom -e 'puts SecureRandom.urlsafe_base64(32)'`"
+    end
+
     # A token for one app in development, when none is configured: 32 random
     # bytes, base64url (43 characters).
     def self.development_token
@@ -129,7 +154,7 @@ module Cronwatch
 
     # The line a development token is announced with, printed once to stdout
     # on the app's first request. `origin` is the `origin:` option when set,
-    # otherwise that request's origin (scheme, host and any port) when its
+    # otherwise that request's origin (scheme, host, and any port) when its
     # host is loopback, and nil for any other host: the request's host is
     # the client's to choose, so the line then leaves it out rather than
     # point the link, token and all, somewhere else. `base` is the base path
@@ -168,6 +193,11 @@ module Cronwatch
       Origin.parse(value)
     end
 
+    # Whether the app runs under Rails, which trusts forwarded headers by default.
+    def self.rails?
+      defined?(::Rails::Railtie) ? true : false
+    end
+
     # The client given, or Cronwatch.client when none was.
     def client
       @client || Cronwatch.client
@@ -203,7 +233,7 @@ module Cronwatch
 
       announce(request, base) if @generated && !@announced
 
-      # The app shell: the manifest, icons, service worker, app.js and the
+      # The app shell: the manifest, icons, service worker, app.js, and the
       # offline page. Served to anyone, since a browser fetches some of it
       # without cookies and none of it says anything about the jobs.
       if %w[GET HEAD].include?(method)
@@ -230,7 +260,9 @@ module Cronwatch
       # 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"]
+        body = read_body(request)
+        # A body too large is no token at all.
+        sent = body.equal?(TOO_LARGE) ? nil : body["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),
@@ -260,7 +292,10 @@ module Cronwatch
           # 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))
+          # One leading slash: "//host/..." would be a protocol-relative Location,
+          # off this site, and a browser reads a backslash there as a slash.
+          return redirect(request.pathname.sub(%r{\A[/\\]+}, "/") + request.search_without("token"),
+                          "set-cookie" => sign_in_cookie(request, base))
         end
       end
 
@@ -301,8 +336,11 @@ module Cronwatch
         return html(HTML.message_page("No such job", "#{name} is not in the store.", base), 404) unless cw.job_summary(name)
 
         if action == "silence"
+          body = read_body(request)
+          return html(HTML.message_page("Not silenced", "The request was too large.", base), 413) if body.equal?(TOO_LARGE)
+
           begin
-            duration = silence_duration(read_body(request)["for"])
+            duration = silence_duration(body["for"])
           rescue ArgumentError => e
             return html(HTML.message_page("Not silenced", e.message, base), 400)
           end
@@ -346,6 +384,8 @@ module Cronwatch
 
         if rest[2] == "silence"
           body = read_body(request)
+          return api({ ok: false, error: "Request body too large" }, 413) if body.equal?(TOO_LARGE)
+
           begin
             duration = silence_duration(body.key?("for") ? body["for"] : request.query("for"))
           rescue ArgumentError => e
@@ -399,7 +439,8 @@ module Cronwatch
       end
       return unless first
 
-      shown = @origin || (Web.loopback_origin?(request.origin) ? request.origin : nil)
+      own = request_origin(request)
+      shown = @origin || (Web.loopback_origin?(own) ? own : nil)
       $stdout.puts(Web.development_sign_in_line(shown, base, @token))
       $stdout.flush
     end
@@ -477,17 +518,26 @@ module Cronwatch
       !site.nil? && site != "same-origin" && site != "none"
     end
 
+    # A request body past Request::MAX_BODY, which read_body answers with.
+    TOO_LARGE = Object.new.freeze
+    private_constant :TOO_LARGE
+
     # The form fields or JSON object of a request, each value as String(value)
-    # gives it in JavaScript. The body is read as the SDK's request.json()
-    # reads it: bytes that are not UTF-8 become U+FFFD, and a leading byte
-    # order mark is dropped.
+    # gives it in JavaScript, or TOO_LARGE for a body past Request::MAX_BODY.
+    # The body is read as the SDK's request.json() reads it: bytes that are
+    # not UTF-8 become U+FFFD, and a leading byte order mark is dropped.
     def read_body(request)
       type = request.header("content-type") || ""
-      if type.include?("application/json")
+      json = type.include?("application/json")
+      form = type.include?("application/x-www-form-urlencoded") || type.include?("multipart/form-data")
+      return {} unless json || form
+      return TOO_LARGE if request.too_large?
+
+      if json
         data = JSON.parse(Output.utf8(request.body).delete_prefix(""))
         return data.to_h { |k, v| [k.to_s, js_string(v)] } if data.is_a?(Hash)
         return data.each_with_index.to_h { |v, i| [i.to_s, js_string(v)] } if data.is_a?(Array)
-      elsif type.include?("application/x-www-form-urlencoded") || type.include?("multipart/form-data")
+      else
         return request.form.transform_values { |v| form_value(v) }
       end
       {}
@@ -547,7 +597,12 @@ module Cronwatch
 
     # The origin a browser sees: the `origin` option when set, otherwise the request's own.
     def public_origin(request)
-      @origin || request.origin
+      @origin || request_origin(request)
+    end
+
+    # The request's origin: the forwarded one under trust_proxy, else its own.
+    def request_origin(request)
+      @trust_proxy ? request.forwarded_origin : request.origin
     end
 
     def api(body, status = 200, headers = {})
@@ -607,11 +662,35 @@ module Cronwatch
         @env[key]
       end
 
-      # scheme://host[:port], the page's origin, lowercased as a browser
-      # writes it in Origin and Referer (Rack's base_url keeps the case of
-      # the Host or X-Forwarded-Host it read).
+      # scheme://host[:port], the page's origin as the request URL gives it
+      # (rack.url_scheme and the Host header, never a forwarded header),
+      # normalised as a browser writes it in Origin and Referer.
       def origin
-        @rack.base_url.downcase
+        scheme = @env["rack.url_scheme"].to_s.downcase
+        scheme = "http" unless %w[http https].include?(scheme)
+        host = @env["HTTP_HOST"].to_s
+        host = [@env["SERVER_NAME"], @env["SERVER_PORT"]].compact.join(":") if host.empty?
+        Origin.bare("#{scheme}://#{host}") || "#{scheme}://#{host.downcase}"
+      end
+
+      # With trust_proxy: the first X-Forwarded-Proto and X-Forwarded-Host,
+      # each falling back to the request's own, when either is present and
+      # well formed; otherwise the request's own origin. The SDK's forwardedOrigin.
+      def forwarded_origin
+        own = origin
+        proto = Request.first_value(header("x-forwarded-proto"))&.downcase
+        host = Request.first_value(header("x-forwarded-host"))
+        return own if proto.nil? && host.nil?
+        return own unless proto.nil? || %w[http https].include?(proto)
+
+        scheme, authority = own.split("://", 2)
+        Origin.bare("#{proto || scheme}://#{host || authority}") || own
+      end
+
+      # The first of a header's comma-separated values, trimmed, or nil.
+      def self.first_value(value)
+        first = value&.split(",", 2)&.first&.strip
+        first.nil? || first.empty? ? nil : first
       end
 
       # URLSearchParams#get: the first value, or nil.
@@ -627,12 +706,24 @@ module Cronwatch
         pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
       end
 
+      # The most of a request body the routes read (1 MiB), as every port's.
+      MAX_BODY = 1 << 20
+
+      # Whether the body is past MAX_BODY: by its Content-Length when that
+      # says more, else by reading one byte past the cap at most, so a client
+      # cannot make the server hold a body of any size. The forms and JSON the
+      # routes take are a few bytes. What was read is left to be read again.
+      def too_large?
+        @too_large = measure_too_large if @too_large.nil?
+        @too_large
+      end
+
       def body
         input = @env["rack.input"]
         return "" unless input
 
         input.rewind if input.respond_to?(:rewind)
-        text = input.read.to_s
+        text = input.read(MAX_BODY + 1).to_s
         input.rewind if input.respond_to?(:rewind)
         text.force_encoding(Encoding::UTF_8)
       end
@@ -645,6 +736,30 @@ module Cronwatch
         fields.each_with_object({}) { |(k, v), out| out[Output.utf8(k)] = v }
       end
 
+      private
+
+      def measure_too_large
+        length = @env["CONTENT_LENGTH"].to_s
+        return true if length.match?(/\A\d+\z/) && length.to_i > MAX_BODY
+
+        input = @env["rack.input"]
+        return false unless input
+
+        input.rewind if input.respond_to?(:rewind)
+        read = input.read(MAX_BODY + 1).to_s
+        return true if read.bytesize > MAX_BODY
+
+        # An input that cannot be rewound is handed on as what was read.
+        if input.respond_to?(:rewind)
+          input.rewind
+        else
+          @env["rack.input"] = StringIO.new(read)
+        end
+        false
+      end
+
+      public
+
       # application/x-www-form-urlencoded parsing as URLSearchParams does it:
       # "+" is a space, and a bad escape is kept as written rather than refused.
       def self.parse_query(text)

data/lib/cronwatch/web/html.rb

@@ -10,7 +10,7 @@ module Cronwatch
     # person reads, a mono for what a machine printed, neutral greys, and
     # colour only for the states CronWatch reports. The page loads nothing but
     # its own app shell (its CSP is default-src 'none' plus 'self' for the
-    # script, the manifest, the worker and images), so the fonts are system
+    # script, the manifest, the worker, and images), so the fonts are system
     # stacks that echo the site's Newsreader and IBM Plex Mono, and use them
     # when they are installed.
     #
@@ -251,7 +251,7 @@ module Cronwatch
       end
 
       # 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,
+      # head links the web app manifest, the icons, and app.js, the one script,
       # which registers the service worker and toggles the theme (Web::PWA). Everything works
       # without it.
       def layout(title, body, base, refresh: nil)

data/lib/cronwatch/web/origin.rb

@@ -42,7 +42,7 @@ module Cronwatch
       end
 
       # scheme://host[:port] for text that is a scheme and a bare host, or nil
-      # when it carries credentials, a path, a query or a fragment, or is not
+      # when it carries credentials, a path, a query, or a fragment, or is not
       # an http or https URL.
       def bare(value)
         return nil unless value.is_a?(String)
@@ -61,7 +61,7 @@ module Cronwatch
       end
 
       # Whether what follows the host would show in the URL: a path other
-      # than "/", a query or a fragment.
+      # than "/", a query, or a fragment.
       def past_host?(after)
         path, hash, fragment = after.partition("#")
         path, _, query = path.partition("?")

data/lib/cronwatch/web/pwa.rb

@@ -4,7 +4,7 @@ module Cronwatch
   class Web
     # What makes the dashboard an installable web app, as the SDK's
     # routes/pwa.ts has it: a manifest, icons, a service worker, the script
-    # that registers it and a page to show offline. None of it says anything
+    # 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).
     #
@@ -46,7 +46,7 @@ module Cronwatch
       JS
 
       # The service worker. It caches the app shell (the offline page, the
-      # manifest, the icons and app.js) and nothing else: every other request
+      # manifest, the icons, and app.js) and nothing else: every other request
       # goes to the network as the page made it, and its answer is never
       # stored, since the pages and the JSON carry job data. When a page
       # cannot be reached it shows the offline page. Its scope gives the base,
@@ -95,7 +95,7 @@ module Cronwatch
         });
       JS
 
-      # One app shell file: its type, body and Cache-Control, and whether it
+      # One app shell file: its type, body, and Cache-Control, and whether it
       # is the service worker (which may control everything under the base).
       Asset = Struct.new(:type, :body, :cache, :worker, keyword_init: true)
 
@@ -120,7 +120,7 @@ module Cronwatch
           id: "#{base}/",
           name: "CronWatch",
           short_name: "CronWatch",
-          description: "The scheduled jobs of this app: their health, their last day and their runs.",
+          description: "The scheduled jobs of this app: their health, their last day, and their runs.",
           start_url: "#{base}/",
           scope: "#{base}/",
           display: "standalone",

data/lib/cronwatch/web/timeline.rb

@@ -239,11 +239,11 @@ module Cronwatch
 
         if open?(job, :over_budget) && last
           over = over_ceilings(job)
-          return "went over budget#{over.empty? ? "" : " on #{over.join(" and ")}"} at #{when_at(last.started_at, now)}"
+          return "went over budget#{over.empty? ? "" : " on #{Format.and_list(over)}"} at #{when_at(last.started_at, now)}"
         end
         if open?(job, :under_floor) && last
           under = under_floors(job)
-          return "fell short#{under.empty? ? "" : " on #{under.join(" and ")}"} at #{when_at(last.started_at, now)}"
+          return "fell short#{under.empty? ? "" : " on #{Format.and_list(under)}"} at #{when_at(last.started_at, now)}"
         end
         return "slow: took #{Duration.format(last.duration_ms)}" if open?(job, :slow) && !last&.duration_ms.nil?
         return "failing" if open?(job, :failed)
@@ -405,7 +405,7 @@ module Cronwatch
           [box.call("run ok"), "ran"],
           [box.call("run bad"), "failed"],
           [box.call("run timeout"), "timed out"],
-          [box.call("run warn"), "over budget, under floor or slow"],
+          [box.call("run warn"), "over budget, under floor, or slow"],
           [box.call("run running"), "running"],
           [box.call("missed"), "missed"],
         ]

data/lib/cronwatch.rb

@@ -110,5 +110,5 @@ module Cronwatch
 end
 
 # In a Rails app Bundler requires gems after Rails itself, so `gem "cronwatch"`
-# alone brings in the Railtie, the ActiveJob concern and the generator.
+# alone brings in the Railtie, the ActiveJob concern, and the generator.
 require_relative "cronwatch/rails" if defined?(::Rails::Railtie)

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

@@ -22,7 +22,7 @@ module Cronwatch
       desc "Creates the CronWatch migration and initializer."
 
       class_option :prefix, type: :string, default: Cronwatch::Stores::ActiveRecord::DEFAULT_PREFIX,
-                            desc: "Table name prefix: lowercase letters, digits and underscores"
+                            desc: "Table name prefix: lowercase letters, digits, and underscores"
       class_option :database, type: :string, aliases: %i[--db],
                               desc: "The database for the tables, in an app with several (from config/database.yml)"
 
@@ -107,7 +107,7 @@ module Cronwatch
 
           require "cronwatch/active_record"
 
-          # The tables CronWatch keeps jobs, runs and alert state in. They are
+          # The tables CronWatch keeps jobs, runs, and alert state in. They are
           # created with the SDK's own statements, so a Node process using
           # @cronwatch/sdk can share them.
           class #{migration_name.camelize} < ActiveRecord::Migration[#{::ActiveRecord::Migration.current_version}]
@@ -127,7 +127,7 @@ module Cronwatch
           # frozen_string_literal: true
 
           # CronWatch: told when a scheduled job is missed, failed, stuck, slow,
-          # over budget or under its floor. https://cronwatch.dev/docs/
+          # over budget, or under its floor. https://cronwatch.dev/docs/
           #
           # Monitor a job by including Cronwatch::ActiveJob and declaring its schedule:
           #
@@ -138,7 +138,7 @@ module Cronwatch
           #
           # and run Cronwatch::CheckJob every few minutes to catch the runs that never happen.
           Cronwatch.configure do |c|
-            # Jobs, runs and alert state, in #{database_name ? "the #{database_name} database (see app/models/cronwatch_record.rb)" : "this app's database"}.
+            # Jobs, runs, and alert state, in #{database_name ? "the #{database_name} database (see app/models/cronwatch_record.rb)" : "this app's database"}.
             c.store = Cronwatch::Stores::ActiveRecord.new#{store_args}
 
             # Where alerts go. With none set, they are written to standard error.
@@ -154,7 +154,7 @@ module Cronwatch
             # Applied to every job that does not set its own.
             # c.defaults = { grace: "10m", timezone: "Europe/London", failures_before_alert: 1 }
 
-            # Called with (error, where) when the store, a channel or triage fails. Default: Rails.logger.
+            # Called with (error, where) when the store, a channel, or triage fails. Default: Rails.logger.
             # c.on_error = ->(error, where) { Rails.error.report(error, handled: true, context: { cronwatch: where }) }
 
             # The bearer secret the dashboard's check endpoint takes. Default: ENV["CRON_SECRET"].

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cronwatch
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 0.13.0
 platform: ruby
 authors:
 - Jon C. Phillips
@@ -24,8 +24,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.11'
 description: 'Wrap a job, run a check, get told when it is missed, failed, stuck,
-  slow or over budget. The Ruby port of @cronwatch/sdk: same rules, same alerts, same
-  stored rows.'
+  slow, or over budget. The Ruby port of @cronwatch/sdk: same rules, same alerts,
+  same stored rows.'
 executables: []
 extensions: []
 extra_rdoc_files: []