Hyrax's Event Bus (Hyrax::Publisher)

Beginning in 3.0.0, Hyrax supports a topic-based event bus using dry-events. This interface seeks to provide a single integration point for event-driven behavior in Hyrax and dependent applications.

Whenever Hyrax performs one of the actions associated with a named Event, it promises to push an event to the Publisher with a payload. The Event payloads are specific to each event type/topic, but usually contain the object acted on and the user responsible for triggering the Event. Applications can subscribe Listeners which will be triggered and passed the Event and payload whenever an Event is published. Likewise, applications can (and should) publish Events to trigger Hyrax's listeners.

Listeners can perform any kind of action in response to published events, from critical behavior like triggering workflow state changes and updating indexes to administrative/informational tasks like logging or data collection for analytics. These kinds of tasks are hard to do consistently when many peices of code across multiple gems may perform the same action. By providing a unified and documented interface, we hope to shift the burden of consistency from Hyrax applications to the engine itself.

The key point of reference for the implementation of this system is Hyrax::Publisher.

Topics

The topics (aka 'channels' or 'event types') Hyrax supports are:

Topic	Payload	Added
'batch.created'		3.0.0
'collection.membership.updated'		3.2.0
'collection.metadata.updated'		3.2.0
'file.characterized'		3.5.0
'file.downloaded'		3.3.0
'file.metadata.updated'		3.4.0
'file.set.audited'		3.0.0
'file.set.attached'		3.0.0
'file.set.url.imported'		3.0.0
'file.set.restored'		3.0.0
'object.deleted'		3.0.0
'object.failed_deposit'		3.0.0
'object.deposited'		3.0.0
'object.acl.updated'		3.0.0
'object.metadata.updated'		3.0.0

We expect this list to grow over time, but we're also taking care to keep the maintenance burden small. Please be in touch about application-side needs.

Replacing Hyrax::Callbacks

Hyrax had a prior interface offering pub/sub-like behavior: Hyrax::Callbacks. This system allowed a user to set a block as a named callback method, which would then be triggered by engine or application code.

# to register
Hyrax.config.callback.set(:after_create_concern) do |curation_concern, user|
  ContentDepositEventJob.perform_later(curation_concern, user)
end

# from application code
Hyrax.config.callback.run(:after_create_concern, curation_concern, user)

In 3.0.0, this interface is replaced by Hyrax::Publisher. The old default callbacks are deprecated for removal in 4.0.0, and their implementations have been ported to Listener classes. The callbacks themselves now publish events (see chart below) which triggers the ported code by default. Existing Hyrax engine code that invokes Hyrax.config.callback will continue to do until 4.0.0 but, in general, new code won't invoke callbacks. If your application disabled default callbacks, registered/enabled custom ones, or overwrote callback behavior, this should provide you a measure of compatibility.

We recommend updating existing Hyrax::Callbacks usage soon. Hyrax plans to make extensive internal usage of Hyrax::Publisher during the 3.0.0 release series and beyond.

Callback	Event(s)
:after_create_concern	'object.deposited', 'object.metadata.updated'
:after_create_fileset	'file_set.attached'
:after_revert_content	'file_set.restored'
:after_update_metadata	'object.metadata.updated'
:after_destroy	'object.deleted'
:after_batch_create_success	'batch.created' (result: :success)
:after_batch_create_failure	'batch.created' (result: :failure)
:after_import_url_failure	'file.set.url.imported' (result: :failure)