tracyloisel / active_topic

Rails gem Active Topic

ActiveTopic

ActiveTopic is a gem developed for Ruby on Rails that will allow you to simply add Google Cloud Topics to your Ruby on Rails application. It is a wrapper of the google-cloud-pubsub gem.

Information

• Source code available on GitHub

Installation

Add this line to your application's Gemfile:

gem 'active_topic', '~> 0.1.0'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install active_topic

Getting Started

There are two generators provided by ActiveTopic in order to help you to setup your ActiveTopic installation.

After having add ActiveTopic to your Gemfile and ran bundle install, you need to run the following generator:

rails generate active_topic:setup

This generator will create a new file (config/initializers/active_topic.rb). In this file you will find:

ActiveTopic.configure do |config|
  config.project_id = 'Your Google Cloud project id'
  config.credentials = 'Your Google Cloud credentials'
end

project_id will contain your Google Cloud project id credentials will be the absolute path to the credentials json file that you can for your Google service account.

How to use?

Generate your classes

After having filled up the config/initializers/active_topic.rb file, you can then run the following generator:

rails generate active_topic:topic TopicName

TopicName is the name of the topic to which you want to publish messages. As an example you could run:

rails generate active_topic:topic MyFirstOne

This generator will create a new file app/topics/my_first_one_topic.rb. This file will contain a simple ruby class:

class MyFirstOneTopic < ActiveTopic::Base
end

All the classes generated by the generator will be suffixed by Topic and automatically be placed under the app/topics directory.

The class MyFirstOneTopic inherits from ActiveTopic::Base.

There are two methods you can use for this class in order to override the configuration provided by config/initializers/active_topic.rb when you want to use a different project or a different service account.

To override the project_id:

class MyFirstOneTopic < ActiveTopic::Base
    with_project_id 'different_project_id'
end

To override the credentials:

class MyFirstOneTopic < ActiveTopic::Base
    with_credentials 'different_credentials'
end

Using ActiveTopic

The classes that inherits with ActiveTopic::Base are provided with a bunch of methods.

To check for the existence of the topic on GoogleCloud, you have the following method:

topic_created?

This method will return true if the topic already exists or will return false if it does not.

To create the topic:

create_topic!

The name of the created topic will be the name of the class in snake_case without the topic suffix (for instance, for a class named MyFirstOneTopic, the topic created will be my_first_one) This method will return true if the topic is created with success. If you try the create a topic that already exists, this method will raise an ActiveTopic::Exceptions:TopicAlreadyExists exception.

Using the classes inheriting from ActiveTopic::Base

To use ActiveTopic you need to use an instance of a class that inherits from ActiveTopic::Base.

example:

active_topic = MyFirstOneTopic.new

Creating a new subscription:

You can use the method subscribe to create a subscription to the topic of your class:

active_topic.subscribe 'subscription_name'

You can also provide the number of seconds to wait for the aknowledgement of the messages and also the URL endpoint to push messages to:

active_topic.subscribe 'subscription_name', deadline: 60, endpoint: 'https://example.com/endpoint'

Publishing a message on the topic:

You can publish a message to the topic of your class with the method publish:

active_topic.publish 'message'

You can also publish a message with attributes:

active_topic.publish 'message', attr: 4, hello: :ok

It is possible to send multiple messages at the same in a batch by passing a block to publish:

active_topic.publish do |batch|
  batch.publish 'message 1', attr: :ok
  batch.publish 'message 2', attr: :okok
end

Publishing a message asynchronously to the topic:

You can publish a message asynchronously to the topic of your class with method publish_async:

active_topic.publish_async 'message'

You can publish a message asynchronously with attributes:

active_topic.publish_async 'message', attr: 4, hello: :ok

You can also have a callback by passing a block to publish_async:

active_topic.publish_async 'message' do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

To manage the messages that are published asynchronously, you can use the async_publisher method:

active_topic.async_publisher.stop! # Stops the messages asynchronous publishing

More information on the AsyncPublisher class on GoogleApis Documentation.

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/shopmium/active_topic.

We use rubocop for the linting. Please take into account the linting rules that are available in the .rubocop.yml file.

Testing

For your tests, we recommend you to use the Google Cloud Pub/Sub emulator. It will enable you to stub the calls made to the GoogleCloud Pub/Sub API.

About Shopmium

Shopmium is a free application that enables you to access exclusive offers on everyday brands found in supermarkets. As a user, you simply buy the featured product at the nearest store, take a picture of your receipt and get up to 100% cashback paid directly into your PayPal or bank account!

Offers in the app changes weekly as we work with over 500 of the biggest supermarkets products manufacturers, such as Danone, Nestlé, SC Johnson, Heineken, McCain, Pepsico and much more. These products manufacturers are featuring different products and are providing Shopmium users with exclusive offers to buy these products. More than 5 million people in the UK, France and Belgium are already experiencing Shopmium.

Shopmium started in France in 2011, and today, across Paris and London, we are a team of 70 and proud to say that we’ve already won many awards for our app.

In 2015, Shopmium joined Quotient Technology Inc. a US based organisation that owns Coupons.com.

License

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