When I first started writing Ruby code professionally back in 2011, one of the things that impressed me the most about the language was its flexibility. It felt as though with Ruby, everything was possible. Compared to the rigidity of languages like C# and Java, Ruby programs almost seemed like they were alive.

Consider how many incredible things you can do in a Ruby program. You can define and delete methods at will. You can call methods that don't exist. You can conjure entire nameless classes out of thin air. It's absolutely wild.

But that's not where the story ends. While you can apply these techniques inside your own code, Ruby also lets you apply them to anything loaded into the virtual machine. In other words, you can mess with other people's code as easily as you can your own.

What Are Monkeypatches?

Enter the monkeypatch.

In short, monkeypatches "monkey with" existing code. The existing code is often code you don't have direct access to, like code from a gem or from the Ruby standard library. Patches are usually designed to alter the original code's behavior to fix a bug, improve performance, etc.

The most unsophisticated monkeypatches reopen ruby classes and modify behavior by adding or overriding methods.

This reopening idea is core to Ruby's object model. Whereas in Java, classes can only be defined once, Ruby classes (and modules for that matter) can be defined multiple times. When we define a class a second, third, fourth time, etc, we say that we're reopening it. Any new methods we define are added to the existing class definition and can be called on instances of that class.

This short example illustrates the class reopening concept:

1class Sounds
2  def honk
3    "Honk!"
4  end
5end
6
7class Sounds
8  def squeak
9    "Squeak!"
10  end
11end
12
13sounds = Sounds.new
14sounds.honk    # => "Honk!"
15sounds.squeak  # => "Squeak!"

Notice that both the #honk and #squeak methods are available on the Sounds class through the magic of reopening.

Essentially, monkeypatching is the act of reopening classes in 3rd-party code.

Is Monkeypatching Dangerous?

If the previous sentence scared you, that's probably a good thing. Monkeypatching, especially when done carelessly, can cause real chaos.

Consider for a moment what would happen if we were to redefine Array#<<:

1class Array
2  def <<(*args)
3    # do nothing 😈
4  end
5end

With these four lines of code, every single array instance in the entire program is now broken.

What's more, the original implementation of #<< is gone. Aside from restarting the Ruby process, there's no way to get it back.

When Monkeypatching Goes Horribly Wrong

Back in 2011, I worked for a prominent social networking company. At the time, the codebase was a massive Rails monolith running on Ruby 1.8.7. Several hundred engineers contributed to the codebase on a daily basis, and the pace of development was very fast.

At one point, my team decided to monkeypatch String#% to make writing plurals easier for internationalization purposes. Here's an example of what our patch could do:

1replacements = {
2  horse_count: 3,
3  horses: {
4    one: "is 1 horse",
5    other: "are %{horse_count} horses"
6  }
7}
8
9# "there are 3 horses in the barn"
10"there %{horse_count:horses} in the barn" % replacements

We wrote up the patch and eventually got it deployed into production... only to find that it didn't work. Our users were seeing strings with literal %{...} characters instead of nicely pluralized text. It didn't make sense. The patch had worked perfectly well in the development environment on my laptop. Why wasn't it working in production?

Initially, we thought we'd found a bug in Ruby itself, only later, to find that a production Rails console produced a different result than a Rails console in development. Since both consoles ran on the same Ruby version, we could rule out a bug in the Ruby standard library. Something else was going on.

After several days of head-scratching, a co-worker was able to track down a Rails initializer that added another implementation of String#% that none of us had seen before. To further complicate things, this earlier implementation also contained a bug, so the results we saw in the production console differed from Ruby's official documentation.

That's not the end of the story though. In tracking down the earlier monkeypatch, we also found no less than three others, all patching the same method. We looked at each other in horror. How did this ever work??

We eventually chalked the inconsistent behavior up to Rails' eager loading. In development, Rails lazy loads Ruby files, i.e., only loads them when they are required. In production, however, Rails loads all of the app's Ruby files at initialization. This can throw a big monkey wrench into monkeypatching.

Consequences of Reopening a Class

In this case, each of the monkeypatches reopened the String class and effectively replaced the existing version of the #% method with another one. There are several major pitfalls to this approach:

• The last patch applied "wins", meaning, behavior is dependent on load order
• There's no way to access the original implementation
• Patches leave almost no audit trail, which makes them very difficult to find later

