DEV Community: Martin Streicher

Squash Your Ruby and Rails Bugs Faster

Martin Streicher — Thu, 05 Sep 2024 11:00:00 +0000

A bug in software can be disruptive, elusive, maddening, and invasive. Indeed, a developer often needs the tenacity of Edison to find and fix an issue.

But grit isn't the only asset a developer requires. One also needs information to debug code: What are the symptoms and effects of the issue? What is its frequency? Pervasiveness? Provenance? The evidence and artifacts of a bug — a core dump, stack trace, log, or test case — are invaluable.

Let's explore a few techniques and tools readily available to Ruby and Rails developers for gathering and investigating evidence of an issue. Data can't supplant tenacity, but it can help to ease your efforts (and spare you your sleep).

Use Environment Variables to Tune Your Tools in Rails

Rails provides some excellent tools to peer into a running application, including a configurable Logger to capture diagnostics of its own and any that you'd like to add. Rails also provides a verbose query log to pinpoint the origin of database queries and a verbose enqueue log to illuminate where background jobs are queued. The latter two logs are enabled by default in the development environment; you can enable both in other environments with two statements.

##
# In any initializer... enable the verbose query log to see the file
# name and line number of the code initiating each query
ActiveRecord.verbose_query_logs = true

##
# In config/application.rb or any environment initializer, enable the
# queueing log to find where each job is enqueued
config.active_job.verbose_enqueue_logs = true

A lesser-known log option available since Rails 7 annotates each SQL query with comments. If you add the following to config/application.rb or any environment file:

##
# Add to config/application.rb or any environment initializer file
config.active_record.query_log_tags_enabled = true

Your query log is automatically amended with the application name, controller name, action name, or background job name. The following sample output comes directly from Rails's debugging guide:

Article Load (0.2ms)  SELECT "articles".* FROM "articles"
/*application='Blog',controller='articles',action='index'*/

Article Update (0.3ms)  UPDATE "articles" SET "title" = ?, "updated_at" = ? WHERE "posts"."id" = ?
/*application='Blog',job='ImproveTitleJob'*/
[["title", "Improved Rails debugging guide"], ["updated_at", "2022-10-16 20:25:40.091371"], ["id", 1]]

You likely do not want to enable all these features in production. Log generation can be costly in terms of memory and time (finite resources for an application under load).

However, there are exceptions. You may want to briefly enable an on-demand feature, especially when debugging in development and test modes. Rather than alter code (and perhaps redeploy) to enable or disable a diagnostic, use environment variables to control state. In some environments, such as Heroku, changing the setting of an environment variable does not mandate a new deployment.

For example, you can define a set of variables to control logging and verbosity.

Variable Name	Purpose	Values
`COMMENTED_QUERY_LOG`	Enable comments in query log	Non-blank value enables feature
`LOG_ALL`	Enable all logging features	Non-blank value enables feature
`LOG_LEVEL`	Control the threshold for log messages	`debug`, `info`, `warn`, `error`, `fatal`, `unknown` (from most verbose to least verbose order)
`VERBOSE_ENQUEUE_LOG`	Display where jobs are queued	Non-blank value enables feature
`VERBOSE_QUERY_LOG`	Show the origin of each Active Record query	Non-blank value enables feature

For convenience, create a small class to query configuration settings.

##
# Put this in a file such as config/initializers/env_configuration.rb
class EnvironmentConfiguration
  def self.enabled?(envvar)
    Rails.env.development? ||
      ENV.fetch('LOG_ALL', nil).present? ||
      ENV.fetch(envvar.to_s, nil).present?
  end
end

Now use the variables and the code to set logging features in config/application.rb:

##
# Centralize configuration of all logging features in config/application.rb
#
module MyApplication
  class Application < Rails::Application
    # . . .
    ActiveRecord.verbose_query_logs             = EnvironmentConfiguration.enabled?('VERBOSE_QUERY_LOG')
    config.active_job.verbose_enqueue_logs      = EnvironmentConfiguration.enabled?('VERBOSE_ENQUEUE_LOG')
    config.active_record.query_log_tags_enabled = EnvironmentConfiguration.enabled?('COMMENTED_QUERY_LOG')
    config.log_level = (ENV.fetch('LOG_LEVEL', nil).presence || 'info').to_sym
  end
end

Use your shell, a dotenv file, your continuous integration, or hosting and deployment platform to set each option. You can also use a feature on demand. Simply start the application with the environment variable defined on the command line.

LOG_ALL=on LOG_LEVEL=debug bundle exec rails s

Tune Puma for Development

Building on the previous section, let's look at how to use environment variables to tailor your Puma configuration for debugging in the development environment.

Typically, Puma is configured to maximize throughput in production, running multiple workers and many threads per worker. In development, you want the opposite: one worker, one thread, and a very long timeout to allow for interactive debugging. Each of those is a parameter you can tune.

