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/ribbon 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 5mo ago
• 12 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Concentrated ownership — top contributor handles 56% 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 Netflix/ribbon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Netflix/ribbon.

What it runs against: a local clone of Netflix/ribbon — 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/ribbon | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 173 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "ribbon-core/src/main/java/com/netflix/client/IClient.java" \\
  && ok "ribbon-core/src/main/java/com/netflix/client/IClient.java" \\
  || miss "missing critical file: ribbon-core/src/main/java/com/netflix/client/IClient.java"
test -f "ribbon-core/src/main/java/com/netflix/client/config/IClientConfig.java" \\
  && ok "ribbon-core/src/main/java/com/netflix/client/config/IClientConfig.java" \\
  || miss "missing critical file: ribbon-core/src/main/java/com/netflix/client/config/IClientConfig.java"
test -f "ribbon-core/src/main/java/com/netflix/client/ClientRequest.java" \\
  && ok "ribbon-core/src/main/java/com/netflix/client/ClientRequest.java" \\
  || miss "missing critical file: ribbon-core/src/main/java/com/netflix/client/ClientRequest.java"
test -f "ribbon-archaius/src/main/java/com/netflix/client/config/ArchaiusClientConfigFactory.java" \\
  && ok "ribbon-archaius/src/main/java/com/netflix/client/config/ArchaiusClientConfigFactory.java" \\
  || miss "missing critical file: ribbon-archaius/src/main/java/com/netflix/client/config/ArchaiusClientConfigFactory.java"
test -f "ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.java" \\
  && ok "ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.java" \\
  || miss "missing critical file: ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.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 173 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~143d)"
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/ribbon"
  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).

Ribbon is a client-side Inter-Process Communication (IPC) library that provides software-based load balancing, fault tolerance, and retry logic for distributed systems. It enables REST calls with pluggable serialization schemes (HTTP, TCP, UDP) and integrates with Netflix's Eureka service registry and Hystrix circuit breaker patterns to make RPC calls resilient and efficient across cloud infrastructure. Multi-module Gradle monorepo with ribbon-core as the shared foundation (IClient, ClientRequest, RetryHandler interfaces in ribbon-core/src/main/java/com/netflix/client/), ribbon-archaius for Archaius-based configuration (DefaultClientConfigImpl, ArchaiusPropertyResolver), ribbon-loadbalancer for server selection logic, ribbon-eureka for dynamic service discovery integration, and ribbon-httpclient for HTTP transport. Each module has its own build.gradle and follows com.netflix.* package naming.

Java backend engineers at Netflix and other organizations building microservices that need client-side load balancing without deploying separate infrastructure; specifically those integrating with Eureka-based service discovery or needing fine-grained control over retry behavior and server selection per-request.

Production-ready but in maintenance mode. Netflix deploys ribbon-core, ribbon-loadbalancer, and ribbon-eureka at scale in production; however, Netflix has stated they are not adding new functionality and wrapped these components internally. The project has 1.3M+ lines of Java code, established CI/CD via Gradle/Nebula, and structured module organization, but external contribution velocity is intentionally low per Netflix's stated maintenance posture.

