larva

Larva

Larva is a Ruby daemon builder based on top of the Propono pub/sub library and the Filum logging library.

It is the foundation for daemons in Meducation's infrastructure.

Getting started is simple. Just install the gem and run

larva spawn my_daemon_name

Installation

If you want to add this to an existing daemon, add this line to your application's Gemfile:

gem 'larva'

And then execute:

$ bundle install

Usage

Larva provides you with listeners, processors and a worker pool to quickly build an application that listens and responds to Propono messages.

Here is a sample application that forms the basis of a rake task for most Meducation daemons.

require 'larva'

# Setup Config for Filum and Propono

class MyProcessor < Larva::Processor
  def comment_created
    # I get called when the message is received :)
  end
end

processors = {my_topic: MyProcessor}
Larva::WorkerPool.start(processors, "queue-suffix")

# In another application...
Propono.publish(:my_topic, {entity: "comment", action: "created", id: 8}

Listeners

Larva Listeners provide an easy way of listening to a Propono topic and processing the message, complete with lots of logging through Filum.

Larva::Listener.listen(:my_topic, processor, "queue_suffix")

This will listen for messages on :my_topic and pass them to processor.process. It will log what is happening via Filum.

Processors

Processors are used by listeners to handle the messages that are received.

If your messages have an entity and action fields, then you can create methods named `#{entity}_#{action}, which get called when a message is received.

For example:

class MyProcessor < Larva::Processor
  def comment_created
    # I get called for the first message
  end
end
Larva::Listener.listen(:my_topic, MyProcessor, "")
Propono.publish(:my_topic, {entity: "comment", action: "created", id: 8}

If those methods do not exist, then a method called process is called. This method has acccess to message, action, entity and id fields. If this returns true, then the message is considered processed, else if it returns false, an error wil be logged.

For example:

class MyProcessor
  def process
    if message[:foo] == bar
      # Larva will consider this message processed successfully
      true
    else
      # An error is logged for this message
      false
    end
  end
end
Larva::Listener.listen(:my_topic, MyProcessor, "")
Propono.publish(:my_topic, {foo: "bar"} # -> Will be logged as a success
Propono.publish(:my_topic, {foo: "meh"} # -> Will be logged as unprocessed.

Worker Pool

The worker pool creates a listener for each topic, and proxies messages to the associated processors. If any processors die, the application will die.

Creating a worker pool is trivial:

processors = {
  my_topic_1: MyProcessor1
  my_topic_2: MyProcessor2
}
Larva::WorkerPool.start(processors, "queue-suffix")

Is it any good?

Yes.

Contributing

Firstly, thank you!! :heart::sparkling_heart::heart:

We'd love to have you involved. Please read our contributing guide for information on how to get stuck in.

Contributors

This project is managed by the Meducation team.

These individuals have come up with the ideas and written the code that made this possible:

• Jeremy Walker
• Malcolm Landon
• Charles Care
• Rob Styles

Licence

Copyright (C) 2013-2014 New Media Education Ltd

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

A copy of the GNU Affero General Public License is available in Licence.md along with this program. If not, see http://www.gnu.org/licenses/.