studio-engine 0.108.0.rc1 → 0.108.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01a56dee2b229822d24c392ac0f3c62f4b2a1d8c0328a2e84966dd4aa73630cc
-  data.tar.gz: 4b906a31d12a9fe5aae18b11f222fda647a1b7dba53627173c681f9da1fbb0b0
+  metadata.gz: 2990527dd511a02eea248d9a8ceb2e5f2df97b2b19423f3022b864ea162e38b0
+  data.tar.gz: 24d9da854c8773924858c46fe3bcf31e81ecf4b2e5a1c40b629e16067ad661ac
 SHA512:
-  metadata.gz: 944aa8ae14a3a9b5a213a4e3594969a2343849ac972a9eba576e9a2fc784eb4c77ca082b947d3f0238478cd9e2e2bd9e5ee3d976365fe0a4cf47c721fbd13f9d
-  data.tar.gz: 472497c4720a4365117f33135f57cd7b9eefdbc2ee7c339f3f9354b9226ae1e05c1dae7fb424c47f1b7efa18302f4ca468e9ac59e4f7abf1767750f9dda051aa
+  metadata.gz: 847d51a58aafc2e75e1d7621cdb674b4dda4c6d54b30676a95803fe5980ad5630392ead197848afe25255b8176cc7754b34c6971a1a27c5fc0f9a162c898c6f6
+  data.tar.gz: fc2bfa04fe01978a9b60ad854553cf89c6d1cb250ebe9ff0c5b75c9b09b49b02ba3a0203e069b32e774763d6505400f4a8a5c5c5574479a39f353e3606451557

data/CHANGELOG.md

@@ -4,6 +4,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+
+- **`GET /_studio/health_report`: the daily health report as JSON, for the
+  hub's central pull.** McRitchie Studio runs one 07:00 America/Denver job that
+  pulls every app's report and posts it to Discord, so a satellite needs no
+  worker or schedule of its own. Drawn by `Studio.routes` in every environment,
+  production included, and inert until the app names a token:
+  `config.health_report_token` or `STUDIO_HEALTH_TOKEN` (new). With none it
+  answers a bare 404; a request without `Authorization: Bearer <token>`
+  (compared in constant time) gets 401; `?ending=<ISO 8601>` picks the day
+  that ends there (a bad value is 400), else the day the job would report now.
+  The body is the same `Studio::HealthReport.build` the email uses, counts only
+  (`schema`, `app`, `engine_version`, `window`, `quiet`, `sections`,
+  `error_kinds`, `error_groups`): no section's names or emails ever leave the
+  app, and an email address quoted in an error message is sent as `[email]`. It runs on `ActionController::API`, so no host `before_action`,
+  session, cookie or redirect touches it. See `docs/HEALTH_REPORT.md`, *The
+  hub endpoint*.
+
 ## 0.108.0 — 2026-10-15
 
 ### Changed

data/README.md

