happn 1.1.7 → 1.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a473282e160c8ae5a0f8eea7615bae2700e63e2b458ae59c0e221a36824a26
-  data.tar.gz: 19140eaf6bac43db02fb65fbfdd1b6ffaa8eb95bb29307d0a2be561649ff11e5
+  metadata.gz: 97331b5fd43edeae737ee8937f4b838d9788285404dbef888e77a28109e3d384
+  data.tar.gz: 173f02ea108c6911b6077399765e3326a3b792fd5368d5e4ca89028f37406f9b
 SHA512:
-  metadata.gz: 8bb235e0cf250362916c7f399829248eaef752e2e4772178c7690896901aa763eb9dc9f2741bf12ff18caad3f925bbb151edd8109ea056b64cafa7f69494327d
-  data.tar.gz: 1b30f2f49e6450d670c903f16096d42bc188ac279154a8d4d256795e446274ca0dc3424118e6a8b494611ab3773992c69afd6d59629bb9cc5620a5be087670fa
+  metadata.gz: 6b5c37de3a0d01ff984bd92cebf76c09b7905f7ddb556eb5757defca1bfb0957d488aa8e6909f922db84418ac623dd81b6c63cac5f5742f8d96efa3928e7ac5d
+  data.tar.gz: 95c55b9d1cadec849aaf6ad4107fbc05d4ba8411dc5aaaa62bb63c108bd7d2a1affe89545f82928913c155fcb43e9a78cfca58ea1a97bd8121ee1d2d3cb82fe6

data/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+### [1.1.8] - 2026-08-03
+
+* `Happn` no longer runs a handler several times for a single event. `"all"` is both the wildcard a query is stored under and a value an event may legitimately carry, and the dispatch used to list it twice: an event whose `emitter`, `kind` and `status` were all `"all"` ran each of its matching handlers 8 times, and 16 times when its `name` carried it too.
+* `Happn` now reads the existing bindings of its queue on the vhost its broker connection uses, instead of always on the default one. On any other vhost it used to read someone else's bindings, and to unbind legitimate ones from its own queue as a result. Both `vhost` and `virtual_host` are honoured in `bunny_options`, with the precedence Bunny gives them.
+* `Happn` now only unbinds the routing keys bound to its own exchange. It used to consider every binding of the queue, whatever its source, so the implicit binding each queue carries to the default exchange triggered a useless `unbind` on every start up.
+* `Happn.stop` stops the consumption started by `Happn.start` and releases the thread it blocks. It cancels the consumer, lets the messages already handed over run to completion, then closes the broker connection.
+* `Happn` builds an event from its payload about 5 times faster. The conversion of a payload key into an underscored symbol is now memoized instead of being recomputed on every key of every message.
+* `Happn` allocates far fewer arrays while looking up the handlers of an event: the list under construction is filled in place instead of being reallocated on each of the 16 combinations looked up, which also lightens the garbage collector on a busy queue.
+* `Happn.register` is now really private. It was meant to be, and read as such, but the `private` guarding it had no effect on a method defined on the module itself, leaving it callable from the outside.
+* Publishing a version now requires the whole test suite to pass.
+
 ### [1.1.7] - 2026-08-01
 
 * **Breaking**: `required_ruby_version` is raised from `>= 3.0` to `>= 3.2`.

data/README.md

@@ -43,7 +43,8 @@ Each configuration is detailed below.
 * `Happn` consumes a single queue through the RabbitMQ's [Topic Exchange Model](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchange-topic).
 * If the queue does not exist when `Happn` starts, it is created automatically.
 * When connecting a queue, please be careful that each connection parameter must match the existing queue's parameters. For instance, the value of `x-queue-mode` must match to avoid a `PRECONDITION FAILED` error.
-* All bindings between queues and their exchange are reset when starting `Happn`. Based on all the projectors that have been registered (option `projector_classes`), `Happn` detects which events must be consumed and binds its queue to the exchange depending on these event matchers.
+* The bindings between the queue and the exchange `Happn` consumes are reset when starting `Happn`. Based on all the projectors that have been registered (option `projector_classes`), `Happn` detects which events must be consumed, binds its queue to the exchange depending on these event matchers, and unbinds the routing keys that no longer match any projector. Bindings the same queue may have to _other_ exchanges are left untouched.
+* `Happn` reads those existing bindings through the RabbitMQ management API, on the vhost its broker connection uses. To consume a vhost other than the default one, declare it in `bunny_options` (`vhost` or `virtual_host`, as Bunny accepts both): `Happn` follows it on both the AMQP connection and the management API.
 
 ## About projectors
 
