flu-rails 8.0.5 → 8.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24d179705111c94185f7421297a692e1f962feeef2a9c2132a04e744d70a6503
-  data.tar.gz: 93526441dcfaea7cc3a5be4795c5e86cdb9a4acdbaf95b825e530259b3c89d64
+  metadata.gz: bbe2d214138e198e66d6291a86e2614950e53f14c5556ee424cc98bd1a993981
+  data.tar.gz: c4884ce66ae50205a1a5033a3264da67dbd105d5f4e6210a6afbd9619161a1c8
 SHA512:
-  metadata.gz: bd84b67b67c9f209fbab6c5309d719719e3d9f19df12e1d7816acc6690c084dad052e8590cc39b85cfcc9477b6c187d1ec352a3a8e55a932c5f51d22c062e458
-  data.tar.gz: e7e0eab197a600c06a10c1bb6ec801499cfe3d55327e94232b565830b5ee6fa69c4a5bf7c19ab3082f0492917d83e6c36581ce53600d5cbf9ef0259df1b620b1
+  metadata.gz: fbd2777d9c2e08e2a46b2af5ed1baa357fa0bd16d75bf38b69352ef20318d4aa2b6ef75892a7e5438a2f31659e9fda808b0caef7897909e1c13928923e10c395
+  data.tar.gz: bb2e43abb4c22309616ca7c1bdca175922a89732cbd259978f634e9064e1f61a39bfc8b8a7007c0ba96f96b87dd573b1f5c71253ac1784921b0a97fa423d6eba

data/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+### [8.0.8] - 2026-08-26
+
+**Fixed**
+
+* Keep the event publisher across code reloads. The railtie re-runs `init` on every reload, and `init` disconnected the publisher it replaced -- but a tracked model publishes through the very publisher it was tracked with, so every model the reload did not reload kept publishing on a connection that had just been closed, and nothing ever reopened it: `Flu::NotConnectedError` ("'connect' was never called, or 'disconnect' was") on every event from then on, until the process was restarted. The publisher now outlives the reloads, and only a change of kind (the real publisher for the dummy one, or the other way round) replaces and disconnects it.
+* Reopen a connection Bunny has stopped recovering. Bunny reopens a connection it lost, but not one that never opened, nor one whose recovery attempts ran out: `publish` only ever reconnected after a fork, so a publisher left with such a connection raised on every event for the rest of the process. It now reopens it on the next publication, and no more than once every five seconds, since a broker that hangs rather than refuses costs a full `connect_timeout` per attempt.
+
+**Changed**
+
+* `connect` no longer retries an unreachable broker forever. It gives up after `max_connect_wait` seconds and raises `Flu::ConnectionLostError`. The railtie calls it from `to_prepare`, which runs on every code reload: waiting on a broker that never answers held the reload interlock, and the request behind it, for good.
+* A broker that cannot be reached at startup no longer keeps the application from booting. `Flu.start` logs the failure, and publishing opens the connection once the broker answers again.
+
+**Added**
+
+* `max_connect_wait` (default `30`), how many seconds the startup retries a broker that does not answer before letting the application boot. `nil` waits for the broker for as long as it takes.
+
+### [8.0.6] - 2026-08-19
+
+**Fixed**
+
+* Publish the events of a transaction from its commit rather than from each record's `after_commit`, which used to lose events two separate ways: Rails runs the transactional callbacks of a row on one single instance of it and skips the others (which one it picks is what `run_commit_callbacks_on_first_saved_instances_in_transaction` decides, and neither value was safe), and it skips every callback still queued as soon as one of them raises. Events now go out from the commit itself, which nothing can skip, once per recorded change and in the order the records were saved. A non-joinable transaction, such as the one `use_transactional_tests` wraps an example in, is never waited on, so a test suite sees what production does.
+* Keep an event whose publication failed for another attempt rather than giving up on it there and then. It waits in memory, per thread, up to `max_pending_events`, and is published by the next transaction to commit on that thread or at the end of the request or the job, whichever comes first. Nothing is attempted while the publisher reports itself unreachable, and an event still refused after three attempts, or pushed out of a full buffer, is handed to `on_publication_failure`.
+* Build and publish every change on its own, so an event that cannot be built or cannot reach the broker no longer costs the events queued behind it. A failed publication does not fail the transaction it belongs to either -- it has already committed by then.
+* Reconnect to RabbitMQ after a fork. A forked child inherited the parent's `Bunny` connection and published on it, which the broker then ended for both. `EventPublisher` now remembers the pid it connected under, caches channels per process as well as per thread, and drops an inherited connection instead of closing it.
+* Serialize `connect` and `disconnect` on a mutex. Two threads reaching `connect` together both opened a connection, the second overwriting the first, which stayed open and unreachable.
+
+**Added**
+
+* `Flu::ConnectionLostError`, raised by `publish` while the connection to RabbitMQ is down.
+* `on_publication_failure`, called with the event and the error when an event cannot be published, so that an application can keep it rather than read about it in the logs. The event is `nil` when it could not even be built.
+* `max_pending_events` (default `1000`), how many events a thread keeps waiting for the broker to be reachable again before the oldest are handed to `on_publication_failure`.
+
+**Changed**
+
+* Publishing while the connection is down now raises `Flu::ConnectionLostError` instead of the bare `RuntimeError` `Bunny::Session#create_channel` raises ("this connection is not open"), which nothing could tell apart from any other `RuntimeError`. It still fails immediately rather than waiting: Bunny reopens the connection in the background, and publishing works again once it has.
+
 ### [8.0.5] - 2026-08-03
 
 **Fixed**

