solid_objects 0.12.1 → 0.13.1

data/sig/generated/lib/solid_objects/web/csrf_protection.rbs

@@ -0,0 +1,55 @@
+# Generated from lib/solid_objects/web/csrf_protection.rb with RBS::Inline
+
+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: untyped
+
+      TOKEN_BYTES: ::Integer
+
+      MISSING_SESSION: ::String
+
+      # @rbs (untyped) -> void
+      def initialize: (untyped) -> void
+
+      # @rbs (Hash[String, untyped]) -> Array[untyped]
+      def call: (Hash[String, untyped]) -> Array[untyped]
+
+      private
+
+      # @rbs (Hash[String, untyped]) -> bool
+      def accept?: (Hash[String, untyped]) -> bool
+
+      # @rbs (Hash[String, untyped], String?) -> bool
+      def valid?: (Hash[String, untyped], String?) -> bool
+
+      # @rbs (String, String) -> bool
+      def matches?: (String, String) -> bool
+
+      # @rbs (String) -> String
+      def mask: (String) -> String
+
+      # @rbs (String) -> String
+      def unmask: (String) -> String
+
+      # @rbs (String, String) -> String
+      def exclusive_or: (String, String) -> String
+
+      # @rbs (String) -> String
+      def encode: (String) -> String
+
+      # @rbs (String) -> String?
+      def decode: (String) -> String?
+
+      # @rbs (Hash[String, untyped]) -> Hash[untyped, untyped]
+      def session!: (Hash[String, untyped]) -> Hash[untyped, untyped]
+
+      # @rbs () -> Array[untyped]
+      def forbidden: () -> Array[untyped]
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web/helpers.rbs

@@ -0,0 +1,118 @@
+# Generated from lib/solid_objects/web/helpers.rb with RBS::Inline
+
+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: untyped
+
+      TRUNCATION_LIMIT: ::Integer
+
+      # @rbs (untyped) -> String
+      def h: (untyped) -> String
+
+      # @rbs () -> String
+      def root_path: () -> String
+
+      # @rbs (String) -> String
+      def path_to: (String) -> String
+
+      # @rbs () -> String
+      def current_path: () -> String
+
+      # @rbs (String) -> bool
+      def current_tab?: (String) -> bool
+
+      # @rbs () -> Hash[String, String]
+      def tabs: () -> Hash[String, String]
+
+      # @rbs () -> String?
+      def csp_nonce: () -> String?
+
+      # @rbs () -> String
+      def csrf_tag: () -> String
+
+      # @rbs (String) -> String
+      def form_to: (String) -> String
+
+      # @rbs (untyped) -> String
+      def relative_time: (untyped) -> String
+
+      # @rbs (untyped) -> String
+      def number: (untyped) -> String
+
+      # @rbs (Numeric?) -> String
+      def duration: (Numeric?) -> String
+
+      # @rbs (untyped, ?Integer) -> String
+      def json_block: (untyped, ?Integer) -> String
+
+      # @rbs (String, ?Integer) -> String
+      def truncate: (String, ?Integer) -> String
+
+      # @rbs (String?) -> String
+      def status_label: (String?) -> String
+
+      # @rbs (untyped) -> String
+      def actor_label: (untyped) -> String
+
+      # @rbs (untyped) -> String
+      def instance_link: (untyped) -> String
+
+      # @rbs (?Hash[String, untyped]) -> String
+      def query_string: (?Hash[String, untyped]) -> String
+
+      # @rbs (?Hash[String, untyped]) -> String
+      def page_link: (?Hash[String, untyped]) -> String
+
+      # @rbs (Instance) -> String
+      def lease_state: (Instance) -> String
+
+      # @rbs () -> Statistics
+      def statistics: () -> Statistics
+
+      # @rbs (untyped) -> Paginator
+      def paginate: (untyped) -> Paginator
+
+      # 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: (Array[String], ?default: String?) -> String?
+
+      # @rbs () -> Instance
+      def find_instance: () -> Instance
+
+      # @rbs () -> untyped
+      def filtered_instances: () -> untyped
+
+      # @rbs (String) -> untyped
+      def mailbox_messages: (String) -> untyped
+
+      # 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: (String, untyped) -> String
+
+      # 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: () -> String
+
+      # @rbs () -> String
+      def chart_library_integrity_attributes: () -> String
+
+      # @rbs () -> String
+      def environment_name: () -> String
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web/paginator.rbs

