Significant changes in the new event messaging system in master

[waiting-for-dev]

Hey!

The following is a notice relevant for all people using the Solidus master branch.

As you probably know, we've been working on replacing the event bus with a new, more friendly and advanced system. As we kept working on it, we realized that the best way to make it evolve was to extract it into a standalone gem. The new gem is called Omnes, and we just merged the PR introducing it on Solidus.

As it's a meaningful change, we want to provide support also to people using master (although that's unstable by definition).

If you experience any issues or like more information, please feel free to add any comment or DM me on Slack (@waiting_for_dev).

These are the instructions to update:

• Skip this message if you're not using Solidus master branch.

• Skip this message if you're not using Solidus events for anything.

• Remove config.events.adapter setting from config/initializers/spree.rb.

• Add config.use_legacy_events = false in config/initializers/spree.rb.

• Replace references to Spree::Event for Spree::Bus.

• Replace references to Spree::Bus.fire for Spree::Bus.publish.

• Make sure you always reference to event names as Symbol and not as String (look for Spree::Bus.publish and Spree::Bus.subscribe & Spree::Bus.register).

• Register events within a .to_prepare block in an initializer. E.g.:

Rails.application.config.to_prepare do
  Spree::Bus.register(:foo)
end

• Don't use regexp subscriptions:
  • If you were subscribing to /.*\.spree$/, use instead Spree::Bus.subscribe_to_all.
  • If you do want to keep using them (although we consider it an anti-pattern as it can catch false positives), register a custom matcher on Omnes:

ORDER_EVENTS_MATCHER = ->(event) { event.omnes_event_name.match?(/order_/) }
Spree::Bus.subscribe_with_matcher(ORDER_EVENTS_MATCHER) do |event|
  # ...
end

• Use Omnes subscribers instead of module subscribers:

# Instead of

module MySubscriber
  event_action :do_something, event_name: :order_finalized
  event_action :order_recalculated
  
  def do_something(event)
   # ...
  end
  
  def order_recalculated(event)
    # ... 
  end
end

# do

class MySubscriber
  handle :order_finalized, with: :do_something
  handle :order_recalculated, with: :order_recalculated

  def do_something(event)
   # ...
  end
  
  def order_recalculated(event)
    # ... 
  end
end

• Make sure to subscribe subscribers within a .to_prepare block. E.g.:

Rails.application.config.to_prepare do
  MySubscriber.new.subscribe_to(Spree::Bus)
end

• If you were using Spree::TestingSupport::EventHelpers:

  • Replace it by Spree::TestingSupport::BusHelpers (and require spree/testing_support/bus_helpers).
  • Use stub_spree_bus instead of stub_spree_event
  • Use to_have_been_published matcher instead of to_have_been_fired.

• Read everything else Omnes provides!!

Thanks!! 🚌

[jarednorman]

Amazing. Thanks for the info. I'm just upgrading one of our applications now. So far, so good.

[jarednorman]

I really like that it gives us control over constructing our subscribers, so we can pass in collaborating objects. Very nice design.