data/README.md

@@ -16,7 +16,7 @@ For now, events are generated from:
 Add the gem to your project's Gemfile:
 
   ```ruby
-  gem "flu-rails", "8.0.5"
+  gem "flu-rails", "8.0.8"
   ```
 
 Then, create an initializer into your Rails app (`config/initializers/flu-rails.rb`)
@@ -50,7 +50,8 @@ Each configuration is detailed below.
 ### Start up
 
 `flu-rails` starts automatically through its `Railtie`: there is nothing to call by hand.
-Its startup waits until its RabbitMQ exchange is connected.
+Its startup waits for its RabbitMQ exchange to be connected, for at most `max_connect_wait` seconds. A broker that is still not there by then does not keep the application from booting:
+publishing reopens the connection itself once the broker answers again.
 
 ### Track changes on an ActiveRecord model
 
@@ -168,6 +169,9 @@ All options have a default value. However, all of them can be changed in your in
 | `default_ignored_request_params` | `[:password, :password_confirmation, :controller, :action]` | Boolean | Optional | By default, all these parameters will be ignored from controller request's `params` when creating an event. Independently of this option, any parameter your Rails application already masks through `config.filter_parameters` (passwords, tokens,...) is replaced with `"[FILTERED]"` in the event too, including inside nested params. | `false` |
 | `application_name` | `Rails.application.class.module_parent_name`, resolved on startup | String | Required | Is used as `emitter` for each event created by `flu-rails`, if not overriden by the `track_met`. | `my_app` |
 | `bunny_options` | `{}` | Hash of symbols | Optional | Additional options to add when connecting the RabbitMQ broker. This overrides the existing options with the same name. | `{ verify_peer: true }` |
+| `max_pending_events` | `1000` | Integer | Optional | An event the broker refused waits for the connection to be back, and is published by the next commit of the thread or at the end of the request. This is how many a thread keeps waiting before handing the oldest to `on_publication_failure`. They are held in memory: a process that dies takes them with it. | `5000` |
+| `on_publication_failure` | `nil` | Lambda | Optional | Called with the event and the error when an event cannot be published, instead of logging it. The transaction the event belongs to has already committed by then, so this is the last chance to keep it: store it and publish it again later. The event is `nil` when it could not even be built. | `lambda { |event, error| OutboxEvent.create!(payload: event&.to_json, error: error.message) }` |
+| `max_connect_wait` | `30` | Integer or `nil` | Optional | How many seconds the startup retries a broker that does not answer before giving up and letting the application boot. Publishing reopens the connection itself once the broker answers again. `nil` waits for the broker for as long as it takes. | `nil` |
 
 ## How to execute tests
 
