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/Netflix/Hystrix 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.

WAIT — Slowing — last commit 5mo ago

• Last commit 5mo ago
• 26+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ No license — legally unclear to depend on

_{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 Netflix/Hystrix repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Netflix/Hystrix.

What it runs against: a local clone of Netflix/Hystrix — 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 Netflix/Hystrix | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 172 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Netflix/Hystrix. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Netflix/Hystrix.git
#   cd Hystrix
#
# 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 Netflix/Hystrix and re-run."
  exit 2
fi

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

# 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 "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f "hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java" \\
  && ok "hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java" \\
  || miss "missing critical file: hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java"
test -f "hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java" \\
  && ok "hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java" \\
  || miss "missing critical file: hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java"
test -f "hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java" \\
  && ok "hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java" \\
  || miss "missing critical file: hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 172 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~142d)"
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/Netflix/Hystrix"
  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).

Hystrix is a latency and fault-tolerance library for Java that isolates access to remote services and dependencies via circuit breakers, timeouts, and thread/semaphore pooling to prevent cascading failures in distributed systems. It wraps synchronous and asynchronous calls with bulkheads (thread pools or semaphores) and automatically triggers fallbacks when services degrade, stop cascading failures before they spread across your service mesh. Multi-module Gradle monorepo: hystrix-core contains the circuit breaker engine and command/request abstractions; hystrix-contrib houses optional integrations (hystrix-clj for Clojure, hystrix-codahale-metrics-publisher for metrics export). CI workflows (nebula-.yml) drive builds and Maven Central publishing. Metrics are published via HystrixCodaHaleMetricsPublisher classes and Codahale Metrics integration.

Backend Java engineers at companies running microservices architectures (especially those managing Netflix-scale infrastructure) who need to add resilience to HTTP clients, database calls, and third-party API integrations without rewriting business logic. DevOps and SRE teams monitoring distributed system health.

Hystrix is stable but officially in maintenance mode as of v1.5.18 (final release). Netflix shifted focus to adaptive implementations like resilience4j. The codebase shows enterprise-grade maturity: multi-language support (Java, Clojure), CI/CD via GitHub Actions (nebula-ci.yml, nebula-publish.yml), comprehensive test suites, and codequality checks (checkstyle.xml). However, no active development — pull requests are not being merged and issues are not reviewed by Netflix maintainers.

Critical risk: project is in maintenance mode with no active development from Netflix. Community takeover (hystrixoss@googlegroups.com) has not materialized. Dependency security patches may lag, and breaking changes in Java/library ecosystem are not addressed. The recommendation in README explicitly points users toward resilience4j for new projects. Production use is safe for stable workloads, but greenfield projects should seriously evaluate alternatives.

No active development. The repository is frozen at v1.5.18. GitHub workflows (nebula-ci.yml, nebula-snapshot.yml, nebula-publish.yml) still run but only for snapshot/release automation, not feature work. The CHANGELOG.md and maintenance-mode README indicate this is a stable holding pattern, not an evolving project.

git clone https://github.com/Netflix/Hystrix.git
cd Hystrix
./gradlew build
./gradlew test

Gradlew wrapper (gradlew, gradlew.bat) handles Gradle setup. JDK 8+ required. Check gradle.properties for Gradle version.

Daily commands:

./gradlew build          # Compile all modules
./gradlew test           # Run unit/integration tests
./gradlew assemble       # Build all JARs without running tests
./gradlew publishToMavenLocal  # Publish to local Maven repo for local testing

No dev server — this is a library, not an application. Examples live in hystrix-examples (check GitHub for runnable demo projects).

