David Runger : Blog

My decorator-style memoization shard for Crystal

2026-08-23T00:00:00-05:00

I was surprised that I couldn’t find an established Crystal shard for memoization with the API I wanted. Rubyists have plenty of options, including MemoWise, Memoist, and the memoization support in dry-core. In Crystal, my searches mostly turned up snippets or code embedded in a larger framework.

So I made memoization, a small Crystal shard that lets me write this:

memoize def current_content_sha(file_or_directory : String) : String
  # Calculate and return a SHA-256 digest...
end

Each distinct argument gets its own cached result, and repeated calls reuse it.

Why I wanted a memoization shard

Memoization is an easy optimization to understand: save a method’s result and reuse it when the same arguments are passed again.

For a method without arguments, I could manage that myself with an instance variable:

def expensive_value : String
  @expensive_value ||= calculate_expensive_value
end

However, that adds state-management boilerplate to a method whose meaningful job is simply to calculate a value. It also requires more careful handling when nil or false is valid; otherwise, the calculation can run again on every call.

Arguments make manual memoization more cumbersome. Remembering current_content_sha("README.md") independently from current_content_sha("src") requires a hash keyed by the method’s arguments, plus lookup and assignment logic around the actual implementation.

One reason I enjoy Ruby and Crystal is that they strip away boilerplate and leave expressive code. Building and maintaining a cache by hand felt like a step backward. I wanted the method definition to say what it calculates, with memoize as the one clear declaration that its results should be reused.

The code I found

My path to the shard included a Crystal Forum thread about a caching decorator. Someone pointed to the memoize macro in the Lucky framework, whose syntax was almost exactly what I wanted:

memoize def somefun(a, b) : Whatever
  # ...
end

There was one important limitation: for methods with arguments, a call with different arguments replaced the previous cached value. The forum thread’s original poster described the same problem:

I’m looking to use it for dynamic programming, so I’d want to use it for all param sets, not just the latest.

I adapted Lucky’s code so that methods with arguments use a hash keyed by argument tuples, preserving results for many sets of arguments instead of only the latest one.

I was very inexperienced with Crystal macros, and getting this working was difficult and fairly bumbling. The macro has to inspect the method definition at compile time and generate a typed cache, an uncached implementation, and a public wrapper. Somewhat to my surprise, I figured it out.

The code first lived in my dotfiles. Git history tells me that I added it in August 2024 while converting a personal tool from Ruby to Crystal. In March 2025, I extracted it into the standalone memoization shard so that I could reuse it elsewhere.

Installation and use

Add the shard to shard.yml:

dependencies:
  memoization:
    github: davidrunger/memoization

Then install it and require it:

shards install

require "memoization"

Add memoize before a method definition. Both the return type and every argument type must be explicit so that the macro can construct the correctly typed cache:

class Greeting
  memoize def message(name : String) : String
    puts "Generating a greeting for #{name}"
    "Hello, #{name}!"
  end
end

greeting = Greeting.new

greeting.message("Jane")
# Prints "Generating a greeting for Jane" and returns "Hello, Jane!"

greeting.message("John")
# Prints "Generating a greeting for John" and returns "Hello, John!"

greeting.message("Jane")
# Returns the cached "Hello, Jane!" without printing anything

The cache belongs to the object instance, with a separate entry for each argument combination. The shard also supports methods without arguments, nil results, default and named arguments, private methods, and method names ending in ? or !.

Where I use it

I use the shard throughout the Crystal tools in my dotfiles. For example, one method calculates a SHA-256 digest for a file or directory. Calls for the same path reuse that work while other paths are cached independently.

I also use it in Skedjewel, a scheduler for Sidekiq jobs. Skedjewel memoizes parsed schedule values and its lock manager. I use Skedjewel to run scheduled jobs for the david_runger Rails app, so this is “production” use in the sense that it runs my hobby app, not evidence from a large commercial deployment.

Limitations

This is a small library that solves the problem I have, not a comprehensive caching system. In particular:

Cached entries have no expiration, eviction, or reset mechanism.
A method called with an unbounded number of distinct argument combinations will grow its cache without bound.
The shard does not promise thread safety.
It memoizes instance methods, with caches scoped to individual object instances.

A more sophisticated implementation might address these limitations. I haven’t needed those features, so I have kept the shard simple.

