pgbus 0.5.1 → 0.6.1

data/lib/puma/plugin/pgbus_streams.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "puma/plugin"
+
+# Puma plugin that tears down the pgbus Streamer cleanly on worker
+# shutdown (SIGTERM, SIGUSR2 phased restart, SIGINT). Without this
+# hook, Puma closes hijacked SSE sockets abruptly during shutdown,
+# which looks to the browser like a network error and causes an
+# immediate reconnect attempt mid-deploy. With the hook, the Streamer
+# writes a `pgbus:shutdown` sentinel event to each connection and
+# closes them cleanly, and clients reconnect to the new worker via
+# EventSource's built-in Last-Event-ID mechanism — picking up any
+# messages that landed during the flip via the PGMQ archive replay path.
+#
+# Users opt in by adding `plugin :pgbus_streams` to their puma.rb:
+#
+#   # config/puma.rb
+#   plugin :pgbus_streams
+#
+# Auto-registering at gem load time would be too magical and would
+# break users who aren't running Puma (e.g. the gem also ships a CLI
+# and a non-Rails use case). Explicit opt-in is safer.
+Puma::Plugin.create do
+  def start(launcher)
+    launcher.events.register(:after_stopped) do
+      teardown_streamer(launcher)
+    end
+
+    launcher.events.register(:before_restart) do
+      teardown_streamer(launcher)
+    end
+  end
+
+  def teardown_streamer(launcher)
+    return unless defined?(Pgbus::Web::Streamer)
+
+    # Go through the public API so `@current_mutex` guards both the
+    # read and the clear. Bypassing it with instance_variable_get/set
+    # would race with any thread that's currently inside
+    # `Streamer.current` building a new Instance.
+    Pgbus::Web::Streamer.reset!
+  rescue StandardError => e
+    log_error(launcher, e)
+  end
+
+  def log_error(launcher, error)
+    message = "[Pgbus::Puma::Plugin] streamer teardown raised: #{error.class}: #{error.message}"
+    if launcher.respond_to?(:log_writer)
+      launcher.log_writer.log(message)
+    elsif defined?(Pgbus) && Pgbus.respond_to?(:logger)
+      Pgbus.logger.warn { message }
+    end
+  end
+end

data/lib/tasks/pgbus_streams.rake

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+namespace :pgbus do
+  namespace :streams do
+    desc "Fail if any pgbus controller or web component includes ActionController::Live"
+    task :lint_no_live do
+      # ActionController::Live has well-documented interactions with Puma
+      # that tie up worker threads for the lifetime of a streaming response
+      # (puma/puma#1009, puma/puma#938, puma/puma#569, rails/rails#10948).
+      # The pgbus streams subsystem is built on rack.hijack specifically to
+      # avoid this class of bug — hijack releases the worker thread as long
+      # as the Rack code returns promptly after hijacking. Any accidental
+      # reintroduction of ActionController::Live into the pgbus web layer
+      # would regress the architecture invisibly, so we guard against it
+      # in CI.
+      # The host app's Pgbus-namespaced controllers live under
+      # Rails.root/app/controllers/pgbus. The gem's own streaming
+      # code lives under gem_root/lib/pgbus/web. __dir__ here is
+      # gem_root/lib/tasks, which is why the app path needs
+      # Rails.root (or Dir.pwd when this task runs outside a Rails
+      # context) — resolving `app/controllers/pgbus` from __dir__
+      # would silently lint the gem itself and miss every consumer
+      # app's overrides.
+      app_root = defined?(Rails) && Rails.respond_to?(:root) ? Rails.root.to_s : Dir.pwd
+      roots = [
+        File.expand_path("app/controllers/pgbus", app_root),
+        File.expand_path("../pgbus/web", __dir__)
+      ].select { |p| File.directory?(p) }
+
+      offenders = []
+      roots.each do |root|
+        Dir.glob("#{root}/**/*.rb").each do |path|
+          content = File.read(path)
+          offenders << path if content.match?(/^\s*include\s+ActionController::Live\b/)
+        end
+      end
+
+      if offenders.any?
+        warn "\e[31m✗ ActionController::Live found in pgbus web code:\e[0m"
+        offenders.each { |p| warn "    #{p}" }
+        warn ""
+        warn "  Rationale: the pgbus streams subsystem uses rack.hijack to"
+        warn "  avoid Puma thread pinning (puma/puma#1009). Including"
+        warn "  ActionController::Live reintroduces the bug it was designed"
+        warn "  to avoid. Use Pgbus::Web::StreamApp for SSE endpoints."
+        abort
+      end
+
+      puts "\e[32m✓ pgbus web code is free of ActionController::Live\e[0m"
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgbus
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -143,6 +143,8 @@ files:
 - app/frontend/pgbus/vendor/apexcharts.js
 - app/frontend/pgbus/vendor/turbo.js
 - app/helpers/pgbus/application_helper.rb