• README.md — Project overview explaining Hystrix is in maintenance mode; critical for understanding project status and recommendations to use resilience4j for new projects
• build.gradle — Root build configuration using Nebula Netflix OSS plugin; defines all subproject dependencies and build structure that all contributors must understand
• hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java — Core annotation interface for marking methods as Hystrix commands; primary API entry point that contributors extending Hystrix functionality must understand
• hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java — AspectJ weaving implementation that intercepts @HystrixCommand annotations; load-bearing infrastructure for annotation-based Hystrix integration
• hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java — Core metrics publisher for Codahale integration; demonstrates the metrics publishing pattern used throughout contrib modules
• CHANGELOG.md — Version history and migration guide; essential for understanding breaking changes and deprecations in the maintenance-mode project
• gradle.properties — Project version and build properties; single source of truth for versioning across all subprojects

Add a new Hystrix Command with Annotation-based Configuration

1. Define a service class with a method annotated with @HystrixCommand from hystrix-javanica (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java)
2. Configure properties (timeout, thread pool size, circuit breaker thresholds) via @HystrixProperty annotations or DefaultProperties (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixProperty.java)
3. Implement a fallback method and reference it via fallbackMethod parameter in @HystrixCommand (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java)
4. Enable AspectJ weaving in your build.gradle to enable interception at compile-time or load-time (hystrix-contrib/hystrix-javanica/build.gradle)
5. Write tests using ajcTest source set to verify command execution, timeouts, and fallback invocation (hystrix-contrib/hystrix-javanica/src/ajcTest/java/com/netflix/hystrix/contrib/javanica/test/aspectj/command/CommandTest.java)

Integrate Codahale Metrics Publishing for Monitoring

1. Add hystrix-codahale-metrics-publisher dependency to your project's build.gradle (hystrix-contrib/hystrix-codahale-metrics-publisher/build.gradle)
2. Instantiate HystrixCodaHaleMetricsPublisher and register it with Hystrix's metrics system at application startup (hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java)
3. Optionally configure metric filtering using ConfigurableCodaHaleMetricFilter to exclude low-priority metrics (hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/ConfigurableCodaHaleMetricFilter.java)
4. Verify metrics collection with integration tests similar to HystrixCodaHaleMetricsPublisherCommandTest (hystrix-contrib/hystrix-codahale-metrics-publisher/src/test/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisherCommandTest.java)

Add a Request Collapser for Batch Processing

1. Annotate a method that accepts individual requests with @HystrixCollapser to enable batching (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCollapser.java)
2. Implement a separate method annotated with @HystrixCommand that processes the batched list of requests (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixCommand.java)
3. Configure collapser properties (batch size, time window) via @HystrixProperty on the collapser annotation (hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/annotation/HystrixProperty.java)
4. Test collapser behavior with ajcTest to verify requests are batched and results mapped correctly (hystrix-contrib/hystrix-javanica/src/ajcTest/java/com/netflix/hystrix/contrib/javanica/test/aspectj/collapser/CollapserTest.java)

1) Maintenance mode stasis: Code builds and tests pass, but pull requests are not merged. Do not expect bug fixes or security patches from Netflix. 2) Version lock: Final release is v1.5.18; do not expect version bumps. 3) Java 8+ requirement: Older JDKs will fail gradle build. 4) Gradle wrapper versioning: gradle/wrapper/gradle-wrapper.properties pins Gradle version; do not manually override without testing. 5) Clojure contrib instability: hystrix-clj may have outdated Clojure dependencies; check compatibility before using in new Clojure projects. 6) Netflix Nebula plugin quirks: Build uses com.netflix.nebula.netflixoss which has opinionated defaults for publishing; if you fork, understand the plugin's manifest/signing setup or builds may fail.