@@ -313,8 +317,8 @@ scoped RubyGems credential.
 3. Tag the commit and push the tag:
 
 ```
-  $ git tag -a v8.0.5 -m "Version 8.0.5"
-  $ git push origin v8.0.5
+  $ git tag -a v8.0.8 -m "Version 8.0.8"
+  $ git push origin v8.0.8
 ```
 
 The workflow then checks that the tag matches `Flu::VERSION`, runs the tests, builds the gem

data/lib/flu-rails/active_record_extender.rb

@@ -1,16 +1,23 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/object/try"
+require "active_support/notifications"
 
 module Flu
   class ActiveRecordExtender
     def self.extend_models(event_factory, event_publisher)
+      publish_on_transaction_commit
+
       ActiveRecord::Base.class_eval do
         unless singleton_class.method_defined?(:flu_is_tracked)
           class_attribute :flu_is_tracked,               instance_accessor: false, default: false
           class_attribute :flu_user_metadata_lambdas,    instance_accessor: false, default: {}.freeze
           class_attribute :flu_ignored_model_changes,    instance_accessor: false, default: [].freeze
           class_attribute :flu_overriden_emitter_lambda, instance_accessor: false, default: nil
+          # Held per model rather than looked up on 'Flu', so that the publication driven by the
+          # transaction reaches the very publisher the model was tracked with.
+          class_attribute :flu_event_factory,            instance_accessor: false, default: nil
+          class_attribute :flu_event_publisher,          instance_accessor: false, default: nil
         end
 
         define_singleton_method(:track_entity_changes) do |options = {}|
@@ -18,6 +25,8 @@ module Flu
           self.flu_user_metadata_lambdas    = options.fetch(:user_metadata, {})
           self.flu_ignored_model_changes    = options.fetch(:ignored_model_changes, []).map(&:to_s)
           self.flu_overriden_emitter_lambda = options.fetch(:emitter, nil)
+          self.flu_event_factory            = event_factory
+          self.flu_event_publisher          = event_publisher
         
           after_create   { flu_track_entity_change(:create, saved_changes, event_factory) }
           after_update   { flu_track_entity_change(:update, saved_changes, event_factory) }
@@ -46,7 +55,8 @@ module Flu
         # and used 'run_callbacks(:commit)' instead, which runs *every* 'after_commit' callback on the record, 
         # including the hoste application's own (mailers, jobs, cache invalidation), not just Flu's.
         define_method(:flu_publish_events!) do
-          flu_commit_changes(event_factory, event_publisher)
+          flu_commit_changes(self.class.flu_event_factory   || event_factory,
+                             self.class.flu_event_publisher || event_publisher)
         end
 
         def flu_add_manual_event(name, data)
@@ -56,24 +66,37 @@ module Flu
             data: data,
             flu_is_a_manual_event: true
           })
+          Flu::TransactionBuffer.current.record(self) if self.class.flu_is_tracked
         end
 
         def flu_changes_as_events(event_factory)
-          flu_changes.select do |data|
-            !data[:changes].try(:empty?) || data[:flu_is_a_manual_event]
-          end.map do |data|
-            if data[:flu_is_a_manual_event]
-              event_factory.build_manual_event(data[:name], data[:data])
-            else
-              event_factory.build_entity_change_event(data)
-            end
+          flu_publishable_changes.map { |change| flu_change_as_event(change, event_factory) }
+        end
+
+        def flu_publishable_changes
+          flu_changes.select do |change|
+            !change[:changes].try(:empty?) || change[:flu_is_a_manual_event]
+          end
+        end
+
+        def flu_change_as_event(change, event_factory)
+          if change[:flu_is_a_manual_event]
+            event_factory.build_manual_event(change[:name], change[:data])
+          else
+            event_factory.build_entity_change_event(change)
           end
         end
 
