# Ruby

SlowShield serves rubygems.org at `https://slowshield.example.com/rubygems`. Bundler uses it as a mirror of rubygems.org, so Gemfiles and `Gemfile.lock` keep naming rubygems.org; `gem` uses it as its only source.

## Set it up

Both settings live in your home directory and cover every project on the machine:

### Bundler

Release age: Bundler 4.0.13 or later (older versions ignore it). It reads the created_at that SlowShield passes on

*command (writes ~/.bundle/config; also for CI and Dockerfiles)*

```
bundle config set --global mirror.https://rubygems.org https://slowshield.example.com/rubygems
```

*release age*

```
bundle config set --global cooldown 3
```

### gem

*~/.gemrc: SlowShield as the only source*

```
---
:sources:
- https://slowshield.example.com/rubygems/
```

*CI and Dockerfiles (replaces ~/.gemrc)*

```
printf -- '---\n:sources:\n- %s\n' https://slowshield.example.com/rubygems/ > ~/.gemrc
```

- **A mirror, not a new `source`.** Gemfiles keep `source "https://rubygems.org"`, and `Gemfile.lock` keeps `remote: https://rubygems.org/` and its checksums, so a project builds the same with or without SlowShield.

- **No `fallback_timeout`.** With `mirror.https://rubygems.org.fallback_timeout` set, Bundler goes to rubygems.org when SlowShield doesn't answer in time.

- **The mirror covers `https://rubygems.org` only.** Other gem servers, `git:` and `github:` gems, and a Gemfile that says `source "http://rubygems.org"` go around it.

- **Leave rubygems.org out of `~/.gemrc`.** `gem` asks every source it lists. `gem sources` shows them.

## What changes

- **The publish time** is the `created_at` rubygems.org writes for every version in its index. The first one SlowShield sees is kept, so it can't move earlier.

- **Held versions are left out** of the index Bundler and `gem install` read, so `bundle update`, `bundle add` and `gem install` pick the newest version that is old enough.

- **Platform gems wait on their own.** Every platform gem (`nokogiri-1.19.4-x86_64-linux-gnu`) is pushed separately, with its own time. One pushed today for a version that is a year old waits like a new version, and Bundler installs the plain gem of that version, or an older version, meanwhile.

- **A `Gemfile.lock` that pins a held version** fails, because Bundler can't find it in the index:
   ```
   Your bundle is locked to rubocop (1.92.1) from rubygems repository https://rubygems.org/ or installed locally, but that version can no longer be found in that source.
   ```
   Bundler says the author removed it; here it means the version is younger than the delay. `bundle update rubocop` picks the newest version that is old enough.

- **Asking for the gem file itself** gets `425 Too Early` with `Retry-After`; Bundler and `gem` show only the status line, curl the message.

- **Brand-new gems** none of whose versions is old enough are held too: RubyGems doesn't fail open, because brand-new gems are the realistic attack (typosquats). Bundler and `gem` say they can't find the gem.

- **Malware** from OSV and GitHub is refused: left out of the index, and `451` for the file. Every `.gem` is checked against the sha256 in rubygems.org's index and the fingerprint SlowShield recorded the first time, and never changed, so `Gemfile.lock` `CHECKSUMS` keep matching.

## The second layer

Bundler 4.0.13 and later have a release age of their own, `cooldown`, in days. It reads the same `created_at`, which SlowShield passes on unchanged. `gem` has none: there, SlowShield is the only layer.

## In Docker and CI

Run the commands in the build stage, before `bundle install`. With a build argument, the same Dockerfile still builds without SlowShield when the argument is empty:

```
FROM ruby:3.4
ARG RUBYGEMS_MIRROR=https://slowshield.example.com/rubygems
RUN if [ -n "$RUBYGEMS_MIRROR" ]; then \
      bundle config set --global mirror.https://rubygems.org "$RUBYGEMS_MIRROR" && \
      printf -- '---\n:sources:\n- %s/\n' "$RUBYGEMS_MIRROR" > ~/.gemrc; fi
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
```

In CI, run the Setup page's commands before `bundle install`. `ruby/setup-ruby` with `bundler-cache: true` installs the gems within its own step, before any command of yours can run: leave it off and run `bundle install` after the commands. [Building images](https://slowshield.org/docs/container-builds/) covers the base image too, and how to check that nothing in a build goes around SlowShield.

## Limits

- `gem search`, `gem list --remote`, `gem outdated` and `gem update` need rubygems.org's full index, which lists every gem without times and so can't be filtered: they find nothing through SlowShield, and `gem update --system` fails. `bundle outdated` and `bundle update` work.

- Checked with Bundler 2.4, 2.6 and 4.0 and RubyGems 3.6.

- Not served: publishing (`gem push`, `yank` and `owner` go to rubygems.org), and other gem servers.

- Gems already installed, or in Bundler's cache, are used without asking SlowShield.

- Block rubygems.org and index.rubygems.org at the firewall for machines that should only use SlowShield.

---

This page as HTML: https://slowshield.org/docs/ruby/. All of the guide in one file: https://slowshield.org/llms-full.txt
