Add cooldown to delay newly published gem

[hsbt]

Adds the cooldown setting discussed at #9113, mirroring npm's min-release-age, pnpm's minimumReleaseAge, and Dependabot's cooldown to mitigate freshly published supply-chain attacks.

Users opt in through:

• --cooldown N on install, update, add, and outdated
• bundle config set cooldown N or BUNDLE_COOLDOWN
• per-source via source "URL", cooldown: N in the Gemfile

Design decisions adopted from #9113 and the follow-up review:

• The value is a non-negative Integer day count. Strings, floats, arrays, and negative numbers raise InvalidOption from both the Gemfile DSL and the CLI handlers, so a typo can't silently disable the filter.
• Precedence is CLI > config > Gemfile per-source, applied uniformly to every source — not just ones that declare their own cooldown: value.
• --cooldown 0 is the global escape hatch and applies to the whole resolve including transitive dependencies; combine with --conservative to minimize churn during urgent updates.
• Per-gem cooldown is out of scope; private registries opt out by declaring source "URL", cooldown: 0 in the Gemfile.
• The filter runs per-version (rolling delay) rather than from the latest release timestamp.
• Lockfile-pinned versions bypass the filter, and bundle install against an existing lockfile short-circuits the resolver entirely, so a cooldown setting never invalidates a working lock.
• bundle update filters and falls back to the newest version satisfying cooldown; bundle outdated annotates the latest-but-cooled version ((cooldown Nd) in the table form, in cooldown for N more days in --parseable) rather than hiding it.
• When the resolver fails because every matching version is in cooldown, both error paths surface the same hint suggesting --cooldown 0 to bypass.
• Specs whose created_at is absent are treated as outside the window and remain resolvable.
• Out of scope: CVE-aware bypass (Dependabot/Renovate territory), semver-level differentiation, gem install -v X exact-version cooldown errors (deferred), and a dedicated exit code for cooldownfailures.

The EndpointSpecification parses created_at defensively against older rubygems whose APISet::GemParser splits ISO8601 on every colon and the flat String shape are accepted, malformed values become nil.

Make sure the following tasks are checked

• Describe the problem / feature
• Write tests for features and bug fixes
• Write code to solve the problem
• Make sure you follow the current code style and write meaningful commit messages without tags

[Copilot]

Pull request overview

Adds an opt-in “cooldown” (minimum release age in days) to Bundler installs/updates/resolution, using per-version created_at metadata from the v2 compact index to avoid selecting freshly published versions.

Changes:

