Hanami Events for Google Cloud Pub/sub

Installation

bundle add hanami-events-cloud_pubsub

If using Hanami, register the adapter in your config/environment.rb:

# config/environment.rb
# ...
require_relative './../lib/my_app'
require_relative './../apps/web/application'
# ...

require 'hanami/events/cloud_pubsub/register' # <----

Configure the pubsub adapter how you want (optional):

# config/environment.rb

Hanami.configure do
  environment :development do
    cloud_pubsub do |config|
      config.pubsub = { project_id: 'emulator' } # optional
      config.logger = Hanami.logger # optional
      config.namespace = :staging # optional
      config.auto_create_topics = false # optional
      config.auto_create_subscriptions = false # optional
      config.on_shutdown = ->(adapter) { Analytics.flush } # optional
      config.error_handlers << ->(err, message) { MyErrorReporter.report(err) }
      # ...
    end
  end
end

Usage

This gem is compatible with the hanami-events gem, with a couple caveats:

1. All subscribers must specify an id: attribute. When you subscribe, you should pass this:

Hanami.events.subscribe('user.deleted', id: 'my-subscriber-id') do |payload|
  puts "Deleted user: #{payload}"
end

Additional options will be passed to Google::Cloud::Pubsub::Subscription#listen:

Hanami.events.subscribe('foo', id: 'bar', deadline: 30) do |payload|
  sleep 29 # message will finish before deadline
end

2. Responding to events is done in a different process via the CLI.

First, create a config file:

# config/cloudpubsub.rb

require 'config/environment'

Hanami.boot

class CustomMiddleware
  def call(message)
    puts 'Middleware started!'
    yield
    puts 'Middleware ended!'
  end
end

Hanami::Events::CloudPubsub.configure do |config|
  # required
  config.subscriptions_loader = -> do
    # Ensure these files are not loaded until *after* the subscriptions are
    # setup, or else you will have an undefined reference to `$events`
    Hanami::Utils.require! 'apps/web/subscriptions'
  end

  # (optional)
  config.logger = Hanami.logger

  # (optional)
  config.error_handlers << lambda do |err, message|
    Honeybadger.notify(err, context: message.attributes)
  end

  config.middleware << CustomMiddleware.new # must respond to #call
end

Then, run the worker process:

bundle exec cloudpubsub run

RequestId Integration

To gem has an integration with request_id, so you can trace interactions between various components in your app. To make it work properly, make sure the request_id is added to your Gemfile, then require the middleware:

require 'hanami/events/cloud_pubsub/middleware/request_id'

Hanami::Events::CloudPubsub.configure do |config|
  # ...
end

Yabeda Prometheus Integration

If you have the yabeda-prometheus gem installed, a /metrics endpoint will be available on the health check server which can be scraped.

All you need to do to activate this is to make sure to require 'yabeda/prometheus'.

Testing

If you would like to use an emulator process for testing:

$(gcloud beta emulators pubsub env-init)
gcloud beta emulators pubsub start
bundle exec cloudpubsub run --emulator

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

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/ianks/hanami-events-cloud_pubsub. 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 Hanami::Events::CloudPubsub project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.