If that tradeoff fits your program, you can find the source, installation instructions, and complete examples at github.com/davidrunger/memoization.

Easy PostgreSQL major version upgrades for a Docker Compose hobby app

2026-01-22T00:00:00-06:00

For a small hobby app, a logical dump and restore is a simple, low-risk way to upgrade PostgreSQL. The old database remains untouched until you delete its Docker volume, making rollback straightforward.

This is the runbook that I use for my Docker Compose app. I paste each command into an SSH session individually and check its output before continuing.

Caveats

This approach requires downtime and assumes that the database is small enough to dump and restore quickly (mine is about 122 MB). For a large database or strict uptime requirements, consider pg_upgrade or a replication-based cutover instead.

The examples also assume that:

PostgreSQL runs through Docker Compose.
Its data lives in a named Docker volume.
You can SSH into the server and run commands interactively.

Adapt the service, database, user, and volume names to your app.

Before the upgrade

Confirm that your application supports the new PostgreSQL version. Review its release notes for relevant breaking changes and run your test suite against it.

Prepare a pull request that updates the PostgreSQL image, volume name, and, if necessary, volume mount path. During the upgrade, you will apply those changes temporarily, revert them, and then merge the pull request to make them permanent.

Upgrade from PostgreSQL 17 to 18

1. Record the current state

git status
git show

docker compose exec postgres psql -U app_user app_production -c 'SELECT VERSION();'

docker compose exec postgres psql -U app_user app_production -c \
  'SELECT COUNT(*) FROM users; SELECT * FROM orders ORDER BY created_at DESC LIMIT 1;'

The query results provide a baseline for verification after the restore.

2. Create an off-server backup

If you have a separate backup pipeline, run it now:

bin/backup-to-s3.sh

This backup provides another recovery path if the server itself fails during the upgrade.

3. Update the Docker configuration

Update docker-compose.yml so that:

The image changes from postgres:17.x to postgres:18.x.
The volume name changes from postgres-data-v17 to postgres-data-v18.
The volume mount path changes if required by the new image.

A new volume name gives the new PostgreSQL version an empty data directory and preserves the old database for rollback.

For example:

sed -i'' 's/postgres:17.6-alpine/postgres:18.0-alpine/g' docker-compose.yml
sed -i'' 's/postgres-data-v17:/postgres-data-v18:/g' docker-compose.yml
sed -i'' 's|/var/lib/postgresql/data|/var/lib/postgresql|g' docker-compose.yml

Then review the changes:

git status
git diff

Only the image tag, volume name, and mount path should have changed.

PostgreSQL 18 image note (updated July 2026): The official image now sets PGDATA to /var/lib/postgresql/18/docker and expects the volume to be mounted at /var/lib/postgresql. Earlier PostgreSQL images used /var/lib/postgresql/data. This change reached the PostgreSQL 18 image through several revisions, so my upgrades from 17 to 18.0 and 18.0 to 18.1 still worked with the old mount path, while 18.1 to 18.4 required another dump and restore. Check the official image documentation before any image update, including a minor-version update.

4. Pull the new image

Pull it before the downtime begins:

docker compose pull postgres
docker images postgres

5. Stop application services

docker compose stop web worker nginx

Nothing should write to PostgreSQL after this point.

6. Dump the old database cluster

pg_dumpall creates a portable SQL script containing all databases and global objects, including roles and permissions. A complete dump and restore generally require a database superuser. Check your app user:

docker compose exec postgres psql -U app_user -c \
  'SELECT rolsuper FROM pg_roles WHERE rolname = current_user;'

If the command returns true or t, create and inspect the dump:

docker compose exec postgres pg_dumpall -U app_user > backup.sql
head -5 backup.sql | grep -q "PostgreSQL" && echo "Backup format looks correct"
ls -lh backup.sql

Confirm that the file size is plausible before continuing.

7. Replace PostgreSQL

Stop and remove the old PostgreSQL container, then start the service with its new image and volume:

docker compose down postgres
docker compose up --detach postgres

Verify the new version:

docker compose exec postgres psql -U app_user -c 'SELECT VERSION();'

8. Restore and verify the data

docker compose exec --no-TTY postgres psql -U app_user < backup.sql