Low risk for consuming existing functionality (it's production-proven), but high risk for new feature development: Netflix explicitly states large feature requests won't be prioritized, and newer components like ribbon-transport and ribbon-httpclient (non-SSL parts) are not actively maintained. Dependency on Archaius (ribbon-archaius/src) for dynamic configuration and RxNetty for transport adds transitive risk if those libraries diverge. Last commit activity and open issue backlog are not visible in provided data, requiring manual verification.

The project is in maintenance mode with no active feature development. CI workflows exist (gradle-wrapper-validation.yml, nebula-ci.yml, nebula-publish.yml, nebula-snapshot.yml) suggesting automated builds and releases, but the README explicitly states Netflix has frozen new functionality and wrapped Ribbon components internally for their own use.

git clone https://github.com/Netflix/ribbon.git && cd ribbon && ./gradlew build (or gradlew.bat on Windows). Java 8+ is required per gradle.properties. Maven dependencies are published to Maven Central; alternatively add com.netflix.ribbon:ribbon:2.2.2 to your project.

Daily commands: No runnable server. Ribbon is a client library. Run tests via ./gradlew test or integrate into your own application via Maven/Gradle dependency on com.netflix.ribbon:ribbon or specific submodules. See ribbon-example/ for example usage (not detailed in file list provided).

• ribbon-core/src/main/java/com/netflix/client/IClient.java — Core interface defining the contract for all client implementations; essential to understand how requests are routed and executed across the framework.
• ribbon-core/src/main/java/com/netflix/client/config/IClientConfig.java — Configuration abstraction that every contributor must understand to properly configure load balancing, retry, and timeout behavior.
• ribbon-core/src/main/java/com/netflix/client/ClientRequest.java — Request envelope class that carries metadata and routing information through the entire IPC pipeline.
• ribbon-archaius/src/main/java/com/netflix/client/config/ArchaiusClientConfigFactory.java — Factory integrating Archaius for dynamic property resolution; critical for understanding how configuration is wired at runtime.
• ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.java — Primary integration point between Eureka service discovery and Ribbon's load balancer; required for any dynamic server list implementation.
• build.gradle — Multi-module Gradle build definition showing module relationships and dependency structure across ribbon-core, ribbon-eureka, ribbon-archaius.
• ribbon-core/src/main/java/com/netflix/client/RetryHandler.java — Contract for retry logic and fault tolerance strategy; critical for implementing resilience patterns in this IPC framework.

Add a New Retry Strategy

1. Implement the RetryHandler interface defining your retry logic, backoff strategy, and which exceptions to retry (ribbon-core/src/main/java/com/netflix/client/RetryHandler.java)
2. Register your implementation in client configuration via CommonClientConfigKey property (ribbon-core/src/main/java/com/netflix/client/config/CommonClientConfigKey.java)
3. Wire your handler into the client's request execution pipeline via IClient implementation (ribbon-core/src/main/java/com/netflix/client/IClient.java)

Add a New Load Balancing Rule

1. Create a new server list provider extending the discovery pattern or static list pattern (ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.java)
2. Implement a health check mechanism by extending the ping interface used in NIWSDiscoveryPing (ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/NIWSDiscoveryPing.java)
3. Register your rule in CommonClientConfigKey and wire into IClient implementation (ribbon-core/src/main/java/com/netflix/client/config/CommonClientConfigKey.java)

Add Dynamic Configuration for a New Feature

1. Define a new configuration key in CommonClientConfigKey with appropriate type and default value (ribbon-core/src/main/java/com/netflix/client/config/CommonClientConfigKey.java)
2. Create a Property or FallbackProperty wrapper in your config implementation to enable dynamic resolution (ribbon-core/src/main/java/com/netflix/client/config/Property.java)
3. In ArchaiusClientConfigFactory, bind your new key to an Archaius property for runtime updates (ribbon-archaius/src/main/java/com/netflix/client/config/ArchaiusClientConfigFactory.java)
4. Access the config value in your IClient or handler implementation (ribbon-core/src/main/java/com/netflix/client/IClient.java)

Integrate a New Service Discovery Backend

1. Create a new server list provider similar to DiscoveryEnabledNIWSServerList for your discovery system (ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/DiscoveryEnabledNIWSServerList.java)
2. Implement health checks specific to your backend, following the pattern in NIWSDiscoveryPing (ribbon-eureka/src/main/java/com/netflix/niws/loadbalancer/NIWSDiscoveryPing.java)
3. Create a new module (e.g., ribbon-myservice) with build.gradle dependencies and metadata provider (ribbon-eureka/build.gradle)
4. Register your provider via META-INF services or direct dependency injection (ribbon-eureka/src/main/resources/META-INF/services)

• Archaius (Netflix config library) — Provides dynamic property resolution without application restart, critical for adjusting timeouts, retry policies, and load balancer rules in cloud environments
• Eureka (Netflix service discovery) — Enables automatic server list population from a service registry, eliminating hardcoded endpoints and supporting auto-scaling
• RxNetty (Reactive network I/O) — Provides asynchronous and non-blocking HTTP/TCP/UDP communication, essential for handling high concurrency in cloud IPC
• Gradle with Nebula plugin — Standardizes multi-module builds across Netflix's ecosystem and automates versioning and publishing workflows
• Apache HttpClient — Battle-tested HTTP implementation with mature connection pooling and SSL support, wrapped by ribbon-httpclient module

• Abstract IClient interface over concrete HTTP/TCP/UDP implementations

  • Why: Allows clients to plug in different protocols and transports without changing application code
  • Consequence: Increases abstraction layers and makes debugging across protocol boundaries more complex

• Configuration via Archaius dynamic properties

  • Why: undefined
  • Consequence: undefined

1. Archaius dependency: ribbon-archaius uses Archaius for dynamic configuration; if Archaius properties are not configured, clients will use defaults. 2) VIP address vs hostname: SimpleVipAddressResolver.java and VipAddressResolver interface expect VIP (Virtual IP) format; Eureka integration in ribbon-eureka must resolve VIPs correctly. 3) Java 8 only: gradle.properties enforces Java 8 (languageVersion = 8); build will fail on Java 9+ without adjustment. 4) No built-in metrics/observability in core; Netflix wraps Ribbon with internal tracing—OSS version lacks observability hooks. 5) Retry handler state: RequestSpecificRetryHandler vs DefaultLoadBalancerRetryHandler can be set per-request; configuration precedence is non-obvious without reading code.