+        # Every change is built and published on its own: one that cannot be is reported and the next
+        # one goes out all the same, where a raise would take the whole rest of the batch with it.
         def flu_commit_changes(event_factory, event_publisher)
-          flu_changes_as_events(event_factory).each do |event|
+          flu_publishable_changes.each do |change|
+            event = flu_change_as_event(change, event_factory)
             event_publisher.publish(event)
+          rescue StandardError => error
+            Flu.publication_failed(event, error, event_publisher)
           end
+        ensure
           flu_flush_changes
         end
 
@@ -98,10 +121,49 @@ module Flu
                                                                                            self.class.flu_association_columns,
                                                                                            self.class.flu_ignored_model_changes,
                                                                                            self.class.flu_overriden_emitter_lambda)
-            flu_changes.push(data) unless data.nil?
+            return if data.nil?
+            flu_changes.push(data)
+            Flu::TransactionBuffer.current.record(self)
           end
         end
       end
     end
+
+    # The commit of the transaction, unlike the 'after_commit' callbacks that follow it, is a moment
+    # Rails cannot skip: the notification is emitted once the COMMIT is through and before the first
+    # callback runs, so no callback raising afterwards can cost anybody their events.
+    def self.publish_on_transaction_commit
+      unless @subscribed
+        @subscribed = true
+
+        ActiveSupport::Notifications.subscribe("start_transaction.active_record") do |*, payload|
+          TransactionBuffer.current.transaction_started if joinable?(payload)
+        end
+
+        ActiveSupport::Notifications.subscribe("transaction.active_record") do |*, payload|
+          next unless joinable?(payload)
+
+          buffer = TransactionBuffer.current
+          if payload[:outcome] == :commit
+            buffer.transaction_committed.each do |entity|
+              # Nothing may travel from here into the commit that is calling us.
+              entity.flu_commit_changes(entity.class.flu_event_factory, entity.class.flu_event_publisher)
+            rescue StandardError => error
+              Flu.config.logger&.error("Flu could not build the events of #{entity.class}: " \
+                                      "#{error.class}: #{error.message}")
+            end
+            Flu.retry_pending_publications
+          else
+            buffer.transaction_rolled_back.each(&:flu_rollback_changes)
+          end
+        end
+      end
+    end
+
+    # A transaction opened as non-joinable, such as the one 'use_transactional_tests' wraps an
+    # example in, is rolled back rather than committed and only its savepoints publish anything.
+    def self.joinable?(payload)
+      !payload[:transaction].equal?(ActiveRecord::Transaction::NULL_TRANSACTION)
+    end
   end
 end

data/lib/flu-rails/configuration.rb

@@ -18,6 +18,9 @@ module Flu
                   :default_ignored_model_changes,
                   :default_ignored_request_params,
                   :application_name,
-                  :bunny_options
+                  :bunny_options,
+                  :on_publication_failure,
+                  :max_pending_events,
+                  :max_connect_wait
   end
 end

data/lib/flu-rails/errors.rb

@@ -6,4 +6,7 @@ module Flu
 
   class NotConnectedError < Error
   end
+
+  class ConnectionLostError < Error
+  end
 end

data/lib/flu-rails/event_publisher.rb

@@ -10,11 +10,18 @@ module Flu
     NOT_CONNECTED_MESSAGE = "no connection to RabbitMQ: 'connect' was never called, or " \
                             "'disconnect' was. The railtie calls it at boot unless " \
                             "'auto_connect_to_exchange' is false."
+    CONNECTION_LOST_MESSAGE = "the connection to RabbitMQ is down. Bunny reopens it in the " \
+                              "background when 'automatically_recover' is on, and publishing " \
+                              "works again once it has."
+    CONNECTION_FAILED_MESSAGE = "could not reach RabbitMQ within %s seconds. Publishing reopens " \
+                                "the connection itself once the broker answers again."
+    RECONNECTION_INTERVAL = 5
 
     def initialize(configuration)