+- app/helpers/pgbus/streams_helper.rb
+- app/javascript/pgbus/stream_source_element.js
 - app/models/pgbus/application_record.rb
 - app/models/pgbus/batch_entry.rb
 - app/models/pgbus/blocked_execution.rb
@@ -155,6 +157,7 @@ files:
 - app/models/pgbus/recurring_execution.rb
 - app/models/pgbus/recurring_task.rb
 - app/models/pgbus/semaphore.rb
+- app/models/pgbus/stream_stat.rb
 - app/models/pgbus/uniqueness_key.rb
 - app/views/layouts/pgbus/application.html.erb
 - app/views/pgbus/dashboard/_processes_table.html.erb
@@ -202,18 +205,24 @@ files:
 - lib/generators/pgbus/add_job_locks_generator.rb
 - lib/generators/pgbus/add_job_stats_generator.rb
 - lib/generators/pgbus/add_job_stats_latency_generator.rb
+- lib/generators/pgbus/add_job_stats_queue_index_generator.rb
 - lib/generators/pgbus/add_outbox_generator.rb
+- lib/generators/pgbus/add_presence_generator.rb
 - lib/generators/pgbus/add_queue_states_generator.rb
 - lib/generators/pgbus/add_recurring_generator.rb
+- lib/generators/pgbus/add_stream_stats_generator.rb
 - lib/generators/pgbus/install_generator.rb
 - lib/generators/pgbus/migrate_job_locks_generator.rb
 - lib/generators/pgbus/templates/add_failed_events_unique_index.rb.erb
 - lib/generators/pgbus/templates/add_job_locks.rb.erb
 - lib/generators/pgbus/templates/add_job_stats.rb.erb
 - lib/generators/pgbus/templates/add_job_stats_latency.rb.erb
+- lib/generators/pgbus/templates/add_job_stats_queue_index.rb.erb
 - lib/generators/pgbus/templates/add_outbox.rb.erb
+- lib/generators/pgbus/templates/add_presence.rb.erb
 - lib/generators/pgbus/templates/add_queue_states.rb.erb
 - lib/generators/pgbus/templates/add_recurring_tables.rb.erb
+- lib/generators/pgbus/templates/add_stream_stats.rb.erb
 - lib/generators/pgbus/templates/add_uniqueness_keys.rb.erb
 - lib/generators/pgbus/templates/migrate_job_locks_to_uniqueness_keys.rb.erb
 - lib/generators/pgbus/templates/migration.rb.erb
@@ -231,6 +240,8 @@ files:
 - lib/pgbus/circuit_breaker.rb
 - lib/pgbus/cli.rb
 - lib/pgbus/client.rb
+- lib/pgbus/client/ensure_stream_queue.rb
+- lib/pgbus/client/read_after.rb
 - lib/pgbus/concurrency.rb
 - lib/pgbus/concurrency/blocked_execution.rb
 - lib/pgbus/concurrency/semaphore.rb
@@ -246,6 +257,8 @@ files:
 - lib/pgbus/event_bus/subscriber.rb
 - lib/pgbus/failed_event_recorder.rb
 - lib/pgbus/generators/config_converter.rb
+- lib/pgbus/generators/database_target_detector.rb
+- lib/pgbus/generators/migration_detector.rb
 - lib/pgbus/instrumentation.rb
 - lib/pgbus/outbox.rb
 - lib/pgbus/outbox/poller.rb
@@ -272,11 +285,30 @@ files:
 - lib/pgbus/recurring/task.rb
 - lib/pgbus/serializer.rb
 - lib/pgbus/stat_buffer.rb
+- lib/pgbus/streams.rb
+- lib/pgbus/streams/cursor.rb
+- lib/pgbus/streams/envelope.rb
+- lib/pgbus/streams/filters.rb
+- lib/pgbus/streams/presence.rb
+- lib/pgbus/streams/signed_name.rb
+- lib/pgbus/streams/turbo_broadcastable.rb
+- lib/pgbus/streams/watermark_cache_middleware.rb
 - lib/pgbus/uniqueness.rb
 - lib/pgbus/version.rb
 - lib/pgbus/web/authentication.rb
 - lib/pgbus/web/data_source.rb
+- lib/pgbus/web/stream_app.rb
+- lib/pgbus/web/streamer.rb
+- lib/pgbus/web/streamer/connection.rb
+- lib/pgbus/web/streamer/dispatcher.rb
+- lib/pgbus/web/streamer/heartbeat.rb
+- lib/pgbus/web/streamer/instance.rb
+- lib/pgbus/web/streamer/io_writer.rb
+- lib/pgbus/web/streamer/listener.rb
+- lib/pgbus/web/streamer/registry.rb
+- lib/puma/plugin/pgbus_streams.rb
 - lib/tasks/pgbus_pgmq.rake
+- lib/tasks/pgbus_streams.rake
 homepage: https://github.com/mhenrixon/pgbus
 licenses:
 - MIT