@@ -72,6 +73,28 @@ Starting `Happn` consumes events sequentially. For instance, it can be started f
   end
   ```
 
+### Shutting Down
+
+`Happn.start` blocks the calling thread for as long as the consumption lasts. `Happn.stop` releases it: it cancels the consumer, lets the messages already being handled run to completion, and closes the broker connection. It is meant to be called from another thread than the one blocked in `Happn.start`.
+
+`Happn` installs no signal handler of its own, because only the application knows what a graceful shutdown means for it. Wiring one is up to you:
+
+  ```ruby
+  namespace :events do
+    desc "Listen all events and consume them."
+    task consume: :environment do
+      Happn.init
+      Signal.trap("TERM") { Thread.new { Happn.stop } }
+      Signal.trap("INT")  { Thread.new { Happn.stop } }
+      Happn.start
+    end
+  end
+  ```
+
+Signal handlers run in a context where very little is allowed, hence the `Thread.new`.
+
+Without it, an orchestrator stopping the process interrupts the handler in flight. Nothing is lost, the message was never acknowledged, so the broker redelivers it, but it is consumed twice, once partially.
+
 ### Define a Projector
 
 A projector is a class that defines how to consume one or multiple types of events. This class must:
@@ -87,7 +110,7 @@ class LoggerProjector < Happn::Projector
     end
 
     on kind: "request", status: :new do |event|
-      Rails.logger("This is a new request to the controller: #{event.data["controller_name"]}")
+      Rails.logger("This is a new request to the controller: #{event.data[:controller_name]}")
     end
   end
 end
@@ -145,7 +168,7 @@ All options have a default value. However, all of them can be changed in your `H
 | `rabbitmq_queue_mode` | `nil` | String | Optional | When creating the queue, this option can be passed to set `x-queue-mode`. For instance, a queue can be made _"lazy"_ by passing `"lazy"` as a value. See [RabbitMQ's documentation](https://www.rabbitmq.com/lazy-queues.html) for more details.  | `lazy` |
 | `rabbitmq_prefetch_size` | `10` | Integer | Optional | Also known as RabbitMQ's QOS. From the [RabbitMQ's documentation](http://www.rabbitmq.com/consumer-prefetch.html): _"AMQP specifies the basic.qos method to allow you to limit the number of unacknowledged messages on a channel (or connection) when consuming (aka "prefetch count")."_ | `1000` |
 | `projector_classes` | `[]` | Array of constants | Required | All Projector classes to register. This value can be generated by reading all descendant classes from `Happn::Projector`. | `[MyProjector]` |
-| `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 }` |
+| `bunny_options` | `{}` | Hash of symbols | Optional | Additional options to add when connecting the RabbitMQ broker. This overrides the existing options with the same name. A `vhost` (or `virtual_host`) declared here is also the vhost `Happn` queries through the management API. | `{ verify_peer: true }` |
 | `management_options` | `{}` | Hash of symbols | Optional | Additional options to add when accessing the RabbitMQ Managmement. This overrides the existing options with the same name. The options are defined at https://github.com/ruby-amqp/rabbitmq_http_api_client | `{ verify: false }` |
 | `on_error` | `nil` | `block` with an argument `exception` | false | When the consumption of an event raises an Error, the consumption exits. However, this block can be called before exiting the consumption execution. | `lambda { |exception| Raven.capture_exception(exception) }` (see Sentry's [documentation](https://github.com/getsentry/raven-ruby) | 
 
@@ -161,8 +184,8 @@ scoped RubyGems credential.
 3. Tag the commit and push the tag:
 
 ```
-  $ git tag -a v1.1.7 -m "Version 1.1.7"
-  $ git push origin v1.1.7
+  $ git tag -a v1.1.8 -m "Version 1.1.8"
+  $ git push origin v1.1.8
 ```
 
 The workflow then checks that the tag matches `Happn::VERSION`, runs the tests, builds the gem

data/lib/happn/event.rb

@@ -1,42 +1,131 @@
 require "date"
 
 module Happn
+  # A single CREPE event, as it was consumed from the exchange.
+  #
+  # An event is built from the parsed payload of a message. That payload carries
+  # two entries: `meta`, describing the event itself, and `data`, describing what
+  # happened. A projector handler receives an instance of this class.
+  #
+  # ## Key conversion
+  #
+  # Every key of the payload, at every depth, is converted into an underscored
+  # Symbol when the event is built. A payload emitted in camel case is therefore
+  # read in snake case, and always through symbols:
+  #
+  #     # {"meta" => {…}, "data" => {"requestMetadata" => {"controllerName" => "countries"}}}
+  #     event.data[:request_metadata][:controller_name]  # => "countries"
+  #     event.data["request_metadata"]                   # => nil
+  #
+  # Dashes become underscores, `::` becomes `/`, and the capitals of an acronym
+  # are kept together: `"HTTPResponseCode"` is read as `:http_response_code`.
+  #
+  # ## Changes
+  #
+  # An entity change carries a `changes` entry, mapping an attribute to the pair
+  # of values it went through:
+  #
+  #     event.changes  # => { name: ["France", "Belgium"] }
+  #
+  # Events of another shape carry no such entry at all, a `request` for instance.
+  # {#changes} then returns `nil`, and the five methods reading through it raise
+  # a NoMethodError: guard them with {#changes} when a handler may be reached by
+  # events of several shapes.
+  #
+  # @example Reading an event in a projector
+  #   on kind: "entity_change", name: "update country" do |event|
+  #     Rails.logger.info("#{event.emitter} renamed a country at #{event.timestamp}")
+  #     Rails.logger.info("from #{event.change_before(:name)} to #{event.change_after(:name)}")
+  #   end
   class Event
 
+    # The whole `data` entry of the payload, keys converted.
+    #
+    # This is the hash the event holds, not a copy: {#changes=} and {#add_change}
+    # write into it, and so does anything the caller does to it.
+    #
+    # @return [Hash] the payload data, or whatever `data` held if it was no hash
+    attr_reader :data
+
+    # Builds an event from a parsed payload.
+    #
+    # @param args [Hash] the parsed payload, with its `"meta"` and `"data"`
+    #   entries, both keyed by String
+    # @raise [KeyError] if the payload carries no `"meta"` or no `"data"` entry
     def initialize(args)
       @meta = deep_underscore_keys(args.fetch("meta"))
       @data = deep_underscore_keys(args.fetch("data"))
     end
 
-    def data
-      @data
-    end
-
+    # The metadata the emitter attached to the user behind the event.
+    #
+    # @return [Hash, nil] nil when the payload carries no `user_metadata`
     def user_metadata
       @data[:user_metadata]
     end
 
+    # The metadata the emitter attached to the request behind the event.
+    #
+    # @return [Hash, nil] nil when the payload carries no `request_metadata`
     def request_metadata
       @data[:request_metadata]
     end
 
+    # The attributes the event changed, each mapped to its before and after
+    # values.
+    #
+    # @return [Hash{Symbol => Array}, nil] nil when the payload carries no
+    #   `changes` entry, which is the case of every event that is not an entity
+    #   change
     def changes
       @data[:changes]
     end
 
+    # Replaces the whole set of changes.
+    #
+    # Keys are taken as they are given: unlike the ones read from the payload,
+    # they go through no conversion.
+    #
+    # @param new_changes [Hash{Symbol => Array}] the changes to substitute
+    # @return [Hash{Symbol => Array}] the changes that were set
     def changes=(new_changes)
       @data[:changes] = new_changes
     end
 
+    # Records a change on an attribute.
+    #
+    # The "before" value is always `nil`: the method describes a value that was
+    # set, not a transition. An empty String is normalized into `nil`, so that a
+    # blank emitted value and an absent one are recorded alike.
+    #
+    # @example
+    #   event.add_change(:name, "Belgium")  # => [nil, "Belgium"]
+    #   event.add_change(:name, "")         # => [nil, nil]
+    #
+    # @param name [Symbol, String] the attribute the change bears on
+    # @param value [Object] the value the attribute was set to
+    # @return [Array] the pair of values recorded
+    # @raise [NoMethodError] if the payload carries no `changes` entry
     def add_change(name, value)
       new_value            = value == "" ? nil : value
       changes[name.to_sym] = [nil, new_value]
     end
 
+    # The entities the event relates to.
+    #
+    # @return [Hash, nil] nil when the payload carries no `associations`
     def associations
       @data[:associations]
     end
 
+    # When the event was emitted.
+    #
+    # The raw value is parsed on every call, and its offset is kept as it was
+    # emitted rather than being normalized.
+    #
+    # @return [DateTime, nil] nil when the payload carries no timestamp, or an
+    #   empty one
+    # @raise [Date::Error] if the timestamp cannot be parsed
     def timestamp
       raw_timestamp = @meta[:timestamp]
       if raw_timestamp.nil? || raw_timestamp.to_s.strip.empty?
@@ -46,48 +135,101 @@ module Happn
       end
     end
 
+    # The identifier the emitter gave the event.
+    #
+    # @return [String, nil] nil when the payload carries no id
     def id
       @meta[:id]
     end
 
+    # What the event says happened, matched by the `name` of a query.
+    #
+    # @return [String, nil] nil when the payload carries no name
     def name
       @meta[:name]
     end
 
+    # The state of the event, matched by the `status` of a query.
+    #
+    # @return [String, nil] nil when the payload carries no status
     def status
       @meta[:status]
     end
 
+    # The category of the event, matched by the `kind` of a query.
+    #
+    # @return [String, nil] nil when the payload carries no kind
     def kind
       @meta[:kind]
     end
 
+    # The application the event comes from, matched by the `emitter` of a query.
+    #
+    # @return [String, nil] nil when the payload carries no emitter
     def emitter
       @meta[:emitter]
     end
 
+    # The value an attribute was changed to.
+    #
+    # @param attribute_name [Symbol, String] the attribute to read
+    # @return [Object, nil] nil when the attribute did not change
+    # @raise [NoMethodError] if the payload carries no `changes` entry
     def change_after(attribute_name)
       changes[attribute_name.to_sym]&.last
     end
 
+    # The value an attribute was changed from.
+    #
+    # @param attribute_name [Symbol, String] the attribute to read
+    # @return [Object, nil] nil when the attribute did not change
+    # @raise [NoMethodError] if the payload carries no `changes` entry
     def change_before(attribute_name)
       changes[attribute_name.to_sym]&.first
     end
 
+    # Whether an attribute changed.
+    #
+    # @param attribute_name [Symbol, String] the attribute to look for
+    # @return [Boolean]
+    # @raise [NoMethodError] if the payload carries no `changes` entry
     def has_change?(attribute_name)
       !changes[attribute_name.to_sym].nil?
     end
 
+    # Drops the change recorded on an attribute.
+    #
+    # @param attribute_name [Symbol, String] the attribute to drop
+    # @return [Array, nil] the pair of values that was dropped, nil when the
+    #   attribute did not change
+    # @raise [NoMethodError] if the payload carries no `changes` entry
     def delete_change(attribute_name)
       changes.delete(attribute_name.to_sym)
     end
 
+    # Underscoring a key is five regular expression passes and three String
+    # allocations, and an event stream keeps sending the very same keys. The cache
+    # is therefore bound by the vocabulary of the payloads, which is closed: an
+    # emitter putting a variable part inside a key name would make it grow forever.
+    UNDERSCORED_KEYS = {}
+    private_constant :UNDERSCORED_KEYS
+
     private
 
+    # Converts a payload key into the symbol the event is read through, memoized
+    # for every event at once.
+    #
+    # @param key [String] a key as the emitter wrote it
+    # @return [Symbol] its underscored form
     def underscore_key(key)
-      underscore(key).to_sym
+      UNDERSCORED_KEYS[key] ||= underscore(key).to_sym
     end
 
+    # Converts the keys of a payload fragment, walking through hashes and arrays
+    # down to the values, which are left as they are.
+    #
+    # @param value [Object] a fragment of the payload
+    # @return [Object] the same fragment, keyed by underscored symbols
     def deep_underscore_keys(value)
       case value
         when Array
@@ -99,6 +241,10 @@ module Happn
        end
     end
 
+    # Underscores a word, splitting it on its capitals and turning `::` into `/`.
+    #
+    # @param camel_cased_word [String] the word to convert
+    # @return [String] its underscored, downcased form
     def underscore(camel_cased_word)
       camel_cased_word.gsub(/::/, '/').
         gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').

data/lib/happn/event_consumer.rb

@@ -17,6 +17,7 @@ module Happn
         automatically_recover: true
       }.merge(@configuration.bunny_options || {})
       @connection              = Bunny.new(options)
+      @vhost                   = options[:virtual_host] || options[:vhost] || "/"
 
       management_options = {
         username: @configuration.rabbitmq_user,
@@ -43,6 +44,13 @@ module Happn
       consume
     end
 
+    def stop
+      @logger.info("Stopping events consumption...")
+      @consumer&.cancel
+      @consumer = nil
+      @connection.close if @connection.open?
+    end
+
     private
 
     def connect
@@ -60,9 +68,8 @@ module Happn
       arguments                        = {}
       arguments["x-queue-mode"]        = @configuration.rabbitmq_queue_mode unless @configuration.rabbitmq_queue_mode.nil?
       @queue                           = @channel.queue(@queue_name, durable: true, arguments: arguments)
-      exchange                         = @channel.send(:topic,
-                                                       @configuration.rabbitmq_exchange_name,
-                                                       durable: @configuration.rabbitmq_exchange_durable)
+      exchange                         = @channel.topic(@configuration.rabbitmq_exchange_name,
+                                                        durable: @configuration.rabbitmq_exchange_durable)
 
       routing_keys = @subscription_repository.find_all.map do | subscription |
         subscription.query.to_routing_key
@@ -77,18 +84,19 @@ module Happn
       @logger.info("Ready!")
     end
 
+    # 'Queue#subscribe' blocks before it can return the consumer it built, so the
+    # consumer is built here instead: 'stop' needs a handle on it to cancel it.
+    # Bunny's fourth argument is 'no_ack', hence false for a manual acknowledgement.
     def consume
-      options  = {
-        manual_ack: true,
-        block: true
-      }
-      @queue.subscribe(options) do | delivery_info, _properties, event |
+      @consumer = Bunny::Consumer.new(@channel, @queue, @channel.generate_consumer_tag, false)
+      @consumer.on_delivery do | delivery_info, _properties, event |
         begin
           handle_message(event, delivery_info)
         rescue => exception
           handle_exception(exception, delivery_info)
         end
       end
+      @queue.subscribe_with(@consumer, block: true)
     end
 
     def handle_message(message, delivery_info)
@@ -111,8 +119,6 @@ module Happn
       raise exception
     end
 
-    private
-
     def unbind_useless_routing_keys(queue, exchange, useful_routing_keys)
       all_routing_keys = find_all_routing_keys_of(queue)
       keys_to_remove   = all_routing_keys - useful_routing_keys
@@ -122,8 +128,9 @@ module Happn
     end
 
     def find_all_routing_keys_of(queue)
-      @management_client.list_queue_bindings("/", queue.name).map do | binding |
-        binding.routing_key
+      exchange_name = @configuration.rabbitmq_exchange_name
+      @management_client.list_queue_bindings(@vhost, queue.name).filter_map do | binding |
+        binding.routing_key if binding.source == exchange_name
       end
     end
   end

data/lib/happn/subscription_repository.rb

@@ -25,16 +25,17 @@ module Happn
     end
 
     def find_subscriptions_for(event)
-      possible_event_statuses = ["all", event.status.to_s]
-      possible_event_emitters = ["all", event.emitter.to_s]
-      possible_event_names    = ["all", event.name.to_s]
-      possible_event_kinds    = ["all", event.kind.to_s]
+      possible_event_statuses = ["all", event.status.to_s].uniq
+      possible_event_emitters = ["all", event.emitter.to_s].uniq
+      possible_event_names    = ["all", event.name.to_s].uniq
+      possible_event_kinds    = ["all", event.kind.to_s].uniq
       subscriptions           = []
       possible_event_statuses.each do | status |
         possible_event_emitters.each do | emitter |
           possible_event_kinds.each do | kind |
             possible_event_names.each do | name |
-              subscriptions += @subscriptions.dig(status, emitter, kind, name) || []
+              found = @subscriptions.dig(status, emitter, kind, name)
+              subscriptions.concat(found) if found
             end
           end
         end
@@ -47,7 +48,7 @@ module Happn
     def flatten(item)
       if item.instance_of?(Hash)
         item.values.inject([]) do | result, value |
-          result += flatten(value)
+          result.concat(flatten(value))
         end
       else
         item

data/lib/happn/version.rb

@@ -1,3 +1,3 @@
 module Happn
-  VERSION = "1.1.7"
+  VERSION = "1.1.8"
 end

data/lib/happn.rb

@@ -24,7 +24,7 @@ module Happn
   def self.init
     @logger                 = @configuration.logger || Logger.new(STDOUT)
     subscription_repository = SubscriptionRepository.new(@logger)
-    Happn::register(@configuration.projector_classes, subscription_repository)
+    register(@configuration.projector_classes, subscription_repository)
     @event_consumer         = EventConsumer.new(@logger, @configuration, subscription_repository)
   end
 
@@ -32,6 +32,10 @@ module Happn
     @event_consumer.start
   end
 
+  def self.stop
+    @event_consumer&.stop
+  end
+
   def self.create_queue_only
     Happn.init
     @event_consumer.wait_until_connected
@@ -56,8 +60,6 @@ module Happn
     config.management_options         = {}
   end
 
-  private
-
   def self.register(projector_classes, subscription_repository)
     @logger.info("#{projector_classes.size} projector are going to be registered...")
     projector_classes.each do | projector_class |
@@ -66,5 +68,6 @@ module Happn
       @logger.info("Projector '#{projector_class}' registered")
     end
   end
+  private_class_method :register
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: happn
 version: !ruby/object:Gem::Version
-  version: 1.1.7
+  version: 1.1.8
 platform: ruby
 authors:
 - Commuty