¶ ↑
RefrigeratorRefrigerator offers an easy way to freeze all ruby core classes and modules. It’s designed to be used in production and when testing to make sure that no code is making unexpected changes to core classes or modules at runtime.
¶ ↑
Installationgem install refrigerator
¶ ↑
Source CodeSource code is available on GitHub at github.com/jeremyevans/ruby-refrigerator
¶ ↑
Usage¶ ↑
freeze_coreAfter loading all of the code for your application, you can call the freeze_core
method to freeze all core classes:
require 'refrigerator' Refrigerator.freeze_core
This will freeze all core classes, so that modifications to them at runtime will raise exceptions.
In a rack-based application, a good place to call ‘freeze_core` is at the end of the `config.ru` file.
You can also pass an :except option to freeze_core
with an array of class names not to freeze:
Refrigerator.freeze_core(:except=>['BasicObject'])
One reason to exclude certain classes is because you know they will be modified at runtime.
¶ ↑
check_requireRefrigerator also offers a check_require
method for checking libraries for modifications to the core classes. It allows you to easily see what fails when when you try to require the library with a frozen core, and offers some options that you can use to try to get the require to not raise an exception. This allows you to see what changes the library makes to the core classes. Here’s an example of basic use:
Refrigerator.check_require('open3', :modules=>[:Open3])
The check_require
method takes the following options:
- :modules
-
Define the given module names before freezing the core (array of symbols)
- :classes
-
Define the given class names before freezing the core (array of symbols or two element arrays with class name symbol and superclass name symbol)
- :exclude
-
Exclude the given class/module names from freezing (array of strings)
- :depends
-
Any dependencies to require before freezing the core (array of strings)
Without any options, check_require
will likely raise an exception, as it freezes the core before requiring, and if the required files tries to add a class or module to the global namespace, that will fail. The :modules and :classes options exist so that you can predefine the class so that the required file will reopen the existing class instead of defining a new class.
The :depends option can be easily used to load all dependencies of the required file before freezing the core. This is also necessary in most cases, especially when using the stdlib, since many stdlib files modify the core classes in ways beyond adding modules or classes. The :exclude option is basically a last resort, where you can disable the freezing of certain core classes, if you know the required library modifies them.
Here’s an example using Sequel, a ruby database toolkit:
Refrigerator.check_require 'sequel', :depends=>%w'bigdecimal date thread time uri', :modules=>[:Sequel]
And an example using Roda, a ruby web toolkit:
Refrigerator.check_require 'roda', :depends=>%w'rack uri fileutils set tmpdir tempfile thread date time', :classes=>[:Roda]
Note that many stdlib libraries will fail check_require
unless you use the :exclude option, for example, date
:
Refrigerator.check_require 'date', :classes=>[:Date, [:DateTime, :Date]] # Fails due to Time#to_date addition Refrigerator.check_require 'date', :classes=>[:Date, [:DateTime, :Date]], :exclude=>['Time'] # => true
¶ ↑
bin/check_requirerefrigerator ships with a check_require
binary that offers access to Refrigerator.check_require
from the command line. Here’s the usage:
$ bin/check_require Usage: check_require [options] path Options: -m, --modules [Module1,Module2] define given modules under Object before freezing core classes -c [Class1,Class2/SuperclassOfClass2], --classes define given classes under Object before freezing core classes -r, --require [foo,bar/baz] require given libraries before freezing core classes -e, --exclude [Object,Array] exclude given core classes from freezing -h, -?, --help Show this message
You can use this to easily check ruby libraries for issues when requiring. For example, let’s try with open3
:
$ bin/check_require open3 Traceback (most recent call last): 4: from bin/check_require:42:in `<main>' 3: from /home/billg/ruby-refrigerator/lib/refrigerator.rb:35:in `check_require' 2: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' 1: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' /usr/local/lib/ruby/2.5/open3.rb:32:in `<top (required)>': can't modify frozen #<Class:Object> (FrozenError) $ bin/check_require -m Open3 open3
As displayed above, open3 does not modify any core classes, beyond defining the Open3
module.
Let’s try with date
:
$ bin/check_require date Traceback (most recent call last): 6: from bin/check_require:42:in `<main>' 5: from /home/billg/ruby-refrigerator/lib/refrigerator.rb:35:in `check_require' 4: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' 3: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' 2: from /usr/local/lib/ruby/2.5/date.rb:4:in `<top (required)>' 1: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require': can't modify frozen #<Class:Object> (FrozenError) $ bin/check_require -c Date,DateTime/Date date Traceback (most recent call last): 6: from bin/check_require:42:in `<main>' 5: from /home/billg/ruby-refrigerator/lib/refrigerator.rb:35:in `check_require' 4: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' 3: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' 2: from /usr/local/lib/ruby/2.5/date.rb:4:in `<top (required)>' 1: from /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require' /usr/local/lib/ruby/2.5/rubygems/core_ext/kernel_require.rb:59:in `require': can't modify frozen class (FrozenError) $ bin/check_require -c Date,DateTime/Date -e Time date
The first failure is because date
defines the Date
and DateTime
classes, so you must define those classes first, using a slash to separate DateTime from the superclass Date. Note that it still fails in that case, but it doesn’t even tell you why. It turns out the reason is that date
also adds to_date
and other methods to Time
, so you need to exclude the freezing of Time
as well.
Here are a couple more examples, using Sequel and Roda:
bin/check_require -m Sequel -r bigdecimal,date,thread,time,uri sequel bin/check_require -c Roda -r rack,uri,fileutils,set,tmpdir,tempfile,thread,date,time roda
¶ ↑
Supporting new ruby minor versionsThe list of constants that freeze_core
will freeze are stored in the module_names/*.txt files in the repository, with separate files per ruby minor version. When new ruby minor versions are released, the module_names
rake task can be run with the new ruby minor version, and it will generate the appropriate file.
¶ ↑
Skipped Classes and ModulesInternal, deprecated, and private classes and modules are not frozen by refrigerator.
¶ ↑
LicenseMIT
¶ ↑
AuthorJeremy Evans <[email protected]>