• Circuit Breaker Pattern — Core pattern in Hystrix; state machine (CLOSED/OPEN/HALF_OPEN) that prevents cascading failures by fast-failing when downstream services degrade
• Thread Pool / Semaphore Bulkheading — Hystrix isolates each service dependency in its own thread pool or semaphore to prevent resource exhaustion from one failing dependency starving the whole application
• Request Collapsing — Hystrix aggregates multiple concurrent requests for the same resource into a single backend call, reducing latency and load on dependent services
• Fallback / Graceful Degradation — Instead of failing hard, Hystrix allows commands to return fallback values (cached data, default responses) when primary logic times out or circuit opens
• Rolling Window Metrics Aggregation — Hystrix tracks success/failure/latency in rolling time windows (e.g., 10-second windows with 1-second buckets) to compute circuit breaker thresholds and publish health metrics
• Semaphore Isolation — Lightweight alternative to thread pool bulkheading; Hystrix can cap concurrent calls via java.util.concurrent.Semaphore for I/O-bound (not CPU-bound) dependencies
• Coda Hale Metrics Integration — Hystrix exports circuit breaker state, latency percentiles, and thread pool stats via Codahale Metrics for integration with monitoring stacks (Graphite, CloudWatch, datadog)

• resilience4j/resilience4j — Direct successor recommended by Netflix; lightweight, functional Java 8+ library with circuit breaker, retry, bulkhead, and rate limiter patterns inspired by Hystrix
• grpc-ecosystem/go-grpc — gRPC's built-in interceptors and circuit breaker patterns serve similar isolation/fault-tolerance goals for microservices in Go/Python/Java polyglot environments
• Netflix/Ribbon — Companion Netflix library for client-side load balancing; often paired with Hystrix for intelligent request routing and failover in distributed systems
• spring-cloud/spring-cloud-circuitbreaker — Spring's abstraction layer providing pluggable circuit breaker implementations (Hystrix, resilience4j, others); standard for Spring Boot microservices
• sentinel-group/sentinel — Alibaba's high-performance circuit breaker and concurrency limiter; alternative to Hystrix for high-throughput systems with adaptive flow control

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 integration tests for hystrix-codahale-metrics-publisher

The hystrix-codahale-metrics-publisher module has only 2 test files (ConfigurableCodaHaleMetricFilterTest.java and HystrixCodaHaleMetricsPublisherCommandTest.java) but 5 main implementation classes. The HystrixCodaHaleMetricsPublisherCollapser.java and HystrixCodaHaleMetricsPublisherThreadPool.java classes lack corresponding test coverage. This is critical for a metrics publisher that integrates with production monitoring systems.

• [ ] Create hystrix-contrib/hystrix-codahale-metrics-publisher/src/test/java/.../HystrixCodaHaleMetricsPublisherCollapserTest.java with tests for collapser-specific metrics
• [ ] Create hystrix-contrib/hystrix-codahale-metrics-publisher/src/test/java/.../HystrixCodaHaleMetricsPublisherThreadPoolTest.java with threadpool metrics validation
• [ ] Add integration test verifying end-to-end metric flow from command execution through CodaHale registry

Add unit tests for hystrix-clj Clojure wrapper core functionality

The hystrix-clj module (hystrix-contrib/hystrix-clj/src/main/clojure/com/netflix/hystrix/core.clj) provides Clojure language bindings but has minimal test coverage in core_test.clj. Given Clojure's functional nature, edge cases around exception handling, timeout behavior, and async execution patterns in the wrapper need explicit verification to ensure interop stability.

• [ ] Expand hystrix-contrib/hystrix-clj/src/test/clojure/.../core_test.clj with tests for timeout scenarios and exception propagation
• [ ] Add tests for async/future handling in Clojure wrappers to verify proper thread pool behavior
• [ ] Add property-based tests (using test.check) for command execution under varying load patterns

Create GitHub Actions workflow for multi-version Java compatibility testing

The .github/workflows directory has nebula-ci.yml, nebula-publish.yml, and nebula-snapshot.yml but no explicit Java version matrix testing. Given Hystrix's 1.5.18 maintenance status and broad adoption across Java versions, a workflow testing against Java 8, 11, 17, and 21 LTS versions would catch compatibility regressions early and increase contributor confidence.

• [ ] Create .github/workflows/java-compatibility.yml with matrix strategy testing Java versions [8, 11, 17, 21]
• [ ] Configure workflow to run ./gradlew build test for each Java version on pull requests
• [ ] Add workflow output documenting which Java versions passed/failed for visibility in PR reviews

