startback 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d6c4214ad33ba472543754def2abcda5d8b4bb00b632ff7521c7938c1bb9e5
-  data.tar.gz: f5a3e38d97b24cfc6081e4f2dbc6939bbc3ee98f216522b85d88a82e3214ebc5
+  metadata.gz: 844c222d0b34ee64835caafe69e4a52b0fad2176653b007208fb16feba998556
+  data.tar.gz: c7a8ff0dd59aa367d4de6fdf4f23c4c916ac52e98e935316ca267af834ef7655
 SHA512:
-  metadata.gz: 3c817bcfe4072d5a5b7a529e58d9cefde85afb6306fd4c173e5b478a2b5fb56096a30ca5ae1ac18fcb56dfd6ed7102eb2a55fe818da4aefa5739800078b24b3c
-  data.tar.gz: b48bb2f32f7fb30be9359fe6758042574099a043abf4e9a82f2ec235b5e3e25b9241b2964effb8ab95fdb47943fede69a255aa0d5fc45bf324aa858497c28085
+  metadata.gz: e928708f893554970de832c1b0c1f1235134614f0fe7e6b82ed8208502f423c6f911d0ad3898f3ddd8185d0bdc85634d03ec40e9b169164100e64c72b1ca824e
+  data.tar.gz: ab333a49176eda2128b6cc1c502135be60c4cbc9479f05afef983186452f412c9c388f12cd2cece970e3da5a2a39da05e24dd7c2793f5d57e53d2365d90847d0

data/CHANGELOG.md