• Software Load Balancing (Client-Side) — Ribbon's core value: server selection logic runs in the client JVM, not a separate proxy, reducing infrastructure dependencies and enabling per-request routing decisions based on request-specific metadata
• Retry Handler Pattern — RequestSpecificRetryHandler and DefaultLoadBalancerRetryHandler encapsulate retry logic per-client or per-request; understanding when to retry (transient vs permanent failures) is critical for reliability in distributed systems
• Virtual IP (VIP) Address Resolution — Ribbon and Netflix Eureka use VIP (e.g., 'my-service.vip.com') as a logical service identifier; SimpleVipAddressResolver and VipAddressResolver convert VIPs to actual server lists; essential for understanding Ribbon's service discovery model
• Dynamic Configuration (Archaius) — ArchaiusPropertyResolver enables runtime updates to client config (timeouts, retry counts, server lists) without restarting; Ribbon's integration with Archaius is what allows Netflix to reconfigure load balancers on-the-fly at scale
• Pluggable Serialization Schemes — Ribbon abstracts transport and serialization; IClient interface does not mandate JSON/XML, allowing custom protocols (Protobuf, Thrift, etc.); ribbon-transport and ribbon-httpclient are separate implementations
• Circuit Breaker Pattern (Hystrix Integration) — Top-level ribbon module integrates Hystrix to fail-fast when a service is degraded; prevents cascading failures across distributed systems by rejecting requests to unhealthy servers
• Service Provider Interface (SPI) for Configuration — ribbon-archaius/src/main/resources/META-INF/services/com.netflix.client.config.ClientConfigFactory uses Java SPI to auto-discover and register ArchaiusClientConfigFactory; allows swapping config implementations without code changes

• Netflix/eureka — Companion library for dynamic service discovery; ribbon-eureka integrates Eureka clients to populate server lists automatically
• Netflix/hystrix — Sibling circuit-breaker library that Ribbon integrates with for fault tolerance; top-level ribbon module uses Hystrix patterns
• Netflix/archaius — Configuration management library that ribbon-archaius depends on for dynamic property resolution and application-wide config management
• Netflix/RxNetty — Async networking library used by ribbon-transport for HTTP, TCP, UDP transport with RxJava; enables non-blocking RPC calls
• grpc/grpc-java — Modern alternative to Ribbon for RPC; Google Cloud and CNCF standard that replaces Ribbon's role in new microservice architectures

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 unit tests for ribbon-archaius configuration module

The ribbon-archaius module provides critical dynamic configuration via Archaius integration (ArchaiusClientConfigFactory.java, ArchaiusPropertyResolver.java, DefaultClientConfigImpl.java), but the file structure shows no visible test directory. This is a core feature for runtime configuration changes in distributed systems. Adding tests would ensure configuration hot-reloading, property resolution, and factory initialization work correctly across version updates.

• [ ] Create ribbon-archaius/src/test/java/com/netflix/client/config/ directory structure
• [ ] Add ArchaiusPropertyResolverTest.java with tests for property resolution, fallbacks, and dynamic updates
• [ ] Add ArchaiusClientConfigFactoryTest.java with tests for factory initialization and SPI discovery
• [ ] Add DefaultClientConfigImplTest.java with tests for config merging and property precedence
• [ ] Add integration test for ScheduledThreadPoolExectuorWithDynamicSize.java thread pool resizing behavior

Add GitHub Actions workflow for Java 11+ compatibility testing

The build.gradle specifies Java 8 as the toolchain target, but Netflix's production environments likely use Java 11+. Currently only nebula-ci.yml workflow exists. Adding a dedicated compatibility matrix test would catch breaking changes early, especially for SSL/TLS handling in ribbon-core/src/main/java/com/netflix/client/ssl/ which varies significantly across Java versions.

• [ ] Create .github/workflows/java-compatibility-matrix.yml workflow
• [ ] Configure matrix strategy to test against Java 8, 11, 17, and 21 LTS versions
• [ ] Run full gradle test suite for each version to validate AbstractSslContextFactory.java and URLSslContextFactory.java across versions
• [ ] Add workflow trigger for pull requests and main branch pushes
• [ ] Document Java version support matrix in README.md

Add integration tests for RetryHandler implementations and retry configuration

The ribbon-core module contains critical retry logic (DefaultLoadBalancerRetryHandler.java, RequestSpecificRetryHandler.java, RetryHandler.java interface) but no visible test suite demonstrates retry behavior under various failure scenarios. This is essential for fault tolerance validation—users need confidence that retries work correctly with circuit breakers, timeouts, and different exception types.