-      @logger        = configuration.logger
-      @configuration = configuration
-      @exchange_key  = :"flu_exchange_#{object_id}" # Channels are cached per thread
+      @logger          = configuration.logger
+      @configuration   = configuration
+      @mutex           = Mutex.new
+      @next_attempt_at = 0
     end
 
     def publish(event, persistent=true)
@@ -22,54 +29,112 @@ module Flu
       @logger.debug { "Publishing event with id '#{event.id}' with routing key: #{routing_key}" }
       exchange.publish(event.to_json, routing_key: routing_key, persistent: persistent)
       @logger.debug { "Event published." }
+    rescue Bunny::ConnectionClosedError
+      raise ConnectionLostError, CONNECTION_LOST_MESSAGE
     end
 
+    # Retries a broker that is not there yet, for at most 'max_connect_wait' seconds. Waiting on it
+    # forever would hold whatever called it -- the railtie calls it from 'to_prepare', which runs on
+    # every code reload, holding the reload interlock and the request that triggered it.
     def connect
-      unless connected?
-        connected = false
-        while !connected
-          begin
-            connect_to_exchange
-            connected = true
-          rescue Bunny::TCPConnectionFailedForAllHosts
-            @logger.warn("RabbitMQ connection failed, try again in 1 second.")
-            sleep 1
-          end
+      @mutex.synchronize do
+        next if connected?
+        give_up_at = deadline
+        begin
+          connect_to_exchange
+        rescue Bunny::TCPConnectionFailedForAllHosts
+          raise ConnectionLostError, format(CONNECTION_FAILED_MESSAGE, @configuration.max_connect_wait) if expired?(give_up_at)
+          @logger.warn("RabbitMQ connection failed, try again in 1 second.")
+          sleep 1
+          retry
         end
       end
     end
 
     def connected?
-      !@connection.nil? && @connection.open?
+      !forked? && !@connection.nil? && @connection.open?
     end
 
     # Closing the connection closes every channel opened on it, and stops the heartbeat and
     # recovery threads Bunny runs alongside it.
     # The guard is on the connection alone: a connection that was opened before the exchange could
     # be declared still has to be closed.
+    # An inherited connection is dropped rather than closed: its socket is the parent's.
     def disconnect
-      if !@connection.nil? && @connection.open?
-        @connection.close
+      @mutex.synchronize do
+        @connection.close if connected?
+        @connection = nil
+        @pid        = nil
+        Thread.current[exchange_key] = nil
       end
-      @connection = nil
-      Thread.current[@exchange_key] = nil
     end
 
     private
 
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # A nil 'max_connect_wait' waits on the broker for however long it takes.
+    def deadline
+      @configuration.max_connect_wait.nil? ? nil : now + @configuration.max_connect_wait
+    end
+
+    def expired?(give_up_at)
+      !give_up_at.nil? && now >= give_up_at
+    end
+
+    # A connection Bunny is recovering comes back on its own. One that never opened, or that Bunny
+    # has given up on, comes back from here or not at all.
+    def abandoned?
+      return false if @connection.nil? || @connection.open?
+      !@connection.recovering_from_network_failure? &&
+        (!@connection.automatically_recover? ||
+         @connection.closed? ||
+         @connection.status == :not_connected)
+    end
+
+    # A broker that hangs rather than refuses costs a full Bunny 'connect_timeout' per attempt, so
+    # publishing pays for one at most every 'RECONNECTION_INTERVAL' seconds.
+    def due_for_another_attempt?
+      return false if now < @next_attempt_at
+      @next_attempt_at = now + RECONNECTION_INTERVAL
+      true
+    end
+
+    # Reopening is best effort: the caller is publishing, and an event that cannot go out is
+    # reported through the connection errors below rather than through whatever the broker refused.
+    def reconnect
+      @mutex.synchronize { connect_to_exchange unless connected? }
+    rescue StandardError => error
+      @logger.warn("Could not reopen the connection to RabbitMQ: #{error.class}: #{error.message}")
+    end
+
+    # A child inherits the parent's socket but none of the threads Bunny runs on it.
+    def forked?
+      !@pid.nil? && @pid != Process.pid
+    end
+
+    # Per process too: a channel cached before the fork still reports itself open in the child.
+    def exchange_key
+      :"flu_exchange_#{object_id}_#{Process.pid}"
+    end
+
     # One channel per thread rather than one for the whole publisher. 
     # Bunny serialises every publication on the channel's own mutex.
     #
     # No bookkeeping of the channels handed out is needed. 
     # Closing the connection closes all of them, so a thread holding a closed channel simply opens a new one on its next publication:
     # 'disconnect' and a reconnection are both covered without reaching into other threads.