Because the new container’s initialization may already have created the app role and database, the restore can report that they already exist. Review the complete output for any other errors.

Run the same verification query as before:

docker compose exec postgres psql -U app_user app_production -c \
  'SELECT COUNT(*) FROM users; SELECT * FROM orders ORDER BY created_at DESC LIMIT 1;'

The results should match the baseline.

9. Restart and test the application

docker compose up -d web worker nginx

Confirm that the app loads and can write to the database, such as by submitting a form that creates a test record.

10. Deploy the permanent configuration

Revert the temporary edit:

git restore docker-compose.yml

Merge and deploy the prepared pull request. Then confirm that the app still uses the new PostgreSQL version and that its data remains intact:

docker compose exec postgres psql -U app_user app_production -c 'SELECT VERSION();'
docker compose exec postgres psql -U app_user app_production -c \
  'SELECT COUNT(*) FROM users; SELECT * FROM orders ORDER BY created_at DESC LIMIT 1;'

11. Remove the rollback data

After you are confident that the deployment succeeded:

rm backup.sql
docker volume rm app_postgres-data-v17

Rolling back

Until you remove the old volume, you can return to PostgreSQL 17:

docker compose down
git restore docker-compose.yml
docker compose up -d postgres
docker compose up -d web worker nginx

Complete example

I use this process for the davidrunger.com database. See the complete playbook and its docker-compose.yml for a concrete example with my service names, deployment flow, verification queries, and volume naming scheme.

Automatically compiling Crystal for development tooling

2024-08-08T00:00:00-05:00

Why Crystal?

I write many small command-line tools for my own development workflow. For example, my gform command fetches a Git repository and rebases the current branch onto the updated main branch. It also runs install-packages-in-background, another tool that checks dependency lock files and installs any changed dependencies in the background.

Most of my small tools are bash scripts. Bash starts quickly:

❯ time bash -c 'echo "Hi!"'
Hi!
bash -c 'echo "Hi!"'  0.00s user 0.00s system 89% cpu 0.006 total

Bash becomes unpleasant for more complicated logic, though, and it lacks a package ecosystem comparable to those of many general-purpose languages. Ruby and Node are more expressive, but their startup time is noticeable for frequently invoked tools. On my machine, even minimal programs took about 130 milliseconds with Ruby and 200 milliseconds with Node.

I also tried Lua, which starts as quickly as bash and has a package manager, but its limited standard library left me implementing basic functionality that I expected the language to provide.

A compiled language offered fast programs and richer language features, but introduced a different inconvenience: I would need to recompile each tool after changing its source and make the resulting binary available on my PATH.

ChatGPT and I devised a setup that handles both tasks automatically. Although I use it with Crystal, the same approach should work with other compiled languages such as Rust or Go.

The code lives in my dotfiles repository. Its current runner and symlink setup script are the source of truth, so readers can see how the setup has evolved since this post was published.

Why I chose Crystal

Crystal is a compiled, statically typed language with Ruby-inspired syntax. Its type inference means that explicit type annotations are often unnecessary, while its compiler produces efficient native programs.

I also appreciate Crystal’s clear compiler errors and approachable documentation. It gives me much of what I enjoy about writing Ruby while producing fast, memory-efficient executables.

Example: my `unique-union` program

As an example, my unique-union program combines the words in two arguments, removes duplicates, and sorts the result:

❯ unique-union "wave hello bye" "hello ocean wave"
bye
hello
ocean
wave

I use this small program as a building block in another tool.

Here is its Crystal source:

#!/usr/bin/env crystal

# file location: ~/code/dotfiles/crystal-programs/unique-union.cr

def unique_union(set1 : String, set2 : String) : Array(String)
  set1_words = set1.split
  set2_words = set2.split

  (set1_words | set2_words).sort
end

if ARGV.size == 2
  unique_union(ARGV[0], ARGV[1]).each { |item| puts(item) }
else
  puts "Usage: unique-union \"first list of words\" \"second list of words\""
  exit(1)
end

Setting up automatic Crystal compilation

Two shell scripts make the source available as a command and compile it when necessary.

Part 1: `symlink-crystal-programs`

My ~/.zshrc runs symlink-crystal-programs in the background whenever I open a terminal:

# Set up (in the background) symlinks for programs written in Crystal
{ ( symlink-crystal-programs >&3 & ) } 3>&1