• Add missing integration tests for HystrixCircuitBreaker state transitions: The state machine (CLOSED → OPEN → HALF_OPEN → CLOSED) lacks comprehensive edge-case tests for rapid failure spikes and recovery timing. Write tests in hystrix-core/src/test/java/ covering timeout-based state recovery and success-based healing.
• Document Clojure API examples in hystrix-contrib/hystrix-clj/README.md: The Clojure wrapper exists but README has no runnable code samples. Add concrete examples showing defcommand macro usage, fallback definition, and error handling compared to Java equivalents.
• Add JMH benchmarks for thread pool vs. semaphore isolation: build.gradle includes me.champeau.jmh plugin but no benchmarks are committed. Create hystrix-core/src/jmh/java/ with latency/throughput comparisons of HystrixThreadPool vs. HystrixSemaphore isolation strategies under load.

The Netflix Hystrix codebase shows a reasonable security posture for a maintenance-mode project. No critical vulnerabilities were identified in the provided file structure and configuration. The primary concerns are: (1) the project's maintenance-mode status which limits security update frequency, (2) outdated build plugin versions that should be verified for CVEs, (3) the gradle-wrapper.jar binary artifact requiring integrity verification, and (4) suppressed Javadoc build errors that could mask issues. The build system relies on Maven Central, which is a secure practice. No hardcoded credentials, SQL injection risks, XSS vulnerabilities, or container configuration issues were found in the provided materials. Organizations using Hystrix should monitor security advisories closely and evaluate migration to actively maintained alternatives like resilience4j.

• Medium · Outdated Gradle Build Plugin — build.gradle - plugins block. The Nebula NetflixOSS plugin version 11.3.1 is used, which may contain known vulnerabilities. Gradle plugins should be kept up-to-date to receive security patches. Additionally, the JMH plugin version 0.7.1 should be verified for known CVEs. Fix: Update to the latest stable versions of 'com.netflix.nebula.netflixoss' and 'me.champeau.jmh' plugins. Run 'gradle dependencyUpdates' to identify outdated dependencies.
• Medium · Gradle Wrapper JAR Security — gradle/wrapper/gradle-wrapper.jar. The gradle-wrapper.jar file is a binary artifact that is typically checked into version control. If the wrapper is compromised, all builds could be affected. The wrapper version should be verified and the JAR should be kept updated. Fix: Verify the integrity of gradle-wrapper.jar against official Gradle releases. Consider implementing build verification steps. Update the Gradle wrapper to the latest stable version using 'gradle wrapper --gradle-version=<latest>'.
• Low · Javadoc Build Failure Suppression — build.gradle - tasks.withType(Javadoc).configureEach block. The build configuration sets 'failOnError = false' for Javadoc tasks, which may mask documentation generation errors or security-related warnings that should be addressed. Fix: Investigate why Javadoc failures need to be suppressed. Fix underlying Javadoc errors and enable strict error reporting: change 'failOnError = false' to 'failOnError = true'.
• Low · Repository Configuration — build.gradle - repositories block. Only Maven Central is configured as a repository. While this is generally safe, ensure that no external or untrusted repositories are added during dependency resolution. The configuration lacks repository authentication controls. Fix: Continue using only Maven Central for releases. If private repositories are needed, configure proper authentication and verification mechanisms. Consider using repository mirrors or proxies to control dependency sources.
• Low · Maintenance Mode Project — README.md - Hystrix Status section. The project README explicitly states 'Hystrix is no longer in active development, and is currently in maintenance mode.' This means security patches and updates may be delayed or not applied. Applications using this library should plan migration to actively maintained alternatives. Fix: For new projects, consider using actively maintained alternatives like resilience4j. For existing applications using Hystrix, establish a security monitoring and patching schedule. Plan a gradual migration to successor libraries.

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.