fix: poll rather than pretend when an adapter cannot be built

`wake_up_adapter = :postgresql` on a database with no notification
channel built the adapter anyway and reported `crosses_processes: true`,
so the doctor said PASS while every `LISTEN` failed. `:redis` without
`SOLID_OBJECTS_REDIS_URL` reached for the client default rather than say
it had no address.

Each case now polls, logs `solid_objects.wake_up.unavailable` once, and
records the reason in the capability, so the doctor warns. That is what
the capability record exists for. Only a name that does not exist is
still refused, because a typo cannot be honoured at all.

`configure` validates the name now. An unknown one raised at the first
wake-up, which is after a commit, rather than at boot.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cardmagic

CHANGELOG.md

@@ -23,6 +23,14 @@
 - Keep the capability that a configured adapter reports about itself. A
   configured `SolidObjects::WakeUp` now reports `:in_process` and warns, rather
   than claim that it crosses processes.
+- Poll rather than pretend when a requested adapter cannot be built.
+  `wake_up_adapter = :postgresql` on a database with no notification channel,
+  `:redis` without `SOLID_OBJECTS_REDIS_URL`, and a Redis URL without the redis
+  gem each log `solid_objects.wake_up.unavailable` once and record the reason in
+  the capability, so the doctor warns rather than claim a cross-process wake-up
+  that cannot happen.
+- Validate `wake_up_adapter` in `configure`. An unknown name raised at the first
+  wake-up, which is after a commit, rather than at boot.
 - Report the resolved choice. `SolidObjects.wake_up.capability` names the
   adapter, whether it crosses processes, its measured floor, and why it was
   chosen. The doctor reports it, and the polling-only warning now fires on what

lib/solid_objects/configuration.rb

@@ -237,6 +237,7 @@ def validate!
         raise ArgumentError, "actor type cannot be empty" if actor_type.to_s.empty?
         raise ArgumentError, "instance retention must be positive" unless retention.positive?
       end
+      validate_wake_up_adapter!
       unless component_path_resolver.nil? || component_path_resolver.respond_to?(:call)
         raise ArgumentError, "component_path_resolver must respond to call"
       end
@@ -252,6 +253,26 @@ def validate!
 
     private
 