@@ -148,6 +148,8 @@ Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys
 
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
+In every environment, production included, it also draws `/_studio/health_report`: the daily health report as counts-only JSON, which the McRitchie Studio hub pulls at 07:00 and posts to Discord. It answers 404 until the app sets `STUDIO_HEALTH_TOKEN` (or `config.health_report_token`), and 401 to a request without that bearer token ([`docs/HEALTH_REPORT.md`](docs/HEALTH_REPORT.md#the-hub-endpoint)).
+
 ## Non-Production Banners
 
 Consumer layouts can render the shared environment banner inside their sticky

data/app/controllers/studio/health_reports_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Studio
+  # GET /_studio/health_report — the daily health report as JSON, for the
+  # McRitchie Studio hub's one 07:00 America/Denver job, which pulls every app
+  # and posts to Discord. Drawn in every environment, production included; the
+  # report is the same Studio::HealthReport.build the email uses, so the two can
+  # never disagree. docs/HEALTH_REPORT.md, "The hub endpoint".
+  #
+  # INERT BY DEFAULT. With no Studio.health_report_token (else
+  # ENV["STUDIO_HEALTH_TOKEN"]) it answers a bare 404, the same as a route that
+  # is not there. With one, a request without `Authorization: Bearer <token>`
+  # gets 401; the compare is constant-time (Studio::HealthReport.authorized?).
+  #
+  # COUNTS ONLY. Studio::HealthReport.payload drops every section's `items`, so
+  # no signup's or contact's name or email ever leaves the app.
+  #
+  # ActionController::API, NOT the host's ApplicationController: a server-to-
+  # server fetch carries no session, and a host's before_actions (sign-in, geo,
+  # allow_browser, onboarding) would answer it with a redirect or an HTML page.
+  # This base runs none of them, keeps no session, sets no cookie and checks no
+  # CSRF token, and every answer here is JSON or a bare status.
+  class HealthReportsController < ActionController::API
+    def show
+      return head(:not_found) if Studio.health_report_token.blank?
+
+      response.headers["Cache-Control"] = "no-store"
+      unless Studio::HealthReport.authorized?(request.authorization)
+        response.headers["WWW-Authenticate"] = 'Bearer realm="studio-health-report"'
+        return render(json: { error: "unauthorized" }, status: :unauthorized)
+      end
+
+      window = begin
+        Studio::HealthReport.window_for(params[:ending].presence)
+      rescue ArgumentError
+        return render(json: { error: "ending must be an ISO 8601 time" }, status: :bad_request)
+      end
+
+      render json: Studio::HealthReport.payload(Studio::HealthReport.build(window: window))
+    rescue StandardError => e
+      # build already turns a failing SOURCE into a section's `failure`; this is
+      # anything else. Logged as an ErrorLog row, answered as JSON, never HTML.
+      Studio::HealthReport.capture(e)
+      render json: { error: "health report failed" }, status: :internal_server_error
+    end
+  end
+end

data/lib/studio/health_report.rb

@@ -6,6 +6,10 @@ require "active_support/core_ext/module/attribute_accessors"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/object/try"
 require "active_support/core_ext/string/filters"
+require "active_support/security_utils"
+require "digest"
+require "time"
+require_relative "version"
 
 # The daily application health report: signups, errors and (optionally) contact
 # messages from the last day, emailed at 07:00 in the app's zone. The full
@@ -48,8 +52,20 @@ module Studio
   #   config.health_report_contacts = ->(window) { ContactSubmission.where(created_at: window) }
   mattr_accessor :health_report_contacts, default: nil
 
+  # The bearer token the hub presents to GET /_studio/health_report, the JSON
+  # copy of this report that McRitchie Studio pulls from every app at 07:00 and
+  # posts to Discord. nil or blank falls through to ENV["STUDIO_HEALTH_TOKEN"],
+  # read on every request; blank there too means the endpoint answers 404.
+  mattr_writer :health_report_token, default: nil
+
+  def self.health_report_token
+    class_variable_get(:@@health_report_token).presence || ENV.fetch(HealthReport::TOKEN_ENV_KEY, nil).presence
+  end
+
   module HealthReport
     ENV_KEY = "STUDIO_HEALTH_REPORT_TO"
+    TOKEN_ENV_KEY = "STUDIO_HEALTH_TOKEN"
+    SCHEMA = 1         # the JSON contract's version; bump on a breaking change
     LISTED = 10        # names shown under a count; the count is always whole
     ERROR_GROUPS = 15  # distinct errors shown; the rest are counted as "more"
 
@@ -131,6 +147,65 @@ module Studio
       "#{count} #{count == 1 ? noun : "#{noun}s"}"
     end
 
+    # ---- the JSON endpoint (Studio::HealthReportsController) ---------------
+
+    # Does this Authorization header carry the configured token? false when no
+    # token is configured. Both sides are digested before the constant-time
+    # compare, so neither the token's bytes nor its length leak through timing.
+    def authorized?(authorization, token: Studio.health_report_token)
+      return false if token.blank?
+
+      presented = authorization.to_s[/\ABearer[ ]+(\S+)\s*\z/i, 1]
+      return false if presented.nil?
+
+      ActiveSupport::SecurityUtils.secure_compare(Digest::SHA256.hexdigest(presented),
+                                                  Digest::SHA256.hexdigest(token.to_s))
+    end
+
+    # The window the endpoint reports: the day ENDING at `ending` (an ISO 8601
+    # time), else the day the job would report now. Raises ArgumentError on a
+    # value that is not ISO 8601, which the controller answers with a 400.
+    def window_for(ending, now: Time.now)
+      return window(now) if ending.nil?
+
+      window_ending(Time.iso8601(ending.to_s))
+    end
+
+    SECTION_KEYS = %i[signups errors contacts].freeze
+
+    # The report as the hub reads it. COUNTS ONLY, by construction: a Section's
+    # `items` (names and emails) never reach this hash, so no signup or contact
+    # detail leaves the app. Error groups carry the class and the truncated
+    # message the email already shows.
+    def payload(report)
+      {
+        schema: SCHEMA,
+        app: report.app_name.to_s,
+        engine_version: Studio::VERSION,
+        window: { begin: iso(report.window.begin), end: iso(report.window.end), label: report.window_label },
+        quiet: report.quiet?,
+        sections: SECTION_KEYS.filter_map do |key|
+          section = report.public_send(key)
+          next unless section
+
+          { key: key.to_s, title: section.title, count: section.count.to_i, failure: section.failure }
+        end,
+        error_kinds: report.error_kinds.to_i,
+        error_groups: Array(report.error_groups).map do |group|
+          { error_class: group.error_class, message: scrub(group.message), count: group.count.to_i,
+            first_seen: iso(group.first_seen), last_seen: iso(group.last_seen) }
+        end
+      }
+    end
+
+    def iso(time) = time&.iso8601
+
+    EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/
+
+    # An exception message can quote the address it choked on ("no account for
+    # ann@example.com"). The email may show it; the JSON leaving the app may not.
+    def scrub(message) = message.to_s.gsub(EMAIL, "[email]")
+
     # ---- gathering (needs the host's database) ------------------------------
 
     def build(window: self.window(Time.now))

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.108.0.rc1"
+  VERSION = "0.108.0.rc2"
 end

data/lib/studio.rb

@@ -1447,6 +1447,14 @@ module Studio
       get  "auth/:provider/callback", to: "omniauth_callbacks#create"
       get  "auth/failure", to: "omniauth_callbacks#failure"
 
+      # The daily health report as JSON, for the hub's central 07:00 pull
+      # (Studio::HealthReportsController). Drawn in EVERY environment, production
+      # included: the controller is the gate, answering 404 until the app names
+      # a token (Studio.health_report_token / STUDIO_HEALTH_TOKEN) and 401 to a
+      # request that does not present it.
+      get "_studio/health_report", to: "studio/health_reports#show", as: :studio_health_report,
+          defaults: { format: :json }
+
       # Developer-desk tools. Drawn outside production, and each controller
       # re-checks Studio.local_tool_enabled? per request (loopback only) — the
       # route being absent is the outer gate, not the only one.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.108.0.rc1
+  version: 0.108.0.rc2
 platform: ruby
 authors:
 - Alex McRitchie
@@ -398,6 +398,7 @@ files:
 - app/controllers/studio/component_previews_controller.rb
 - app/controllers/studio/emails_controller.rb
 - app/controllers/studio/geo_settings_controller.rb
+- app/controllers/studio/health_reports_controller.rb
 - app/controllers/studio/knowledge_docs_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb