solid_objects 0.12.1 → 0.13.1

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

data/lib/solid_objects/worker.rb

@@ -5,6 +5,7 @@ require "solid_objects/activation_manager"
 require "solid_objects/activation"
 require "solid_objects/executor"
 require "solid_objects/lease_renewer"
+require "solid_objects/polling_backoff"
 
 module SolidObjects
   class Worker
@@ -13,6 +14,7 @@ module SolidObjects
     # @rbs @activations: Hash[Integer, Activation]
     # @rbs @stopped: bool
     # @rbs @shutdown_requested: bool
+    # @rbs @polling_backoff: PollingBackoff
 
     # @rbs (?process_registry: ProcessRegistry) -> void
     def initialize(process_registry: ProcessRegistry.new)
@@ -22,6 +24,23 @@ module SolidObjects
       @activations = {}
       @stopped = false
       @shutdown_requested = false
+      @polling_backoff = PollingBackoff.new(
+        minimum_interval: [
+          SolidObjects.configuration.polling_interval,
+          SolidObjects.configuration.lease_renewal_interval
+        ].min,
+        maximum_interval: [
+          SolidObjects.configuration.idle_polling_interval,
+          SolidObjects.configuration.lease_renewal_interval
+        ].min,
+        on_change: ->(transition) do
+          SolidObjects.instrument(
+            :"polling.interval_changed",
+            role: "actors",
+            **transition
+          )
+        end
+      )
     end
 
     # @rbs () -> Integer
@@ -70,11 +89,23 @@ module SolidObjects
 
     # @rbs () -> void
     def run
+      ProcessRegistry.warn_if_polling_is_only_cross_process_wake_up
+
       until shutdown_requested?
+        wake_up = SolidObjects.wake_up
+        watch = wake_up.respond_to?(:watch) ? wake_up.watch : wake_up
         processed = run_once
-        next if processed.positive?
+        if processed.positive?
+          polling_backoff.reset(:work)
+          next
+        end
 
-        SolidObjects.wake_up.wait(timeout: SolidObjects.configuration.polling_interval)
+        notified = watch.wait(timeout: current_polling_interval)
+        if notified == false
+          polling_backoff.record_idle
+        else
+          polling_backoff.reset(:wake_up)
+        end
       end
     ensure
       stop
@@ -107,9 +138,14 @@ module SolidObjects
       @shutdown_requested
     end
 
+    # @rbs () -> Float
+    def current_polling_interval
+      polling_backoff.current_interval
+    end
+
     private
 
-    attr_reader :process_registry, :activation_manager, :activations
+    attr_reader :process_registry, :activation_manager, :activations, :polling_backoff
 
     # @rbs () -> Activation?
     def cached_ready_activation

data/lib/solid_objects.rb

@@ -52,6 +52,7 @@ require "solid_objects/wake_up"
 require "solid_objects/wake_up_adapters/postgresql"
 require "solid_objects/wake_up_adapters/redis"
 require "solid_objects/wake_up_adapters"
+require "solid_objects/polling_backoff"
 require "solid_objects/effect_registry"
 require "solid_objects/commit_action_registry"
 require "solid_objects/lease"
@@ -153,6 +154,7 @@ module SolidObjects
 
     # @rbs () -> void
     def reset!
+      ProcessRegistry.reset_polling_warning! if defined?(ProcessRegistry)
       @configuration = Configuration.new
       @registry = ActorRegistry.new
       @client = nil

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class BroadcastExecutor
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -31,12 +33,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Broadcast?
     def claim_next: () -> Broadcast?
 

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class Configuration
+    @table_name_prefix: String
+
     @process_alive_threshold: Float
 
     @shutdown_timeout: Float
@@ -56,10 +58,10 @@ module SolidObjects
 
     @authorize_administration: Proc
 
-    @table_name_prefix: String
-
     @polling_interval: Float
 
+    @idle_polling_interval: Float
+
     @sync_polling_interval: Float
 
     @lease_duration: Float
@@ -94,6 +96,8 @@ module SolidObjects
 
     attr_accessor polling_interval: untyped
 
+    attr_accessor idle_polling_interval: untyped
+
     attr_accessor sync_polling_interval: untyped
 
     attr_accessor lease_duration: untyped

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

@@ -23,6 +23,8 @@ module SolidObjects
   class EffectExecutor
     ACTOR_MESSAGE_EFFECT: ::String
 
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -52,12 +54,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs () -> Effect?
     def claim_next: () -> Effect?
 

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

