If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ankane/the-ultimate-guide-to-ruby-timeouts shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4mo ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ankane/the-ultimate-guide-to-ruby-timeouts repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ankane/the-ultimate-guide-to-ruby-timeouts.

What it runs against: a local clone of ankane/the-ultimate-guide-to-ruby-timeouts — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ankane/the-ultimate-guide-to-ruby-timeouts | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 154 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ankane/the-ultimate-guide-to-ruby-timeouts. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts.git
#   cd the-ultimate-guide-to-ruby-timeouts
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ankane/the-ultimate-guide-to-ruby-timeouts and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ankane/the-ultimate-guide-to-ruby-timeouts(\\.git)?\\b" \\
  && ok "origin remote is ankane/the-ultimate-guide-to-ruby-timeouts" \\
  || miss "origin remote is not ankane/the-ultimate-guide-to-ruby-timeouts (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "Appraisals" \\
  && ok "Appraisals" \\
  || miss "missing critical file: Appraisals"
test -f "Rakefile" \\
  && ok "Rakefile" \\
  || miss "missing critical file: Rakefile"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 154 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~124d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ankane/the-ultimate-guide-to-ruby-timeouts"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A comprehensive reference guide that documents timeout configuration patterns for 100+ popular Ruby gems across HTTP clients, databases, message queues, and external APIs. It provides tested, copy-paste-ready code examples showing exactly how to set connect/read/write/checkout timeouts for each gem, solving the critical production problem of unresponsive services hanging your entire Ruby application. Monolithic reference structure: README.md contains all timeout patterns organized by gem category (Standard Library, Data Stores, HTTP Clients, Commands), gemfiles/ directory has 60+ Appraisal gemfiles for testing each gem independently, and test/ directory (inferred) validates that documented patterns work. No src/ or lib/—this is documentation-driven.

Ruby backend engineers and DevOps specialists who need to harden their applications against hung network calls and database queries. Specifically targets developers using gems like Faraday, ActiveRecord, Redis, Elasticsearch, and AWS SDK who want production-safe timeout configurations without guessing.

Actively maintained and production-ready. The repo has comprehensive CI setup (.github/workflows/build.yml), 60+ tested gemfile configurations in gemfiles/, clear README documentation, and is part of ankane's multi-language timeout guide series. Regular GitHub Actions testing ensures examples stay compatible with current gem versions.

Low risk overall, but this is a reference repo with no dependencies beyond the gems being documented—the real risk is in the user's implementation if timeout values are misconfigured. Single maintainer (ankane) means updates depend on one person's availability, but the nature of the content (timeout patterns) is stable and unlikely to require frequent changes. Biggest risk: timeout recommendations may drift if gems change their APIs significantly.

Active maintenance adding new gems and timeout patterns. The repo structure with gemfiles/ shows ongoing testing of popular libraries. Based on file listing showing recent gems (google_cloud, influxdb_client, typesense, graphql_client), the maintainer is regularly adding emerging tools. CI automation in .github/workflows/build.yml ensures documented patterns stay tested.

git clone https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts.git
cd the-ultimate-guide-to-ruby-timeouts
bundle install
bundle exec rake test  # Run test suite

Daily commands:

bundle exec appraise install  # Install all gemfile variants
bundle exec appraise rake test  # Run tests across all gems

• README.md — Central reference documentation listing timeout configurations for 100+ Ruby gems—essential context for understanding the repo's purpose and scope.
• Gemfile — Declares core testing dependencies and gem versions; contributors must ensure test suite runs against correct gem versions.
• Appraisals — Defines all 140+ gemfile variants for testing each Ruby gem in isolation; critical for understanding how the test matrix is structured.
• Rakefile — Test orchestration and build task definitions; contributors need to know how to run the full test suite locally.
• .github/workflows/build.yml — CI/CD pipeline that validates all gemfile combinations; defines the quality gate for PRs and releases.

• README.md (Markdown) — Single source of truth for timeout configurations across 100+ Ruby gems, organized by category
  • Failure mode: Outdated or incorrect timeout patterns cause users to misconfigure gems and experience hangs or premature timeouts