+    # @rbs () -> void
+    def validate_wake_up_adapter!
+      return if wake_up_adapter.nil?
+      return validate_wake_up_object! unless wake_up_adapter.is_a?(Symbol)
+      return if WakeUpAdapters::NAMES.include?(wake_up_adapter)
+
+      raise ArgumentError,
+        "unknown wake_up_adapter #{wake_up_adapter.inspect}, " \
+        "expected one of #{WakeUpAdapters::NAMES.join(", ")} or an adapter"
+    end
+
+    # @rbs () -> void
+    def validate_wake_up_object!
+      %i[signal wait watch].each do |method_name|
+        next if wake_up_adapter.respond_to?(method_name)
+
+        raise ArgumentError, "wake_up_adapter must respond to #{method_name}"
+      end
+    end
+
     # @rbs () -> Hash[Symbol, Numeric]
     def positive_values
       {

lib/solid_objects/wake_up_adapters.rb

@@ -32,13 +32,62 @@ def build(setting)
     def named(name)
       case name
       when :in_process then labelled(WakeUp.new, :in_process, false, nil, "in-process signalling was requested")
-      when :postgresql then labelled(Postgresql.new, :postgresql_notify, true, POSTGRESQL_FLOOR_MS, "PostgreSQL LISTEN was requested")
-      when :redis then labelled(Redis.new(url: redis_url), :redis, true, REDIS_FLOOR_MS, "Redis was requested")
+      when :postgresql then requested_postgresql
+      when :redis then requested_redis
       else
         raise ArgumentError, "unknown wake_up_adapter #{name.inspect}, expected one of #{NAMES.join(", ")} or an adapter"
       end
     end
 
+    # @rbs () -> untyped
+    def requested_postgresql
+      family = DatabaseAdapter.family(Record.connection)
+      unless family == :postgresql
+        return unavailable_selection(
+          "wake_up_adapter :postgresql needs a database with a notification " \
+          "channel, and #{family || "this database"} provides none"
+        )
+      end
+
+      labelled(Postgresql.new, :postgresql_notify, true, POSTGRESQL_FLOOR_MS, "PostgreSQL LISTEN was requested")
+    end
+
+    # @rbs () -> untyped
+    def requested_redis
+      url = redis_url
+      unless url
+        return unavailable_selection(
+          "wake_up_adapter :redis needs #{REDIS_URL_VARIABLE}, which is not set"
+        )
+      end
+
+      redis_adapter(url, "Redis was requested")
+    end
+
+    # @rbs (String, String) -> untyped
+    def redis_adapter(url, reason)
+      return unavailable_selection("#{REDIS_URL_VARIABLE} is set, and the redis gem is not installed") unless redis_installed?
+
+      labelled(Redis.new(url:), :redis, true, REDIS_FLOOR_MS, reason)
+    end
+
+    # @rbs () -> bool
+    def redis_installed?
+      require "redis"
+      true
+    rescue LoadError
+      false
+    end
+
+    # @rbs (String) -> untyped
+    def unavailable_selection(reason)
+      SolidObjects.configuration.logger.warn(
+        event: "solid_objects.wake_up.unavailable",
+        reason:
+      )
+      polling_adapter(reason)
+    end
+
     # @rbs (untyped) -> untyped
     def configured(adapter)
       return adapter unless adapter.respond_to?(:capability=)
@@ -111,8 +160,8 @@ def redis_url
 
     # @rbs (String) -> untyped
     def redis_selection(url)
-      labelled(
-        Redis.new(url:), :redis, true, REDIS_FLOOR_MS,
+      redis_adapter(
+        url,
         "#{REDIS_URL_VARIABLE} is set, so Redis carries the signal between processes"
       )
     end

sig/generated/lib/solid_objects/configuration.rbs

@@ -2,6 +2,8 @@
 
 module SolidObjects
   class Configuration
+    @process_heartbeat_interval: Float
+
     @process_alive_threshold: Float
 
     @shutdown_timeout: Float
@@ -96,8 +98,6 @@ module SolidObjects
 
     @lock_retry_attempts: Integer
 
-    @process_heartbeat_interval: Float
-
     attr_accessor table_name_prefix: untyped
 
     attr_accessor polling_interval: untyped
@@ -230,6 +230,12 @@ module SolidObjects
 
     private
 
+    # @rbs () -> void
+    def validate_wake_up_adapter!: () -> void
+
+    # @rbs () -> void
+    def validate_wake_up_object!: () -> void
+
     # @rbs () -> Hash[Symbol, Numeric]
     def positive_values: () -> Hash[Symbol, Numeric]
 

sig/generated/lib/solid_objects/wake_up_adapters.rbs

@@ -23,6 +23,21 @@ module SolidObjects
     # @rbs (Symbol) -> untyped
     def self?.named: (Symbol) -> untyped
 
+    # @rbs () -> untyped
+    def self?.requested_postgresql: () -> untyped
+
+    # @rbs () -> untyped
+    def self?.requested_redis: () -> untyped
+
+    # @rbs (String, String) -> untyped
+    def self?.redis_adapter: (String, String) -> untyped
+
+    # @rbs () -> bool
+    def self?.redis_installed?: () -> bool
+
+    # @rbs (String) -> untyped
+    def self?.unavailable_selection: (String) -> untyped
+
     # @rbs (untyped) -> untyped
     def self?.configured: (untyped) -> untyped
 

test/integration/wake_up_selection_test.rb

@@ -93,13 +93,52 @@ def wait(timeout:) = false
   end
 
   test "a name selects that adapter without probing" do
+    ENV["SOLID_OBJECTS_REDIS_URL"] = "redis://127.0.0.1:6379/15"
     SolidObjects.configuration.wake_up_adapter = :redis
 
     capability = SolidObjects.wake_up.capability
     assert_equal :redis, capability.adapter
     assert_match(/requested/i, capability.reason)
   end
 
+  test "a requested postgresql adapter polls when the database has no channel" do
+    skip if database_family == :postgresql
+    warnings = []
+    SolidObjects.configuration.logger = Logger.new(IO::NULL).tap do |logger|
+      logger.define_singleton_method(:warn) { |payload| warnings << payload }
+    end
+    SolidObjects.configuration.wake_up_adapter = :postgresql
+
+    capability = SolidObjects.wake_up.capability
+    assert_equal :polling, capability.adapter
+    assert_not capability.crosses_processes
+    assert_match(/notification channel/i, capability.reason)
+    assert_equal [ "solid_objects.wake_up.unavailable" ],
+      warnings.map { |payload| payload[:event].to_s }
+  end
+
+  test "a requested redis adapter polls when no url is set" do
+    warnings = []
+    SolidObjects.configuration.logger = Logger.new(IO::NULL).tap do |logger|
+      logger.define_singleton_method(:warn) { |payload| warnings << payload }
+    end
+    SolidObjects.configuration.wake_up_adapter = :redis
+
+    capability = SolidObjects.wake_up.capability
+    assert_equal :polling, capability.adapter
+    assert_match(/SOLID_OBJECTS_REDIS_URL/, capability.reason)
+    assert_equal [ "solid_objects.wake_up.unavailable" ],
+      warnings.map { |payload| payload[:event].to_s }
+  end
+
+  test "an unknown name is refused when the configuration is validated" do
+    SolidObjects.configuration.wake_up_adapter = :carrier_pigeon
+
+    error = assert_raises(ArgumentError) { SolidObjects.configuration.validate! }
+    assert_match(/carrier_pigeon/, error.message)
+    assert_match(/automatic/, error.message)
+  end
+
   test "an unknown name is refused rather than silently polling" do
     SolidObjects.configuration.wake_up_adapter = :carrier_pigeon