Alter config/puma.rb to reflect the following code.

##
# Control thread count with environment variables.
# Each environment setting, if set, is always a string. Use `Integer` to
# convert the string to an integer value.
#
max_threads_count = Integer ENV.fetch('PUMA_MAX_THREADS', 5)
min_threads_count = Integer ENV.fetch('PUMA_MIN_THREADS, max_threads_count)
threads min_threads_count, max_threads_count

##
# Specify the duration Puma waits before terminating a worker.
# The default is 30 seconds.
#
worker_timeout Integer ENV.fetch('PUMA_WORKER_TIMEOUT', 30)

##
# Set the number of workers
worker_count = Integer ENV.fetch('PUMA_WEB_CONCURRENCY, 2)
workers worker_count
preload_app! if worker_count.positive?

You can now configure the three environment variables to control Puma in each environment. In development, set the values to optimize for interactive debugging.

export PUMA_MAX_THREADS=1
export PUMA_WORKERS=0
export PUMA_WEB_CONCURRENCY=0
export PUMA_WORKER_TIMEOUT=3600

If you want to validate your Puma settings, set the environment variable PUMA_LOG_CONFIG=true and start your application. Puma emits its active configuration on startup.

=> Booting Puma
=> Rails 6.1.7.7 application starting in development
=> Run `bin/rails server --help` for more startup options
Configuration:
. . .
- environment: development
- max_threads: 5
- min_threads: 5
- worker_timeout: 3600
- workers: 0

Coincidentally, the default Puma configuration in the most recent Rails release is similar to what's shown here (thanks to Nate Matykiewicz for the tip).

Run Background Jobs Inline

A Rails application of any complexity typically leverages background jobs to run compute-intensive and (relatively) long-running tasks. Background jobs run asynchronously, disconnected from the request/response cycle. Ideal candidates for "out of band" processing include generating reports, sending emails, and interacting with third-party APIs. But the asynchronous nature of jobs also complicates debugging.

To simplify troubleshooting, run jobs immediately in your local development and test environments. In immediate mode, jobs are not queued, but instead execute instantaneously. Running in the "foreground", you can set breakpoints and inspect state interactively.

Let's look at an example using Delayed Job, a popular and easy-to-manage queueing backend for Active Job. Delayed Job provides a setting to enable queueing. By default, the setting is true and jobs are queued as per usual. However, if set to false, jobs run immediately.

Add the following code to your application in config/initializers/delayed_job.rb:

Delayed::Worker.delay_jobs = ENV.fetch('DELAYED_JOBS_DISABLE_JOB_QUEUES', false).blank?

If DELAYED_JOBS_DISABLE_JOB_QUEUES is set to any value, queueing is disabled. If the environment variable is blank or not defined, queueing is enabled.

Next, in your shell, on the command line, or in your dot files, set
DELAYED_JOBS_DISABLE_JOB_QUEUES as needed.

# Set the variable in the current shell
export DELAYED_JOBS_DISABLE_JOB_QUEUES=true

# Set the variable only for the current command
DELAYED_JOBS_DISABLE_JOB_QUEUES=true rails s

# In .env.development, .env.local, and/or .env.test, add the line...
DELAYED_JOBS_DISABLE_JOB_QUEUES=true

Set the environment variable to nothing or delete the environment variable to restore queueing.

# Set the variable to blank
export DELAYED_JOBS_DISABLE_JOB_QUEUES=

# Remove the variable from the environment
unset DELAYED_JOBS_DISABLE_JOB_QUEUES

There are no rules for naming environment variables. Choose names meaningful to you. One helpful convention to categorize variables is to add a package name as a prefix, such as PUMA_ and DELAYED_JOB_. The former indicates variables affecting Puma; the latter connotes variables used by Delayed Job.

Peer Into Network Calls

Like background jobs, Rails applications can also consume application
programming interfaces (APIs). APIs provide access to external services, such as GraphQL databases, e-commerce transactions, and public data sources.

Here's another example to conditionally emit HTTP requests and responses from the Net::HTTP library. If the environment variable DEBUG_HTTP is set to any non-blank value, the outgoing request and inbound responses are printed to STDOUT.

def construct_uri(hostname:, path:, port:, params: {}, protocol: 'https')
  target =
    Addressable::URI.new.tap do |uri|
      uri.hostname     = hostname
      uri.path         = path
      uri.port         = port
      uri.query_values = params
      uri.scheme       = protocol
    end

  URI.parse target
end

def debug?
  ENV.fetch['DEBUG_HTTP'].present?
end

def request
  uri = construct_uri(...)

  Net::HTTP.new(uri.host, uri.port).tap do |http|
    http.set_debug_output($stdout) if debug?
    http.use_ssl = uri.scheme == "https"
  end
end

To see the network activity, simply start the application with
the environment variable defined on the command line.

DEBUG_HTTP=on bundle exec rails s

The debug? method provides some abstraction from the actual flag implementation. It, and the rest of this code, can form a base class for all your network requests, as shown in this gist taken from production code.

Add Ruby Gems to Your Toolbox

The universe of Ruby gems is vast: it's impossible to cover all the great gems available for debugging. Instead, let's look at a few tools you can add today for an instant boost. You'll likely add each of these to all your projects.

awesome_print and table_print create rich, readable inspections of Ruby data structures, including Active Record models. You can use either gem in code or from the console.

Here is an example of a model emitted by awesome_print in the console:

  > ap User.find_by(email: 'george@bigbrother.gov')
  #<User:0x00000001163482f0> {
         :account_balance => 0.0,
            :confirmed_at => Mon, 11 Mar 2024 12:29:30.000000000 EDT -04:00,
              :created_at => Mon, 11 Mar 2024 12:29:30.000000000 EDT -04:00,
                   :email => "george@bigbrother.gov",
      :encrypted_password => "992c45d528f9b445de3d6653e14d3e6165171944",
              :first_name => "George",
               :last_name => "Orwell",
           :sign_in_count => 0,
                   :state => "active"
  }

Instead of p, use ap to show the enhanced output. awesome_print lists attributes in alphabetical order, one attribute per line, among other niceties.

better_errors replaces the standard Rails error page with an enhanced stack backtrace, parameter list, and an interactive console where you can probe the stack frame and variables at the scene of the exception. You can also tie source code links to your favorite editor. Here is code to tie better_errors to Visual Studio Code:

  if Rails.env.development?
  BetterErrors.editor =
    if (ENV['BETTER_ERRORS_EDITOR'].presence || ENV['EDITOR']) =~ /vscode/i
      proc { |file, line| "vscode://file#{file}:#{line}" }
    else
      :macvim
    end
  end

Run export BETTER_ERRORS_EDITOR=vscode in your shell and restart the Rails server. Now links to files open automatically in Visual Studio.

Keep the faker and factory_bot gems (or their alternatives) in both the testing and development groups in Gemfile. Both are invaluable if you need to generate data quickly in the console.

  group :development, :test do
    # other gems
    # ...
    gem 'factory_bot'
    gem 'faker'
  end

One more idea: If you use AppSignal as your application monitoring tool, it has features to interpret your logs and pinpoint the source of errors. See Debugging in Ruby with AppSignal for more details.

Debugging is a Skill

Debugging code is something of an art, and like any creative endeavor, the more practice you have, the better you become.

Debug while pairing with another developer, especially an experienced developer. If your partner is willing, think out loud together and exchange hunches and insights.

Go forth and hack!

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!

An Introduction to Nix for Ruby Developers

Martin Streicher — Wed, 21 Aug 2024 13:52:08 +0000

A predictable, stable environment (in terms of your operating system, system libraries, build tools, and programming libraries) is essential to each development step: from onboarding, to collaboration, continuous integration, quality assurance, and deployment. Deviation can cause one-off, intermittent, and even catastrophic failures.

However, consistency can be elusive, even with the best intentions, best practices, and tools in place, because:

Developer machines are easily polluted with clashing libraries and binaries.
Programming libraries — Ruby's gems or Python's eggs, for example — are regularly updated on unadvertised and unpredictable schedules.
Docker images can be removed from public repositories without notice.
Continuous integration providers change internals without forewarning or ex post facto notice.

Nix aims to solve some of these issues. Specifically, it is designed to reproduce packages and environments verbatim. Given a set of inputs, it generates the same output every time.

Let's explore how Nix can reproduce an environment for Ruby and Rails
development, including a version of Ruby, a collection of gems, a PostgreSQL database, and a Redis cache.

An Overview of Nix

Nix is an entire universe of software. It runs on Linux and macOS, on both Apple Silicon and Intel processors, and has several components:

The Nix Programming Language is a declarative, domain-specific, functional language dedicated to system composition. Portions of the language manipulate Nix directly, while others provide typical programming constructs like flow control and variables.
Nix Packages is an expansive repository of software, from awk to zsh. At the time of writing, the repository contains more than 100,000 entries, each usable with Nix. Each package in the Nix archive explicitly documents all its dependencies down to a specific commit. Further, the nixpkgs archive is itself versioned, providing even greater control over package provenance.
nix-shell provides a virtual, sacrosanct environment contained in a shell. Given a Nix description of a system — a derivation in Nix parlance — you can compose and boot a system in a walled garden isolated from all other virtual and physical systems. For example, you can download, install, build, and run an independent instance of Ruby with nix-shell.
The Nix Store persists immutable data (such as software packages) and all dependencies. On some systems, the Nix Store is the local file system; however, it can also be retained on Amazon S3 and even a remote SSH server.
NixOS is an entire Linux distribution configured entirely by the Nix language and composed from versions in Nixpkgs.

Nix is expansive and each component warrants deep exploration. This
introduction focuses on the nix-shell and Nix Packages and presents
just enough of the Nix programming language to boot a Rails application. Tony Finn's Nix from First Principles
provides another take on Nix.

Nix Versus Docker

Docker and Nix are both capable of building environments. However, Nix provides consistency everywhere, including build tools and source packages.

Docker is not a package manager. While you can connect and coordinate
containers using Docker Compose, you cannot use Docker to combine containers into a new container.

It's trivial with Nix to combine disparate Ruby and PostgreSQL derivations into a new environment.

If a Docker image changes without notice, the output of docker build changes too. Pinning a version obviously helps, but if a
Docker image is deleted or an image's repository goes offline, a
Docker build fails without recourse.

Each package and version stored by Nix can have a unique ID akin to a git SHA. You can think of a complete Nix derivation as a manifest of tens or hundreds of SHAs. A change in any one SHA is detectable and two derivations will not be the same if a single entity has changed.

Get Started with Nix

Let's dive into Nix.

To install Nix natively on Apple MacOS, open the Terminal application in Applications/Utilities and run the following command at the shell prompt:

# Shell command to download and install Nix on your system
curl --proto '=https' --tlsv1.2 -sSf \
  -L https://install.determinate.systems/nix \
  | sh -s -- install

Enter the password for the root user of your system when prompted.
(If you are a Mac administrator, you can enter your password too.) You need privileged access as the install creates a new storage volume specifically for Nix and tweaks several system settings, such as excluding the Nix store from Time Machine backups.

The installer summarizes all the modifications it plans to perform and prompts you to proceed. Enter Yes.

# Nix output
Nix install plan (v0.18.0)
Planner: macos (with default settings)

Planned actions:
* Create an encrypted APFS volume `Nix Store` for Nix on `disk1` and add it to `/etc/fstab` mounting on `/nix`
* Fetch `https://releases.nixos.org/nix/nix-2.21.2/nix-2.21.2-x86_64-darwin.tar.xz` to `/nix/temp-install-dir`
* Create a directory tree in `/nix`
* Move the downloaded Nix into `/nix`
* Create build users (UID 301-332) and group (GID 30000)
* Configure Time Machine exclusions
* Setup the default Nix profile
* Place the Nix configuration in `/etc/nix/nix.conf`
* Configure the shell profiles
* Configuring zsh to support using Nix in non-interactive shells
* Create a `launchctl` plist to put Nix into your PATH
* Configure Nix daemon related settings with launchctl
* Remove directory `/nix/temp-install-dir`

Proceed? ([Y]es/[n]o/[e]xplain): Y

 INFO Step: Create an encrypted APFS volume `Nix Store` for Nix on `disk1` and add it to `/etc/fstab` mounting on `/nix`
 INFO Step: Provision Nix
 INFO Step: Create build users (UID 301-332) and group (GID 30000)
 INFO Step: Configure Time Machine exclusions
 INFO Step: Configure Nix
 INFO Step: Configuring zsh to support using Nix in non-interactive shells
 INFO Step: Create a `launchctl` plist to put Nix into your PATH
 INFO Step: Configure Nix daemon related settings with launchctl
 INFO Step: Remove directory `/nix/temp-install-dir`

Nix was installed successfully! To get started using Nix, open a new shell or run `. /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh`

The installation takes only a moment or two to finish.

You can easily test it when it's done by running the following sequence of commands in your current shell.

# Load Nix into the current shell environment
source /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh

# Display the free space found on the new volume at /nix
df /nix

# Filesystem   512-blocks      Used Available Capacity iused      ifree %iused  Mounted on
# /dev/disk1s7  976490576    799416 228759728     1%   73715 1143798640    0%   /nix

# Use Nix to install and run the `hello` command
nix run 'nixpkgs#hello'
# Produces `Hello, World!'

The nix run command is something akin to magic. To run the hello utility, Nix:

Downloads all the packages required to build hello, including tools such as make, gcc, and tar. (On the machine used to develop this article, an i9 iMac running MacOS Sonoma, Nix downloaded more than 400 prerequisite packages into /nix/store.)
Downloads the most recent version of hello (as no version number was specified).
Builds and executes the utility, producing Hello, World!.
Terminates and returns to the original shell.

If you run the same command — nix run 'nixpkgs#hello' — again, Nix executes hello immediately, as the assets required for the utility are cached and readily accessible.

You can use Nix to run almost any utility on-demand. Here is another example.

# Launch the `fish` shell (see https://fishshell.com)
nix run `nixpkgs#fish`
martin@iMac ~/p/o/a/martin (ruby-on-nix)>

The penultimate line of the output above is the default fish prompt, showing a user name, machine name, an abbreviated current working directory name, and the current git branch, if any. Press Control-D to exit the shell.

If you're following along, try this: Launch fish via Nix and enter the command which hello. The result should look like this:

strike@iMac ~/p/o/a/martin (ruby-on-nix)> which hello
strike@iMac ~/p/o/a/martin (ruby-on-nix) [1]>

which hello fails in the current environment. ([1] is the return value of the previous command, not the output of the previous command. Shell utilities return non-zero values on failure.) Where is the hello from the previous install? It's in its own encapsulated derivation, completely isolated from the one created for fish.

A one-off Nix derivation such as the one above has its uses, but a Nix derivation is not limited to a sole utility. A derivation may contain any number of packages. Better yet, a derivation can be declared, shared, and re-instantiated in identical form on any machine.

Nix for Ruby Development

Let's create a Nix derivation for Rails development. The derivation must have:

A version of Ruby, such as 3.2.0 (the latest version of Ruby available via Nix at the time of writing). Each Ruby package includes gem and irb.
A database service to persist information. Here, let's use PostgreSQL Version 15.
A key store for caching data, partials, and views. Redis is quite capable.
Tools for JavaScript and asset compilation.

Of course, a plenary Rails environment also needs the rails gem and many others. Ideally, a Nix derivation for Rails development also automatically bundles necessary gems, producing a standalone environment ready for development.

A Nix Derivation for Ruby Development

The code below is a nascent, but working, Nix derivation for Rails development. A Nix derivation is like a Dockerfile or a blueprint to build a working environment from scratch.

let
  nixpkgs =
    import (builtins.fetchTarball {
      url = https://github.com/NixOS/nixpkgs/archive/ee4a6e0f566fe5ec79968c57a9c2c3c25f2cf41d.tar.gz;
    }) { };

  targetRuby = nixpkgs.ruby_3_2;

  myBundler = nixpkgs.bundler.override {
    ruby = targetRuby;
  };

  gems =
    nixpkgs.bundlerEnv {
      inherit (nixpkgs) ruby_3_2;

      name     = "rails-gems";
      bundler  = myBundler;
      gemfile  = ./Gemfile;
      lockfile = ./Gemfile.lock;
      gemset   = ./gemset.nix;
    };

in
  nixpkgs.mkShell {
    buildInputs = [
      targetRuby
      gems
      gems.wrappedRuby
      nixpkgs.bundler
      nixpkgs.bundix
      nixpkgs.nodejs
      nixpkgs.yarn
      nixpkgs.postgresql
    ];
  }

The sample derivation has two sections. The let section defines settings, while the in portion controls the build and enumerates the packages to construct and install in the derivation.

Before discussing how to use the derivation, some commentary:

The setting nixpkgs requires a specific version of the Nix archive. Like a git repository, each iteration of the Nix packages archive is represented by a unique SHA reflecting the state of its contents. If the contents of the archive change, such as by incorporating a new version of Ruby, the SHA changes in tandem. Similar to referencing specific commits in git, you can lock your derivation to a specific iteration of the archive. The particular archive referred to here, ee4a6e0, contained a bug fix required to build the example derivation.
The setting targetRuby specifies a Ruby version. Here, the derivation uses the latest version of Ruby 3.2 available in the archive.
The setting myBundler customizes the Nix build to use the same version of Ruby specified for the shell environment.
Lastly, the setting named gems configures the Nix version of bundler.

As with native bundler, the Nix bundler requires a Gemfile and a Gemfile.lock. gemset.nix is original to Nix and is a translation of Gemfile.lock to the Nix syntax.

If you want to know what versions of Ruby are available, point your browser to the Nix Packages Index and search for ruby. The search results include all the Ruby iterations available, such as ruby, ruby_3_2, and ruby_3_3, for Ruby 3.1, 3.2, and 3.3, respectively. Each package in the search result specifies the exact version number, such as 3.1.4 for the ruby package.

If you want to use a specific version of Ruby that is not named in the archive, try nixpkgs-ruby. For instance, to use Ruby 3.2.2, replace the line targetRuby = nixpkgs.ruby_3_2; in shell.nix with this code:

nixpkgs-ruby =
  import (builtins.fetchTarball {
    url = "https://github.com/bobvanderlinden/nixpkgs-ruby/archive/c1ba161adf31119cfdbb24489766a7bcd4dbe881.tar.gz";
  });

targetRuby = nixpkgs-ruby.packages.x86_64-linux."ruby-3.2.2";

Running the Nix Shell

Using the Nix derivation for Rails development proceeds much like development in any shell. The big exception: There is no need to install Ruby or attendant services beforehand. If you have Nix installed, you're ready to go.

Install Nix if necessary.
Clone a Rails project into a new directory or choose an existing codebase. cd to the directory for the project.
Copy and paste the code for the sample derivation to a new file in the project directory named shell.nix. (shell.nix is the customary name for a derivation, but the name is otherwise arbitrary.)
Generate gemset.nix to catalog the gems used within the project.

   nix \
     --extra-experimental-features nix-command \
     --extra-experimental-features flakes \
     run 'nixpkgs/nixos-unstable#bundix' -- --lock

This command runs bundix, a Nix program, to convert Gemfile.lock_into _gemset.nix. Both are gem manifests, albeit the latter expressed natively in the Nix language. For comparison, here is an entry for actioncable from gemset.nix and from Gemfile.lock.

   # From gemset.nix
   #
   actioncable = {
     dependencies = ["actionpack" "activesupport" "nio4r" "websocket-driver" "zeitwerk"];
     groups = ["default"];
     platforms = [];
     source = {
       remotes = ["https://rubygems.org"];
       sha256 = "0ifiz4nd6a34z2n8lpdgvlgwziy2g364b0xzghiqd3inji0cwqp1";
       type = "gem";
     };
     version = "7.1.3.2";
   };

   ## From Gemfile.lock
   #
   actioncable (7.1.3.2)
     actionpack (= 7.1.3.2)
     activesupport (= 7.1.3.2)
     nio4r (~> 2.0)
     websocket-driver (>= 0.6.1)
     zeitwerk (~> 2.6)

Generate and launch the derivation.

nix-shell --verbose

The --verbose option is not required, but provides good and numerous insights into how nix-shell assembles the environment.

The Downsides: Nix has Some Flaws

Nix is a rich, robust, and burgeoning option for building, reproducing, and sharing environments. Nix is also an emergent tool: its current users are early adopters.

Nix is already a workable solution for many problems, but Ruby support seems to be a work in progress. For example, at the time of writing, no official archive is available for newer versions of Ruby 3.3, and there is no guarantee the latest Nix archive contains every gem in your Gemfile. Documentation for Ruby on Nix is scattered between various GitHub repos, the official Nix website, and user forums. I am grateful to a number of intrepid Nix developers who helped me craft the sample shell.nix, including Evan Travers, Bob van der Linden, and Norbert Melzer.

Nix currently is akin to git's "porcelain": powerful but esoteric. However, much like git evolved into exoteric, user-friendly tools such as git-flow, GitHub Desktop, and Tower to become user-friendly, many developers are building abstractions, wrappers, and utilities to simplify Nix usage. Let's briefly look at a few of these tools now.

Tools to Help with Nix: `devbox`, `devenv.sh`, and `fleek`

A tool to experiment with is devbox. devbox turned a 10-year-old Macbook Pro laptop running macOS Big Sur into a development machine for a modern Rails application in a few minutes. The setup did not include automatic bundling of gems, but it did install Ruby (including bundler and gem), Redis, and PostgreSQL in an isolated and pristine shell environment. devbox eschews a bespoke programming language for configuration and uses JSON. The environment on the MacBook Pro booted from this minimal file named devbox.json:

{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.6/.schema/devbox.schema.json",
  "packages": [
    "postgresql@latest",
    "redis@latest",
    "ruby@3.2.2",
    "libsass@latest"
  ]
}

devenv.sh merits exploration too. It is something of a hybrid, with a JSON-like programming language, YAML configuration, and Docker-like composition of services.

fleek is another Nix-based tool to craft and share configurations for development machines. It also avoids the Nix programming language and instead provides Homebrew-like commands to build an environment.

Wrapping Up

In this post, we've seen how Nix can help reproduce a stable environment for Ruby and Rails applications.

While it has some flaws, Nix and the myriad offshoots in development are worth watching.

Go forth and hack!

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!

Five Things to Avoid in Ruby

Martin Streicher — Wed, 05 Jun 2024 12:25:03 +0000

As a contract software developer, I am exposed to oodles of Ruby code. Some code is readable, some obfuscated. Some code eschews whitespace, as if carriage returns were a scarce natural resource, while other code resembles a living room fashioned by Vincent Van Duysen. Code, like the people who author it, varies.

Yet, it's ideal to minimize variation. Time and effort are best spent on novel problems.

In this post, we'll explore five faux pas often seen in Ruby code and learn how to turn these idiosyncrasies into idioms.

But first, how can we minimize variance in Ruby?

Minimizing Variance in Ruby with Rubocop and Idioms

Ruby developers can gain efficiency with Rubocop, which unifies style within a single project or across many projects. Rails is a boon to uniformity, too, as it favors convention over configuration. Indeed, disparate Rails codebases are identical in places and, overall, quite similar.

Beyond tools and convention, variance is also minimized by idioms, or those "structural forms peculiar to a language". For example, Ruby syntax is a collection of explicit idioms enforced by the interpreter. Reopening a class is a Ruby idiom, too.

But not all Ruby idioms are dicta. Most Ruby idioms are best practices, shorthand, and common usages Ruby developers share informally and in practice.

Learning idioms in Ruby is like learning idioms in any second spoken (or programming) language. It takes time and practice. Yet the more adept you are at recognizing and proffering Ruby's idioms, the better your code will be.

What to Avoid in Ruby

Now, let's move on to looking at five things to avoid in Ruby:

Verbosity
Long expressions to detect nil
Overuse of self
Collecting results in temporary variables
Sorting and filtering in memory

Verbosity

If you've delved into Ruby, you can appreciate how expressive, compact, fun, and flexible it is. Any given problem can be solved in a number of ways. For example, if/unless, case, and the ternary operator ?: all express decisions — which one you should apply depends on the problem.

However, per Ruby idiom, some if statements are better than others. For instance, the following blocks of code achieve the same result, but one is idiomatic to Ruby:

# Verbose approach

actor = nil

if response == 1
  actor = "Groucho"
elsif response == 2
  actor = "Chico"
elsif response == 3
  actor = "Harpo"
else
  actor = "Zeppo"
end

# Idiomatic approach

actor =
  if response == 1
    "Groucho"
  elsif response == 2
    "Chico"
  elsif response == 3
    "Harpo"
  else
    "Zeppo"
  end

Almost every Ruby statement and expression yields a value, including if, which returns a final code statement value and a matching condition. The version of the if statement in the second code block above leverages this behavior. If response is 2, actor is set to Chico. Assigning the result of an if statement is idiomatic to Ruby. (The same construct can be applied to case, unless, begin/end, and others.)

Another Ruby idiom is present: you need not predefine a variable used within an if statement (or while, for, and others). So, the latter code removes the line actor = nil. In Ruby, unlike other languages, the body of an if statement is not considered a separate scope.

Long Expressions to Detect `nil`

nil represents "nothing" in Ruby. It's a legitimate value and is its own class (NilClass) with methods. Like other classes, if you call a method that's not defined on nil, Ruby throws an exception akin to undefined method 'xxx' for nil:NilClass.

To avoid this exception, you must first test a variable to determine if it's nil. For example, code such as this is common in Rails applications:

if user && user.plan && user.plan.name == 'Standard'
  # ... some code for the Standard plan
end

The trouble is that such a long chain of assertions is unwieldy. Imagine having to repeat the condition user && user.plan && ... every time you have to reference a user's plan name.

Instead, use Ruby's safe navigation operator, &. It is shorthand for the logic "If a method is called on nil, return nil; otherwise, call the method per normal." Using &. reduces the code above to the much more readable:

if user&.plan&.name == 'Standard'
  // ... some code
end

If user is nil and plan is nil, the expression user&.plan&.name is nil.

The example above assumes user and plan represent a custom structure or Rails model of some kind. You can also use the safe navigation operator if a value represents an Array or Hash.

For example, assume a_list_of_values is an Array:

a_list_of_values[index]

If the variable a_list_of_values is nil, an exception is thrown. If you expectantly try a_list_of_values&.[index], a syntax error occurs. Instead, use &. with the Array#at method.

a_list_of_values&.at(index)

Now, if a_list_of_values is nil, the result of the expression is nil.

Overuse of `self`

Ruby uses self in three substantive ways:

To define class methods
To refer to the current object
To differentiate between a local variable and a method if both have the same name

Here's an example class demonstrating all three usages.

class Rectangle
  def self.area(length, width)
    new(length, width).area
  end

  def self.volume(length, width, height)
    area(length, width) * height
  end

  def initialize(length, width, height = nil)
    self.length = length
    self.width  = width
    self.height = height
  end

  def area
    length * width
  end

  def volume
    area = 100
    self.area * height
  end

  private

  attr_reader :length, :width, :height
end

def self.area is an example of the first purpose for self, defining a class method. Given this class, the Ruby code puts Rectangle.area(10, 5) produces 50.

The code self.length = length demonstrates the second application of self: the instance variable length is set to the value of the argument length. (The attr_reader statement at the bottom defines the instance variable and provides a getter method.) Here, the statement self.length = length is functionally the same as @length = length.

The third use of self is shown in the volume method. What does puts Rectangle.volume(10, 5, 2) emit? The answer is 100. The line area = 100 sets a method-scoped, local variable named area. However, the line self.area refers to the method area. Hence, the answer is 10 * 5 * 2 = 100.

Consider one more example. What is the output if the volume method is written like this?:

 def volume
   height = 10
   self.area * height
end

The answer is 500 because both uses of height refer to the local variable, not the instance variable.

Inexperienced Rails developers make unnecessary use of self, as in:

# Class User
# first_name: String
# last_name: String
# ...

class User < ApplicationRecord
  ...
  def full_name
    "#{self.first_name} #{self.last_name}"
  end
end

Technically, this code is correct, yet using self to refer to model attributes is unnecessary. If you combine Rubocop with your development environment, Rubocop flags this issue for you to correct.

Collecting Results in Temporary Variables

A common code chore is processing lists of records. You might eliminate records due to certain criteria, map one set of values to another, or separate one set of records into multiple categories. A typical solution is to iterate over the list and accumulate a result.

For instance, consider this a solution to find all even numbers from a list of integers:

def even_numbers(list)
  even_numbers = []

  list.each do |number|
    even_numbers << number if number&.even?
  end

  return even_numbers
end

The code creates an empty list to aggregate results and then iterates over the list, ignoring nil items, and accumulating the even values. Finally, it returns the list to the caller. This code serves its purpose, but it isn't idiomatic.

A better approach is to use Ruby's Enumerable methods.

def even_numbers(list)
  list.select(&:even?) # shorthand for `.select { |v| v.even? }`
end

select is one of many Enumerable methods. Each Enumerable method iterates over a list and collects results based on a condition. Specifically, select iterates over a list and accumulates all items where a condition yields a truthy value. In the example above, even? returns true if the item is an even number. select returns a new list, leaving the original list unchanged. A variant named select! performs the same purpose, but alters (mutates) the original list.

The Enumerable methods include reject and map (also known as collect). reject collects all items from a list where a condition yields a falsey value. map returns a new list where each item in the original list is transformed by an expression.

Here's one more example Enumerable method in action. First, some non-idiomatic code:

def transform(hash)
  new_hash = {}

  hash.each_pair do |key, value|
    new_hash[key] = value ? value * 2 : nil
  end

  return new_hash
end

And now a more idiomatic approach:

def transform(hash)
  hash.transform_values { |value| value&.*(2) }
end

transform_values is another Enumerable method available for Hash. It returns a new hash with the same keys, but each associated value is transformed. Remember, even integers are objects in Ruby and have methods. value&.*(2) returns nil if value is nil, else value * 2.

Sorting and Filtering in Memory

Here's one last faux pas — this one is specific to Rails and ActiveRecord. Let's examine this code:

# class Student
# name: String
# gpa: Float
# ...
#

class Student < ApplicationRecord
  ...

  def self.top_students
    Student
      .all
      .sort_by { |score| student.gpa }
      .select { |score| student.gpa >= 90.0 }
      .reverse
  end
end

Calling Student.top_students returns all students with a GPA greater than or equal to 90.0 in ranked order, from highest to lowest. Technically, this code is correct, but it isn't very efficient in space or time because:

It must load all records from the students table into memory.
It first sorts all records and then filters based on GPA, performing unnecessary work.
It reverses the order of the list in memory.

Sorting and filtering are best performed in the database, if possible, using ActiveRecord's tools.

def self.top_students
  Student.where(gpa: 90.0..).order(gpa: :desc)
end

The shorthand 90.0.. in the where clause is a Ruby Range expressing a value between 90.0 and Float::INFINITY. If gpa is indexed in the students table, this query is likely very fast and loads only the matching records. If the student records are being fetched for display, more efficiency (in memory) can be gained via pagination (albeit at the possible expense of more queries to fetch the batches).

Wrapping Up and Next Steps

In this post, we've covered five key things to avoid in Ruby and the idioms to use instead.

I highly recommend reading the documentation for Ruby's core classes and modules, including Array, Hash, and Enumerable. The documents are a treasure trove of methods and techniques, and chances are a method exists to solve your problem at hand. Turn knowledge into practice by writing small code samples to learn how each method works.

Add Rubocop into your workflow, even your text editor. Rubocop keeps your code looking nice but can also flag idiosyncratic code. Using Rubocop is one of the best ways to learn to code the Ruby way.

Finally, read other developers' code, especially open-source Ruby projects. To peruse the code of any gem, run bundle open <gem>, where <gem> is the name of a library. If you've included a debugger in your Gemfile, you can even set breakpoints in any gem and step through the code.

Go forth and code!

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!

P.P.S. Use AppSignal for Ruby for deeper debugging insights.

DEV Community: Martin Streicher

Squash Your Ruby and Rails Bugs Faster

Use Environment Variables to Tune Your Tools in Rails

Tune Puma for Development

Run Background Jobs Inline

Peer Into Network Calls

Add Ruby Gems to Your Toolbox

Debugging is a Skill

An Introduction to Nix for Ruby Developers

An Overview of Nix

Nix Versus Docker

Get Started with Nix

Nix for Ruby Development

A Nix Derivation for Ruby Development

Running the Nix Shell

The Downsides: Nix has Some Flaws

Tools to Help with Nix: devbox, devenv.sh, and fleek

Wrapping Up

Five Things to Avoid in Ruby

Minimizing Variance in Ruby with Rubocop and Idioms

What to Avoid in Ruby

Verbosity

Long Expressions to Detect nil

Overuse of self

Collecting Results in Temporary Variables

Sorting and Filtering in Memory

Wrapping Up and Next Steps

Tools to Help with Nix: `devbox`, `devenv.sh`, and `fleek`

Long Expressions to Detect `nil`

Overuse of `self`