closeyourit-ruby 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8e0fc4eed9289e8fbb3ac2b93e6bcf71c950200b24483be93ca9b03cbb5edf5
-  data.tar.gz: bec0fc92de3a19b85caa500e41953726a1693ca8f757cd98022b8b5287e83f76
+  metadata.gz: c46a549b542395326541c9def86cc019d5cd9620fef9c8f4584c90543ca1b179
+  data.tar.gz: 5ac2011a99d7be1d09a751334832154cf1d23765fe8527333adecda9862f50c1
 SHA512:
-  metadata.gz: f39ecd3584260bf7257fb8efc7fcf12222a2adec2fa2d1ba7ff3a59e368ae6c6e52921d5c83dda516c588946d718c4407aa934d6f495cfd9269621226fd58555
-  data.tar.gz: a634e8af76d32b12d1ffe210e73d3070c8059d15a55953caed9406d2c8db7fbeaac0f34bf800ee049bf9b4cdcb737d0239f3968978b970bb1175f42dfca3f0c5
+  metadata.gz: 95b4271a533b85cb3d9cf0bf718f08b07a87ce180cd00c03fcc82c30cf24047bc240d1ad572be09bac04402b00ecb728e87250905d28666d443fd22d65111981
+  data.tar.gz: 9210728ff21f26c59b49a31007a068f1f3dd334214c2f67f5eb7aa9ce7b418ecdec3f6c1c9cc6b2935e950cded2252ebc417183c3c4518b7d8a4ca130d9a9a44

data/README.md

@@ -401,6 +401,40 @@ ActiveJob dentro Sidekiq è osservato una sola volta quando il subscriber Active
 Sampling, disabilitazione o perdita del transport impediscono di considerare questi log un censimento.
 Il raggruppamento backend v1 separa framework, nome, coda e misura; i gruppi legacy restano intatti.
 
+## Open Dashboard (opt-in)
+
+Il servizio mostra i suoi numeri (utenti, abbonamenti, incassi…) a chi ha la chiave, su
+`GET /open-dashboard`. Lo standard completo: contratto `contracts/open-dashboard/v1`.
+
+```ruby
+# config/initializers/open_dashboard.rb
+CloseYourIt::OpenDashboard.configure do |od|
+  od.token  = ENV["OPEN_DASHBOARD_TOKEN"] # without it the route does not exist
+  od.name   = "scontino"
+  od.app    = "scontino-rails"
+  od.url    = "https://scontino.it"
+  od.locale = "it"
+
+  od.metric "users.registered", label: "Utenti registrati", group: "Utenti", type: :count do |since|
+    { value: User.count, previous: User.where(created_at: ...since).count }
+  end
+
+  od.metric "revenue.mrr", label: "Incasso mensile ricorrente", group: "Incassi",
+            type: :money, currency: "EUR" do
+    Subscription.active.sum(:amount_cents)
+  end
+end
+```
+
+- `since` è l'inizio del periodo di confronto (`period:`, default `"30d"`; anche `1d`, `7d`, `90d`, `365d`).
+- Il blocco restituisce un numero, oppure `{ value:, previous: }`.
+- Tipi: `count` e `money` (interi; `money` in centesimi con `currency`), `percent` (0–100), `duration` (secondi).
+- `better: :down` per i numeri che vanno bene quando scendono.
+- Una metrica che solleva arriva come «non disponibile» e l'errore finisce in CloseYourIt; le altre restano.
+- I blocchi girano a ogni richiesta e chi legge aspetta al massimo 10 secondi: i numeri lenti vanno precalcolati.
+- Una dichiarazione sbagliata (chiave doppia, tipo sconosciuto, `money` senza valuta) blocca l'avvio.
+- Solo totali: mai dati di singole persone.
+
 ## Privacy & PII
 
 Privacy-by-default (`send_pii = false`). In sintesi:

