solid_objects 0.12.0 → 0.13.0

data/lib/solid_objects/web/application.rb

@@ -0,0 +1,239 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  class Web
+    # The pages. Each route states the administration policy it needs, and
+    # `call` asks that policy before the handler runs, so a page cannot read
+    # the actor tables on behalf of an unauthorized request.
+    class Application
+      extend Router
+
+      SCRIPT_PLACEHOLDER = "!script-src!"
+      CONTENT_SECURITY_POLICY = [
+        "default-src 'self'",
+        "base-uri 'self'",
+        "form-action 'self'",
+        "frame-ancestors 'none'",
+        "img-src 'self' data:",
+        "style-src 'self'",
+        "script-src #{SCRIPT_PLACEHOLDER}",
+        "connect-src 'self'",
+        "object-src 'none'"
+      ].join("; ").freeze
+
+      MAILBOX_MEMBERSHIPS = %w[ready claimed].freeze
+      RECENT_LIMIT = 10
+      CHART_TYPE_LIMIT = 12
+
+      head "/", policy: { action: "index", resource: "dashboard" } do
+        # The cheapest liveness check available: it proves the dashboard can
+        # reach the database the actors run on, and returns no body.
+        ReadyMessage.count
+        ""
+      end
+
+      get "/", policy: { action: "index", resource: "dashboard" } do
+        @statistics = statistics.to_h
+        @processes = Process.order(last_heartbeat_at: :desc).limit(RECENT_LIMIT)
+        @dead_letters = DeadLetter.order(last_failed_at: :desc, id: :desc).limit(RECENT_LIMIT)
+        # The only chart that costs its own query, and the only one the poller
+        # cannot refresh, because the other two read what `/stats` already
+        # returns. Bounded so a runtime with many actor types draws a readable
+        # chart rather than every type it has ever seen.
+        @instances_by_type = Instance
+          .group(:actor_type)
+          .order(Arel.sql("COUNT(*) DESC"))
+          .limit(CHART_TYPE_LIMIT)
+          .count
+        erb(:dashboard)
+      end
+
+      get "/stats", policy: { action: "index", resource: "dashboard" } do
+        json(statistics.to_h)
+      end
+
+      get "/instances", policy: { action: "index", resource: "instances" } do
+        @paginator = paginate(filtered_instances)
+        # Suggestions come from the registry rather than a DISTINCT over the
+        # instances table, which no adapter can answer from an index. The field
+        # stays free text, so an actor type that is no longer registered is
+        # still reachable.
+        @actor_types = SolidObjects.registry.to_h.keys.sort
+        erb(:instances)
+      end
+
+      get "/instances/:id", policy: { action: "show", resource: "instances" } do
+        @instance = find_instance
+        @ready_messages = @instance.messages
+          .where(id: ReadyMessage.select(:message_id))
+          .order(sequence: :asc)
+          .limit(RECENT_LIMIT)
+        @claimed_messages = @instance.messages
+          .where(id: ClaimedMessage.select(:message_id))
+          .order(sequence: :asc)
+          .limit(RECENT_LIMIT)
+        @recent_messages = @instance.messages.order(sequence: :desc).limit(RECENT_LIMIT)
+        @reminders = Reminder.where(instance_id: @instance.id).order(next_run_at: :asc).limit(RECENT_LIMIT)
+        @effects = Effect.where(instance_id: @instance.id).order(id: :desc).limit(RECENT_LIMIT)
+        @broadcasts = Broadcast.where(instance_id: @instance.id).order(id: :desc).limit(RECENT_LIMIT)
+        @dead_letters = DeadLetter.where(instance_id: @instance.id).order(last_failed_at: :desc).limit(RECENT_LIMIT)
+        erb(:instance)
+      end
+
+      # Pausing stops the activation manager from claiming the instance again.
+      # A pass already in flight finishes its turn, and a synchronous caller
+      # waiting on this instance times out rather than being answered, so this
+      # is an operator brake and not a delivery guarantee.
+      post "/instances/:id/pause", policy: { action: "pause", resource: "instances" } do
+        instance = find_instance
+        instance.update!(paused_at: SolidObjects.database_adapter.database_now)
+        redirect("/instances/#{instance.id}")
+      end
+
+      post "/instances/:id/resume", policy: { action: "resume", resource: "instances" } do
+        instance = find_instance
+        instance.update!(paused_at: nil)
+        redirect("/instances/#{instance.id}")
+      end
+
+      get "/mailbox", policy: { action: "index", resource: "messages" } do
+        @membership = filter_value(MAILBOX_MEMBERSHIPS, default: "ready")
+        @paginator = paginate(mailbox_messages(@membership))
+        erb(:mailbox)
+      end
+
+      get "/messages/:id", policy: { action: "show", resource: "messages" } do
+        @message = Message.find_by(id: route_params(:id))
+        halt(404) unless @message
+        erb(:message)
+      end
+
+      get "/reminders", policy: { action: "index", resource: "reminders" } do
+        @status = filter_value(Statistics::REMINDER_STATUSES)
+        relation = Reminder.order(next_run_at: :asc, id: :asc)
+        @paginator = paginate(@status ? relation.where(status: @status) : relation)
+        erb(:reminders)
+      end
+
+      get "/effects", policy: { action: "index", resource: "effects" } do
+        @status = filter_value(Statistics::EFFECT_STATUSES)
+        relation = Effect.order(id: :desc)
+        @paginator = paginate(@status ? relation.where(status: @status) : relation)
+        erb(:effects)
+      end
+
+      get "/broadcasts", policy: { action: "index", resource: "broadcasts" } do
+        @status = filter_value(Statistics::BROADCAST_STATUSES)
+        relation = Broadcast.order(id: :desc)
+        @paginator = paginate(@status ? relation.where(status: @status) : relation)
+        erb(:broadcasts)
+      end
+
+      get "/dead_letters", policy: { action: "index", resource: "dead_letters" } do
+        @paginator = paginate(DeadLetter.order(last_failed_at: :desc, id: :desc))
+        erb(:dead_letters)
+      end
+
+      get "/dead_letters/:id", policy: { action: "show", resource: "dead_letters" } do
+        @dead_letter = DeadLetter.find_by(id: route_params(:id))
+        halt(404) unless @dead_letter
+        erb(:dead_letter)
+      end
+
+      # A retry re-enters the mailbox, which refuses work the runtime cannot
+      # accept: an actor class that no longer exists, a full mailbox, a payload
+      # over the cap. The operator who pressed the button is told which,
+      # instead of being handed a bare 500 from the Rack handler.
+      post "/dead_letters/:id/retry", policy: { action: "retry", resource: "dead_letters" } do
+        SolidObjects.dead_letters.retry(route_params(:id).to_i, authorization_context: self)
+        redirect("/dead_letters")
+      rescue Unauthorized
+        raise
+      rescue SolidObjects::Error => error
+        @dead_letter = DeadLetter.find_by(id: route_params(:id))
+        halt(404) unless @dead_letter
+        @error = "#{error.class.name.split("::").last}: #{error.message}"
+        status(422)
+        erb(:dead_letter)
+      end
+
+      get "/processes", policy: { action: "index", resource: "processes" } do
+        @status = filter_value(Statistics::PROCESS_STATES)
+        relation = Process.order(last_heartbeat_at: :desc)
+        @paginator = paginate(@status ? relation.where(shutdown_state: @status) : relation)
+        # Counted in one grouped query rather than once per row, because this
+        # page is read while the runtime is already under load.
+        @activated_counts = Instance
+          .where(activation_owner_id: @paginator.records.map(&:id))
+          .group(:activation_owner_id)
+          .count
+        erb(:processes)
+      end
+
+      # @rbs (Hash[String, untyped]) -> Array[untyped]
+      def call(env)
+        route = self.class.match(env["REQUEST_METHOD"].to_s, env["PATH_INFO"].to_s)
+        return not_found unless route
+
+        action = Action.new(env:, route:)
+        return forbidden unless authorized?(action)
+
+        respond(action, catch(:halt) { action.call })
+      rescue Unauthorized
+        forbidden
+      end
+
+      private
+
+      # @rbs (Action, untyped) -> Array[untyped]
+      def respond(action, result)
+        return result if result.is_a?(Array)
+
+        [ action.response_status, page_headers(action.env), [ result.to_s ] ]
+      end
+
+      # @rbs (Action) -> bool
+      def authorized?(action)
+        policy = action.route.policy
+        SolidObjects.configuration.authorize_administration.call(
+          action: policy.fetch(:action),
+          resource: policy.fetch(:resource),
+          resource_id: action.route_params(:id),
+          authorization_context: action
+        )
+      end
+
+      # @rbs (Hash[String, untyped]) -> Hash[String, String]
+      def page_headers(env)
+        {
+          "content-type" => "text/html; charset=utf-8",
+          "cache-control" => "private, no-store",
+          "content-security-policy" => content_security_policy(env),
+          "x-content-type-options" => "nosniff",
+          "referrer-policy" => "same-origin"
+        }
+      end
+
+      # The chart host is named only when one is configured, so a deployment
+      # that vendors the library or turns charts off never advertises a third
+      # party origin it does not use.
+      # @rbs (Hash[String, untyped]) -> String
+      def content_security_policy(env)
+        sources = [ "'self'", "'nonce-#{env[Web::NONCE_KEY]}'", Web.chart_library_origin ].compact
+        CONTENT_SECURITY_POLICY.sub(SCRIPT_PLACEHOLDER, sources.join(" "))
+      end
+
+      # The cascade header lets a host application serve its own 404 for a path
+      # below the mount that the dashboard does not define.
+      # @rbs () -> Array[untyped]
+      def not_found
+        [ 404, { "content-type" => "text/plain", "x-cascade" => "pass" }, [ "Not Found" ] ]
+      end
+
+      # @rbs () -> Array[untyped]
+      def forbidden
+        [ 403, { "content-type" => "text/plain" }, [ "Forbidden" ] ]
+      end
+    end
+  end
+end