• Introduces cooldown configuration/precedence (CLI > config/env > Gemfile per-source) and wires it through sources/remotes to the resolver.
• Parses and propagates created_at from compact-index metadata into EndpointSpecification, and filters resolver candidates within the cooldown window.
• Documents --cooldown across relevant commands and adds comprehensive specs + artifice support.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
spec/support/shards.rb	Adds new cooldown specs to CI sharding.
spec/support/artifice/helpers/compact_index_cooldown.rb	Adds an artifice compact-index API variant that emits created_at.
spec/support/artifice/compact_index_cooldown.rb	Activates the new cooldown-aware artifice endpoint.
spec/install/cooldown_spec.rb	End-to-end coverage for cooldown behavior and precedence.
spec/bundler/source/rubygems/remote_spec.rb	Tests Remote#cooldown and #effective_cooldown.
spec/bundler/source_list_spec.rb	Tests per-remote cooldown storage on sources.
spec/bundler/settings_spec.rb	Tests that cooldown is coerced via settings.
spec/bundler/resolver/cooldown_spec.rb	Unit tests for resolver cooldown filtering and hinting.
spec/bundler/endpoint_specification_spec.rb	Tests robust parsing of created_at metadata shapes.
spec/bundler/dsl_spec.rb	Validates Gemfile DSL input validation for cooldown:.
spec/bundler/compact_index_client/parser_spec.rb	Ensures compact index parser accepts created_at metadata.
lib/rubygems/resolver/api_set/gem_parser.rb	Fixes parsing to avoid splitting ISO8601 values on colons.
bundler/lib/bundler/source/rubygems/remote.rb	Adds cooldown state to remotes and computes effective cooldown.
bundler/lib/bundler/source/rubygems.rb	Tracks per-remote cooldowns and passes them into Remote objects.
bundler/lib/bundler/source_list.rb	Allows storing cooldown when adding global rubygems remotes.
bundler/lib/bundler/settings.rb	Treats cooldown as a numeric setting key.
bundler/lib/bundler/resolver.rb	Filters candidate specs by cooldown and adds user-facing hints on failure.
bundler/lib/bundler/man/bundle-update.1.ronn	Documents --cooldown on bundle update.
bundler/lib/bundler/man/bundle-update.1	Generated manpage update for bundle update.
bundler/lib/bundler/man/bundle-outdated.1.ronn	Documents --cooldown behavior/annotation on bundle outdated.
bundler/lib/bundler/man/bundle-outdated.1	Generated manpage update for bundle outdated.
bundler/lib/bundler/man/bundle-install.1.ronn	Documents --cooldown on bundle install.
bundler/lib/bundler/man/bundle-install.1	Generated manpage update for bundle install.
bundler/lib/bundler/man/bundle-config.1.ronn	Documents cooldown config/env and precedence rules.
bundler/lib/bundler/man/bundle-config.1	Generated manpage update for bundle config.
bundler/lib/bundler/man/bundle-add.1.ronn	Documents --cooldown on bundle add.
bundler/lib/bundler/man/bundle-add.1	Generated manpage update for bundle add.
bundler/lib/bundler/endpoint_specification.rb	Adds created_at field and parses it from metadata.
bundler/lib/bundler/dsl.rb	Adds Gemfile source ..., cooldown: N parsing + validation + wiring.
bundler/lib/bundler/cli/update.rb	Validates/applies --cooldown into settings for updates.
bundler/lib/bundler/cli/outdated.rb	Validates/applies --cooldown and annotates cooldown remaining.
bundler/lib/bundler/cli/install.rb	Validates/applies --cooldown into settings for installs.
bundler/lib/bundler/cli/common.rb	Adds shared cooldown validation helper.
bundler/lib/bundler/cli/add.rb	Validates/applies --cooldown for bundle add.
bundler/lib/bundler/cli.rb	Exposes --cooldown option on install/update/add/outdated commands.

Comments suppressed due to low confidence (1)

bundler/lib/bundler/settings.rb:53

• cooldown is treated as a numeric setting via to_i, which silently accepts malformed/negative values (e.g. BUNDLE_COOLDOWN=7days becomes 7, -7 disables filtering via days <= 0). Since cooldown is intended as a supply-chain protection feature, this should be validated as a non-negative integer (and reject floats/garbage) when coming from config/env as well, so typos can’t silently change/disable the filter.

    NUMBER_KEYS = %w[
      cooldown
      jobs
      redirect
      retry
      ssl_verify_mode
      timeout
    ].freeze

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[hsbt]

📝 I should inject rake vendor:compact_index into test_setup

https://github.com/ruby/rubygems/blob/master/spec/support/rubygems_ext.rb#L30

[mark-young-atg]

@hsbt I'm very excited to see you tackle this functionality. Thank you.

Please can you confirm how it will behave in the following scenario:

Day 0: I have popular_gem v1.0 installed
Day 1: popular_gem v1.1 released with hidden malware
Day 5: popular_gem v1.2 released with malware removed
Day 10: I run "bundle update --cooldown 7"

Will I get v1.1 installed and thus suffer from the now known bad code, or will it delay updating until Day 12 when it will give me v1.2?

If I get v1.1 then unfortunately I think that negates what feels like the benefits of this mechanism. The goal for me is safety and security, so I'd want it to automatically prevent me getting the bad release.