Not surprisingly, perhaps, we ran into all of these.

At first, we didn't even know there were other monkeypatches at play. Because of the bug in the winning method, it appeared the original implementation was broken. When we discovered the other competing patches, it was impossible to tell which won without adding copious puts statements.

Finally, even when we did discover which method won in development, a different one would win in production. It was also programmatically difficult to tell which patch had been applied last since Ruby 1.8 didn't have the wonderful Method#source_location method we now have.

I spent at least a week trying to figure out what was going on, time I essentially wasted chasing an entirely avoidable problem.

Eventually, we decided to introduce the LocalizedString wrapper class with an accompanying #% method. Our String monkeypatch then simply became:

1class String
2  def localize
3    LocalizedString.new(self)
4  end
5end

When Monkeypatching Fails

In my experience, monkeypatches often fail for one of two reasons:

• The patch itself is broken. In the codebase I mentioned above, not only were there several competing implementations of the same method, but the method that "won" didn't work.
• Assumptions are invalid. The host code has been updated and the patch no longer applies as written.

Let's look at the second bullet point in more detail.

Even the Best-Laid Plans...

Monkeypatching often fails for the same reason you reached for it in the first place — because you don't have access to the original code. For precisely that reason, the original code can change out from under you.

Consider this example in a gem that your app depends on:

1class Sale
2  def initialize(amount, discount_pct, tax_rate = nil)
3    @amount = amount
4    @discount_pct = discount_pct
5    @tax_rate = tax_rate
6  end
7
8  def total
9    discounted_amount + sales_tax
10  end
11
12  private
13
14  def discounted_amount
15    @amount * (1 - @discount_pct)
16  end
17
18  def sales_tax
19    if @tax_rate
20      discounted_amount * @tax_rate
21    else
22      0
23    end
24  end
25end

Wait, that's not right. Sales tax should be applied to the full amount, not the discounted amount. You submit a pull request to the project. While you're waiting for the maintainer to merge your PR, you add this monkeypatch to your app:

1class Sale
2  private
3
4  def sales_tax
5    if @tax_rate
6      @amount * @tax_rate
7    else
8      0
9    end
10  end
11end

It works perfectly. You check it in and forget about it.

Everything is fine for a long time. Then one day the finance team sends you an email asking why the company hasn't been collecting sales tax for a month.

Confused, you start digging into the issue and eventually notice one of your co-workers recently updated the gem that contains the Sale class. Here's the updated code:

1class Sale
2  def initialize(amount, discount_pct, sales_tax_rate = nil)
3    @amount = amount
4    @discount_pct = discount_pct
5    @sales_tax_rate = sales_tax_rate
6  end
7
8  def total
9    discounted_amount + sales_tax
10  end
11
12  private
13
14  def discounted_amount
15    @amount * (1 - @discount_pct)
16  end
17
18  def sales_tax
19    if @sales_tax_rate
20      discounted_amount * @sales_tax_rate
21    else
22      0
23    end
24  end
25end

Looks like one of the project maintainers renamed the @tax_rate instance variable to @sales_tax_rate. The monkeypatch checks the value of the old @tax_rate variable, which is always nil. Nobody noticed because no errors were ever raised. The app chugged along as if nothing had happened.

Why Monkeypatch?

Given these examples, it might seem like monkeypatching just isn't worth the potential headaches. So why do we do it? In my opinion, there are three major use-cases:

• To fix broken or incomplete 3rd-party code
• To quickly test a change or multiple changes in development
• To wrap existing functionality with instrumentation or annotation code

In some cases, the only viable way to address a bug or performance issue in 3rd-party code is to apply a monkeypatch.

But with great power comes great responsibility.

Monkeypatching Responsibly

I like to frame the monkeypatching conversation around responsibility instead of whether or not it's good or bad. Sure, monkeypatching can cause chaos when done poorly. However, if done with some care and diligence, there's no reason to avoid reaching for it when the situation warrants it.

Here's the list of rules I try to follow:

1. Wrap the patch in a module with an obvious name and use Module#prepend to apply it
2. Make sure you're patching the right thing
3. Limit the patch's surface area
4. Give yourself escape hatches
5. Over-communicate

