Zaikio Loom ruby gem

The Zaikio Loom ruby gem simplifies publishing events on the Zaikio Loom event system.

Applications can only publish events to Loom which have been configured in the Zaikio Hub, on the "Provided events" tab under your App configuration.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add zaikio-loom

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install zaikio-loom

Usage

To configure the gem, first add an initializer to your application:

# config/initializers/zaikio_loom.rb

Zaikio::Loom.configure do |config|

  # Loom instance to receive the events. Only `:sandbox` and `:production` will actually emit
  # events, all other environments will merely log the output, this can be controlled by
  # setting `config.logger`.
  config.environment = Rails.env

  # The name of your application, matches the "technical identifier" in the Hub
  config.application 'my_application' do |app|

    # Your application's event password for the chosen environment
    # Do not commit this password to version control.
    app.password = ENV.fetch('ZAIKIO_LOOM_PASSWORD')
  end

  # The version of the event payload, format and structure
  config.version = '1.0'
end

You can use multiple clients at once, just add a config.application(name, &block) for each one. Now, you can fire events at Zaikio Loom:

Zaikio::Loom.fire_event(
  :event_name,
  subject: 'Org/3a242896-fa57-41ba-997e-8c212d7157f3',
  payload: { foo: 'bar', baz: [1, 2, 3] }
)

This example would publish an event (in the background) to Zaikio Loom with a random UUID and the current timestamp. If you want to publish the event for a specific client, you have to include it as part of the event name:

Zaikio::Loom.fire_event(
  'my_other_app.event_name',
  subject: 'Org/3a242896-fa57-41ba-997e-8c212d7157f3',
  payload: { foo: 'bar', baz: [1, 2, 3] }
)

If you need more control over the published event, for example:

  • to provide a specific unique UUID or timestamp in the past, or
  • you want to override the version for this specific event, or
  • you want to check Loom's response to this request

then you can use the underlying Event constructor and call #fire on it:

event = Zaikio::Loom::Event.new(
  :event_name,
  subject: 'Org/3a242896-fa57-41ba-997e-8c212d7157f3',
  id: 'f5cecfce-eda7-4eae-a0b2-62da7d51e8a2',
  payload: { foo: 'bar', baz: [1, 2, 3] },
  timestamp: Time.current,
  version: '1.1.beta'
)

unless event.fire         # imagine the event_name does not exist
  event.status_code       # => 422
  event.response_body     # => '{ "errors": { "name": ["excludes a valid event name"] } }'
end

Required arguments

This gem is able to add some defaults or fallback values to the requests against the Loom API, for example:

  • the app name,
  • an unique id,
  • the version or
  • the current timestamp.

Nevertheless, the following arguments are required for every fired event and must follow the conventions described in the Loom API Guide:

  • the name of the event
  • a subject that triggered the event

Furthermore, the payload can be omitted, but must be set as a hash if given.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/zaikio/zaikio-loom-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Zaikio Loom Ruby gem project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.