data/lib/solid_objects/web/csrf_protection.rb

@@ -0,0 +1,130 @@
+# rbs_inline: enabled
+
+require "rack/request"
+require "rack/utils"
+require "securerandom"
+
+module SolidObjects
+  class Web
+    # A state changing request must carry the token of the session that asked
+    # for the form. The token a form receives is masked with a fresh one-time
+    # pad on every request, so the bytes on the wire differ each time and a
+    # compression side channel cannot recover the session token.
+    class CsrfProtection
+      SAFE_METHODS = %w[GET HEAD OPTIONS TRACE].freeze
+      TOKEN_BYTES = 32
+
+      MISSING_SESSION = <<~MESSAGE
+        SolidObjects::Web needs a Rack session for CSRF protection.
+
+        Mount it inside the application routes so the Rails session middleware runs first:
+
+          Rails.application.routes.draw do
+            mount SolidObjects::Web => "/solid_objects"
+          end
+
+        In a bare Rack application, run a session middleware before it:
+
+          use Rack::Session::Cookie, secret: ENV.fetch("SESSION_SECRET"), same_site: true
+          run SolidObjects::Web
+      MESSAGE
+
+      # @rbs (untyped) -> void
+      def initialize(app)
+        @app = app
+      end
+
+      # @rbs (Hash[String, untyped]) -> Array[untyped]
+      def call(env)
+        return forbidden unless accept?(env)
+
+        session = session!(env)
+        session[:csrf] ||= SecureRandom.base64(TOKEN_BYTES)
+        env[Web::CSRF_TOKEN_KEY] = mask(session[:csrf])
+        @app.call(env)
+      end
+
+      private
+
+      # @rbs (Hash[String, untyped]) -> bool
+      def accept?(env)
+        return true if SAFE_METHODS.include?(env["REQUEST_METHOD"])
+
+        valid?(env, ::Rack::Request.new(env).params["authenticity_token"])
+      end
+
+      # @rbs (Hash[String, untyped], String?) -> bool
+      def valid?(env, given)
+        return false if given.nil? || given.empty?
+
+        session = session!(env)
+        stored = session[:csrf]
+        return false if stored.nil?
+
+        token = decode(given)
+        return false unless token
+
+        # The secret is not rotated here. A page renders one Retry form per
+        # dead letter, and a browser keeps pages open in other tabs, so
+        # spending the secret on the first submission would answer 403 to
+        # every other form already rendered. Single use is not what a CSRF
+        # token provides: it proves the request came from a page this session
+        # was served, and the per-request mask below is what keeps the value
+        # on the wire from repeating.
+        matches?(token, stored)
+      end
+
+      # @rbs (String, String) -> bool
+      def matches?(token, stored)
+        candidate = case token.bytesize
+        when TOKEN_BYTES then token
+        when TOKEN_BYTES * 2 then unmask(token)
+        else return false
+        end
+
+        ::Rack::Utils.secure_compare(candidate, decode(stored).to_s)
+      end
+
+      # @rbs (String) -> String
+      def mask(token)
+        decoded = decode(token).to_s
+        pad = SecureRandom.random_bytes(decoded.bytesize)
+        encode(pad + exclusive_or(pad, decoded))
+      end
+
+      # @rbs (String) -> String
+      def unmask(masked)
+        half = masked.bytesize / 2
+        exclusive_or(masked[0, half].to_s, masked[half..].to_s)
+      end
+
+      # @rbs (String, String) -> String
+      def exclusive_or(left, right)
+        left.bytes.zip(right.bytes).map { |first, second| first ^ second.to_i }.pack("c*")
+      end
+
+      # @rbs (String) -> String
+      def encode(token)
+        [ token ].pack("m0").tr("+/", "-_")
+      end
+
+      # @rbs (String) -> String?
+      def decode(token)
+        decoded = token.tr("-_", "+/").unpack1("m0")
+        decoded.is_a?(String) ? decoded : nil
+      rescue ArgumentError
+        nil
+      end
+
+      # @rbs (Hash[String, untyped]) -> Hash[untyped, untyped]
+      def session!(env)
+        env["rack.session"] || raise(MISSING_SESSION)
+      end
+
+      # @rbs () -> Array[untyped]
+      def forbidden
+        [ 403, { "content-type" => "text/plain" }, [ "Forbidden" ] ]
+      end
+    end
+  end
+end

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