@@ -0,0 +1,54 @@
+# Generated from lib/solid_objects/web/paginator.rb with RBS::Inline
+
+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: ::Integer
+
+      MAXIMUM_PER_PAGE: ::Integer
+
+      @page: Integer
+
+      @per_page: Integer
+
+      @total: Integer
+
+      @records: Array[untyped]
+
+      attr_reader page: untyped
+
+      attr_reader per_page: untyped
+
+      attr_reader total: untyped
+
+      attr_reader records: untyped
+
+      # @rbs (relation: untyped, ?page: String?, ?per_page: String?) -> void
+      def initialize: (relation: untyped, ?page: String?, ?per_page: String?) -> void
+
+      # @rbs () -> Integer
+      def last_page: () -> Integer
+
+      # @rbs () -> Integer?
+      def previous_page: () -> Integer?
+
+      # @rbs () -> Integer?
+      def next_page: () -> Integer?
+
+      # @rbs () -> Integer
+      def first_record: () -> Integer
+
+      # @rbs () -> Integer
+      def last_record: () -> Integer
+
+      private
+
+      # @rbs (String?, default: Integer, maximum: Integer) -> Integer
+      def bounded: (String?, default: Integer, maximum: Integer) -> Integer
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web/route.rbs

@@ -0,0 +1,45 @@
+# Generated from lib/solid_objects/web/route.rb with RBS::Inline
+
+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: ::Regexp
+
+      SEGMENT_CAPTURE: ::String
+
+      @matcher: String | Regexp
+
+      @request_method: String
+
+      @pattern: String
+
+      @policy: Hash[Symbol, String]
+
+      @handler: Proc
+
+      attr_reader request_method: untyped
+
+      attr_reader pattern: untyped
+
+      attr_reader policy: untyped
+
+      attr_reader handler: untyped
+
+      # @rbs (request_method: String, pattern: String, policy: Hash[Symbol, String], handler: Proc) -> void
+      def initialize: (request_method: String, pattern: String, policy: Hash[Symbol, String], handler: Proc) -> void
+
+      # @rbs (String) -> bool
+      def match?: (String) -> bool
+
+      # @rbs (String) -> Hash[Symbol, String?]
+      def capture: (String) -> Hash[Symbol, String?]
+
+      private
+
+      # @rbs (String) -> (String | Regexp)
+      def compile: (String) -> (String | Regexp)
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web/router.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/solid_objects/web/router.rb with RBS::Inline
+
+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: (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+
+      # @rbs (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def get: (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+
+      # @rbs (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def post: (String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+
+      # @rbs (String, String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+      def route: (String, String, policy: Hash[Symbol, String]?) { () -> untyped } -> void
+
+      # @rbs () -> Hash[String, Array[Route]]
+      def routes: () -> Hash[String, Array[Route]]
+
+      # @rbs (String, String) -> Route?
+      def match: (String, String) -> Route?
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web/statistics.rbs

@@ -0,0 +1,46 @@
+# Generated from lib/solid_objects/web/statistics.rb with RBS::Inline
+
+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: untyped
+
+      BROADCAST_STATUSES: untyped
+
+      REMINDER_STATUSES: untyped
+
+      PROCESS_STATES: untyped
+
+      @now: Time
+
+      attr_reader now: untyped
+
+      # @rbs (?now: Time) -> void
+      def initialize: (?now: Time) -> void
+
+      # @rbs () -> Hash[Symbol, untyped]
+      def to_h: () -> Hash[Symbol, untyped]
+
+      # @rbs () -> Hash[Symbol, Integer]
+      def instances: () -> Hash[Symbol, Integer]
+
+      # 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: () -> Hash[Symbol, untyped]
+
+      # @rbs () -> Hash[Symbol, Integer]
+      def reminders: () -> Hash[Symbol, Integer]
+
+      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: (untyped, Symbol, Array[String]) -> Hash[Symbol, Integer]
+    end
+  end
+end

data/sig/generated/lib/solid_objects/web.rbs

@@ -0,0 +1,129 @@
+# Generated from lib/solid_objects/web.rb with RBS::Inline
+
+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: untyped
+
+    VIEWS: untyped
+
+    ASSETS: untyped
+
+    NONCE_KEY: ::String
+
+    CSRF_TOKEN_KEY: ::String
+
+    NONCE_BYTES: ::Integer
+
+    ASSET_CACHE_SECONDS: ::Integer
+
+    TEMPLATE_NAME: ::Regexp
+
+    # 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: ::String
+
+    CHART_LIBRARY_INTEGRITY: ::String
+
+    DEFAULT_TABS: untyped
+
+    LOCK: untyped
+
+    # 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: untyped
+
+    # 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_integrity: untyped
+
+    # @rbs () -> String?
+    def self.chart_library_url: () -> String?
+
+    # @rbs () -> String?
+    def self.chart_library_integrity: () -> String?
+
+    # @rbs () -> bool
+    def self.charts?: () -> bool
+
+    # 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 self.chart_library_origin: () -> String?
+
+    # @rbs () -> Hash[String, String]
+    def self.tabs: () -> Hash[String, String]
+
+    # 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 self.views: () -> Array[String]
+
+    # @rbs () -> Array[[Array[untyped], Proc?]]
+    def self.middlewares: () -> Array[[ Array[untyped], Proc? ]]
+
+    # 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 self.use: (*untyped) ?{ () -> untyped } -> void
+
+    # 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 self.register: (untyped, tab: String, path: String, ?views: String?) -> void
+
+    # @rbs (Symbol) -> untyped
+    def self.template: (Symbol) -> untyped
+
+    # @rbs () -> void
+    def self.reset!: () -> void
+
+    # @rbs (Hash[String, untyped]) -> Array[untyped]
+    def self.call: (Hash[String, untyped]) -> Array[untyped]
+
+    # @rbs () -> Web
+    def self.application: () -> Web
+
+    # @rbs () -> Hash[Symbol, untyped]
+    private def self.templates: () -> Hash[Symbol, untyped]
+
+    # 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
+    private def self.template_path: (Symbol) -> String
+
+    # @rbs (Hash[String, untyped]) -> Array[untyped]
+    def call: (Hash[String, untyped]) -> Array[untyped]
+
+    # @rbs () -> untyped
+    def app: () -> untyped
+
+    private
+
+    # @rbs () -> untyped
+    def build: () -> untyped
+  end
+end

data/sig/generated/lib/solid_objects/worker.rbs

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class Worker
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -36,6 +38,9 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
@@ -44,6 +49,8 @@ module SolidObjects
 
     attr_reader activations: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Activation?
     def cached_ready_activation: () -> Activation?
 

data/web/assets/javascripts/application.js

@@ -0,0 +1,118 @@
+// Refreshes the summary bar in place. Nothing else on the page polls, because
+// a dashboard that reloads a table an operator is reading is worse than one
+// that shows a stale table with a live total.
+(function () {
+  "use strict";
+
+  var POLL_INTERVAL = 5000;
+  var STORAGE_KEY = "solid-objects-live";
+
+  var timer = null;
+
+  function readPath() {
+    return document.body.getAttribute("data-stats-path");
+  }
+
+  function lookup(payload, path) {
+    return path.split(".").reduce(function (value, key) {
+      return value == null ? null : value[key];
+    }, payload);
+  }
+
+  // Must match SolidObjects::Web::Helpers#number and #duration. A polled cell
+  // sits beside server-rendered ones, and a value that changes shape the
+  // moment polling starts reads as a different measurement.
+  //
+  // The cell declares which one it is. A duration of exactly zero arrives from
+  // JSON as an integer-valued number, so guessing from the value would print
+  // "0" where the server printed "0.000 s".
+  function format(value, kind) {
+    if (typeof value !== "number") return String(value);
+    if (kind !== "duration") return value.toLocaleString("en-US");
+    if (value < 60) return value.toFixed(3) + " s";
+
+    return Math.floor(value / 60) + " min " + Math.round(value % 60) + " s";
+  }
+
+  function apply(payload) {
+    var cells = document.querySelectorAll("[data-statistic]");
+    Array.prototype.forEach.call(cells, function (cell) {
+      var value = lookup(payload, cell.getAttribute("data-statistic"));
+      if (value == null) return;
+
+      var text = format(value, cell.getAttribute("data-format"));
+      if (cell.textContent !== text) cell.textContent = text;
+    });
+  }
+
+  function poll() {
+    var path = readPath();
+    if (!path) return;
+
+    fetch(path, { credentials: "same-origin", headers: { Accept: "application/json" } })
+      .then(function (response) {
+        return response.ok ? response.json() : null;
+      })
+      .then(function (payload) {
+        if (!payload) return;
+
+        apply(payload);
+        // The charts subscribe to this rather than polling on their own, so
+        // one request refreshes every number on the page.
+        document.dispatchEvent(
+          new CustomEvent("solid-objects:statistics", { detail: payload })
+        );
+      })
+      .catch(function () {
+        // A failed poll leaves the last rendered totals in place.
+      });
+  }
+
+  function setLive(button, live) {
+    button.setAttribute("aria-pressed", live ? "true" : "false");
+
+    try {
+      window.localStorage.setItem(STORAGE_KEY, live ? "on" : "off");
+    } catch (error) {
+      // Storage is unavailable in private windows; the toggle still works.
+    }
+
+    if (timer) {
+      window.clearInterval(timer);
+      timer = null;
+    }
+
+    if (live) {
+      poll();
+      timer = window.setInterval(poll, POLL_INTERVAL);
+    }
+  }
+
+  function stored() {
+    try {
+      return window.localStorage.getItem(STORAGE_KEY) === "on";
+    } catch (error) {
+      return false;
+    }
+  }
+
+  function start() {
+    var button = document.querySelector("[data-poll-toggle]");
+    if (!button) return;
+
+    button.addEventListener("click", function () {
+      setLive(button, button.getAttribute("aria-pressed") !== "true");
+    });
+
+    if (stored()) setLive(button, true);
+  }
+
+  // The tag is deferred, so the document is usually still parsing. A script
+  // evaluated after the document finished would never see the event, and
+  // waiting for one that already fired leaves the toggle inert.
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", start, { once: true });
+  } else {
+    start();
+  }
+})();