startback 1.2.4 → 2.1.0

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/security/rate_limiter.rb

@@ -104,7 +104,7 @@ module Startback
           op_class: op.class.name.to_s,
           value: value,
         }
-        JSON.fast_generate(key)
+        JSON.generate(key)
       end
 
       def defaults

data/lib/startback/version.rb

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

data/lib/startback/web/auto_caching.rb

@@ -1,3 +1,5 @@
+require 'rack'
+
 module Startback
   module Web
     #
@@ -53,8 +55,12 @@ module Startback
 
     protected
 
+      # Rack::Headers is used so that the defaults set here are actually
+      # overriden by the downstream application, whatever the case it uses
+      # for its own header names.
       def patch_response_headers(hs)
-        (development? ? @cache_headers[:development] : @cache_headers[:production]).merge(hs)
+        defaults = development? ? @cache_headers[:development] : @cache_headers[:production]
+        Rack::Headers[defaults].merge(hs)
       end
 
       def development?
@@ -68,16 +74,16 @@ module Startback
       def default_headers
         {
           development: {
-            "Cache-Control" => DEVELOPMENT_CACHE_CONTROL
+            "cache-control" => DEVELOPMENT_CACHE_CONTROL
           },
           production: {
-            "Cache-Control" => PRODUCTION_CACHE_CONTROL
+            "cache-control" => PRODUCTION_CACHE_CONTROL
           }
         }
       end
 
       def normalize_headers(h)
-        Hash[h.map{|k,v| [k, v.is_a?(Hash) ? v : {"Cache-Control" => v} ] }]
+        Hash[h.map{|k,v| [k, v.is_a?(Hash) ? v : {"cache-control" => v} ] }]
       end
 
     end # class AutoCaching

data/lib/startback/web/cors_headers.rb

@@ -1,3 +1,5 @@
+require 'rack'
+
 module Startback
   module Web
     #
@@ -62,7 +64,8 @@ module Startback
           headers = cors_headers(origin).merge(headers)
         end
         if env['REQUEST_METHOD'] == 'OPTIONS'
-          headers['Content-Length'] = '0'
+          headers = Rack::Headers[headers]
+          headers['content-length'] = '0'
           status, headers, body = [204, headers, []]
         end
         [status, headers, body]
@@ -70,8 +73,11 @@ module Startback
 
     private
 
+      # Rack::Headers is used so that the CORS headers set here are actually
+      # overriden by the downstream application, whatever the case it uses
+      # for its own header names.
       def cors_headers(origin)
-        headers = @options[:headers].dup
+        headers = Rack::Headers[@options[:headers]]
         if bounce = do_bounce(origin)
           headers['Access-Control-Allow-Origin'] = bounce
         else

data/lib/startback/web/health_check.rb

@@ -32,7 +32,7 @@ module Startback
 
       def call(env)
         if debug_msg = check!(env)
-          [ 200, { "Content-Type" => "text/plain" }, Array(debug_msg) ]
+          [ 200, { "content-type" => "text/plain" }, Array(debug_msg) ]
         else
           [ 204, {}, [] ]
         end

data/spec/spec_helper.rb

@@ -1,3 +1,9 @@
+# Sinatra 4 restricts the Host header to localhost-like values in the
+# `development` environment, which is the one used when RACK_ENV is unset.
+# Rack::Test issues requests against `example.org`, hence the need to be
+# explicit about running in test mode here.
+ENV["RACK_ENV"] ||= "test"
+
 require 'startback'
 require 'startback/caching'
 require 'startback/event'
@@ -6,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