-    # Only the absence of a connection is reported here. A connection that exists but is closed or
-    # recovering is Bunny's story to tell, and its own error says more about it than this one could.
+    # A connection that is down is reported as such rather than left to 'create_channel', which
+    # raises a bare 'RuntimeError' the caller has no way to tell from any other.
     def exchange
-      cached = Thread.current[@exchange_key]
+      reconnect if forked? || (abandoned? && due_for_another_attempt?)
+      cached = Thread.current[exchange_key]
       return cached if cached && cached.channel.open?
       raise NotConnectedError, NOT_CONNECTED_MESSAGE if @connection.nil?
-      Thread.current[@exchange_key] = declare_exchange
+      raise ConnectionLostError, CONNECTION_LOST_MESSAGE unless @connection.open?
+      Thread.current[exchange_key] = declare_exchange
     end
 
     def declare_exchange
@@ -90,7 +155,8 @@ module Flu
 
       @connection = Bunny.new(options)
       @connection.start
-      Thread.current[@exchange_key] = declare_exchange
+      @pid = Process.pid
+      Thread.current[exchange_key] = declare_exchange
     end
   end
 end

data/lib/flu-rails/pending_publications.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Flu
+  # The events whose publication failed, kept for another attempt.
+  #
+  # A broker that closes a connection takes a few seconds to be usable again, since Bunny reopens it
+  # in the background, and an event published in that window has nowhere to go. Rather than being
+  # given up on there, it waits here for the connection to be back: the next transaction to commit on
+  # the thread comes back for it, and so does the end of the request or the job it belongs to.
+  #
+  # In memory, and per thread: what is waiting here dies with the process. An application that cannot
+  # afford to lose an event keeps it itself, from 'on_publication_failure', which is called for every
+  # event this gives up on.
+  class PendingPublications
+    MAX_ATTEMPTS = 3
+
+    def self.current
+      Thread.current[:flu_pending_publications] ||= new
+    end
+
+    def initialize
+      @entries = []
+    end
+
+    def size
+      @entries.size
+    end
+
+    def push(event, publisher, error)
+      give_up(@entries.shift) while @entries.size >= Flu.config.max_pending_events
+      @entries.push({ event: event, publisher: publisher, error: error, attempts: 1 })
+    end
+
+    # Publishes again what its publisher can reach again, keeps what it cannot, and gives up on what
+    # has been refused MAX_ATTEMPTS times, an event the broker itself rejects being no more publishable
+    # on the tenth attempt than on the first.
+    def drain
+      return if @entries.empty?
+
+      kept = []
+      @entries.each do |entry|
+        next kept.push(entry) unless reachable?(entry[:publisher])
+
+        begin
+          entry[:publisher].publish(entry[:event])
+        rescue StandardError => error
+          entry[:error]     = error
+          entry[:attempts] += 1
+          entry[:attempts] < MAX_ATTEMPTS ? kept.push(entry) : give_up(entry)
+        end
+      end
+      @entries = kept
+    end
+
+    private
+
+    def reachable?(publisher)
+      publisher.connected?
+    rescue StandardError
+      false
+    end
+
+    def give_up(entry)
+      Flu.report_publication_failure(entry[:event], entry[:error])
+    end
+  end
+end