data/lib/closeyourit/open_dashboard/metric.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module CloseYourIt
+  module OpenDashboard
+    # Raised at boot when the service declares a metric the standard does not allow.
+    class ConfigurationError < StandardError; end
+
+    # One metric of the Open Dashboard standard. Rules are checked when the service boots, so a bad
+    # declaration fails the deploy instead of producing an invalid response in production.
+    class Metric
+      TYPES = %w[count money percent duration].freeze
+      INTEGER_TYPES = %w[count money].freeze
+      PERIODS = { "1d" => 1, "7d" => 7, "30d" => 30, "90d" => 90, "365d" => 365 }.freeze
+      BETTER = %w[up down].freeze
+      KEY_FORMAT = /\A[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+\z/
+      CURRENCY_FORMAT = /\A[A-Z]{3}\z/
+      UNAVAILABLE = "unavailable"
+      SECONDS_PER_DAY = 86_400
+
+      attr_reader :key
+
+      def initialize(key, label:, group:, type:, currency: nil, period: "30d", better: nil, &block)
+        @key = key.to_s
+        @label = label.to_s
+        @group = group.to_s
+        @type = type.to_s
+        @currency = currency
+        @period = period.to_s
+        @better = better&.to_s
+        @block = block
+        validate!
+      end
+
+      # The block gets the start of the comparison period. A failure never breaks the other metrics:
+      # it is reported to CloseYourIt and the metric goes out as unavailable.
+      def to_h(now)
+        since = now - (PERIODS.fetch(@period) * SECONDS_PER_DAY)
+        identity.merge(values(@block.call(since)))
+      rescue StandardError => e
+        CloseYourIt.capture_exception(e, handled: true)
+        identity.merge(value: nil, error: UNAVAILABLE)
+      end
+
+      private
+
+      def identity
+        { key: @key, label: @label, group: @group, type: @type, currency: @currency, better: @better }.compact
+      end
+
+      def values(result)
+        return { value: number(result) } unless result.is_a?(Hash)
+
+        out = { value: number(result.fetch(:value)) }
+        out.merge!(previous: number(result[:previous]), period: @period) unless result[:previous].nil?
+        out
+      end
+
+      # Returns the value to emit: an Integer for count/money, a Float for percent/duration.
+      def number(value)
+        reject("value must be numeric") unless value.is_a?(Numeric)
+        reject("value must be finite") unless !value.respond_to?(:finite?) || value.finite?
+
+        normalised = INTEGER_TYPES.include?(@type) ? whole(value) : Float(value)
+        check_range(normalised)
+        normalised
+      end
+
+      def whole(value)
+        reject("#{@type} must be an integer") unless value == value.to_i
+
+        value.to_i
+      end
+
+      def check_range(value)
+        reject("count must not be negative") if @type == "count" && value.negative?
+        reject("percent must be between 0 and 100") if @type == "percent" && !value.between?(0, 100)
+        reject("duration must not be negative") if @type == "duration" && value.negative?
+      end
+
+      def reject(message)
+        raise TypeError, "open_dashboard metric #{@key}: #{message}"
+      end
+
+      def validate!
+        fail_with("key must be lowercase and dotted, e.g. users.registered") unless KEY_FORMAT.match?(@key)
+        fail_with("label is blank") if @label.strip.empty?
+        fail_with("group is blank") if @group.strip.empty?
+        fail_with("type must be one of #{TYPES.join(', ')}") unless TYPES.include?(@type)
+        validate_currency!
+        fail_with("period must be one of #{PERIODS.keys.join(', ')}") unless PERIODS.key?(@period)
+        fail_with("better must be up or down") if @better && !BETTER.include?(@better)
+        fail_with("a block computing the value is required") unless @block
+      end
+
+      def validate_currency!
+        if @type == "money"
+          fail_with("money needs an ISO 4217 currency, e.g. EUR") unless CURRENCY_FORMAT.match?(@currency.to_s)
+        elsif @currency
+          fail_with("currency is allowed only on money")
+        end
+      end
+
+      def fail_with(message)
+        raise ConfigurationError, "open_dashboard metric #{@key}: #{message}"
+      end
+    end
+  end
+end

data/lib/closeyourit/open_dashboard/middleware.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "openssl"
+
+module CloseYourIt
+  module OpenDashboard
+    # Pure Rack: answers GET /open-dashboard and passes everything else to the app. Without a token
+    # the request also goes to the app, so the route simply does not exist (404 from the app).
+    class Middleware
+      JSON_HEADERS = { "content-type" => "application/json", "cache-control" => "no-store" }.freeze
+      BEARER = "Bearer "
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        settings = OpenDashboard.settings
+        return @app.call(env) unless dashboard_request?(env) && settings&.enabled?
+        return [ 401, { "cache-control" => "no-store" }, [] ] unless authorized?(env["HTTP_AUTHORIZATION"], settings.token)
+
+        [ 200, JSON_HEADERS.dup, [ JSON.generate(Report.new(settings).to_h) ] ]
+      end
+
+      private
+
+      def dashboard_request?(env)
+        env["REQUEST_METHOD"] == "GET" && env["PATH_INFO"] == PATH
+      end
+
+      # Hashing both sides gives equal lengths, so the comparison time does not leak the token length.
+      def authorized?(header, token)
+        header = header.to_s
+        return false unless header.start_with?(BEARER)
+
+        OpenSSL.fixed_length_secure_compare(
+          Digest::SHA256.digest(header.delete_prefix(BEARER)),
+          Digest::SHA256.digest(token.to_s)
+        )
+      end
+    end
+  end
+end

data/lib/closeyourit/open_dashboard/report.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "time"
+
+module CloseYourIt
+  module OpenDashboard
+    # Builds the response body. Service identity comes from the same ENV as GET /version, so the
+    # dashboard and the deploy smoke test always agree on which build is live.
+    class Report
+      UNKNOWN = "unknown"
+
+      def initialize(settings, now: Time.now.utc)
+        @settings = settings
+        @now = now
+      end
+
+      def to_h
+        {
+          open_dashboard: SPEC_VERSION,
+          service: service,
+          locale: @settings.locale,
+          generated_at: @now.getutc.iso8601,
+          metrics: @settings.metrics.map { |metric| metric.to_h(@now) }
+        }
+      end
+
+      private
+
+      def service
+        {
+          name: @settings.name,
+          app: @settings.app,
+          version: present(ENV["APP_GIT_TAG"]) || UNKNOWN,
+          sha: present(ENV["APP_GIT_SHA"])&.slice(0, 7) || UNKNOWN,
+          environment: CloseYourIt.configuration.environment.to_s,
+          url: present(@settings.url)
+        }.compact
+      end
+
+      def present(value)
+        value.to_s.strip.empty? ? nil : value.to_s
+      end
+    end
+  end
+end

data/lib/closeyourit/open_dashboard/settings.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CloseYourIt
+  module OpenDashboard
+    # What the service declares in config/initializers/open_dashboard.rb.
+    class Settings
+      LOCALE_FORMAT = /\A[a-z]{2}(-[A-Z]{2})?\z/
+
+      attr_accessor :token, :name, :app, :url, :locale
+      attr_reader :metrics
+
+      def initialize
+        @metrics = []
+      end
+
+      def metric(key, **options, &block)
+        if @metrics.any? { |existing| existing.key == key.to_s }
+          raise ConfigurationError, "open_dashboard metric #{key}: duplicated key"
+        end
+
+        @metrics << Metric.new(key, **options, &block)
+      end
+
+      # No token means the feature is off: the route does not exist.
+      def enabled? = !token.to_s.strip.empty?
+
+      def validate!
+        %i[name app].each do |field|
+          raise ConfigurationError, "open_dashboard: #{field} is required" if public_send(field).to_s.strip.empty?
+        end
+        raise ConfigurationError, "open_dashboard: locale must look like it or en-US" unless LOCALE_FORMAT.match?(locale.to_s)
+        raise ConfigurationError, "open_dashboard: at most #{MAX_METRICS} metrics" if @metrics.size > MAX_METRICS
+      end
+    end
+  end
+end

data/lib/closeyourit/open_dashboard.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CloseYourIt
+  # Open Dashboard standard: GET /open-dashboard returns who the service is and its business
+  # numbers, behind a per-service token. Contract: contracts/open-dashboard/v1.
+  module OpenDashboard
+    SPEC_VERSION = "1.0"
+    PATH = "/open-dashboard"
+    MAX_METRICS = 50
+
+    class << self
+      # Kept separate from CloseYourIt.init: init rebuilds its configuration on every call, and the
+      # dashboard declaration must not disappear when telemetry is reconfigured.
+      def configure
+        candidate = Settings.new
+        yield candidate
+        candidate.validate!
+        @settings = candidate
+      end
+
+      attr_reader :settings
+
+      def reset!
+        @settings = nil
+      end
+    end
+  end
+end
+
+require_relative "open_dashboard/metric"
+require_relative "open_dashboard/settings"
+require_relative "open_dashboard/report"
+require_relative "open_dashboard/middleware"

data/lib/closeyourit/rails/railtie.rb

@@ -28,6 +28,16 @@ module CloseYourIt
         )
       end
 