For the remainder of this article, we're going to use these rules to write up a monkeypatch for Rails' DateTimeSelector so it optionally skips rendering discarded fields. This is a change I actually tried to make to Rails a few years ago. You can find the details here.

You don't have to know much about discarded fields to understand the monkeypatch, though. At the end of the day, all it does is replace a single method called build_hidden with one that effectively does nothing.

Let's get started!

Use Module#prepend

In the codebase I encountered in my previous role, all the implementations of String#% were applied by reopening the String class. Here's an augmented list of the drawbacks I mentioned earlier:

• Errors appear to have originated from the host class or module instead of from the patch code
• Any methods you define in the patch replace existing methods with the same name, meaning, there's no way of invoking the original implementation.
• There's no way to know which patches were applied and therefore, which methods "won"
• Patches leave almost no audit trail, which makes them very difficult to find later

Instead, it's much better to wrap your patch in a module and apply it using Module#prepend. Doing so leaves you free to call the original implementation, and a quick call to Module#ancestors will show the patch in the inheritance hierarchy so it's easier to find if things go wrong.

Finally, a simple prepend statement is easy to comment out if you need to disable the patch for some reason.

Here are the beginnings of a module for our Rails monkeypatch:

1module RenderDiscardedMonkeypatch
2end
3
4ActionView::Helpers::DateTimeSelector.prepend(
5  RenderDiscardedMonkeypatch
6)

Patch the Right Thing

If you take one thing away from this article, let it be this: don't apply a monkeypatch unless you know you're patching the right code. In most cases, it should be possible to verify programmatically that your assumptions still hold (this is Ruby after all). Here's a checklist:

1. Make sure the class or module you're trying to patch exists
2. Make sure methods exist and have the right arity
3. If the code you're patching lives in a gem, check the gem's version
4. Bail out with a helpful error message if assumptions don't hold

Right off the bat, our patch code has made a pretty important assumption. It assumes a constant called ActionView::Helpers::DateTimeSelector exists and is a class or module.

Check Class/Module

Let's ensure that constant exists before trying to patch it:

1module RenderDiscardedMonkeypatch
2end
3
4const = begin
5  Kernel.const_get('ActionView::Helpers::DateTimeSelector')
6rescue NameError
7end
8
9if const
10  const.prepend(RenderDiscardedMonkeypatch)
11end

Great, but now we've leaked a local variable (const) into the global scope. Let's fix that:

1module RenderDiscardedMonkeypatch
2  def self.apply_patch
3    const = begin
4      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
5    rescue NameError
6    end
7
8    if const
9      const.prepend(self)
10    end
11  end
12end
13
14RenderDiscardedMonkeypatch.apply_patch

Check Methods

Next, let's introduce the patched build_hidden method. Let's also add a check to make sure it exists and accepts the right number of arguments (i.e. has the right arity). If those assumptions don't hold, something's probably wrong:

1module RenderDiscardedMonkeypatch
2  class << self
3    def apply_patch
4      const = find_const
5      mtd = find_method(const)
6
7      if const && mtd && mtd.arity == 2
8        const.prepend(self)
9      end
10    end
11
12    private
13
14    def find_const
15      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
16    rescue NameError
17    end
18
19    def find_method(const)
20      return unless const
21      const.instance_method(:build_hidden)
22    rescue NameError
23    end
24  end
25
26  def build_hidden(type, value)
27    ''
28  end
29end
30
31RenderDiscardedMonkeypatch.apply_patch

Check Gem Versions

Finally, let's check that we're using the right version of Rails. If Rails gets upgraded, we might need to update the patch too (or get rid of it entirely).

1module RenderDiscardedMonkeypatch
2  class << self
3    def apply_patch
4      const = find_const
5      mtd = find_method(const)
6
7      if const && mtd && mtd.arity == 2 && rails_version_ok?
8        const.prepend(self)
9      end
10    end
11
12    private
13
14    def find_const
15      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
16    rescue NameError
17    end
18
19    def find_method(const)
20      return unless const
21      const.instance_method(:build_hidden)
22    rescue NameError
23    end
24
25    def rails_version_ok?
26      Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
27    end
28  end
29
30  def build_hidden(type, value)
31    ''
32  end
33end
34
35RenderDiscardedMonkeypatch.apply_patch

Bail Out Helpfully

