pgbus 0.12.4 → 0.13.1

data/lib/pgbus/web/streamer/master_hub_boot.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Pgbus
+  module Web
+    module Streamer
+      # Deferred MasterHub startup for the Puma master (issue #382). The
+      # pgbus_streams plugin's `start` runs BEFORE `preload_app!` loads the
+      # Rails app (and with it the pgbus initializer), so the hub cannot be
+      # built eagerly. This class splits the two halves:
+      #
+      #   1. The socket path is exported to ENV IMMEDIATELY — workers inherit
+      #      it across fork and connect lazily on first SSE use.
+      #   2. A poller thread waits for Pgbus.configuration to become ready
+      #      (the initializer has run — with preload_app!, before the first
+      #      fork), then builds and starts the MasterHub. Workers that race a
+      #      still-booting hub simply fail to connect and fall back to their
+      #      own listener until they recycle — degraded footprint, never
+      #      degraded semantics.
+      #
+      # Without preload_app! the master never loads the app, the deadline
+      # expires quietly, no socket is ever bound, and every worker keeps
+      # today's per-worker listener — :master scope effectively requires
+      # preload_app!, documented on the docs site.
+      class MasterHubBoot
+        def self.default_socket_path
+          File.join(Dir.tmpdir, "pgbus-streams-hub-#{::Process.pid}.sock")
+        end
+
+        def initialize(socket_path: self.class.default_socket_path, hub_factory: nil,
+                       poll_interval: 1.0, deadline: 120, logger: nil)
+          @socket_path = socket_path
+          @hub_factory = hub_factory || lambda do |socket_path:|
+            MasterHub.new(config: Pgbus.configuration, socket_path: socket_path)
+          end
+          @poll_interval = poll_interval
+          @deadline = deadline
+          @logger = logger
+          # Guards @hub and @running: written by the caller thread
+          # (start/stop) and the background poller. A hub whose start
+          # outlives stop's join budget is stopped by whichever side sees
+          # the flag last, so teardown can never leave a live hub behind.
+          @state_mutex = Mutex.new
+          @hub = nil
+          @running = false
+          @thread = nil
+        end
+
+        def start
+          ENV["PGBUS_STREAMS_HUB_SOCKET"] = @socket_path
+          @state_mutex.synchronize { @running = true }
+          @thread = Thread.new { wait_and_start }
+          self
+        end
+
+        def stop
+          to_stop = @state_mutex.synchronize do
+            @running = false
+            hub = @hub
+            @hub = nil
+            hub
+          end
+          @thread&.join(2)
+          @thread = nil
+          to_stop&.stop
+          self
+        end
+
+        private
+
+        def running?
+          @state_mutex.synchronize { @running }
+        end
+
+        def wait_and_start
+          waited = 0.0
+          until configuration_ready?
+            return unless running?
+            return give_up if waited >= @deadline
+
+            sleep @poll_interval
+            waited += @poll_interval
+          end
+          return unless running? && master_scope?
+
+          hub = @hub_factory.call(socket_path: @socket_path)
+          hub.start
+          # Register-or-late-stop: if stop ran while the hub was building,
+          # this thread owns the teardown of the hub stop never saw.
+          late = @state_mutex.synchronize do
+            if @running
+              @hub = hub
+              nil
+            else
+              hub
+            end
+          end
+          late&.stop
+          return if late
+
+          log(:info) { "[Pgbus::Streamer::MasterHubBoot] master hub listening at #{@socket_path}" }
+        rescue StandardError => e
+          @state_mutex.synchronize { @hub = nil }
+          # The method-scoped hub may have STARTED before a later step raised
+          # (e.g. a failing logger after registration) — stop it here or its
+          # LISTEN connection outlives the boot failure. MasterHub#stop is
+          # idempotent and safe on a never-started hub.
+          begin
+            hub&.stop
+          rescue StandardError
+            nil
+          end
+          log(:error) do
+            "[Pgbus::Streamer::MasterHubBoot] master hub failed to start " \
+              "(#{e.class}: #{e.message}) — workers fall back to per-worker listeners"
+          end
+        end
+
+        # Ready once the app's initializer has produced connection options a
+        # dedicated LISTEN connection can be built from (String URL or libpq
+        # Hash; the Proc fallback means "nothing configured yet").
+        def configuration_ready?
+          return false unless defined?(Pgbus) && Pgbus.configuration.streams_enabled
+
+          options = Pgbus.configuration.streams_connection_options
+          options.is_a?(String) || options.is_a?(Hash)
+        rescue StandardError
+          false
+        end
+
+        def master_scope?
+          Pgbus.configuration.streams_listen_scope == :master
+        end
+
+        def give_up
+          log(:info) do
+            "[Pgbus::Streamer::MasterHubBoot] configuration never became ready within #{@deadline}s " \
+              "(no preload_app!?) — no master hub; workers use per-worker listeners"
+          end
+        end
+
+        def log(level, &)
+          (@logger || Pgbus.logger).public_send(level, &)
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/pgbus_streams.rb