data/lib/flu-rails/railtie.rb

@@ -15,5 +15,11 @@ module Flu
       Flu.init
       Flu.start
     end
+
+    # The end of a request or of a job, which runs even when it is an exception that ended it, is the
+    # last chance to publish what the broker could not take a moment earlier.
+    initializer "flu.retry_pending_publications" do |application|
+      application.executor.to_complete { Flu.retry_pending_publications }
+    end
   end
 end

data/lib/flu-rails/transaction_buffer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Flu
+  # The entities that recorded events in the transaction currently open, so that its commit can
+  # publish them.
+  #
+  # A record hands its events over from 'after_commit', and Rails skips every transactional callback
+  # still to run as soon as one of them raises: it re-commits the rest of the batch with
+  # 'should_run_callbacks: false' (ActiveRecord::ConnectionAdapters::Transaction#commit_records). One
+  # raising callback, in this gem or in the application, therefore drops the events of every record
+  # left in the queue. The commit of the transaction itself is the one moment nothing can skip, and
+  # it is where these are published instead.
+  #
+  # One buffer per thread, one mark per open transaction: what a transaction recorded is what was
+  # pushed past its mark, which is what its rollback discards and what the outermost commit hands
+  # back. A thread holding transactions open on several databases at once shares that one stack, so
+  # the events of the first to commit wait for the last.
+  class TransactionBuffer
+    def self.current
+      Thread.current[:flu_transaction_buffer] ||= new
+    end
+
+    def initialize
+      @entities = []
+      @marks    = []
+    end
+
+    # @return [Boolean] false when no transaction is open, in which case nothing will ever drain the
+    #   buffer and the entity is left to publish its own changes.
+    def record(entity)
+      if @marks.empty?
+        false
+      else
+        @entities.push(entity)
+        true
+      end
+    end
+
+    def transaction_started
+      @marks.push(@entities.size)
+    end
+
+    # @return [Array] the entities to publish: those of the outermost transaction, none otherwise,
+    #   a nested transaction leaving what it recorded to the one it is nested in.
+    def transaction_committed
+      @marks.pop
+      if @marks.empty?
+        committed = @entities
+        @entities = []
+        committed
+      else
+        []
+      end
+    end
+
+    # @return [Array] the entities whose events the rollback discards.
+    def transaction_rolled_back
+      @entities.slice!((@marks.pop || 0)..) || []
+    end
+  end
+end

data/lib/flu-rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flu
-  VERSION = "8.0.5"
+  VERSION = "8.0.8"
 end

data/lib/flu-rails.rb

@@ -10,6 +10,8 @@ require_relative "flu-rails/event_factory"
 require_relative "flu-rails/queue_repository"
 require_relative "flu-rails/configuration"
 require_relative "flu-rails/core_ext"
+require_relative "flu-rails/transaction_buffer"
+require_relative "flu-rails/pending_publications"
 require_relative "flu-rails/event_publisher"
 require_relative "flu-rails/util"
 require_relative "flu-rails/dummy/in_memory_event_publisher"
@@ -36,15 +38,41 @@ module Flu
     @event_publisher
   end
 
+  # Keeps an event whose publication failed for another attempt, a broker being reachable again
+  # within seconds. One that could not even be built is reported at once instead.
+  def self.publication_failed(event, error, event_publisher)
+    if event.nil?
+      report_publication_failure(event, error) 
+    else
+      PendingPublications.current.push(event, event_publisher, error)
+    end
+  end
+
+  # Publishes again what the last attempt could not. Never raises: its callers are a transaction that
+  # has committed and the end of a request, neither of which is a place to fail.
+  def self.retry_pending_publications
+    PendingPublications.current.drain
+  rescue StandardError => error
+    config.logger&.error("Flu could not retry the publications it had kept: #{error.class}: #{error.message}")
+  end
+
+  # @param event [Flu::Event, nil] nil when the event could not even be built.
+  def self.report_publication_failure(event, error)
+    handler = config.on_publication_failure
+    if handler.nil?
+      subject = event.nil? ? "an event it could not build" : "the event '#{event.id}' ('#{event.name}')"
+      config.logger&.error("Flu could not publish #{subject}: #{error.class}: #{error.message}. " \
+                           "The event is lost unless 'on_publication_failure' is configured to keep it.")
+    else
+      handler.call(event, error) 
+    end
+  end
+
   def self.init
     @configuration.application_name ||= default_application_name
     raise "configuration.application_name must not be nil" if @configuration.application_name.nil?
     @logger          = @configuration.logger
     @event_factory   = Flu::EventFactory.new(@configuration)