The surrounding shell syntax preserves standard output while letting the script run asynchronously, so it does not delay shell startup.

The script recreates a directory of extensionless symlinks, one for each .cr source file. That directory is on my PATH, and every symlink points to the same run-crystal-program script:

❯ tree ~/bin/crystal-symlinks
/home/david/bin/crystal-symlinks
├── ...
├── install-packages-in-background -> /home/david/code/dotfiles/bin/run-crystal-program
├── ...
├── open-pr-in-browser -> /home/david/code/dotfiles/bin/run-crystal-program
├── runger-config -> /home/david/code/dotfiles/bin/run-crystal-program
└── unique-union -> /home/david/code/dotfiles/bin/run-crystal-program

Here is symlink-crystal-programs:

#!/usr/bin/env bash
# file name (available on PATH): symlink-crystal-programs

set -euo pipefail # exit on any error, don't allow undefined variables, pipes don't swallow errors

crystal_programs_source_code_directory="$HOME/code/dotfiles/crystal-programs"
crystal_executable_symlinks_directory="$HOME/bin/crystal-symlinks"

# Delete the symlinks directory, to ensure that there aren't any dangling programs left there.
rm -rf "$crystal_executable_symlinks_directory"

# Recreate the symlinks directory.
mkdir -p "$crystal_executable_symlinks_directory"

