GorgService

Standard RabbitMQ bot used in Gadz.org SOA

Installation

Add this line to your application's Gemfile:

gem 'gorg_service'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gorg_service

Setup

Before being used, GorgService must be configured. In Rails app, put it in an Initializer.

GorgService.configure do |c|
  # application name for display usage
  c.application_name="My Application Name"
  # application id used to find message from this producer
  c.application_id="my_app_id"

  ## RabbitMQ configuration
  # 
  ### Authentification
  # If your RabbitMQ server is password protected put it here
  #
  # c.rabbitmq_user = nil
  # c.rabbitmq_password = nil
  #  
  ### Network configuration :
  #
  # c.rabbitmq_host = "localhost"
  # c.rabbitmq_port = 5672
  # c.rabbitmq_vhost = "/"
  #
  #
  # c.rabbitmq_event_exchange_name = "exchange"
  #
  # time before trying again on softfail in milliseconds (temporary error)
  # c.rabbitmq_deferred_time = 1800000 # 30min
  # 
  # maximum number of try before discard a message
  # c.rabbitmq_max_attempts = 48 # 24h with default deferring delay
  #
  # The routing key used when sending a message to the central log system (Hardfail or Warning)
  # Central logging is disable if nil
  # c.log_routing_key = nil
  #

 end

Usage

To start the RabbitMQ consummer use :

my_service = GorgService.new
my_service.run

Routing and MessageHandler

When running, GorgService act as a consumer on Gadz.org RabbitMQ network. It bind its queue on the main exchange and subscribes to routing keys with listen_to

Each received message will be routed to the corresponding MessageHandler. AMQP wildcards are supported.The first key to match the incoming routing key will be used.

A MessageHandler is a kind of controller. This is where you the message is processed. A MessageHandler expect a GorgService::Message as param of its initializermethod.

Here is an exemple MessageHandler :

class ExampleMessageHandler < GorgService::Consumer::MessageHandler::EventHandler

  listen_to "event.user.updated"

  EXPECTED_SCHEMA = {
    "type" => "object",
    "required" => ["user_id"],
    "properties" => {
      "user_id" => {"type" => "integer"}
    }
  }
  
  def validate
    message.validate_with(EXPECTED_SCHEMA)
  end
  
  def process
    begin
        if example=Example.update(message.data[:user_id])
          producer=GorgServiceProducer.new
          event=GorgService::Message.new(
            event: "event.example.updated",
            data: {example_id: example.id}
          )
          producer.publish_message(event)
        else
          raise_hardfail("Unable to update example")
        end
     rescue ApiConnectionError => e
      raise_softfail("Unable to connect to API",error: e)
     end
  end
end

As showed in this example,GorgService::MessageHandler provides 2 helpers :

• raise_hardfail: This will raise a HardfailErrorexception. The message can't be processed and will never be. It is logged and send back to main exchange for audit purpose.

• raise_softfail: This will raise a SoftfailErrorexception. The message can't be processed at this moment but may be processed in future : connection problems, rate limiting API, etc. It is sent to a deferred queue where it will be delayed for rabbitmq_deferred_timemillisecconds before being sent back in the main exchange for re-queuing.

Each one of this helpers expect two params :

• message : The information to be displayed in message's error log
• exception (optional) : The runtime exception causing the fail, for debug purpose

Message structure

GorgService::Message is defined here

It provides the following attributes :

• event : this is the same as the routing key
• id: message UUID
• errors: A list of GorgService::Message::ErrorLog
• data: Hash containing the data to be processed
• creation_time: message emission date as DateTime
• sender : message producer id

Error log structure :

• id : Error uuid
• type : Type of error (debug, info, warning, softerror, harderror)
• sender : Id of service emitting this error
• message : Error message
• debug : Hash containing debug infos

To Do

• Allow disable JSON Schema Validation on incomming messages
• Message and ErrorLog attributes validation

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/Zooip/gorg_service.

License

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