@@ -0,0 +1,29 @@
+# Generated from lib/solid_objects/polling_backoff.rb with RBS::Inline
+
+module SolidObjects
+  class PollingBackoff
+    @minimum_interval: Float
+
+    @maximum_interval: Float
+
+    @current_interval: Float
+
+    @on_change: Proc?
+
+    attr_reader current_interval: untyped
+
+    # @rbs (minimum_interval: Numeric, maximum_interval: Numeric, ?on_change: Proc?) -> void
+    def initialize: (minimum_interval: Numeric, maximum_interval: Numeric, ?on_change: Proc?) -> void
+
+    # @rbs () -> void
+    def record_idle: () -> void
+
+    # @rbs (:work | :wake_up) -> void
+    def reset: (:work | :wake_up) -> void
+
+    private
+
+    # @rbs (Float, :idle | :work | :wake_up) -> void
+    def change: (Float, :idle | :work | :wake_up) -> void
+  end
+end

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

@@ -8,6 +8,21 @@ module SolidObjects
     # @rbs (Process, ?now: Time) -> bool
     def self.deregister: (Process, ?now: Time) -> bool
 
+    # @rbs () -> void
+    def self.warn_if_polling_is_only_cross_process_wake_up: () -> void
+
+    # @rbs () -> void
+    def self.reset_polling_warning!: () -> void
+
+    # @rbs () -> bool
+    private def self.another_live_process?: () -> bool
+
+    # @rbs () -> bool
+    private def self.polling_warning_emitted?: () -> bool
+
+    # @rbs () -> Mutex
+    private def self.polling_warning_mutex: () -> Mutex
+
     # @rbs (Process, Time) -> void
     private def self.cleanup_process: (Process, Time) -> void
 

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

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class ReminderScheduler
+    @polling_backoff: PollingBackoff
+
     @shutdown_requested: bool
 
     @stopped: bool
@@ -31,12 +33,17 @@ module SolidObjects
     # @rbs () -> bool
     def shutdown_requested?: () -> bool
 
+    # @rbs () -> Float
+    def current_polling_interval: () -> Float
+
     private
 
     attr_reader process_registry: untyped
 
     attr_reader database_adapter: untyped
 
+    attr_reader polling_backoff: untyped
+
     # @rbs (now: Time?) -> Reminder?
     def claim_next: (now: Time?) -> Reminder?
 

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

@@ -2,18 +2,35 @@
 
 module SolidObjects
   class WakeUp
+    class Watch
+      @wake_up: WakeUp
+
+      @generation: Integer
+
+      # @rbs (WakeUp, Integer) -> void
+      def initialize: (WakeUp, Integer) -> void
+
+      # @rbs (timeout: Numeric) -> bool
+      def wait: (timeout: Numeric) -> bool
+    end
+
     @mutex: Mutex
 
     @condition: Thread::ConditionVariable
 
+    @generation: Integer
+
     # @rbs () -> void
     def initialize: () -> void
 
     # @rbs () -> void
     def signal: () -> void
 
-    # @rbs (timeout: Numeric) -> void
-    def wait: (timeout: Numeric) -> void
+    # @rbs () -> Watch
+    def watch: () -> Watch
+
+    # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+    def wait: (timeout: Numeric, ?generation: Integer?) -> bool
 
     private
 

data/sig/generated/lib/solid_objects/wake_up_adapters/postgresql.rbs

@@ -31,6 +31,9 @@ module SolidObjects
       # @rbs (timeout: Numeric) -> bool
       def wait: (timeout: Numeric) -> bool
 
+      # @rbs () -> self
+      def watch: () -> self
+
       # Starts listening before a caller blocks, so a notification sent between
       # startup and the first wait is not missed.
       # @rbs () -> bool

data/sig/generated/lib/solid_objects/wake_up_adapters/redis.rbs

@@ -10,6 +10,18 @@ module SolidObjects
     # polling interval remains the upper bound, so a missed or failed
     # notification costs latency rather than correctness.
     class Redis
+      class Watch
+        @adapter: Redis
+
+        @generation: Integer
+
+        # @rbs (Redis, Integer) -> void
+        def initialize: (Redis, Integer) -> void
+
+        # @rbs (timeout: Numeric) -> bool
+        def wait: (timeout: Numeric) -> bool
+      end
+
       CHANNEL: ::String
 
       FAILED_WAIT_INTERVAL: ::Float
