solid_objects 0.12.1 → 0.13.0

data/lib/solid_objects/web/helpers.rb

@@ -0,0 +1,227 @@
+# rbs_inline: enabled
+
+require "json"
+require "rack/utils"
+
+module SolidObjects
+  class Web
+    # The methods a view may call. Everything a template prints goes through
+    # `h`, because an actor id, an operation name, and an exception message are
+    # all application supplied strings that reach this page unchanged.
+    module Helpers
+      # Only these survive a page link. A filter an operator set stays set when
+      # they turn the page; anything else the query string carries does not
+      # come back.
+      FORWARDED_PARAMS = %w[actor_type actor_id status per_page].freeze
+      TRUNCATION_LIMIT = 2_000
+
+      # @rbs (untyped) -> String
+      def h(text)
+        ::Rack::Utils.escape_html(text.to_s)
+      end
+
+      # @rbs () -> String
+      def root_path
+        env["SCRIPT_NAME"].to_s
+      end
+
+      # @rbs (String) -> String
+      def path_to(path)
+        "#{root_path}#{path}"
+      end
+
+      # @rbs () -> String
+      def current_path
+        request.path_info
+      end
+
+      # @rbs (String) -> bool
+      def current_tab?(path)
+        return current_path == "/" if path == "/"
+
+        current_path.start_with?(path)
+      end
+
+      # @rbs () -> Hash[String, String]
+      def tabs
+        Web.tabs
+      end
+
+      # @rbs () -> String?
+      def csp_nonce
+        env[Web::NONCE_KEY]
+      end
+
+      # @rbs () -> String
+      def csrf_tag
+        %(<input type="hidden" name="authenticity_token" value="#{h(env[Web::CSRF_TOKEN_KEY])}" />)
+      end
+
+      # @rbs (String) -> String
+      def form_to(path)
+        %(<form method="post" action="#{h(path_to(path))}">#{csrf_tag})
+      end
+
+      # @rbs (untyped) -> String
+      def relative_time(time)
+        return "&mdash;" unless time
+
+        stamp = time.getutc.iso8601
+        %(<time datetime="#{stamp}" title="#{stamp}">#{h(stamp)}</time>)
+      end
+
+      # @rbs (untyped) -> String
+      def number(value)
+        h(value.to_i.to_s.reverse.scan(/\d{1,3}/).join(",").reverse)
+      end
+
+      # @rbs (Numeric?) -> String
+      def duration(seconds)
+        return "&mdash;" unless seconds
+
+        return "#{h(format("%.3f", seconds))} s" if seconds < 60
+
+        h("#{(seconds / 60).floor} min #{(seconds % 60).round} s")
+      end
+
+      # @rbs (untyped, ?Integer) -> String
+      def json_block(value)
+        return "&mdash;" if value.nil?
+
+        %(<pre class="payload">#{h(truncate(JSON.pretty_generate(value)))}</pre>)
+      rescue JSON::GeneratorError, TypeError
+        %(<pre class="payload">#{h(truncate(value.inspect))}</pre>)
+      end
+
+      # @rbs (String, ?Integer) -> String
+      def truncate(text, limit = TRUNCATION_LIMIT)
+        return text if text.length <= limit
+
+        "#{text[0, limit]}…"
+      end
+
+      # @rbs (String?) -> String
+      def status_label(status)
+        %(<span class="status status-#{h(status)}">#{h(status)}</span>)
+      end
+
+      # @rbs (untyped) -> String
+      def actor_label(record)
+        "#{h(record.actor_type)} / #{h(record.actor_id)}"
+      end
+
+      # @rbs (untyped) -> String
+      def instance_link(instance)
+        %(<a href="#{h(path_to("/instances/#{instance.id}"))}">#{actor_label(instance)}</a>)
+      end
+
+      # @rbs (?Hash[String, untyped]) -> String
+      def query_string(overrides = {})
+        merged = FORWARDED_PARAMS
+          .to_h { |name| [ name, url_params(name) ] }
+          .merge(overrides.transform_keys(&:to_s))
+          .reject { |_name, value| value.nil? || value.to_s.empty? }
+        return "" if merged.empty?
+
+        "?#{merged.map { |name, value| "#{::Rack::Utils.escape(name)}=#{::Rack::Utils.escape(value.to_s)}" }.join("&")}"
+      end
+
+      # @rbs (?Hash[String, untyped]) -> String
+      def page_link(overrides = {})
+        h("#{path_to(current_path)}#{query_string(overrides)}")
+      end
+
+      # @rbs (Instance) -> String
+      def lease_state(instance)
+        return "paused" if instance.paused_at
+        return "idle" unless instance.activation_owner_id
+        return "idle" unless instance.activation_expires_at
+
+        (instance.activation_expires_at > statistics.now) ? "activated" : "expired"
+      end
+
+      # @rbs () -> Statistics
+      def statistics
+        @statistics ||= Statistics.new
+      end
+
+      # @rbs (untyped) -> Paginator
+      def paginate(relation)
+        Paginator.new(relation:, page: url_params("page"), per_page: url_params("per_page"))
+      end
+
+      # An unrecognized filter falls back to the default rather than returning
+      # nothing, so a hand edited query string cannot make a page look empty.
+      # @rbs (Array[String], ?default: String?) -> String?
+      def filter_value(allowed, default: nil)
+        value = url_params("status")
+        allowed.include?(value) ? value : default
+      end
+
+      # @rbs () -> Instance
+      def find_instance
+        instance = Instance.find_by(id: route_params(:id))
+        halt(404) unless instance
+
+        instance
+      end
+
+      # @rbs () -> untyped
+      def filtered_instances
+        relation = Instance.order(updated_at: :desc, id: :desc)
+        actor_type = url_params("actor_type")
+        relation = relation.where(actor_type:) unless actor_type.to_s.empty?
+        actor_id = url_params("actor_id")
+        return relation if actor_id.to_s.empty?
+
+        relation.where(
+          Instance.arel_table[:actor_id].matches("%#{Instance.sanitize_sql_like(actor_id)}%")
+        )
+      end
+
+      # @rbs (String) -> untyped
+      def mailbox_messages(membership)
+        membership_model = (membership == "claimed") ? ClaimedMessage : ReadyMessage
+        Message
+          .where(id: membership_model.select(:message_id))
+          .order(available_at: :asc, id: :asc)
+      end
+
+      # Chart data travels in an attribute rather than an inline script block,
+      # so the page needs no script-src exception and an actor type cannot
+      # close the attribute and open a tag.
+      #
+      # The container is not decoration. Chart.js measures a responsive canvas
+      # against its parent, so the parent has to have a height of its own; a
+      # panel that sizes to its children would grow a little on every redraw.
+      # @rbs (String, untyped) -> String
+      def chart(name, values)
+        return "" unless Web.charts?
+
+        %(<div class="chart-frame"><canvas data-chart="#{h(name)}" ) +
+          %(data-chart-values='#{h(JSON.generate(values))}'></canvas></div>)
+      end
+
+      # A vendored copy is a path below the mount; a CDN copy is an absolute
+      # URL and is left alone.
+      # @rbs () -> String
+      def chart_library_source
+        url = Web.chart_library_url.to_s
+        url.include?("//") ? url : path_to(url)
+      end
+
+      # @rbs () -> String
+      def chart_library_integrity_attributes
+        integrity = Web.chart_library_integrity
+        return "" unless integrity
+
+        %( integrity="#{h(integrity)}" crossorigin="anonymous" referrerpolicy="no-referrer")
+      end
+
+      # @rbs () -> String
+      def environment_name
+        ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      end
+    end
+  end
+end

data/lib/solid_objects/web/paginator.rb

@@ -0,0 +1,64 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Web
+    # Counts and slices one relation. The page size is clamped because the page
+    # number and the page size both arrive from the query string, and an
+    # operator page that accepts an unbounded limit is a denial of service
+    # against the database the actors run on.
+    class Paginator
+      DEFAULT_PER_PAGE = 25
+      MAXIMUM_PER_PAGE = 200
+
+      # @rbs @page: Integer
+      # @rbs @per_page: Integer
+      # @rbs @total: Integer
+      # @rbs @records: Array[untyped]
+
+      attr_reader :page, :per_page, :total, :records
+
+      # @rbs (relation: untyped, ?page: String?, ?per_page: String?) -> void
+      def initialize(relation:, page: nil, per_page: nil)
+        @per_page = bounded(per_page, default: DEFAULT_PER_PAGE, maximum: MAXIMUM_PER_PAGE)
+        @total = relation.count
+        @page = bounded(page, default: 1, maximum: last_page)
+        @records = relation.offset((@page - 1) * @per_page).limit(@per_page).to_a
+      end
+
+      # @rbs () -> Integer
+      def last_page
+        [ (total.to_f / per_page).ceil, 1 ].max
+      end
+
+      # @rbs () -> Integer?
+      def previous_page
+        (page > 1) ? page - 1 : nil
+      end
+
+      # @rbs () -> Integer?
+      def next_page
+        (page < last_page) ? page + 1 : nil
+      end
+
+      # @rbs () -> Integer
+      def first_record
+        total.zero? ? 0 : ((page - 1) * per_page) + 1
+      end
+
+      # @rbs () -> Integer
+      def last_record
+        [ page * per_page, total ].min
+      end
+
+      private
+
+      # @rbs (String?, default: Integer, maximum: Integer) -> Integer
+      def bounded(value, default:, maximum:)
+        requested = Integer(value.to_s, 10, exception: false)
+        return default unless requested&.positive?
+
+        [ requested, maximum ].min
+      end
+    end
+  end
+end

data/lib/solid_objects/web/route.rb

@@ -0,0 +1,55 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Web
+    class Route
+      # A named segment stops at the next slash, so `/instances/:id` never
+      # swallows `/instances/1/pause` and route order cannot hide a page.
+      NAMED_SEGMENT = %r{/([^/]*):([^.:$/]+)}
+      SEGMENT_CAPTURE = '/\1(?<\2>[^$/]+)'
+
+      # @rbs @matcher: String | Regexp
+      # @rbs @request_method: String
+      # @rbs @pattern: String
+      # @rbs @policy: Hash[Symbol, String]
+      # @rbs @handler: Proc
+
+      attr_reader :request_method, :pattern, :policy, :handler
+
+      # @rbs (request_method: String, pattern: String, policy: Hash[Symbol, String], handler: Proc) -> void
+      def initialize(request_method:, pattern:, policy:, handler:)
+        @request_method = request_method
+        @pattern = pattern
+        @policy = policy
+        @handler = handler
+        @matcher = compile(pattern)
+      end
+
+      # @rbs (String) -> bool
+      def match?(path)
+        return @matcher == path if @matcher.is_a?(String)
+
+        @matcher.match?(path)
+      end
+
+      # @rbs (String) -> Hash[Symbol, String?]
+      def capture(path)
+        return {} if @matcher.is_a?(String)
+
+        match = @matcher.match(path)
+        return {} unless match
+
+        match.named_captures.transform_keys(&:to_sym)
+      end
+
+      private
+
+      # @rbs (String) -> (String | Regexp)
+      def compile(pattern)
+        return pattern unless pattern.match?(NAMED_SEGMENT)
+
+        Regexp.new("\\A#{pattern.gsub(NAMED_SEGMENT, SEGMENT_CAPTURE)}\\z")
+      end
+    end
+  end
+end

data/lib/solid_objects/web/router.rb

@@ -0,0 +1,46 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Web
+    # Declares the pages of the dashboard. Every route carries the
+    # administration policy it needs, and a route declared without one raises
+    # at load time. A new page therefore cannot reach the database before an
+    # application has said who may read it.
+    module Router
+      # @rbs (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def head(path, policy: nil, &handler)
+        route("HEAD", path, policy:, &handler)
+      end
+
+      # @rbs (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def get(path, policy: nil, &handler)
+        route("GET", path, policy:, &handler)
+      end
+
+      # @rbs (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def post(path, policy: nil, &handler)
+        route("POST", path, policy:, &handler)
+      end
+
+      # @rbs (String, String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def route(request_method, path, policy: nil, &handler)
+        raise ArgumentError, "route #{path} requires an authorization policy" unless policy
+        raise ArgumentError, "route #{path} requires a handler" unless handler
+        raise ArgumentError, "route #{path} requires a policy action" unless policy[:action]
+        raise ArgumentError, "route #{path} requires a policy resource" unless policy[:resource]
+
+        routes[request_method] << Route.new(request_method:, pattern: path, policy:, handler:)
+      end
+
+      # @rbs () -> Hash[String, Array[Route]]
+      def routes
+        @routes ||= Hash.new { |store, request_method| store[request_method] = [] }
+      end
+
+      # @rbs (String, String) -> Route?
+      def match(request_method, path)
+        routes[request_method].find { |route| route.match?(path) }
+      end
+    end
+  end
+end

data/lib/solid_objects/web/statistics.rb

@@ -0,0 +1,78 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Web
+    # The counts behind the dashboard and behind `GET /stats`. Both read the
+    # same object, so the polled JSON and the rendered page can never disagree
+    # about what a number means.
+    class Statistics
+      EFFECT_STATUSES = %w[pending processing completed dead].freeze
+      BROADCAST_STATUSES = %w[pending processing delivered dead].freeze
+      REMINDER_STATUSES = %w[scheduled paused completed].freeze
+      PROCESS_STATES = %w[running draining stopped].freeze
+
+      # @rbs @now: Time
+
+      attr_reader :now
+
+      # @rbs (?now: Time) -> void
+      def initialize(now: SolidObjects.database_adapter.database_now)
+        @now = now
+      end
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_h
+        {
+          instances:,
+          mailbox:,
+          effects: grouped(Effect, :status, EFFECT_STATUSES),
+          broadcasts: grouped(Broadcast, :status, BROADCAST_STATUSES),
+          reminders:,
+          dead_letters: { total: DeadLetter.count },
+          processes: grouped(Process, :shutdown_state, PROCESS_STATES),
+          server_time: now.utc.iso8601
+        }
+      end
+
+      # @rbs () -> Hash[Symbol, Integer]
+      def instances
+        {
+          total: Instance.count,
+          paused: Instance.where.not(paused_at: nil).count,
+          activated: Instance.where(activation_expires_at: now..).count
+        }
+      end
+
+      # The oldest ready message that is already due is the queue latency of
+      # this runtime: how far behind the workers are, in seconds.
+      # @rbs () -> Hash[Symbol, untyped]
+      def mailbox
+        due = ReadyMessage.where(available_at: ..now)
+        oldest = due.minimum(:available_at)
+        {
+          ready: ReadyMessage.count,
+          due: due.count,
+          claimed: ClaimedMessage.count,
+          latency: oldest ? (now - oldest).round(3) : 0.0
+        }
+      end
+
+      # @rbs () -> Hash[Symbol, Integer]
+      def reminders
+        grouped(Reminder, :status, REMINDER_STATUSES).merge(
+          due: Reminder.where(status: "scheduled", next_run_at: ..now).count
+        )
+      end
+
+      private
+
+      # A status the schema allows but the table does not currently hold still
+      # reports zero, so a row of counts keeps the same shape between polls.
+      # @rbs (untyped, Symbol, Array[String]) -> Hash[Symbol, Integer]
+      def grouped(model, column, statuses)
+        counts = model.group(column).count
+        statuses.to_h { |status| [ status.to_sym, counts.fetch(status, 0) ] }
+      end
+    end
+  end
+end

data/lib/solid_objects/web.rb

@@ -0,0 +1,222 @@
+# rbs_inline: enabled
+
+require "erb"
+require "json"
+require "securerandom"
+require "uri"
+require "rack"
+require "rack/builder"
+require "rack/static"
+
+require "solid_objects"
+require "solid_objects/web/route"
+require "solid_objects/web/router"
+require "solid_objects/web/statistics"
+require "solid_objects/web/paginator"
+require "solid_objects/web/helpers"
+require "solid_objects/web/action"
+require "solid_objects/web/csrf_protection"
+require "solid_objects/web/application"
+
+module SolidObjects
+  # An operator dashboard for the actor runtime, served as a Rack application:
+  #
+  #   Rails.application.routes.draw do
+  #     mount SolidObjects::Web => "/solid_objects"
+  #   end
+  #
+  # It is deliberately not loaded by `require "solid_objects"`. A worker
+  # process must not carry a web stack, and an application that never mounts
+  # the dashboard must not pay for it.
+  #
+  # Every page asks `configuration.authorize_administration` first. That block
+  # denies by default, so a mount alone exposes nothing until an application
+  # states who may read it.
+  class Web
+    ROOT = File.expand_path("../../web", __dir__)
+    VIEWS = File.join(ROOT, "views")
+    ASSETS = File.join(ROOT, "assets")
+
+    NONCE_KEY = "solid_objects.content_security_policy_nonce"
+    CSRF_TOKEN_KEY = "solid_objects.csrf_token"
+    NONCE_BYTES = 16
+    ASSET_CACHE_SECONDS = 86_400
+    TEMPLATE_NAME = /\A_?[a-z][a-z0-9_]*\z/
+
+    # The dashboard charts need a charting library, and this one is fetched
+    # from a public CDN with a subresource integrity hash, so a compromised CDN
+    # cannot substitute other code. A deployment with no outbound network
+    # access should vendor the file and point `chart_library_url` at it, or set
+    # that to nil to render the dashboard without charts.
+    CHART_LIBRARY_URL = "https://cdn.jsdelivr.net/npm/chart.js@4.5.0/dist/chart.umd.min.js"
+    CHART_LIBRARY_INTEGRITY = "sha384-XcdcwHqIPULERb2yDEM4R0XaQKU3YnDsrTmjACBZyfdVVqjh6xQ4/DCMd7XLcA6Y"
+
+    DEFAULT_TABS = {
+      "Dashboard" => "/",
+      "Instances" => "/instances",
+      "Mailbox" => "/mailbox",
+      "Reminders" => "/reminders",
+      "Effects" => "/effects",
+      "Broadcasts" => "/broadcasts",
+      "Dead letters" => "/dead_letters",
+      "Processes" => "/processes"
+    }.freeze
+
+    LOCK = Mutex.new
+
+    class << self
+      # A path below the mount serves a vendored copy; an absolute URL is
+      # fetched from that host and is named in the content security policy.
+      # nil renders the dashboard without charts.
+      # @rbs @chart_library_url: String?
+      # @rbs @chart_library_integrity: String?
+      attr_writer :chart_library_url, :chart_library_integrity
+
+      # @rbs () -> String?
+      def chart_library_url
+        defined?(@chart_library_url) ? @chart_library_url : CHART_LIBRARY_URL
+      end
+
+      # @rbs () -> String?
+      def chart_library_integrity
+        defined?(@chart_library_integrity) ? @chart_library_integrity : CHART_LIBRARY_INTEGRITY
+      end
+
+      # @rbs () -> bool
+      def charts?
+        !chart_library_url.nil?
+      end
+
+      # The origin the content security policy has to allow. A vendored copy
+      # served from the mount has none, so the policy stays at 'self'.
+      # @rbs () -> String?
+      def chart_library_origin
+        url = chart_library_url
+        return nil unless url&.include?("//")
+
+        uri = URI.parse(url)
+        return nil unless uri.scheme && uri.host
+
+        "#{uri.scheme}://#{uri.host}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      # @rbs () -> Hash[String, String]
+      def tabs
+        @tabs ||= DEFAULT_TABS.dup
+      end
+
+      # Searched in order, so an extension directory added first wins over the
+      # packaged one and an application can replace a single page.
+      # @rbs () -> Array[String]
+      def views
+        @views ||= [ VIEWS ]
+      end
+
+      # @rbs () -> Array[[Array[untyped], Proc?]]
+      def middlewares
+        @middlewares ||= []
+      end
+
+      # The built stack is memoized, so a middleware added after the first
+      # request would otherwise be dropped without a word.
+      # @rbs (*untyped) ?{ () -> untyped } -> void
+      def use(*arguments, &block)
+        middlewares << [ arguments, block ]
+        LOCK.synchronize { @application = nil }
+      end
+
+      # Adds pages to the dashboard. The extension receives the application
+      # class and declares its own routes on it, which means its routes carry
+      # an authorization policy like every other route.
+      #
+      # @rbs (untyped, tab: String, path: String, ?views: String?) -> void
+      def register(extension, tab:, path:, views: nil)
+        if views
+          self.views.unshift(views)
+          # A template compiled before this call resolved against the old
+          # search path, so a replacement view would never be reached.
+          LOCK.synchronize { @templates = {} }
+        end
+        tabs[tab] = path
+        extension.registered(Application)
+      end
+
+      # @rbs (Symbol) -> untyped
+      def template(name)
+        LOCK.synchronize do
+          templates[name] ||= ERB.new(File.read(template_path(name)), trim_mode: "-")
+        end
+      end
+
+      # @rbs () -> void
+      def reset!
+        LOCK.synchronize { @templates = {} }
+        @tabs = nil
+        @views = nil
+        @middlewares = nil
+        @application = nil
+        remove_instance_variable(:@chart_library_url) if defined?(@chart_library_url)
+        remove_instance_variable(:@chart_library_integrity) if defined?(@chart_library_integrity)
+      end
+
+      # @rbs (Hash[String, untyped]) -> Array[untyped]
+      def call(env)
+        application.call(env)
+      end
+
+      # @rbs () -> Web
+      def application
+        LOCK.synchronize { @application ||= new }
+      end
+
+      private
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def templates
+        @templates ||= {}
+      end
+
+      # A template name never comes from a request, and this keeps it that way
+      # rather than trusting every future caller to know it.
+      # @rbs (Symbol) -> String
+      def template_path(name)
+        raise ArgumentError, "invalid template name" unless name.to_s.match?(TEMPLATE_NAME)
+
+        found = views.lazy.map { |directory| File.join(directory, "#{name}.erb") }.find { |path| File.exist?(path) }
+        found || raise(ArgumentError, "no template named #{name}")
+      end
+    end
+
+    # @rbs (Hash[String, untyped]) -> Array[untyped]
+    def call(env)
+      env[NONCE_KEY] = SecureRandom.base64(NONCE_BYTES)
+      app.call(env)
+    end
+
+    # @rbs () -> untyped
+    def app
+      @app ||= build
+    end
+
+    private
+
+    # @rbs () -> untyped
+    def build
+      assets = ASSETS
+      extra = self.class.middlewares
+
+      ::Rack::Builder.new do
+        use ::Rack::Static,
+          urls: [ "/stylesheets", "/javascripts" ],
+          root: assets,
+          cascade: true,
+          header_rules: [ [ :all, { "cache-control" => "private, max-age=#{ASSET_CACHE_SECONDS}" } ] ]
+        extra.each { |arguments, block| use(*arguments, &block) }
+        use CsrfProtection
+        run Application.new
+      end
+    end
+  end
+end