• Appraisals + Gemfiles (Appraisals gem, Bundler, Ruby) — Defines isolated gem test environments to verify each timeout configuration works correctly
  • Failure mode: Version conflicts or missing dependencies in appraisal groups cause test suite to fail to run
• Test Suite (Rakefile + test/gems/) (Rake, RSpec or Minitest (inferred), Ruby) — Validates that timeout parameters actually enforce connect/read/write limits and prevent hangs
  • Failure mode: Tests pass but timeout behavior changes in new gem version; users experience undocumented timeouts
• GitHub Actions CI/CD (GitHub Actions YAML, Ubuntu runners) — Runs test matrix across all 140+ gem combinations and multiple Ruby versions on every push
  • Failure mode: CI flakes or timeouts prevent validation that documentation remains accurate

• GitHub PR → Appraisals file — Contributor adds or updates gem entry in Appraisals for a new/changed Ruby library
• Appraisals file → Gemfiles directory — Appraisal gem generates isolated Gemfile variants from appraisal definitions
• Gemfiles directory → Test Suite — Each gemfile is bundled and its tests run to validate timeout behavior for that specific gem
• Test Suite results → CI/CD Pipeline — Appraisal test results aggregated across all 140+ gems; failures block merge
• CI/CD approval → README.md — Only after all tests pass, documentation updates are merged to main branch
• README.md → User application code — Developers read guide, copy timeout configuration examples, and apply to their gems at runtime

Add timeout documentation for a new Ruby gem

1. Open README.md and locate the section for the gem's category (HTTP, database, queue, etc.) (README.md)
2. Add a new subsection with the gem name, timeout parameter names, and code example showing how to configure connect/read/write timeouts (README.md)
3. Create a new appraisal group in Appraisals with the gem name and its specific version constraints (Appraisals)
4. Create a corresponding test gemfile in gemfiles/ directory (e.g., gemfiles/newgem.gemfile) that includes the test framework and the target gem (gemfiles/newgem.gemfile)
5. Write a test file validating timeout behavior for the gem (verify connect timeout, read timeout, and write timeout are properly enforced) (test/gems/)

Update timeout configuration for an existing gem after API change

1. Locate the gem's section in README.md and update the timeout parameter names and code examples to match the new API (README.md)
2. Update the gem version constraint in Appraisals to pin the new version range (Appraisals)
3. Update or add new test cases to verify the new timeout parameters work correctly (test/gems/)
4. Run the appraisal group locally: bundle exec appraisal gemname rake test (Rakefile)

Verify all gem timeout configurations in CI

1. The build workflow runs automatically on push; review build.yml to understand the test matrix (.github/workflows/build.yml)
2. To debug locally, run: bundle exec appraisal install && bundle exec appraisal rake test (Rakefile)
3. Each gem is tested in isolation via its appraisal entry to catch version conflicts and timeout behavior changes (Appraisals)

• Appraisals gem + Bundler — Enables isolated testing of each Ruby gem in its own gemfile context without dependency conflicts; standard Ruby testing pattern.
• GitHub Actions CI/CD — Provides matrix testing across multiple Ruby versions and all 140+ gem combinations in parallel; free for open-source.
• Markdown (README.md) — Simple, version-controllable documentation format suitable for GitHub's native rendering and searchability by users.

• Use Appraisals for isolated gem testing rather than monolithic Gemfile

  • Why: Prevents version conflicts and allows testing each gem independently against its real dependencies
  • Consequence: Slower local test cycles (must run per-gem) but more accurate real-world timeout behavior validation

• Documentation-first approach (README.md as primary interface)

  • Why: Timeout configurations are largely library-specific; centralizing examples avoids code duplication and keeps patterns in one searchable place
  • Consequence: Manual updates required when gems release breaking API changes; relies on community PRs for new gems

• No framework abstraction layer; raw gem configuration examples

  • Why: Timeout APIs vary significantly across gems (no common abstraction possible); examples must be literal and tested
  • Consequence: README grows large (140+ gems) but remains clear and unambiguous for copy-paste use

