Making Your Ruby Gem Configurable

#ruby #rails #beginners #coding

Ruby gems are pretty much a module. It's not a big deal to us to declare a module, but how do we create those richest configuration files we usually have in /initializers folder of a Ruby on Rails application? Let's check it out.

First of all, there are many ways to make your gem configurable. I'll present you one, and further, we'll give it a look at how other gems implement it.

Example of implementation

I'll call my example gem gsdk. You can assume the gem structure is the default of bundle gem gsdk (Bundler version 1.17.3), but this isn't important for the context of this post, it's just to give you some orientation. This gem will have a token and a secret key I'd like to inform as configuration, so let's put that in code:

# gsdk/lib/gsdk/configuration

module Gsdk
  class Configuration
    attr_accessor :token, :secret_key

    def initialize(token = nil, secret_key = nil)
      @token = token
      @secret_key = secret_key
    end
  end
end

As simple as that, we have the configuration class that makes token and secret key available through attr_accessor.

Gsdk is a module, but the Configuration is a class instance. How do we make the instance available to be used anywhere, by any class that exists inside the Gsdk module?

module Gsdk
  class << self
    attr_accessor :configuration
  end

  def self.configuration
    @@configuration ||= Configuration.new
  end
end

It's a matter of scope. Although it's a module, modules are implemented as classes (Module.class == Class) and can make use of instance or class variables too. However, we need to inform that to the module, and we do so in a code block inside the class << self. The block code is enough by itself, but I wanna initialize with an empty Configuration instance if configuration is accessed, that's why we have self.configuration.

Now it is possible to configure the gem and make the token and secret key available in the module.

module Gsdk
  class Caller
    def call
      puts "Token: #{Gsdk.configuration.token}"
      puts "Secret key: #{Gsdk.configuration.secret_key}"
    end
  end
end

(base) ➜  gsdk git:(master) ✗ ./bin/console
2.6.6 :001 > configuration = Gsdk::Configuration.new('my_token', 'my_secret_key')
 => #<Gsdk::Configuration:0x000055b8ada3d638 @token="my_token", @secret_key="my_secret_key"> 
2.6.6 :002 > Gsdk.configuration = configuration
 => #<Gsdk::Configuration:0x000055b8ada3d638 @token="my_token", @secret_key="my_secret_key"> 
2.6.6 :003 > Gsdk::Caller.new.call
Token: my_token
Secret key: my_secret_key
 => nil

The gem is already configurable, but we still missing what we proposed to answer in the first paragraph of this post: how to do what was shown above but in a configuration block. Now we know that it's a matter of scope, the answer should be easier to understand :

module Gsdk

...

  def self.configure
    yield(configuration)
  end
end

The class method self.configure allows us to achieve our goal:

Gsdk.configure do |config|
  config.token = "your_token"
  config.secret_key = "your_secret_key"
end

(base) ➜  gsdk git:(master) ✗ ./bin/console
2.6.6 :001 > Gsdk.configure do |config|
2.6.6 :002 >       config.token = "your_token"
2.6.6 :003?>     config.secret_key = "your_secret_key"
2.6.6 :004?>   end
 => "your_secret_key" 
2.6.6 :005 > Gsdk.configuration
 => #<Gsdk::Configuration:0x000055f935a2e818 @token="your_token", @secret_key="your_secret_key"> 
2.6.6 :006 >

With yield we're calling the empty Configuration instance (config.class == Gsdk::Configuration), that uses attr_accessor for token and secret_key, making them available in the code block.

Implementation alternatives

Let's check how big and consolidated gems achieve roughly the same we did above. To identify this we can check two things: (1) where is the method that accepts a configuration block, and (2) how a configuration option is set. The place to get the name of the method and the configuration options is the configuration file usually pointed out in the gem's documentation.

Devise gem:

Devise.setup do |config|
...

config.password_length = 6..128

...
end

This is part of the configuration file generated by Devise using their rails generate devise:install. Looking into lib/devise.rb:

module Devise

...

  mattr_accessor :password_length
  @@password_length = 6..128

...

  def self.setup
    yield self
  end

...
end

Devise uses Rails specific mattr_accessor that provides getters and setters in a class/module level, and self.setup is the equivalent of our self.configure implemented in the previous section.

We could achieve the same as Devise eliminating the use of Gsdk::Configuration and changing our module to:

module Gsdk
  class << self
    attr_accessor :token, :secret_key
  end

  def self.configure
    yield self
  end
end

(base) ➜  gsdk git:(master) ✗ ./bin/console
2.6.6 :001 > Gsdk.configure do |config|
2.6.6 :002 >       config.token = "your_token"
2.6.6 :003?>     config.secret_key = "your_secret_key"
2.6.6 :004?>   end
 => "your_secret_key" 
2.6.6 :005 > Gsdk.secret_key
 => "your_secret_key" 
2.6.6 :006 > Gsdk.token
 => "your_token"

Sidekiq gem

  Sidekiq.configure_server do |config|
    config.redis = { url: ENV.fetch('REDIS_URL') }
  end

This is part of Sidekiq configuration I have in an initializer of a Rails project. Looking into lib/sidekiq.rb:

...

module Sidekiq

...

  def self.redis
    ...
  end

  def self.redis=(hash)
    ...
  end

  def self.configure_server
    yield self if server?
  end

...

end

In Sidekiq they explicitly implement getters and setters, which we saw being accomplished before using attr_accessor and mattr_accessor. Once again, we can change our implementation to work in the same manner:

module Gsdk
  def self.token
    @token
  end

  def self.token=(token)
    @token = token
  end

  def self.secret_key
    @secret_key
  end

  def self.secret_key=(secret_key)
    @secret_key = secret_key
  end

  def self.configure
    yield self
  end
end

(base) ➜  gsdk git:(master) ✗ ./bin/console
2.6.6 :001 > Gsdk.configure do |config|
2.6.6 :002 >       config.token = "your_token"
2.6.6 :003?>     config.secret_key = "your_secret_key"
2.6.6 :004?>   end
 => "your_secret_key" 
2.6.6 :005 > Gsdk.token
 => "your_token" 
2.6.6 :006 > Gsdk.secret_key
 => "your_secret_key"

Conclusion

In this post, we saw how to make a gem configurable. We implemented our configuration strategy and further checked how Devise and Sidekiq gems are implemented to be configurable.

All three implementations explored in this post are different one from another, but they summed up to getters and setters. You can explicitly implement getters and setters on your own or use something like attr_accessor; make use of instance variables or class variables.

Which one is the best implementation strategy? My response would be: don't overthink this. You can argue that to use mattr_accessor you need an extra dependency, or that instance variables in modules are simply poor design. But the point is that we're talking about something trivial, so start with what you think is the best for you.

This is it! If you have any comments or suggestions, don't hold back, let me know.

Options if you like my content and would like to support me directly (never required, but much appreciated):

BTC address: bc1q5l93xue3hxrrwdjxcqyjhaxfw6vz0ycdw2sg06