If your verification code uncovers a discrepancy between expectations and reality, it's a good idea to raise an error or at least print a helpful warning message. The idea here is to alert you and your co-workers when something seems amiss.

Here's how we might modify our Rails patch:

1module RenderDiscardedMonkeypatch
2  class << self
3    def apply_patch
4      const = find_const
5      mtd = find_method(const)
6
7      unless const && mtd && mtd.arity == 2
8        raise "Could not find class or method when patching "\
9          "ActionView's date_select helper. Please investigate."
10      end
11
12      unless rails_version_ok?
13        puts "WARNING: It looks like Rails has been upgraded since "\
14          "ActionView's date_select helper was monkeypatched in "\
15          "#{__FILE__}. Please reevaluate the patch."
16      end
17
18      const.prepend(self)
19    end
20
21    private
22
23    def find_const
24      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
25    rescue NameError
26    end
27
28    def find_method(const)
29      return unless const
30      const.instance_method(:build_hidden)
31    rescue NameError
32    end
33
34    def rails_version_ok?
35      Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
36    end
37  end
38
39  def build_hidden(type, value)
40    ''
41  end
42end
43
44RenderDiscardedMonkeypatch.apply_patch

Limit Surface Area

While it may seem perfectly innocuous to define helper methods in a monkeypatch, remember that any methods defined via Module#prepend will override existing ones through the magic of inheritance. While it might seem as though a host class or module doesn't define a particular method, it's difficult to know for sure. For this reason, I try to only define methods I intend to patch.

Note that this also applies to methods defined in the object's singleton class, i.e. methods defined inside class << self.

Here's how to modify our Rails patch to only replace the one #build_hidden method:

1module RenderDiscardedMonkeypatch
2  class << self
3    def apply_patch
4      const = find_const
5      mtd = find_method(const)
6
7      unless const && mtd && mtd.arity == 2
8        raise "Could not find class or method when patching"\
9          "ActionView's date_select helper. Please investigate."
10      end
11
12      unless rails_version_ok?
13        puts "WARNING: It looks like Rails has been upgraded since"\
14          "ActionView's date_selet helper was monkeypatched in "\
15          "#{__FILE__}. Please reevaluate the patch."
16      end
17
18      const.prepend(InstanceMethods)
19    end
20
21    private
22
23    def find_const
24      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
25    rescue NameError
26    end
27
28    def find_method(const)
29      return unless const
30      const.instance_method(:build_hidden)
31    rescue NameError
32    end
33
34    def rails_version_ok?
35      Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
36    end
37  end
38
39  module InstanceMethods
40    def build_hidden(type, value)
41      ''
42    end
43  end
44end
45
46RenderDiscardedMonkeypatch.apply_patch

Give Yourself Escape Hatches

When possible, I like to make my monkeypatch's functionality opt-in. That's only really an option if you have control over where the patched code is invoked. In the case of our Rails patch, it's doable via the @options hash in DateTimeSelector:

1module RenderDiscardedMonkeypatch
2  class << self
3    def apply_patch
4      const = find_const
5      mtd = find_method(const)
6
7      unless const && mtd && mtd.arity == 2
8        raise "Could not find class or method when patching"\
9          "ActionView's date_select helper. Please investigate."
10      end
11
12      unless rails_version_ok?
13        puts "WARNING: It looks like Rails has been upgraded since"\
14          "ActionView's date_selet helper was monkeypatched in "\
15          "#{__FILE__}. Please reevaluate the patch."
16      end
17
18      const.prepend(InstanceMethods)
19    end
20
21    private
22
23    def find_const
24      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
25    rescue NameError
26    end
27
28    def find_method(const)
29      return unless const
30      const.instance_method(:build_hidden)
31    rescue NameError
32    end
33
34    def rails_version_ok?
35      Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
36    end
37  end
38
39  module InstanceMethods
40    def build_hidden(type, value)
41      if @options.fetch(:render_discarded, true)
42        super
43      else
44        ''
45      end
46    end
47  end
48end
49
50RenderDiscardedMonkeypatch.apply_patch

Nice! Now callers can opt-in by calling the date_select helper with the new option. No other codepaths are affected:

1date_select(@user, :date_of_birth, {
2  order: [:month, :day],
3  render_discarded: false
4})

Over-Communicate