@@ -43,8 +55,11 @@ module SolidObjects
       # The counter is snapshotted before subscribing, and re-checked before
       # blocking, so a signal delivered while this caller was still getting
       # ready is observed rather than absorbed into the new baseline.
-      # @rbs (timeout: Numeric) -> bool
-      def wait: (timeout: Numeric) -> bool
+      # @rbs (timeout: Numeric, ?generation: Integer?) -> bool
+      def wait: (timeout: Numeric, ?generation: Integer?) -> bool
+
+      # @rbs () -> Watch
+      def watch: () -> Watch
 
       # Redis delivers to a subscribed connection only, and a subscribed
       # connection cannot serve other callers, so one background subscription

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

@@ -0,0 +1,78 @@
+# Generated from lib/solid_objects/web/action.rb with RBS::Inline
+
+module SolidObjects
+  class Web
+    # One request. A route handler runs inside an instance of this class, so a
+    # handler and the template it renders share the same helpers and the same
+    # request.
+    class Action
+      include Helpers
+
+      @response_status: Integer
+
+      @layout_rendered: bool
+
+      @request: untyped
+
+      @captures: Hash[Symbol, String?]
+
+      @route: Route
+
+      @env: Hash[String, untyped]
+
+      attr_reader env: untyped
+
+      attr_reader route: untyped
+
+      attr_reader response_status: untyped
+
+      # @rbs (env: Hash[String, untyped], route: Route) -> void
+      def initialize: (env: Hash[String, untyped], route: Route) -> void
+
+      # Sets the status a rendered page is served with. `halt` and `redirect`
+      # stop the handler, so a page that must render its own body and still
+      # report a failure needs this instead.
+      # @rbs (Integer) -> void
+      def status: (Integer) -> void
+
+      # @rbs () -> untyped
+      def request: () -> untyped
+
+      # @rbs () -> Hash[untyped, untyped]?
+      def session: () -> Hash[untyped, untyped]?
+
+      # @rbs (Symbol) -> String?
+      def route_params: (Symbol) -> String?
+
+      # @rbs (String) -> untyped
+      def url_params: (String) -> untyped
+
+      # @rbs () -> untyped
+      def call: () -> untyped
+
+      # The layout is rendered once per request. The flag is raised before the
+      # page body runs so a partial the body renders returns its own fragment
+      # rather than a second whole page. The layout reads the page it wraps
+      # from `locals.fetch(:content)`.
+      # @rbs (Symbol, ?Hash[Symbol, untyped]) -> String
+      def erb: (Symbol, ?Hash[Symbol, untyped]) -> String
+
+      # @rbs (Integer, ?String) -> void
+      def halt: (Integer, ?String) -> void
+
+      # @rbs (String) -> void
+      def redirect: (String) -> void
+
+      # @rbs (untyped) -> void
+      def json: (untyped) -> void
+
+      private
+
+      # `locals` is a local variable of this method, so a template reads it by
+      # name, and every helper is reachable because the template runs against
+      # this object.
+      # @rbs (untyped, Hash[Symbol, untyped]) -> String
+      def evaluate: (untyped, Hash[Symbol, untyped]) -> String
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# Generated from lib/solid_objects/web/application.rb with RBS::Inline
+
+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: ::String
+
+      CONTENT_SECURITY_POLICY: untyped
+
+      MAILBOX_MEMBERSHIPS: untyped
+
+      RECENT_LIMIT: ::Integer
+
+      CHART_TYPE_LIMIT: ::Integer
+
+      # @rbs (Hash[String, untyped]) -> Array[untyped]
+      def call: (Hash[String, untyped]) -> Array[untyped]
+
+      private
+
+      # @rbs (Action, untyped) -> Array[untyped]
+      def respond: (Action, untyped) -> Array[untyped]
+
+      # @rbs (Action) -> bool
+      def authorized?: (Action) -> bool
+
+      # @rbs (Hash[String, untyped]) -> Hash[String, String]
+      def page_headers: (Hash[String, untyped]) -> Hash[String, String]
+
+      # 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: (Hash[String, untyped]) -> String
+
+      # 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: () -> Array[untyped]
+
+      # @rbs () -> Array[untyped]
+      def forbidden: () -> Array[untyped]
+    end
+  end
+end