for crystal_program_source_file in "$crystal_programs_source_code_directory"/*.cr ; do
  symlink_name=$(basename "$crystal_program_source_file" .cr)
  ln -sf ~/code/dotfiles/bin/run-crystal-program "$crystal_executable_symlinks_directory/$symlink_name"
done

Dropping the .cr extension lets me invoke unique-union.cr as simply unique-union.

Part 2: `run-crystal-program`

The shared run-crystal-program script:

Ensures that the Crystal source corresponding to the invoked command exists.
Compiles the source if the binary does not exist or is older than the source, the runner, or the dependency lockfile.
Explains the reason for each rebuild, including the relevant timestamps when it compares files.
Executes the binary with the supplied arguments.

#!/usr/bin/env bash
# file location: ~/code/dotfiles/bin/run-crystal-program

# This program is intended to be symlinked as an executable file to a path with
# the same file name -- minus the `.cr` file extension -- as a Crystal program
# that is defined in `~/code/dotfiles/crystal-programs/`. When invoked, this
# script will compile that Crystal program, if necessary (i.e. if it has never
# been compiled before, if the Crystal source code or `shard.lock` has been
# changed subsequent to the most recent compilation, or if this compilation
# script has changed), and pass along any arguments to that compiled program.
# The compiled programs will live in `~/bin/crystal-binaries/`.

set -euo pipefail # exit on any error, don't allow undefined variables, pipes don't swallow errors

crystal_compiled_binaries_directory="$HOME/bin/crystal-binaries"

script_name=$(basename "$0")
source_file="$HOME/code/dotfiles/crystal-programs/$script_name.cr"
binary_file="$crystal_compiled_binaries_directory/$script_name"
compilation_script_file=$(realpath "$0")
shard_lock_file="$HOME/code/dotfiles/shard.lock"

print_file_timestamp() {
  local file=$1

  printf '  %s: %s\n' "$file" "$(stat -c '%y' "$file")" >&2
}

# Check if the source file exists.
if [ ! -f "$source_file" ] ; then
  echo "Error: Source file $source_file does not exist." >&2
  exit 1
fi

# Check if the binary doesn't exist, the source file has changed, the
# compilation script has changed, or the shard lockfile has changed.
compilation_reason=''
timestamp_comparison_files=()

if [ ! -f "$binary_file" ] ; then
  compilation_reason="the compiled binary $binary_file does not exist"
elif [ "$source_file" -nt "$binary_file" ] ; then
  compilation_reason="the source file is newer than the compiled binary"
  timestamp_comparison_files=("$source_file" "$binary_file")
elif [ "$compilation_script_file" -nt "$binary_file" ] ; then
  compilation_reason="the compilation script is newer than the compiled binary"
  timestamp_comparison_files=("$compilation_script_file" "$binary_file")
elif [ "$shard_lock_file" -nt "$binary_file" ] ; then
  compilation_reason="the shard.lock file is newer than the compiled binary"
  timestamp_comparison_files=("$shard_lock_file" "$binary_file")
fi

if [ -n "$compilation_reason" ] ; then
  # Create the compiled binaries directory.
  mkdir -p "$crystal_compiled_binaries_directory"

  # Add shards directory for dotfiles to the CRYSTAL_PATH.
  # More details: https://github.com/davidrunger/dotfiles/commit/d73a9df .
  export CRYSTAL_PATH="$HOME/.shards/dotfiles:/usr/share/crystal/src"

  # Compile the binary.
  echo "Compiling $source_file because $compilation_reason:" >&2
  for file in "${timestamp_comparison_files[@]}" ; do
    print_file_timestamp "$file"
  done

  if ! crystal build --warnings=none "$source_file" -o "$binary_file" ; then
    echo "There was an error compiling $source_file ." >&2
    exit 1
  fi

  echo "Done compiling $binary_file." >&2
fi

# Execute the compiled binary, passing along any provided arguments.
"$binary_file" "$@"

How the pieces fit together

The setup uses three directories:

~/code/dotfiles/crystal-programs/ stores the Crystal source.
~/bin/crystal-symlinks/, which is on my PATH, stores a symlink for each program.
~/bin/crystal-binaries/ stores the compiled executables.

Invoking unique-union resolves to ~/bin/crystal-symlinks/unique-union, which runs run-crystal-program. The runner derives the source and binary paths from the invoked name, recompiles when any of its tracked inputs is newer, and executes the resulting binary.

Downsides

The first invocation after a source or dependency change pauses for a few seconds while run-crystal-program compiles the executable. Later invocations reuse that binary and are fast.

Even with a current binary, the runner adds roughly eight milliseconds of shell overhead. Pointing each command directly to its binary would avoid that cost, but would also sacrifice automatic compilation.

Conclusion

For me, those costs are worthwhile: I can write development tools in Crystal and run current, compiled versions without a manual build step.

Flaky specs due to ActionCable leakage

2024-07-25T00:00:00-05:00

When this can happen

Your specs can fail intermittently when all of the following are true:

You run tests in parallel (locally and/or in CI).
Your application uses ActionCable with the Redis adapter.
The parallel test processes share a Redis instance, even if they use different Redis databases.
The test channel_prefix in config/cable.yml is not unique to each process.

Why this setup causes flakiness

Redis Pub/Sub channels are shared by every database in an instance. If Spec A broadcasts an ActionCable update, a simultaneously running Spec B can receive it. In a system or feature spec, that unexpected broadcast can change the browser state and fail the spec.

The failing spec offers no obvious clue because the broadcast originated in another process. Which specs overlap varies between runs, so the failure can also be difficult to reproduce.

Use a unique `channel_prefix` for each test process

Set channel_prefix to a value that differs for every test process. ActionCable then uses distinct Redis Pub/Sub channels, keeping each process’s broadcasts isolated.

For example, I changed the test section of config/cable.yml from:

test:
  <<: *default
  channel_prefix: david_runger_test
  url: redis://localhost:6379

to:

test:
  <<: *default
  channel_prefix: david_runger_test<%= ENV['DB_SUFFIX'] %>
  url: redis://localhost:6379

The <%= ENV['DB_SUFFIX'] %> ERB interpolation makes the prefix process-specific. My CI assigns every RSpec process a distinct DB_SUFFIX, such as _unit, _api, or _feature.

Rails documents channel_prefix for avoiding channel-name collisions when applications share a Redis server: Redis Adapter.

Separate Redis databases do not isolate Pub/Sub

Different Redis database numbers do not solve this problem: Redis Pub/Sub is not scoped to databases. Redis recommends prefixing channel names when they need to be scoped: Database & Scoping.

Enforce Git hooks in a Rails initializer

2024-07-02T00:00:00-05:00

Git hooks

Git hooks are scripts that Git runs automatically at points such as before a commit, push, or merge. For example, a pre-push hook in this site’s repository uses Betterleaks to scan the outgoing diff for secrets and runs linters. See the Git hook documentation for the full list.

That feedback is useful only when each contributor’s clone is configured to use the hooks stored in the repository.

The configuration gap

Git does not automatically use hook scripts committed to a repository; each clone must opt in by setting core.hooksPath. Setup documentation can ask contributors to do that, but instructions are easy to miss.

Check during Rails boot

For a Rails application, an initializer can verify the setting and refuse to boot until it is fixed. That makes a missing one-time setup step visible when a developer first uses the app.

This is a usability guardrail, not a security or policy boundary. A developer can bypass Git hooks (for example, with git push --no-verify) or change the initializer without booting the app. Checks that must not be bypassed belong in CI or protected server-side controls.

The idea is not Rails-specific: an application built with any framework could run an equivalent check during local development startup.

The initializer

Place this in config/initializers/githooks_check.rb:

if (
  Rails.env.local? &&
    ENV['SKIP_GITHOOKS_CHECK'].blank? &&
    ENV['CI'].blank? &&
    `git config core.hooksPath`.strip != 'bin/githooks'
)
  $stderr.puts(<<~ERROR)
    You have not configured the git hooks for this repo! To do so, run:
        git config core.hooksPath bin/githooks
    Or, if you must, you can put SKIP_GITHOOKS_CHECK=1 in your .env file.
  ERROR

  exit(1)
end

(You can see the actual source code here.)

Without the setting, bin/rails server prints the following error to standard error and aborts:

❯ bin/rails server
=> Booting Puma
=> Rails 7.1.3.4 application starting in development
=> Run `bin/rails server --help` for more startup options
You have not configured the git hooks for this repo! To do so, run:
    git config core.hooksPath bin/githooks
Or, if you must, you can put SKIP_GITHOOKS_CHECK=1 in your .env file.
Exiting

The conditions limit the check to local, non-CI boots; SKIP_GITHOOKS_CHECK provides an escape hatch. The remaining condition verifies that Git uses bin/githooks. If it does not, the initializer explains the fix and exits unsuccessfully.

Configuring the Git hooks

At the project root, run:

❯ git config core.hooksPath bin/githooks

This tells Git to find hooks in the repository’s bin/githooks/ directory. Git runs pre-push before pushing and pre-commit before committing, when those executable scripts exist.

Rails can now boot:

❯ bin/rails server
=> Booting Puma
=> Rails 7.1.3.4 application starting in development
   [ ... ]
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

Future pushes will also run the repository’s pre-push checks locally.

Using VS Code as a Rails app:update merge tool

2024-06-26T00:00:00-05:00

When upgrading Rails, you should run bin/rails app:update. The command compares your application’s configuration files with those that the new Rails version would generate, then asks how to resolve each difference:

❯ bin/rails app:update
    conflict  config/boot.rb
Overwrite /home/david/code/david_runger/config/boot.rb? (enter "h" for help) [Ynaqdhm]

Entering h explains the available options:

Y - yes, overwrite
n - no, do not overwrite
a - all, overwrite this and all others
q - quit, abort
h - help, show this help
d - diff, show the differences between the old and the new
m - merge, run merge tool

Overwriting (Y) can discard application-specific configuration, while declining (n) can miss relevant changes from the new Rails version. A three-way merge (m) makes it easier to preserve your configuration while incorporating new defaults.

Without a configured merge tool, however, choosing m produces an error:

Overwrite /home/david/code/david_runger/config/boot.rb? (enter "h" for help) [Ynaqdhm] m
Please specify merge tool to `THOR_MERGE` env.
Overwrite /home/david/code/david_runger/config/boot.rb? (enter "h" for help) [Ynaqdhm]

Here is how to use VS Code as that merge tool.

Create a VS Code adapter

For each conflict, Rails’s underlying Thor library passes THOR_MERGE two paths: a temporary file containing the new Rails default and the application’s existing file.

VS Code’s --merge option instead expects four paths:

code --merge <path1> <path2> <base> <result>

An adapter script can supply the two additional paths. Open a new script in VS Code, then make it executable after you save and close it:

code --wait bin/app_update_thor_merge_tool
chmod +x bin/app_update_thor_merge_tool

Paste this into the script:

#!/usr/bin/env bash

rails_default_config=$1
app_current_config=$2

temporary_directory=$(mktemp -d)
trap 'rm -rf "$temporary_directory"' EXIT

current_copy="$temporary_directory/current"
base_copy="$temporary_directory/base"

cp "$app_current_config" "$current_copy"
cp "$app_current_config" "$base_copy"

code --merge \
  "$rails_default_config" \
  "$current_copy" \
  "$base_copy" \
  "$app_current_config" \
  --wait

Then run app:update with the script’s absolute path in THOR_MERGE:

THOR_MERGE="$(pwd)/bin/app_update_thor_merge_tool" bin/rails app:update

When you choose m for a conflict, VS Code opens its three-way merge editor:

The left pane contains the new Rails default, the right pane contains your application’s current configuration, and the center pane contains the result. Review the relevant Rails documentation, resolve the differences, save the result, and close the tab. Because the adapter passes --wait, app:update will then advance to the next file.

Repeat until you have reviewed every conflict.

Quick Tip: Use gem.wtf to open a Ruby gem’s repository

2023-02-13T00:00:00-06:00

gem.wtf takes you straight to a Ruby gem’s source repository (usually a GitHub repo). Enter gem.wtf/<gem-name> in your browser’s address bar; for example, gem.wtf/rails.

It uses the gem’s RubyGems metadata, so it works with repositories outside GitHub too. If a gem does not declare a source repository, it falls back to its documentation or RubyGems page.

It’s handy for checking a gem’s README, issues, and history before using the gem or while debugging a problem.

It was created by Zeke Sikelianos; its source is available on GitHub.

Bonus tip: ghub.io does the same for npm packages.

Mocking external requests in Rails feature tests

2023-01-30T00:00:00-06:00

Need to test a redirect to an external service without contacting it? Intercept the request in the browser that Capybara drives.

Here is the relevant part of a Cuprite feature spec that verifies a Google OAuth redirect:

context 'when OmniAuth test mode is disabled', :permit_all_external_requests do
  around do |spec|
    original_omni_auth_test_mode = OmniAuth.config.test_mode
    OmniAuth.config.test_mode = false

    spec.run
  ensure
    OmniAuth.config.test_mode = original_omni_auth_test_mode
  end

  context 'when Google responds with "This is Google OAuth."' do
    let(:google_response_content) { 'This is Google OAuth.' }

    before do
      browser = page.driver.browser
      browser.network.intercept
      browser.on(:request) do |request|
        if request.match?(%r{\Ahttps://accounts.google.com/o/oauth2/auth\?})
          request.respond(body: google_response_content)
        else
          request.continue
        end
      end
    end

    it "renders Google's response" do
      visit(new_user_session_path)
      expect(page).to have_css('google-sign-in-button')

      click_sign_in_with_google

      expect(page).to have_text(google_response_content)
    end
  end
end

browser.network.intercept pauses requests, and the :request handler either supplies a fake response or lets the request proceed. The URL matcher is deliberately narrow: the assertion only proves the browser reached Google’s OAuth authorization URL when it displays the supplied content. No request reaches Google.

The :permit_all_external_requests metadata is specific to this test suite’s request policy. Keep or replace it with the equivalent configuration in your application. OmniAuth test mode must be disabled because it otherwise skips the external redirect; the ensure restores the original setting even when the example fails.

Why browser interception?

WebMock intercepts HTTP requests made by the Ruby process. In a JavaScript-capable feature spec, the browser is a separate process, so WebMock cannot intercept its navigation to an external site. Cuprite’s browser-level network API fills that gap.

This is useful for integration boundaries such as OAuth. My regression test covers a Content Security Policy (CSP) failure: the login form submits to my application, which redirects the browser to Google. A restrictive form-action directive can block that redirect unless the OAuth domain is allowed. The CSP discussion describes the interaction.

Mocking the destination keeps the test focused on whether the browser follows the redirect. It also avoids a dependency on Google’s availability, content, credentials, and an Internet connection, making the test faster and more reliable.

Selenium alternative

This site previously used selenium-webdriver. Selenium can intercept the same request through its DevTools integration:

around do |spec|
  page.driver.browser.intercept do |request, &continue|
    continue.call(request) do |response|
      if request.url.start_with?('https://accounts.google.com/o/oauth2/auth?')
        response.code = 200
        response.body = 'This is Google OAuth.'
      end
    end
  end

  spec.run
end

Add selenium-devtools to the test group for this approach. The surrounding OmniAuth setup and assertion are the same. The former Selenium version of this test is available in the original implementation; the current Cuprite version is in the site’s source.