• Does not provide a unified timeout wrapper library; it is purely a reference guide
• Does not handle Ruby's Timeout module (explicitly discouraged in README as unsafe)
• Does not generate boilerplate; guides manual configuration per gem
• Not a real-time service; no runtime instrumentation or monitoring

• Avg cyclomatic complexity: ~2 — Repo is primarily documentation + test configuration. Each appraisal and test is simple (mostly gem initialization + timeout verification). No complex algorithmic logic or state management.
• Largest file: README.md (2,500 lines)
• Estimated quality issues: ~3 — Main issues: (1) README requires manual updates for 140+ gems (drift risk), (2) Appraisals file has no modular structure, (3) test coverage assumes each gem is tested but visibility into missing

• Manual timeout updates without test coverage (High) — README.md (entries without corresponding test/gems tests): If a gem's timeout configuration is documented but not tested in the appraisal matrix, it may silently become outdated when the gem releases breaking changes
• Gem version pinning drift in Appraisals vs README (Medium) — Appraisals and README.md: Version constraints in Appraisals may diverge from examples in README, causing users to follow outdated APIs

• GitHub Actions CI pipeline (build.yml) (Build time / CI throughput) — 140+ gem variants tested sequentially or in limited parallelism; total CI time ~15-30 min per run
• README.md maintenance (Developer effort / scalability) — Manual document updates required for each new gem or API change; no automated sync with gem releases
• Appraisals file (Code organization / readability) — Single large file with 140+ gem definitions; lack of modularity makes it harder to organize and search