@@ -1,3 +1,141 @@
+## 2.1.0 - 2026-09-30
+
+Ruby 4.0 support, docker images for several ruby versions, and the Bunny
+event bus finally under test -- which is how two silent bugs and a RabbitMQ
+4.3 incompatibility came to light.
+
+**Almost nothing here asks anything of you.** Startback's API is unchanged
+and the bus upgrade needs no broker-side migration. The one thing that does
+move: the un-suffixed docker tags go from Ruby 3.3 to Ruby 3.4, a minor
+bump. The details are below because the *reasons* matter, not because there
+is much to do.
+
+### Ruby 4.0 is supported
+
+The test grid now runs **Ruby 3.2, 3.3, 3.4 and 4.0** -- the whole range
+`required_ruby_version` allows, so the floor is a tested claim rather than an
+assumed one. Startback needed no source change for 4.0: the gem,
+`startback-jobs`, `startback-web` and the example application's webspicy
+specs are green on all four, with no deprecation warning from Startback's own
+code.
+
+`required_ruby_version` stays `>= 3.2`.
+
+### Docker images are released for Ruby 3.4 and 4.0
+
+Images are built for each ruby version of the release matrix. The tags that
+name no ruby version follow `DEFAULT_MRI_VERSION`, which is **Ruby 3.4**:
+2.0.0 published them from Ruby 3.3, so `enspirit/startback:api` and `:web`
+move by one minor version here, and stay put from now on.
+
+| Tag | Ruby |
+|---|---|
+| `enspirit/startback:api`, `:api-2.1.0`, `:api-2.1` | 3.4 (was 3.3 in 2.0.0) |
+| `enspirit/startback:api-ruby3.4`, `:api-2.1.0-ruby3.4`, `:api-2.1-ruby3.4` | 3.4 |
+| `enspirit/startback:api-ruby4.0`, `:api-2.1.0-ruby4.0`, `:api-2.1-ruby4.0` | 4.0 |
+
+Same for the `web` target. **No Ruby 3.3 image is published any more**: an
+application pinned to `:api-ruby3.3` stays at 2.0.0 and should move to
+`:api-ruby3.4`. Only `DEFAULT_MRI_VERSION` in the Makefile publishes the
+un-suffixed tags, so adding a ruby version to the matrix can
+never change what `:api` means depending on which release job finished last.
+`make images.all` walks the whole matrix the way the release workflow does.
+
+The `web` image moves from **nodejs 20 to nodejs 22**, node 20 having reached
+end of life in April 2026.
+
+### The Bunny event bus is now covered by the test suite
+
+It was the one part of Startback with no automated coverage, on the grounds
+that the grid had no broker. It now has one, and 19 specs that talk to it for
+real -- mocking bunny would only assert that Startback calls the methods
+Startback calls. They cover connecting, autoconnect, the emit/listen round
+trip, fanout across processor queues, type isolation, adoption of a
+pre-existing topology, and the asynchronous contract that emit errors must
+not reach the emitter.
+
+Without a broker those specs skip, so `make tests` stays green for a
+contributor without docker; `make rabbitmq.up` starts one through the new
+`docker-compose.yml`. CI sets `STARTBACK_SPEC_REQUIRE_BUNNY=1`, which turns
+"no broker" into a failure, because otherwise a broken service container
+would take the coverage away without anything turning red.
+
+### The bus stops working on RabbitMQ 4.3, and now does not
+
+`queue_options` defaulted to `{}`, which declares a *transient non-exclusive*
+queue. RabbitMQ deprecated that, and flips it from `permitted_by_default` to
+`denied_by_default` in 4.3:
+
+| RabbitMQ | transient non-exclusive queues | Startback <= 2.0 bus |
+|---|---|---|
+| 4.0, 4.1, 4.2 | permitted | works |
+| **4.3+** | **denied** | **`listen` receives nothing, then `Timeout::Error`** |
+
+The defaults are now durable for both the exchange and the queue, which is
+also what a named processor queue wants: events waiting in it outlive a
+broker restart instead of being dropped, and a durable queue bound to a
+transient exchange would come back after a restart with nothing routing to
+it.
+
+```ruby
+fanout_options: { durable: true },
+queue_options:  { durable: true },
+```
+
+**No migration is required, deliberately.** AMQP refuses to redeclare an
+object with different properties, so on a broker up since an older Startback
+declared its topology the durable declaration is rejected with
+`PRECONDITION_FAILED`. Rather than make that your problem, the bus *adopts*
+whatever is already there (`passive: true` matches an existing object
+whatever its properties) and logs a warning. Transient objects do not survive
+a broker restart, so the durable declaration takes over by itself at the next
+one, with nobody having done anything.
+
+Left alone that would have been a nasty upgrade: `emit` runs inside
+`stop_errors`, so the rejection was swallowed and the application went on
+returning 200s while silently dropping every event.
+
+Applications already passing their own `queue_options`/`fanout_options` are
+unaffected: explicit options still win.
+
+### Two silent bunny bugs fixed
+
+Both predate this release and neither announced itself:
+
+* **A dead channel was cached forever.** A channel-level error closes the
+  channel, and the bus kept one per thread without checking it was still
+  open. One such error therefore broke the bus for that thread permanently --
+  every later `emit` failing with `cannot use a closed channel`, for *any*
+  event type, swallowed by `stop_errors`. The channel is now renewed when
+  found closed.
+
+* **Declaring could unsubscribe your listeners.** A rejected declaration
+  closes the channel it happened on, which was the shared one carrying the
+  consumers. Topology is now probed on a scratch channel, memoized per
+  connection so `emit` does not pay for it on every call.
+
+### Known wart, documented rather than fixed
+
+A Bunny listener receives the raw JSON `String` off the queue, where a
+`Bus::Memory::Async` listener receives a `Startback::Event`. Listeners are
+not portable between the two busses. The bus even carries a `factor_event`
+method for this, defined and never called. A spec pins the current
+behaviour; changing it would break every existing listener.
+
+### Other changes
+
+* CI housekeeping: `actions/checkout` v2/v3 -> v4, `actions/setup-node` v3
+  -> v4 on nodejs 22 (14 was long end of life, and it is the javascript
+  runtime `startback-web`'s sprockets specs need), `docker/login-action` v1
+  -> v3. The image release workflow reads the version to tag from
+  `github.ref_name` rather than `git describe --contains`, which silently
+  yielded nothing on a shallow checkout and downgraded a release to
+  unversioned tags.
+
+* The 2.0.0 notes said `benchmark`, `json`, `logger` and `ostruct` stop being
+  default gems "in Ruby 3.5". That release became 4.0, and `json` is still a
+  default gem there. Corrected in place.
+
 ## 2.0.0 - 2026-09-29
 
 Major dependency upgrade. Sinatra 4 (hence Rack 3) is now required, and the
@@ -130,7 +268,7 @@ however resolve to the newest of each, and each has its own breaking changes:
 
 * `benchmark`, `json`, `logger` and `ostruct` are now explicit runtime
   dependencies. They are required by `lib/startback.rb` and stop being default
-  gems in Ruby 3.5.
+  gems in Ruby 4.0 -- `json` excepted, which is still one there.
 
 * The example application and both contrib gems moved to webspicy 1.0, whose
   own ranges are what makes finitio 1.0, http 6 and rack-robustness 2.0
@@ -144,6 +282,7 @@ however resolve to the newest of each, and each has its own breaking changes:
   RabbitMQ — so bunny 3 is upgraded but unverified by the suite. Likewise,
   `http`, `jwt`, `puma`, `nokogiri`, `tzinfo`, `i18n` and `mustache` are never
   loaded by Startback, so the suite says nothing about their new majors.
+  *(The bus is covered as of 2.1.0.)*
 
 * Applications testing with webspicy must move to its 1.x line. Every 0.27.x
   release requires `finitio < 0.13`, `http < 6.0` and `rack-robustness < 2.0`,

data/README.md

@@ -22,3 +22,45 @@ This gem uses semantic versioning. The public API is defined as follows:
   main `CMD`.
 
 Upgrading across a major version? See [UPGRADING.md](UPGRADING.md).
+
+## Supported rubies
+
+CI runs the suite on **Ruby 3.2, 3.3, 3.4 and 4.0** -- the whole range
+`required_ruby_version` allows. Docker images are released for 3.4 and 4.0.
+
+## Running the tests
+
+    make tests
+
+The `Startback::Event::Bus::Bunny::Async` specs need a real RabbitMQ broker --
+mocking bunny would only assert that Startback calls the methods Startback
+calls. Start one and point the suite at it:
+
+    make rabbitmq.up
+    export STARTBACK_BUS_BUNNY_ASYNC_URL=amqp://guest:guest@localhost:5672
+    make tests
+    make rabbitmq.down
+
+Without a broker those specs **skip**, and the suite is still green. CI sets
+`STARTBACK_SPEC_REQUIRE_BUNNY=1`, which turns "no broker" into a failure, so
+that a broken service container cannot quietly take the coverage away.
+
+## Docker images
+
+    docker pull enspirit/startback:api    # ruby 3.4
+    docker pull enspirit/startback:web    # ruby 3.4, plus nodejs and yarn
+
+The tags that name no ruby version -- `:api`, `:api-2.1.0`, `:api-2.1` -- are
+built with `DEFAULT_MRI_VERSION`, currently **3.4**. Every ruby version listed
+in `RELEASE_MRI_VERSIONS` is also reachable by name:
+
+    docker pull enspirit/startback:api-ruby4.0
+    docker pull enspirit/startback:api-2.1.0-ruby4.0
+
+Both variables live at the bottom of the [Makefile](Makefile). Adding a ruby
+version to the release matrix means listing it there and in the
+`ruby-version` matrix of the tests and release-images workflows.
+
+`make images` builds and pushes one ruby version (`MRI_VERSION`, defaulting to
+`DEFAULT_MRI_VERSION`); `make images.all` walks the whole matrix, as the
+release workflow does with one job per version.

data/UPGRADING.md

@@ -1,5 +1,121 @@
 # Upgrading Startback
 
+## From 2.0.x to 2.1.0
+
+**There is next to nothing to do.** Startback's API is unchanged and the
+event bus upgrade needs no broker-side migration. One thing does move: the
+un-suffixed docker tags go from Ruby 3.3 to Ruby 3.4. This section exists so
+you know *why*, and so you can spot the one thing that might bite you later.
+
+| | |
+|---|---|
+| Ruby | Unchanged, still `>= 3.2`. Ruby 4.0 is now supported and tested. |
+| Docker images | `enspirit/startback:api` and `:web` move from Ruby 3.3 to **Ruby 3.4**. Ruby 4.0 is opt-in by name. |
+| Event bus | Durable topology now, adopted automatically. **But see the RabbitMQ 4.3 wall below.** |
+
+---
+
+### The one thing to know: RabbitMQ 4.3
+
+This is the only item here with a deadline, and it is not really about
+Startback.
+
+`queue_options` used to default to `{}`, declaring a *transient
+non-exclusive* queue. RabbitMQ deprecated that and flips it to denied in 4.3:
+
+| RabbitMQ | transient non-exclusive queues | Startback <= 2.0 bus |
+|---|---|---|
+| 4.0, 4.1, 4.2 | permitted | works |
+| **4.3+** | **denied** | **`listen` receives nothing, then `Timeout::Error`** |
+
+So on 4.2 or earlier nothing is on fire today -- but 4.3 is a wall you hit
+whether or not you upgrade Startback. 2.1.0 is what gets you over it: the
+exchange and queue are now declared `durable: true`.
+
+### Why the durable switch costs you nothing
+
+AMQP refuses to redeclare an exchange or queue with different properties. On
+a broker that has been up continuously since an older Startback declared its
+topology, the new durable declaration is rejected with
+`PRECONDITION_FAILED`. Startback now **adopts** what is already there rather
+than failing on it, logging:
+
+```
+Adopting an existing fanout whose properties differ from the requested ones.
+It will be declared as requested after the next broker restart.
+```
+
+So deploy in any order, with or without restarting the broker. There is
+nothing to drain and nothing to delete: a transient queue holds no durable
+state, and does not survive a broker restart in the first place. You become
+durable by yourself the next time the broker restarts.
+
+Restarting the broker before deploying gets you there immediately, but it is
+an option, not a requirement.
+
+Applications already passing their own `queue_options`/`fanout_options` are
+unaffected: explicit options still win.
+
+### Two bus bugs fixed, in case you saw them
+
+Both predate 2.1.0 and neither announced itself. If you have ever seen the
+bus "just stop" until a restart, this is likely why:
+
+* **A dead channel was cached forever.** A channel-level error closes the
+  channel, and the bus kept one per thread without checking it was still
+  open. One such error broke the bus for that thread permanently -- every
+  later `emit` failing with `cannot use a closed channel`, for *any* event
+  type. Since `emit` runs inside `stop_errors`, the application kept
+  returning 200s while dropping every event.
+
+* **Declaring could unsubscribe your listeners.** A rejected declaration
+  closes the channel it happened on, which was the shared one carrying your
+  consumers. Topology is now probed on a scratch channel.
+
+### Bus listeners still receive a String
+
+Not a change, but now documented and pinned by a spec, because it bites
+people moving a listener between busses:
+
+```ruby
+bus.listen("My::Event::Type", "my-processor") do |body|
+  # Bus::Memory::Async hands over a Startback::Event here.
+  # Bus::Bunny::Async hands over the raw JSON String.
+  event = Startback::Event.json(body, nil)
+end
+```
+
+### Docker images, if you build on them
+
+`enspirit/startback:api` and `:web` are built from `DEFAULT_MRI_VERSION`,
+now **Ruby 3.4**. 2.0.0 published them from Ruby 3.3, so tracking those tags
+moves you one ruby minor version -- not a major, and 3.3 reaches end of life
+in March 2027. Ruby 4.0 stays opt-in, asked for by name:
+
+```dockerfile
+FROM enspirit/startback:api-ruby4.0         # tracks 2.x on ruby 4.0
+FROM enspirit/startback:api-2.1.0-ruby4.0   # pinned
+```
+
+The `web` target now installs **nodejs 22** instead of 20, node 20 being end
+of life since April 2026. Applications pinning a node version in their own
+layer are unaffected.
+
+**Moving your own application to Ruby 4.0** is a separate exercise, and worth
+doing separately. `benchmark`, `logger` and `ostruct` stop being default gems
+there: if your code requires them without declaring them, add them to your
+Gemfile. Startback already declares all three for itself.
+
+### Checklist
+
+- [ ] Nothing, unless you are heading for RabbitMQ 4.3 -- in which case 2.1.0
+      is what you need, and it is enough
+- [ ] `:api` / `:web` move from Ruby 3.3 to 3.4. 2.1.0 publishes no Ruby 3.3
+      image: ask for `-ruby4.0` if you want 4.0, or stay on
+      `:api-2.0.0-ruby3.3` if you are not ready to leave 3.3
+
+---
+
 ## From 1.2.x to 2.0.0
 
 **Startback's own API has not changed.** Every class, require path, constructor
@@ -270,12 +386,14 @@ Applies to `Startback::Event::Bus::Bunny::Async` only.
 
 **Heads up on coverage:** Startback's test matrix has no RabbitMQ, so the Bunny
 bus is upgraded but *unverified by the suite*. If you use it, exercise it in a
-staging environment rather than trusting the green build.
+staging environment rather than trusting the green build. *(Fixed in 2.1.0 --
+and it found a RabbitMQ 4.3 incompatibility. See the 2.1.0 section above.)*
 
 **Not ready?** `gem 'bunny', '~> 2.14'`. Startback accepts `>= 2.14, < 4.0`.
 
 ---
 
+
 ## 10. webspicy must move to 1.x
 
 **You will see** `bundle install` fail outright:

data/lib/startback/event/bus/bunny/async.rb

@@ -5,14 +5,29 @@ module Startback
       module Bunny
         #
         # Asynchronous implementation of the bus abstraction, on top of RabbitMQ
-        # and using the 'bunny' gem (you need to include it in your Gemfile
-        # yourself: it is NOT a startback official dependency).
+        # and using the 'bunny' gem.
         #
         # This bus implementation emits events by dumping them to RabbitMQ using
         # the event type as exchange name. Listeners may use the `processor`
         # parameter to specify the queue name ; otherwise a default "main" queue
         # is used.
         #
+        # WARNING: unlike Bus::Memory::Async, which hands listeners an Event
+        # instance, this bus hands them the **raw JSON String** read off the
+        # queue. A listener moved from the memory bus to this one therefore
+        # receives something else, silently. Parse it yourself, e.g. with
+        # `Startback::Event.json(body, context)`.
+        #
+        # The exchange and queue are declared **durable** by default. RabbitMQ
+        # refuses transient non-exclusive queues from 4.3 on, so the previous
+        # defaults stop working there entirely.
+        #
+        # An exchange or queue that already exists with other properties -- one
+        # an older Startback declared transient -- is **adopted as it stands**
+        # rather than redeclared, so upgrading needs no broker-side migration.
+        # A warning is logged, and the durable declaration takes effect on its
+        # own at the next broker restart, transient objects not surviving one.
+        #
         # Examples:
         #
         #     # Connects to RabbitMQ using all default options
@@ -46,10 +61,21 @@ module Startback
             connection_options: nil,
 
             # (optional) The options to use for the emitter/listener fanout
-            fanout_options: {},
+            #
+            # Durable by default, so that the exchange and the bindings
+            # pointing at it survive a broker restart. A durable queue bound
+            # to a transient exchange would come back alone, with nothing
+            # routing to it.
+            fanout_options: { durable: true },
 
             # (optional) The options to use for the listener queue
-            queue_options: {},
+            #
+            # Durable by default, because RabbitMQ 4 refuses transient
+            # non-exclusive queues: declaring one fails the channel, and
+            # `listen` never receives anything. Durability is also what a
+            # named processor queue wants -- events waiting in it outlive a
+            # broker restart rather than being dropped on the floor.
+            queue_options: { durable: true },
 
             # (optional) Default event factory to use, if any
             event_factory: nil,
@@ -74,12 +100,17 @@ module Startback
           def initialize(options = {})
             options = { url: options } if options.is_a?(String)
             @options = DEFAULT_OPTIONS.merge(options)
+            @topology = {}
+            @topology_lock = Mutex.new
             connect if @options[:autoconnect]
           end
           attr_reader :options
 
           def connect
             disconnect
+            # What the broker holds is only known for a given connection: a
+            # restart in between wipes every transient exchange and queue.
+            @topology_lock.synchronize { @topology = {} }
             conn = options[:connection_options] || options[:url]
             try_max_times(10) do
               @bunny = ::Bunny.new(conn)
@@ -106,7 +137,16 @@ module Startback
               raise Startback::Errors::Error, "Please connect your bus first, or use autoconnect: true"
             end
 
-            Thread.current[CHANNEL_KEY] ||= @bunny.create_channel(
+            # A channel-level error closes the channel, and bunny does not
+            # reopen it. Since this one is cached per thread, a single such
+            # error used to leave the thread with a dead channel forever:
+            # every later emit failed with "cannot use a closed channel",
+            # whatever the event type, and `stop_errors` hid it. Dropping a
+            # closed channel here is what makes the bus recover on its own.
+            current = Thread.current[CHANNEL_KEY]
+            current = nil unless current.nil? || current.open?
+
+            Thread.current[CHANNEL_KEY] = current || @bunny.create_channel(
               nil,
               consumer_pool_size, # consumer_pool_size
               abort_on_exception? # consumer_pool_abort_on_exception
@@ -115,7 +155,7 @@ module Startback
 
           def emit(event)
             stop_errors(self, "emit", event.context) do
-              fanout = channel.fanout(event.type.to_s, fanout_options)
+              fanout = declare(:fanout, event.type.to_s, fanout_options)
               fanout.publish(event.to_json)
             end
           end
@@ -123,9 +163,11 @@ module Startback
           def listen(type, processor = nil, listener = nil, &bl)
             raise ArgumentError, "A listener must be provided" unless listener || bl
 
-            fanout = channel.fanout(type.to_s, fanout_options)
-            queue = channel.queue((processor || "main").to_s, queue_options)
-            queue.bind(fanout)
+            fanout = declare(:fanout, type.to_s, fanout_options)
+            queue = declare(:queue, (processor || "main").to_s, queue_options)
+            # Bound by name on purpose: declaring the queue may have renewed
+            # the channel, in which case `fanout` belongs to a closed one.
+            queue.bind(fanout.name)
             queue.subscribe do |delivery_info, properties, body|
               stop_errors(self, "listen") do
                 (listener || bl).call(body)
@@ -135,6 +177,86 @@ module Startback
 
         protected
 
+          # Declares an exchange (`kind` = :fanout) or a queue (:queue) with
+          # `options`, adopting one that already exists with other properties
+          # instead of failing on it.
+          #
+          # Startback used to declare both transient. AMQP refuses to
+          # redeclare an object with different properties, so an application
+          # upgrading to the durable defaults would get the broker closing its
+          # channel with PRECONDITION_FAILED -- and, `emit` being wrapped in
+          # `stop_errors`, would silently stop emitting rather than crash.
+          #
+          # Requiring a coordinated broker restart to avoid that is a poor
+          # deal for something the upgrade gains nothing from, so adopt what
+          # is there: `passive: true` matches an existing object whatever its
+          # properties. Transient objects disappear at the next broker
+          # restart anyway, and the durable declaration then wins on its own,
+          # with nobody having had to do anything.
+          def declare(kind, name, options)
+            channel.public_send(kind, name, topology_options(kind, name, options))
+          rescue ::Bunny::PreconditionFailed, ::Bunny::NotFound
+            # The topology moved under us -- a broker restart took a transient
+            # object away, or another application redeclared it. Forget what
+            # was known of it and look again.
+            forget_topology(kind, name)
+            renew_channel!
+            channel.public_send(kind, name, topology_options(kind, name, options))
+          end
+
+          # The options that actually work for `name`: the requested ones,
+          # unless an incompatible object is already there, in which case
+          # `passive: true`, which matches whatever its properties are.
+          #
+          # Memoized, because `emit` declares the exchange on every call and
+          # the answer only changes across connections.
+          def topology_options(kind, name, requested)
+            key = [kind, name]
+            @topology_lock.synchronize do
+              return @topology[key] if @topology.key?(key)
+            end
+            probed = probe_topology(kind, name, requested)
+            @topology_lock.synchronize { @topology[key] = probed }
+          end
+
+          def forget_topology(kind, name)
+            @topology_lock.synchronize { @topology.delete([kind, name]) }
+          end
+
+          # Tries the requested options on a **scratch channel**, never on the
+          # one the bus works with. A rejected declaration is a channel-level
+          # error, and the broker closes the channel it happened on: probing
+          # on the shared channel would take down every consumer registered
+          # there, so emitting would silently unsubscribe the listeners.
+          def probe_topology(kind, name, requested)
+            scratch = @bunny.create_channel
+            begin
+              scratch.public_send(kind, name, requested)
+              requested
+            rescue ::Bunny::PreconditionFailed
+              log(:warn, {
+                op: "#{self.class.name}#declare",
+                op_data: {
+                  kind: kind,
+                  name: name,
+                  msg: "Adopting an existing #{kind} whose properties differ " \
+                       "from the requested ones. It will be declared as " \
+                       "requested after the next broker restart."
+                }
+              }, self.options[:context])
+              { passive: true }
+            ensure
+              scratch.close if scratch.open?
+            end
+          end
+
+          # Forgets the current channel, which a channel-level error left
+          # closed, so that `channel` opens a fresh one.
+          def renew_channel!
+            Thread.current[CHANNEL_KEY] = nil
+            channel
+          end
+
           def consumer_pool_size
             options[:consumer_pool_size]
           end

data/lib/startback/version.rb

@@ -1,7 +1,7 @@
 module Startback
   module Version
     MAJOR = 2
-    MINOR = 0
+    MINOR = 1
     TINY  = 0
   end
   VERSION = "#{Version::MAJOR}.#{Version::MINOR}.#{Version::TINY}"

data/spec/spec_helper.rb

@@ -12,6 +12,7 @@ require 'startback/audit'
 require 'startback/security'
 require 'rack/test'
 require 'ostruct'
+require 'support/bunny_broker'
 
 module SpecHelpers
 end

data/spec/support/bunny_broker.rb

@@ -0,0 +1,145 @@
+require 'securerandom'
+
+#
+# Support for the specs that need a real RabbitMQ broker, i.e. those covering
+# Startback::Event::Bus::Bunny::Async. There is no way to cover that bus
+# meaningfully without one: mocking bunny would only assert that Startback
+# calls the methods Startback calls.
+#
+# The broker is located through STARTBACK_BUS_BUNNY_ASYNC_URL, which is also
+# the variable the bus itself reads, so pointing the suite at a broker and
+# pointing an application at one are the same gesture.
+#
+#     STARTBACK_BUS_BUNNY_ASYNC_URL=amqp://guest:guest@localhost:5672
+#
+# `make rabbitmq.up` starts one locally. When no broker answers, those specs
+# are skipped, so that a contributor without docker still gets a green suite.
+#
+# That skip is a trap on CI, where a broken service container would quietly
+# take the coverage away instead of failing. STARTBACK_SPEC_REQUIRE_BUNNY=1
+# turns "no broker" into a hard error, and CI sets it.
+#
+module BunnyBroker
+  extend self
+
+  DEFAULT_URL = "amqp://guest:guest@localhost:5672"
+
+  def url
+    ENV['STARTBACK_BUS_BUNNY_ASYNC_URL'] || DEFAULT_URL
+  end
+
+  def required?
+    !ENV['STARTBACK_SPEC_REQUIRE_BUNNY'].to_s.strip.empty?
+  end
+
+  # Whether a broker answers, memoized: the specs ask once per example and
+  # connecting is not free. `false` is a legitimate memoized answer, hence
+  # `defined?` rather than `||=`.
+  def available?
+    return @available if defined?(@available)
+
+    @available = begin
+      require 'bunny'
+      conn = ::Bunny.new(url, log_level: :fatal, network_recovery_interval: 0,
+                              connection_timeout: 2, continuation_timeout: 4000)
+      conn.start
+      conn.close
+      true
+    rescue StandardError, LoadError => ex
+      @unavailable_reason = "#{ex.class}: #{ex.message}"
+      false
+    end
+  end
+
+  def unavailable_reason
+    @unavailable_reason
+  end
+
+  # Called from a `before` hook, with the example context as argument --
+  # `skip` is a method of the example group instance, not of the Example
+  # object, whose own `skip` is a metadata reader taking no argument.
+  def skip_unless_available!(context)
+    return if available?
+
+    msg = "No RabbitMQ broker at #{url} (#{unavailable_reason})"
+    raise "#{msg}. STARTBACK_SPEC_REQUIRE_BUNNY is set, so this is an error." if required?
+
+    context.skip("#{msg}. Start one with `make rabbitmq.up`.")
+  end
+
+  # Exchanges and queues outlive an example now that both are durable, and
+  # redeclaring one with different options raises PreconditionFailed. Each
+  # example therefore works on names nobody else uses.
+  def unique(prefix)
+    "#{prefix}-#{SecureRandom.hex(6)}"
+  end
+
+  # Removes the topology an example created. Durable means the broker would
+  # otherwise keep it forever.
+  def delete_topology(exchanges: [], queues: [])
+    conn = ::Bunny.new(url, log_level: :fatal)
+    conn.start
+    ch = conn.create_channel
+    queues.each    { |q| ch.queue_delete(q) rescue nil }
+    exchanges.each { |x| ch.exchange_delete(x) rescue nil }
+    conn.close
+  rescue StandardError
+    # Best effort: a cleanup failure must not turn a passing example red.
+  end
+
+  # Whether the broker still lets a *transient non-exclusive queue* be
+  # declared. RabbitMQ denies that from 4.3 on, which is the very reason the
+  # durable defaults exist -- but it also means the queue half of the
+  # adoption path cannot be set up on such a broker. Exchanges are not
+  # restricted, so that half is always exercised.
+  def transient_queues_permitted?
+    return @transient_queues if defined?(@transient_queues)
+
+    @transient_queues = begin
+      conn = ::Bunny.new(url, log_level: :fatal, continuation_timeout: 4000)
+      conn.start
+      name = unique("probe-transient")
+      begin
+        ch = conn.create_channel
+        ch.queue(name, {})
+        ch.queue_delete(name)
+        true
+      rescue StandardError
+        false
+      ensure
+        conn.close rescue nil
+      end
+    rescue StandardError
+      false
+    end
+  end
+
+  # Same trap as skip_unless_available!, one level down: on the CI job whose
+  # whole point is to run the adoption examples, a broker image bumped past
+  # 4.2 would make them skip and take the coverage away silently.
+  def skip_unless_transient_queues!(context)
+    return if transient_queues_permitted?
+
+    msg = "Broker at #{url} denies transient non-exclusive queues " \
+          "(RabbitMQ >= 4.3), so the legacy topology cannot be created here"
+    if !ENV['STARTBACK_SPEC_REQUIRE_TRANSIENT_QUEUES'].to_s.strip.empty?
+      raise "#{msg}. STARTBACK_SPEC_REQUIRE_TRANSIENT_QUEUES is set, so this " \
+            "is an error: this job exists to run these examples."
+    end
+
+    context.skip("#{msg}. The bus-legacy CI job covers it against RabbitMQ 4.1.")
+  end
+
+  # Blocks until `bl` returns something truthy, or the timeout expires.
+  # Returns the value, or nil. Polling rather than sleeping a fixed delay
+  # keeps the suite fast when the broker is responsive, which it usually is.
+  def wait_for(timeout = 10, &bl)
+    deadline = Time.now + timeout
+    while Time.now < deadline
+      value = bl.call
+      return value if value
+      sleep 0.05
+    end
+    nil
+  end
+end

data/spec/unit/event/bus/bunny/test_async.rb

@@ -0,0 +1,296 @@
+require 'spec_helper'
+require 'startback/event/bus/bunny'
+
+module Startback
+  class Event
+    describe Bus::Bunny::Async do
+
+      # Exchange and queue names are per-example, see BunnyBroker#unique:
+      # both are durable, so they outlive the example that created them.
+      let(:type)      { BunnyBroker.unique("Spec::Event") }
+      let(:processor) { BunnyBroker.unique("spec-processor") }
+      let(:url)       { BunnyBroker.url }
+
+      let(:bus) { Bus::Bunny::Async.new(url) }
+
+      # Busses an example connected, closed afterwards whatever happens, so
+      # that a failing example does not leak a connection into the next one.
+      let(:opened) { [] }
+
+      def connected_bus(options = {})
+        Bus::Bunny::Async.new({ url: url }.merge(options)).tap do |b|
+          opened << b
+          b.connect unless options[:autoconnect]
+        end
+      end
+
+      before do
+        BunnyBroker.skip_unless_available!(self)
+      end
+
+      after do
+        opened.each { |b| b.disconnect rescue nil }
+        BunnyBroker.delete_topology(exchanges: [type], queues: [processor, "main"])
+      end
+
+      describe "connecting" do
+
+        it 'is not connected before connect is called' do
+          expect(bus.connected?).to be_falsey
+        end
+
+        it 'connects and disconnects' do
+          b = connected_bus
+          expect(b.connected?).to eql(true)
+          b.disconnect
+          expect(b.connected?).to be_falsey
+        end
+
+        it 'connects at construction when autoconnect is set' do
+          b = connected_bus(autoconnect: true)
+          expect(b.connected?).to eql(true)
+        end
+
+        it 'takes a String as being the url' do
+          b = Bus::Bunny::Async.new(url)
+          opened << b
+          expect(b.options[:url]).to eql(url)
+          b.connect
+          expect(b.connected?).to eql(true)
+        end
+
+        it 'defaults the url to STARTBACK_BUS_BUNNY_ASYNC_URL' do
+          # DEFAULT_OPTIONS captures the variable at load time, so the class
+          # constant is the observable, not a re-read of ENV here.
+          expect(Bus::Bunny::Async::DEFAULT_OPTIONS[:url])
+            .to eql(ENV['STARTBACK_BUS_BUNNY_ASYNC_URL'])
+        end
+
+        it 'refuses to hand out a channel before connecting' do
+          expect {
+            bus.channel
+          }.to raise_error(Startback::Errors::Error, /connect your bus first/)
+        end
+
+      end
+
+      describe "emitting and listening" do
+
+        it 'round trips an event through the broker with default options' do
+          # Regression test for the defaults themselves: RabbitMQ 4 refuses
+          # transient non-exclusive queues, which is what queue_options used
+          # to ask for. This example fails with a Timeout::Error there.
+          b = connected_bus
+          seen = Queue.new
+          b.listen(type, processor) { |body| seen << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+          parsed = JSON.parse(received)
+          expect(parsed["type"]).to eql(type)
+          expect(parsed["data"]).to eql({ "id" => 12 })
+        end
+
+        it 'hands the listener the raw JSON String, not an Event' do
+          # Documents an asymmetry with Bus::Memory::Async, which hands over
+          # an Event instance. Listeners are not portable between the two.
+          b = connected_bus
+          seen = Queue.new
+          b.listen(type, processor) { |body| seen << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).to be_a(String)
+        end
+
+        it 'declares the exchange and the queue durable' do
+          b = connected_bus
+          b.listen(type, processor) { |body| }
+
+          # Redeclaring passively tells us what the broker actually holds:
+          # a mismatch on durable would raise Bunny::PreconditionFailed.
+          expect {
+            ch = b.channel
+            ch.fanout(type, durable: true, passive: true)
+            ch.queue(processor, durable: true, passive: true)
+          }.not_to raise_error
+        end
+
+        it 'allows mixing Symbol vs. String for event type' do
+          b = connected_bus
+          seen = Queue.new
+          b.listen(type.to_sym, processor) { |body| seen << body }
+          b.emit(Event.new(type.to_sym, { id: 12 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+          expect(JSON.parse(received)["type"]).to eql(type)
+        end
+
+        it 'fans an event out to every processor queue' do
+          other = BunnyBroker.unique("spec-other")
+          b = connected_bus
+          one, two = Queue.new, Queue.new
+          b.listen(type, processor) { |body| one << body }
+          b.listen(type, other)     { |body| two << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          expect(BunnyBroker.wait_for { one.pop unless one.empty? }).not_to be_nil
+          expect(BunnyBroker.wait_for { two.pop unless two.empty? }).not_to be_nil
+
+          BunnyBroker.delete_topology(queues: [other])
+        end
+
+        it 'does not deliver an event to a queue bound to another type' do
+          other_type = BunnyBroker.unique("Spec::Other")
+          b = connected_bus
+          seen = Queue.new
+          b.listen(other_type, processor) { |body| seen << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          # Nothing should arrive. Give the broker a real chance to prove us
+          # wrong before concluding, hence a short but non-zero wait.
+          expect(BunnyBroker.wait_for(1) { seen.pop unless seen.empty? }).to be_nil
+
+          BunnyBroker.delete_topology(exchanges: [other_type])
+        end
+
+        it 'requires a listener' do
+          b = connected_bus
+          expect {
+            b.listen(type, processor)
+          }.to raise_error(ArgumentError, /listener must be provided/)
+        end
+
+      end
+
+      describe "adopting a pre-existing topology" do
+
+        # What an older Startback left on the broker: a transient exchange.
+        # This is the upgrade path, and it must not need a broker-side
+        # migration. Only the exchange, because a transient queue cannot be
+        # declared at all from RabbitMQ 4.3 on -- see the last example here.
+        def declare_legacy_exchange!
+          conn = ::Bunny.new(url, log_level: :fatal)
+          conn.start
+          conn.create_channel.fanout(type, {})
+          conn.close
+        end
+
+        it 'emits through a transient exchange instead of dropping the event' do
+          declare_legacy_exchange!
+          b = connected_bus
+
+          seen = Queue.new
+          b.listen(type, processor) { |body| seen << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+          expect(JSON.parse(received)["data"]).to eql({ "id" => 12 })
+        end
+
+        it 'leaves the adopted exchange alone rather than redeclaring it' do
+          declare_legacy_exchange!
+          b = connected_bus
+          b.listen(type, processor) { |body| }
+
+          # Still transient: adopting means taking what is there. Declaring
+          # it transient again would raise had the bus turned it durable.
+          conn = ::Bunny.new(url, log_level: :fatal)
+          conn.start
+          expect {
+            conn.create_channel.fanout(type, durable: false)
+          }.not_to raise_error
+          conn.close
+        end
+
+        it 'keeps the channel usable after the conflict' do
+          # The conflict closes the channel. Before the bus learned to renew
+          # it, the closed one stayed cached per thread and every later emit
+          # failed with "cannot use a closed channel" -- silently, since
+          # `emit` runs inside stop_errors -- whatever the event type.
+          declare_legacy_exchange!
+          b = connected_bus
+          b.emit(Event.new(type, { id: 1 }))
+
+          expect(b.channel.open?).to eql(true)
+
+          other_type = BunnyBroker.unique("Spec::Unrelated")
+          other_proc = BunnyBroker.unique("spec-unrelated")
+          seen = Queue.new
+          b.listen(other_type, other_proc) { |body| seen << body }
+          b.emit(Event.new(other_type, { id: 2 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+
+          BunnyBroker.delete_topology(exchanges: [other_type], queues: [other_proc])
+        end
+
+        it 'keeps delivering when exchange AND queue were both transient' do
+          # The true state an older Startback leaves behind, and the one that
+          # matters: adopting two objects means two channel renewals, so the
+          # consumer ends up on a different channel than the one the exchange
+          # was adopted on. Probing on the shared channel would then have
+          # `emit` close the consumer's channel -- events silently lost.
+          #
+          # Only reproducible where transient queues can still be declared,
+          # i.e. RabbitMQ <= 4.2, which is why CI runs a broker of that
+          # generation alongside the current one.
+          BunnyBroker.skip_unless_transient_queues!(self)
+
+          conn = ::Bunny.new(url, log_level: :fatal)
+          conn.start
+          ch = conn.create_channel
+          ch.queue(processor, {}).bind(ch.fanout(type, {}))
+          conn.close
+
+          b = connected_bus
+          seen = Queue.new
+          b.listen(type, processor) { |body| seen << body }
+          b.emit(Event.new(type, { id: 12 }))
+
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+          expect(JSON.parse(received)["data"]).to eql({ "id" => 12 })
+        end
+
+      end
+
+      describe "the asynchronous contract" do
+
+        it 'hides emit errors from the emitter' do
+          # An async bus MUST NOT let errors reach the emitter. Emitting
+          # without connecting raises inside, and must stay inside.
+          expect {
+            bus.emit(Event.new(type, { id: 12 }))
+          }.not_to raise_error
+        end
+
+        it 'keeps consuming after a listener raised' do
+          b = connected_bus
+          seen = Queue.new
+          calls = Queue.new
+          b.listen(type, processor) do |body|
+            calls << body
+            raise "listener blew up" if JSON.parse(body)["data"]["id"] == 1
+
+            seen << body
+          end
+
+          b.emit(Event.new(type, { id: 1 }))
+          expect(BunnyBroker.wait_for { calls.pop unless calls.empty? }).not_to be_nil
+
+          b.emit(Event.new(type, { id: 2 }))
+          received = BunnyBroker.wait_for { seen.pop unless seen.empty? }
+          expect(received).not_to be_nil
+          expect(JSON.parse(received)["data"]).to eql({ "id" => 2 })
+        end
+
+      end
+
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: startback
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Bernard Lambeau
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -533,6 +533,7 @@ files:
 - lib/startback/web/prometheus.rb
 - lib/startback/web/shield.rb
 - spec/spec_helper.rb
+- spec/support/bunny_broker.rb
 - spec/unit/audit/ext/test_context.rb
 - spec/unit/audit/test_middleware.rb
 - spec/unit/audit/test_prometheus.rb
@@ -546,6 +547,7 @@ files:
 - spec/unit/context/test_middleware.rb
 - spec/unit/context/test_with_world.rb
 - spec/unit/context/test_world.rb
+- spec/unit/event/bus/bunny/test_async.rb
 - spec/unit/event/bus/memory/test_async.rb
 - spec/unit/event/bus/memory/test_sync.rb
 - spec/unit/security/test_rate_limiter.rb