solid_objects 0.12.1 → 0.13.1

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

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