-    # The railtie re-runs 'init' on every code reload. The publisher being replaced owns an open
-    # connection, its channel and Bunny's heartbeat thread: dropping the reference to it without
-    # closing it leaks all three for the lifetime of the process.
-    @event_publisher&.disconnect
     @event_publisher = create_event_publisher(@configuration)
     extend_models_and_controllers
   end
@@ -58,14 +86,24 @@ module Flu
     end
   end
 
+  # The railtie re-runs 'init' on every code reload. Building a new publisher on each of them left
+  # every reference the application had already taken on the previous one -- a tracked model
+  # publishes through the very publisher it was tracked with -- on a connection 'init' had closed
+  # and that nothing ever reopens. The publisher outlives the reloads, and only a change of kind
+  # replaces it: its connection, its channels and Bunny's heartbeat thread are then closed with it.
   def self.create_event_publisher(configuration)
-    if is_testing_environment?
+    publisher_class = event_publisher_class
+    return @event_publisher if @event_publisher.instance_of?(publisher_class)
+
+    @event_publisher&.disconnect
+    if publisher_class == Flu::Dummy::InMemoryEventPublisher
       logger.info("Loading Flu with a dummy event publisher (this will not connect any exchange)")
-      require_relative "flu-rails/dummy/in_memory_event_publisher"
-      Flu::Dummy::InMemoryEventPublisher.new(@configuration)
-    else
-      Flu::EventPublisher.new(@configuration)
     end
+    publisher_class.new(configuration)
+  end
+
+  def self.event_publisher_class
+    is_testing_environment? ? Flu::Dummy::InMemoryEventPublisher : Flu::EventPublisher
   end
 
   def self.is_testing_environment?
@@ -80,8 +118,13 @@ module Flu
     Flu::CoreExt.extend_controller_classes(@event_factory, @event_publisher, @logger)
   end
 
+  # A broker that is not there yet must not keep the application from booting: publishing reopens
+  # the connection itself once the broker answers again.
   def self.start
-    @event_publisher.connect if config.auto_connect_to_exchange
+    return unless config.auto_connect_to_exchange
+    @event_publisher.connect
+  rescue Flu::ConnectionLostError => error
+    config.logger&.error("Flu could not connect to RabbitMQ: #{error.message}")
   end
 
   def self.load_configuration
@@ -103,6 +146,9 @@ module Flu
       config.default_ignored_request_params = [:password, :password_confirmation, :controller, :action]
       config.application_name               = nil
       config.bunny_options                  = {}
+      config.on_publication_failure         = nil
+      config.max_pending_events             = 1000
+      config.max_connect_wait               = 30
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flu-rails
 version: !ruby/object:Gem::Version
-  version: 8.0.5
+  version: 8.0.8
 platform: ruby
 authors:
 - Loïc Vigneron
@@ -203,8 +203,10 @@ files:
 - lib/flu-rails/event.rb
 - lib/flu-rails/event_factory.rb
 - lib/flu-rails/event_publisher.rb
+- lib/flu-rails/pending_publications.rb
 - lib/flu-rails/queue_repository.rb
 - lib/flu-rails/railtie.rb
+- lib/flu-rails/transaction_buffer.rb
 - lib/flu-rails/util.rb
 - lib/flu-rails/version.rb
 homepage: https://github.com/crepesourcing/flu-rails