• [ ] Create ribbon-core/src/test/java/com/netflix/client/ directory structure
• [ ] Add DefaultLoadBalancerRetryHandlerTest.java testing max retries, retry eligibility per exception type, and next server selection
• [ ] Add RequestSpecificRetryHandlerTest.java testing per-request override behavior
• [ ] Add integration test simulating ClientException.java scenarios with IClient.java implementations
• [ ] Add test for ClientRequest.java retry-related properties and their interaction with RetryHandler

• Add integration tests for ArchaiusPropertyResolver.java demonstrating dynamic property updates at runtime; currently no test files listed in ribbon-archaius/src/test/.
• Document the exact precedence order for client configuration (per-request ClientRequest settings vs AbstractDefaultClientConfigImpl defaults vs Archaius property overrides) in a new ribbon-core/docs/CONFIG_PRECEDENCE.md guide.
• Create a simple example in ribbon-example/ showing retry handler customization (extending RequestSpecificRetryHandler with custom logic for specific error codes) since the existing code structure supports it but no example is visible.

• High · Outdated Gradle Wrapper Version — gradle/wrapper/gradle-wrapper.jar, gradle/wrapper/gradle-wrapper.properties. The gradle-wrapper.jar file present in the repository indicates use of Gradle wrapper. Wrapper versions can become outdated and may contain known vulnerabilities. The gradle/wrapper/gradle-wrapper.properties file should be checked to verify the Gradle version is current and patched. Fix: Update to the latest stable Gradle version using './gradlew wrapper --gradle-version=X.X.X' and verify the wrapper properties specify a secure, up-to-date version.
• High · Dependency Version Management Not Explicitly Defined — build.gradle, ribbon-eureka/build.gradle, ribbon-core/build.gradle. The build.gradle file shows dependency management through Nebula plugin but specific versions for core dependencies (Eureka client, Hystrix, etc.) are not visible in the provided content. Without explicit version pinning, transitive dependencies could pull in vulnerable versions. Fix: Implement explicit dependency version management using 'dependencyManagement' or 'constraints' block. Run './gradlew dependencyUpdates' regularly and use './gradlew checkstyle' with security checks enabled.
• Medium · SSL Context Factory Potential Certificate Validation Issues — ribbon-core/src/main/java/com/netflix/client/ssl/URLSslContextFactory.java, ribbon-core/src/main/java/com/netflix/client/ssl/AbstractSslContextFactory.java. The presence of URLSslContextFactory.java and AbstractSslContextFactory.java suggests custom SSL handling. These classes could have improper certificate validation, hostname verification disabled, or support for outdated TLS versions if not properly implemented. Fix: Review SSL context factory implementations to ensure: TLS 1.2+ is enforced, certificate chain validation is enabled, hostname verification is mandatory, and no deprecated algorithms are supported. Use OWASP guidelines for Java SSL/TLS configuration.
• Medium · Potential Deserialization Vulnerability in RPC Library — ribbon-core (general), ribbon-eureka (general). As an IPC/RPC library with multiple serialization scheme support, Ribbon could be vulnerable to insecure deserialization attacks if user-supplied data is deserialized without proper validation. The README mentions serialization scheme support but specific implementations are not visible. Fix: Ensure all deserialization operations: use allow-lists for permitted classes, disable Java serialization if possible in favor of safer formats (JSON, Protocol Buffers), validate and sanitize input before deserialization, implement integrity checks (HMAC/signatures).
• Medium · Retry Handler Configuration Exposure — ribbon-core/src/main/java/com/netflix/client/DefaultLoadBalancerRetryHandler.java, ribbon-core/src/main/java/com/netflix/client/RequestSpecificRetryHandler.java. DefaultLoadBalancerRetryHandler and RequestSpecificRetryHandler classes suggest configurable retry logic. Improper retry configurations could be exploited for denial of service or to amplify attacks through retry storms. Fix: Verify retry handlers implement maximum retry limits, exponential backoff with jitter, rate limiting, and circuit breaker patterns. Ensure default configurations are secure and prevent retry amplification attacks.
• Medium · Dynamic Thread Pool Executor Configuration — ribbon-archaius/src/main/java/com/netflix/utils/ScheduledThreadPoolExectuorWithDynamicSize.java. ScheduledThreadPoolExectuorWithDynamicSize (note: typo in class name) suggests dynamic sizing of thread pools. Dynamic configuration from external sources (Archaius) without proper validation could lead to resource exhaustion or DoS vulnerabilities. Fix: Implement strict bounds checking on dynamically configured thread pool sizes (min/max limits), add monitoring/alerting for unusual pool size changes, validate configuration changes before applying them.
• Low · Exposed Service Provider Interface Files — ribbon-core/src/resources/META-INF/services/com.netflix.client.config.ClientConfigFactory, ribbon-archaius/src/main/resources/META-INF/services/com.netflix.client.config. META-INF/services files are world-readable and could potentially reveal internal service implementations, though this is by design for SPI. Configuration factory implementations are exposed through these files. Fix: undefined

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.