How Lita.io uses the RubyGems and rubygems.org APIs

Today I released a brand new website for Lita at lita.io. While the site consists primarily of static pages for documentation, it also has a cool feature that takes advantage of a few relatively unknown things in the Ruby ecosystem. That feature is the plugins page, an automatically updating list of all Lita plugins that have been published to RubyGems.

Previously, the only directory of Lita plugins was Lita's wiki on GitHub. When someone released a plugin, they'd have to edit the list manually. This was not ideal. It was easy to forget, and required that people knew that the wiki had such a list in the first place. To make an automatically updating list, I had to think about how I could detect Lita plugins out there on the Internet.

I spent some time digging through the rubygems.org source code to see how I might get the information I wanted out of the API. After experimenting with a few things, I discovered an undocumented API: reverse dependencies. You can hit the endpoint /api/v1/gems/GEM_NAME/reverse_dependencies.json and you will get back a list of all gems that depend on the given gem. This was great! Now I had a list of names of all the gems that depend on Lita. It's pretty safe to assume those are all Lita plugins.

This API only returns the names of the gems, however. I also wanted to display a description and the authors' names. This data could be gathered from an additional API request, but there was another piece of information I wanted that couldn't be extracted from the API.

Lita has two types of plugins: adapters and handlers. Adapters allow Lita to connect to a particular chat service, and handlers add new functionality to the robot at runtime; they're the equivalent of Hubot's scripts. I wanted the plugins page to list the plugin type along with the name, author, and link to its page on rubygems.org. To do this, I used another lesser-known feature: RubyGems metadata.

In RubyGems 2.0 or greater, a gem specification can include arbitrary metadata. The metadata consists of a hash assigned to the metadata attribute of a Gem::Specification. The keys and values must all be strings. In Lita 2.7.1, I updated the templates used to generate new Lita plugins so that they automatically included metadata in their gemspecs indicating which type of plugin it is. For example:

Gem::Specification.new do |spec|
  spec.metadata = { "lita_plugin_type" => "handler" }
end

Because Lita requires Ruby 2.0 or greater, which comes with RubyGems 2.0, any Lita plugin can use the metadata attribute. Any plugins created before the generator update in Lita 2.7.1 can still be detected and listed on the plugins page, it just won't list their type.

Now all I had to do was read this information from each plugin gem. Unfortunately, rubygems.org currently has no API that exposes gem metadata, so things got a little tricky. I wrote a script which called gem fetch to download the actual gem files for all the Lita plugins. Once downloaded, running gem spec on the gem file outputs a YAML representation of the gem's specification. In Ruby, loading that YAML with YAML.load returns a Gem::Specification. From there I could simply access the fields I wanted to display, including the type of plugin via spec.metadata["lita_plugin_type"]. This data is then persisted in Postgres. The script runs once a day to get the latest data from RubyGems.

This process could be made much easier and less error-prone if rubygems.org added metadata to the information it exposes over its API. Nevertheless, creating the plugins page for Lita.io was a good challenge and gave me a chance to explore some of the pieces of the RubyGems ecosystem I didn't know existed.

Getting started with Lita

Lita is an extendable chat bot for Ruby programmers that can work with any chat service. If you've used Hubot before, Lita is similar, but written in Ruby instead of JavaScript. It's easy to get started, and you can have your own bot running in minutes.

Lita uses regular RubyGems as plugins. You'll need at least one "adapter" gem to connect to the chat service of your choice. Add as many "handler" gems as you want to add functionality to your bot.

  1. Install the lita gem.
  $ gem install lita
  1. Create a new Lita project.
  $ lita new

This will create a new directory called lita with a Gemfile and Lita configuration file.

  1. Edit the Gemfile, uncommenting or adding the plugins you want to use. There should be an adapter gem (such as lita-hipchat or lita-irc) and as many handler gems as you'd like. For example:
  source "https://rubygems.org"

  gem "lita"
  gem "lita-hipchat"
  gem "lita-karma"
  gem "lita-google-images"
  1. Install all the gems you specified in the Gemfile:

    $ bundle install
  2. Install Redis. On OS X, you can use Homebrew with brew install redis.

  3. Test Lita out right in your terminal with the built-in shell adapter.

    $ bundle exec lita

Type "Lita: help" to get a list of commands available to you.

  1. Edit the Lita configuration file to add connection information for the chat service you're using. For example, if you're using the HipChat adapter, it might look something like this:

    Lita.configure do |config|
      config.robot.name = "Lita Bot"
      config.robot.adapter = :hipchat
      config.adapter.jid = "12345_123456@chat.hipchat.com"
      config.adapter.password = "secret"
      config.adapter.rooms = :all
    end

You'll want to consult the documentation for whichever adapter you're using for all the configuration options. If you're going to deploy Lita to Heroku, you'll want to add the Redis To Go add on and set config.redis.url = ENV["REDISTOGO_URL"].

  1. Deploy your Lita project anywhere you like. If you're deploying to Heroku, you can use a Procfile like this:

    web: bundle exec lita

Lita also has built-in support for daemonization if you want to deploy it to your own server.

Be sure to visit the Lita home page for lots more information on usage, configuration, and adding your own behavior to your robot!

GuerillaPatch: An interface for monkey patching objects for Ruby 1.9 and 2.0

At RubyConf this week, the first preview of the upcoming Ruby 2.0 was released. One of the new features is refinements, a way of adding new behavior to an object that only takes place within a certain scope. This allows a safer way to extend existing objects without screwing up code that may be depending on the original behavior. A common example of this is ActiveSupport, which adds extensions to many of the core classes. With refinements, these extensions can be added to a refinement module, which can then be "used" in other namespaces without affecting the object globally.

This is a powerful new feature, but I was curious how best to write library code that uses it in a way that is interoperable with Ruby 1.9. I created a gem called GuerillaPatch which provides a single interface that will extend an object with a refinement if run under Ruby 2.0, and fall back to simply modifying the class globally if run under 1.9.

Install with gem install guerilla_patch. The source code and usage examples are available on GitHub.

← Previous 1 3 4 5 17