+      # Open Dashboard (GET /open-dashboard). Inside CaptureExceptions, so a crash while building the
+      # report is reported like any other request error. Inert until the app calls
+      # CloseYourIt::OpenDashboard.configure with a token.
+      initializer "closeyourit.open_dashboard" do |app|
+        app.config.middleware.insert_after(
+          CloseYourIt::Rails::CaptureExceptions,
+          CloseYourIt::OpenDashboard::Middleware
+        )
+      end
+
       initializer "closeyourit.subscribe_slow_queries" do
         subscriber = CloseYourIt::Subscribers::SlowQuery.new
 

data/lib/closeyourit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CloseYourIt
-  VERSION = "0.12.1"
+  VERSION = "0.13.0"
 end

data/lib/closeyourit-ruby.rb

@@ -39,6 +39,7 @@ require_relative "closeyourit/rails/active_job_extension"
 require_relative "closeyourit/rails/error_subscriber"
 require_relative "closeyourit/sidekiq/error_handler"
 require_relative "closeyourit/sidekiq/job_metrics_middleware"
+require_relative "closeyourit/open_dashboard"
 
 # CloseYourIt — telemetry client (errors + slow query/method statistics)
 # that sends events to the CloseYourIt ingest endpoint.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: closeyourit-ruby
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Alessio Bussolari
@@ -67,6 +67,11 @@ files:
 - lib/closeyourit/log_buffer.rb
 - lib/closeyourit/log_device.rb
 - lib/closeyourit/monitor.rb
+- lib/closeyourit/open_dashboard.rb
+- lib/closeyourit/open_dashboard/metric.rb
+- lib/closeyourit/open_dashboard/middleware.rb
+- lib/closeyourit/open_dashboard/report.rb
+- lib/closeyourit/open_dashboard/settings.rb
 - lib/closeyourit/performance/request_profile.rb
 - lib/closeyourit/performance/rollup.rb
 - lib/closeyourit/rails/active_job_extension.rb