@@ -22,15 +22,51 @@ require "puma/plugin"
 # and a non-Rails use case). Explicit opt-in is safer.
 Puma::Plugin.create do
   def start(launcher)
+    # Master-side streams hub (issue #382): in cluster mode, ONE LISTEN
+    # connection in the master serves every worker over a Unix socket. The
+    # socket path is exported to ENV here (pre-fork, so workers inherit it);
+    # the hub itself starts once the preloaded app has configured Pgbus (see
+    # MasterHubBoot). Any failure means no socket — workers keep their own
+    # per-worker listeners, trading connections for unchanged semantics.
+    boot_master_hub(launcher)
+
     launcher.events.register(:after_stopped) do
+      teardown_master_hub(launcher)
       teardown_streamer(launcher)
     end
 
     launcher.events.register(:before_restart) do
+      teardown_master_hub(launcher)
       teardown_streamer(launcher)
     end
   end
 
+  def boot_master_hub(launcher)
+    return unless defined?(Pgbus::Web::Streamer::MasterHubBoot)
+    # Single mode: the master IS the (only) serving process — one listener
+    # per host already; a hub would just add a socket hop.
+    return unless cluster_mode?(launcher)
+
+    @master_hub_boot = Pgbus::Web::Streamer::MasterHubBoot.new
+    @master_hub_boot.start
+  rescue StandardError => e
+    @master_hub_boot = nil
+    log_error(launcher, e, "master hub boot")
+  end
+
+  def cluster_mode?(launcher)
+    launcher.respond_to?(:options) && launcher.options[:workers].to_i.positive?
+  rescue StandardError
+    false
+  end
+
+  def teardown_master_hub(launcher)
+    @master_hub_boot&.stop
+    @master_hub_boot = nil
+  rescue StandardError => e
+    log_error(launcher, e, "master hub teardown")
+  end
+
   def teardown_streamer(launcher)
     return unless defined?(Pgbus::Web::Streamer)
 
@@ -43,8 +79,8 @@ Puma::Plugin.create do
     log_error(launcher, e)
   end
 
-  def log_error(launcher, error)
-    message = "[Pgbus::Puma::Plugin] streamer teardown raised: #{error.class}: #{error.message}"
+  def log_error(launcher, error, operation = "streamer teardown")
+    message = "[Pgbus::Puma::Plugin] #{operation} raised: #{error.class}: #{error.message}"
     if launcher.respond_to?(:log_writer)
       launcher.log_writer.log(message)
     elsif defined?(Pgbus) && Pgbus.respond_to?(:logger)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 0.13.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -328,13 +328,16 @@ files:
 - lib/pgbus/process/heartbeat.rb
 - lib/pgbus/process/lifecycle.rb
 - lib/pgbus/process/memory_usage.rb
+- lib/pgbus/process/notify_hub.rb
 - lib/pgbus/process/notify_listener.rb
 - lib/pgbus/process/notify_probe.rb
 - lib/pgbus/process/primary_validator.rb
 - lib/pgbus/process/queue_lock.rb
 - lib/pgbus/process/signal_handler.rb
 - lib/pgbus/process/supervisor.rb
+- lib/pgbus/process/wake_pipe.rb
 - lib/pgbus/process/wake_signal.rb
+- lib/pgbus/process/wildcard_queue_resolver.rb
 - lib/pgbus/process/worker.rb
 - lib/pgbus/queue_factory.rb
 - lib/pgbus/queue_name_validator.rb
@@ -382,11 +385,16 @@ files:
 - lib/pgbus/web/stream_app.rb
 - lib/pgbus/web/streamer.rb
 - lib/pgbus/web/streamer/connection.rb
+- lib/pgbus/web/streamer/failover_listener.rb
 - lib/pgbus/web/streamer/falcon_connection.rb
 - lib/pgbus/web/streamer/heartbeat.rb
+- lib/pgbus/web/streamer/hub_client.rb
+- lib/pgbus/web/streamer/hub_protocol.rb
 - lib/pgbus/web/streamer/instance.rb
 - lib/pgbus/web/streamer/io_writer.rb
 - lib/pgbus/web/streamer/listener.rb
+- lib/pgbus/web/streamer/master_hub.rb
+- lib/pgbus/web/streamer/master_hub_boot.rb
 - lib/pgbus/web/streamer/outbound_pump.rb
 - lib/pgbus/web/streamer/registry.rb
 - lib/pgbus/web/streamer/stream_counter.rb