Appraisal dependency hell: Running bundle exec appraisal installs 60+ separate gem bundles—this requires significant disk space and can take 10+ minutes first run. Ruby version matrix: Some gems require specific Ruby versions (e.g., gRPC doesn't work on all versions)—CI handles this but local testing may fail silently. Network-dependent tests: Examples validating timeouts may actually hit network services or spawn test servers; check test/ for setup requirements. Gem API changes: Timeout parameter names vary wildly between gems (some use timeout:, others connect_timeout:, read_timeout:)—the docs must be extremely precise.

• Connect vs. Read vs. Write timeouts — Different timeout types handle different failure scenarios; this repo documents that connect timeout (TCP handshake) is separate from read timeout (data reception), and both must be set independently for proper coverage
• Connection pool checkout timeout — Many Ruby gems (Dalli, ConnectionPool, ActiveRecord) have separate timeouts for acquiring a connection from the pool; this prevents queue exhaustion when all connections are busy
• Statement timeouts (database-side) — PostgreSQL, MySQL, MariaDB support server-side statement timeouts independent of client timeouts; this is listed as 'single most important' in the repo, preventing runaway queries from blocking the entire database
• Timeout vs. circuit breaker — This repo focuses purely on timeouts but doesn't address circuit breaking; understanding that timeouts detect slow services while circuit breakers prevent cascading failures is essential context
• Appraisal gemfile matrix testing — This repo uses Appraisals to generate isolated gemfiles for each gem; this pattern ensures timeout examples work across gem versions without dependency conflicts in test suite
• Ruby Timeout module (dangerous) — The README explicitly warns against Ruby's stdlib Timeout module; understanding why (uses signals, unreliable, can leave connections open) is critical for safe production Ruby
• Connection leak prevention via timeouts — Unhandled network hangs without timeouts exhaust connection pools, eventually blocking all application requests; this repo documents the must-have configuration to prevent this cascade

• ankane/python-timeouts — Same timeout guide concept for Python ecosystem—reference for porting patterns and feature parity
• ankane/node-timeouts — Same timeout guide concept for Node.js ecosystem—shows how timeouts are configured across language ecosystems
• mikeperham/sidekiq — Job queue library heavily dependent on proper timeouts; commonly documented alongside HTTP client timeouts in production Ruby apps
• ankane/strong_migrations — Companion gem by same author addressing production safety in Ruby; shares philosophy of preventing silent failures in production
• ruby/timeout — Standard library module explicitly advised against in this repo's README; understanding why (signal-based, dangerous) is critical context

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for Gemfile configurations

The repo has 75+ gemfiles for different libraries (activerecord.gemfile, elasticsearch.gemfile, etc.) but there's no visible test directory validating that each gemfile actually installs and runs correctly. A new contributor could create a test suite that ensures each gemfile resolves dependencies without conflicts and basic gem operations work with the documented timeout settings.

• [ ] Create test/gemfile_validation_test.rb to iterate through gemfiles/ directory
• [ ] For each gemfile, validate bundle install succeeds
• [ ] Test that the primary gem from each gemfile can be required
• [ ] Run tests in CI via .github/workflows/build.yml for a subset of critical gemfiles (activerecord, elasticsearch, redis, etc.)
• [ ] Document expected test output in README.md

Create timeout configuration examples directory with runnable scripts

Currently README.md is the only source of truth for timeout configurations across 75+ gems. A new contributor could create a test/examples/ directory with standalone, runnable Ruby scripts for each major gem category (HTTP clients, databases, message queues) that demonstrate proper timeout usage and can be executed to verify the configurations work.

• [ ] Create test/examples/ directory structure: http_clients/, databases/, message_queues/, etc.
• [ ] Add example scripts like test/examples/http_clients/faraday_timeout.rb, test/examples/databases/elasticsearch_timeout.rb
• [ ] Each script should make a real network call with timeout and catch timeout exceptions properly
• [ ] Update Rakefile to run examples as integration tests
• [ ] Document how contributors can add new examples in CONTRIBUTING.md

Add missing gemfiles for popular Ruby gems not yet covered

The gemfiles/ directory has 75+ gems but notable Ruby staples appear absent (e.g., typhoeus, net-http-persistent, httx, sidekiq-redis, puma, thin, torquebox). A contributor could audit popular Ruby gems against the existing list, add missing gemfiles, and update README.md with timeout configurations for high-impact libraries.

• [ ] Review Bundler trends and GitHub dependency data to identify top 10-20 missing gems
• [ ] Create new gemfiles/ entries (e.g., gemfiles/typhoeus.gemfile, gemfiles/sidekiq.gemfile)
• [ ] Add corresponding README.md sections with tested timeout configurations
• [ ] Verify each new gemfile installs cleanly in CI via Appraisals
• [ ] Test actual timeout behavior for each new gem (avoid generic entries)

• Add timeout examples for 3-5 missing gems from the Ruby ecosystem that have network I/O but lack README documentation (search for gems with 1000+ downloads that do HTTP/DB calls but aren't in gemfiles/)
• Create a test helper or shared test class in test/ that validates the timeout pattern works for each documented gem (currently unclear if all examples are actually tested; making this explicit would prevent doc rot)
• Add a 'Testing Timeouts' section to README.md with runnable code showing how to verify timeouts work in a user's own app (e.g., 'How to test that your Faraday timeout actually fires')

This is an educational reference repository documenting timeout best practices for Ruby gems. It contains no production code, hardcoded secrets, or dangerous patterns. The security posture is strong for its intended purpose as a documentation resource. Minor improvements include adding a SECURITY.md file and ensuring dependency versions are regularly audited. The repository appropriately warns against using Ruby's Timeout module and promotes proper timeout configuration across multiple gems.

• Low · Educational Repository with No Production Code — Repository root. This is an educational/reference repository documenting timeout configurations for Ruby gems. It does not contain production code, dependencies, or deployment configurations that could introduce security risks. Fix: No action required. This is by design as a reference guide.
• Low · Missing SECURITY.md File — Repository root. The repository lacks a SECURITY.md file that would provide security vulnerability reporting guidelines and contact information. Fix: Add a SECURITY.md file with instructions for responsibly disclosing security vulnerabilities.
• Low · Potentially Outdated Dependencies in Gemfiles — Appraisals, gemfiles/ directory. The gemfiles reference numerous Ruby gems (acme_client, aws_sdk, elasticsearch, etc.). Without access to version specifications in the Appraisals or gemfiles, there is a potential risk of outdated dependencies with known vulnerabilities. Fix: Ensure all gemfile versions are pinned to secure versions. Use bundle audit regularly to check for known vulnerabilities in dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.