The last piece of advice I have for you is perhaps the most important — communicating what your patch does and when it's time to re-examine it. Your goal with monkeypatches should always be to eventually remove the patch altogether. To that end, a responsible monkeypatch includes comments that:

• Describe what the patch does
• Explain why the patch is necessary
• Outline the assumptions the patch makes
• Specify a date in the future when your team should reconsider alternative solutions, like pulling in an updated gem
• Include links to relevant pull requests, blog posts, StackOverflow answers, etc.

You might even print a warning or fail a test on a predetermined date to urge the team to reconfirm the patch's assumptions and consider whether or not it's still necessary.

Here's the final version of our Rails date_select patch, complete with comments and a date check:

1# ActionView's date_select helper provides the option to "discard" certain
2# fields. Discarded fields are (confusingly) still rendered to the page
3# using hidden inputs, i.e. <input type="hidden" />. This patch adds an
4# additional option to the date_select helper that allows the caller to
5# skip rendering the chosen fields altogether. For example, to render all
6# but the year field, you might have this in one of your views:
7#
8# date_select(:date_of_birth, order: [:month, :day])
9#
10# or, equivalently:
11#
12# date_select(:date_of_birth, discard_year: true)
13#
14# To avoid rendering the year field altogether, set :render_discarded to
15# false:
16#
17# date_select(:date_of_birth, discard_year: true, render_discarded: false)
18#
19# This patch assumes the #build_hidden method exists on
20# ActionView::Helpers::DateTimeSelector and accepts two arguments.
21#
22module RenderDiscardedMonkeypatch
23  class << self
24    EXPIRATION_DATE = Date.new(2021, 8, 15)
25
26    def apply_patch
27      if Date.today > EXPIRATION_DATE
28        puts "WARNING: Please re-evaluate whether or not the ActionView "\
29          "date_select patch present in #{__FILE__} is still necessary."
30      end
31
32      const = find_const
33      mtd = find_method(const)
34
35      # make sure the class we want to patch exists;
36      # make sure the #build_hidden method exists and accepts exactly
37      # two arguments
38      unless const && mtd && mtd.arity == 2
39        raise "Could not find class or method when patching "\
40          "ActionView's date_select helper. Please investigate."
41      end
42
43      # if rails has been upgraded, make sure this patch is still
44      # necessary
45      unless rails_version_ok?
46        puts "WARNING: It looks like Rails has been upgraded since "\
47          "ActionView's date_select helper was monkeypatched in "\
48          "#{__FILE__}. Please re-evaluate the patch."
49      end
50
51      # actually apply the patch
52      const.prepend(InstanceMethods)
53    end
54
55    private
56
57    def find_const
58      Kernel.const_get('ActionView::Helpers::DateTimeSelector')
59    rescue NameError
60      # return nil if the constant doesn't exist
61    end
62
63    def find_method(const)
64      return unless const
65      const.instance_method(:build_hidden)
66    rescue NameError
67      # return nil if the method doesn't exist
68    end
69
70    def rails_version_ok?
71      Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
72    end
73  end
74
75  module InstanceMethods
76    # :render_discarded is an additional option you can pass to the
77    # date_select helper in your views. Use it to avoid rendering
78    # "discarded" fields, i.e. fields marked as discarded or simply
79    # not included in date_select's :order array. For example,
80    # specifying order: [:day, :month] will cause the helper to
81    # "discard" the :year field. Discarding a field renders it as a
82    # hidden input. Set :render_discarded to false to avoid rendering
83    # it altogether.
84    def build_hidden(type, value)
85      if @options.fetch(:render_discarded, true)
86        super
87      else
88        ''
89      end
90    end
91  end
92end
93
94RenderDiscardedMonkeypatch.apply_patch

Conclusion

I totally get that some of the suggestions I've outlined above might seem like overkill. Our Rails patch contains way more defensive verification code than actual patch code!

Think of all that extra code as a sheath for your broadsword. It's a lot easier to avoid getting cut if it's enveloped in a layer of protection.

What really matters, though, is that I feel confident deploying responsible monkeypatches into production. Irresponsible ones are just time bombs waiting to cost you or your company time, money, and developer health.

P.S. If you'd like to read Ruby Magic posts as soon as they get off the press, subscribe to our Ruby Magic newsletter and never miss a single post!