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/apache/dubbo 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 4d ago
• 14 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 85% 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 apache/dubbo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/dubbo.

What it runs against: a local clone of apache/dubbo — 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 apache/dubbo | 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 3.3 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/dubbo(\\.git)?\\b" \\
  && ok "origin remote is apache/dubbo" \\
  || miss "origin remote is not apache/dubbo (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 3.3 >/dev/null 2>&1 \\
  && ok "default branch 3.3 exists" \\
  || miss "default branch 3.3 no longer exists"

# 4. Critical files exist
test -f "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ClusterInvoker.java" \\
  && ok "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ClusterInvoker.java" \\
  || miss "missing critical file: dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ClusterInvoker.java"
test -f "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Directory.java" \\
  && ok "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Directory.java" \\
  || miss "missing critical file: dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Directory.java"
test -f "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java" \\
  && ok "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java" \\
  || miss "missing critical file: dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java"
test -f "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java" \\
  && ok "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java" \\
  || miss "missing critical file: dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java"
test -f "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Configurator.java" \\
  && ok "dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Configurator.java" \\
  || miss "missing critical file: dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Configurator.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 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
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/apache/dubbo"
  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).

Apache Dubbo is a production-grade Java RPC and microservices framework that enables high-performance inter-service communication via protocols like Triple (gRPC-compatible), TCP/Dubbo2, and REST. It provides service discovery, dynamic routing, load balancing, traffic management, and observability features—allowing teams to build distributed systems with minimal boilerplate using Spring Boot integration or lightweight RPC APIs. Multi-module Maven monorepo organized by functional domain: dubbo-cluster/ handles clustering and routing logic, dubbo-rpc-api/ defines core RPC abstractions, protocol implementations live in their own modules (Dubbo-3.3 supports Triple, Dubbo2, REST). The registry and router logic is separated; ClusterInvoker and Cluster interfaces in dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ form the core load-balancing contract.

Java microservices architects and backend engineers building enterprise-grade distributed systems who need service discovery, dynamic routing, load balancing, and observability without managing complex infrastructure. Also relevant for teams migrating from monoliths or adopting cloud-native architectures with Kubernetes/Nacos/Zookeeper.

Highly mature and production-ready. Active development with multiple branch versions (3.1, 3.2, 3.3 visible in CI workflows), comprehensive CI/CD pipeline (.github/workflows/), Maven-based project structure, Apache Foundation backing, and clear versioning strategy. Actively maintained with recent features (Triple protocol, Spring Boot 3 support) and scheduled build tests across multiple versions.

Low risk for core functionality; heavy reliance on Java ecosystem stability and complex distributed system semantics (network failures, clock skew, etc.). Main risks: monorepo size (18M+ lines of Java) means changes ripple broadly; potential for breaking changes across major versions; dependency on external registries (Zookeeper, Nacos) adds operational complexity. However, Apache governance and extensive test coverage mitigate most concerns.

Active development across 3.1, 3.2, and 3.3 branches (evidenced by scheduled CI workflows for each). Focus areas appear to be Triple protocol maturity, Spring Boot 3 compatibility, and observability improvements (tracing, metrics). Build-and-test-pr.yml indicates continuous PR validation; Jenkinsfile.sonar suggests code quality gates are enforced.

git clone https://github.com/apache/dubbo.git
cd dubbo
# Review README for Maven version requirements
mvn clean install -DskipTests
# or for specific module testing:
mvn test -pl dubbo-cluster

Use Maven 3.6+ (inferred from .mvn/wrapper setup). Check .mvn/jvm.config for any JVM flag requirements.

Daily commands: Dubbo is a library framework, not a standalone service. To use it: add org.apache.dubbo:dubbo-spring-boot-starter to your Spring Boot pom.xml, configure service discovery in application.yml (registry URL, protocol), then annotate services with @DubboService and consumers with @DubboReference. Example: mvn spring-boot:run on a consumer module that imports Dubbo. See dubbo-samples/ repos for runnable examples.

• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ClusterInvoker.java — Core cluster invocation logic that orchestrates RPC calls across multiple providers with load balancing and fault tolerance
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Directory.java — Abstract service directory interface that manages provider discovery and routing chain initialization
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Router.java — Core router abstraction for request routing rules and provider filtering logic
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/LoadBalance.java — Load balancing strategy interface for distributing requests across available providers
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/Configurator.java — Configuration management interface for runtime service configuration overrides
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/ProtocolFilterWrapper.java — Filter chain builder that wraps protocol implementations with cross-cutting concerns like context, metrics, and classloading
• dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/RouterChain.java — Router composition container that chains multiple routing rules for hierarchical request filtering

Add a New Load Balancing Strategy

1. Create new load balance class extending AbstractLoadBalance in dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/loadbalance/ (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/loadbalance/YourLoadBalance.java)
2. Implement the doSelect() method returning selected invoker based on your algorithm (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/loadbalance/YourLoadBalance.java)
3. Register SPI via META-INF/dubbo/internal/org.apache.dubbo.rpc.cluster.LoadBalance file (META-INF/dubbo/internal/org.apache.dubbo.rpc.cluster.LoadBalance)
4. Use in configuration with loadbalance=yourname or set as default in cluster provider (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/loadbalance/AdaptiveLoadBalance.java)

Add a New Router for Request Filtering

1. Create router class implementing Router interface in dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/ (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/YourRouter.java)
2. Implement route() method to filter invoker list based on routing rules (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/YourRouter.java)
3. Create corresponding RouterFactory implementing RouterFactory interface (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/YourRouterFactory.java)
4. Register both via META-INF/dubbo/internal SPI files and configure routing rules via GovernanceRuleRepository (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/governance/GovernanceRuleRepository.java)

Add a New Filter for Cross-Cutting Concerns

1. Create filter class in dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/support/ extending Filter or ProtocolFilter (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/support/YourFilter.java)
2. Implement invoke() method to intercept invocations and apply cross-cutting logic (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/support/YourFilter.java)
3. Register via META-INF/dubbo/internal/org.apache.dubbo.rpc.Filter SPI (META-INF/dubbo/internal/org.apache.dubbo.rpc.Filter)
4. Filter is auto-applied by ProtocolFilterWrapper.buildInvokerChain() based on SPI ordering (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/ProtocolFilterWrapper.java)

Add a New Configuration Override Rule

1. Define rule model in dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/parser/model/ (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/parser/model/ConfigItem.java)
2. Create configurator class extending AbstractConfigurator with configure() implementation (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/override/OverrideConfigurator.java)
3. Implement ConfiguratorFactory to parse and create instances of your configurator (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/override/OverrideConfiguratorFactory.java)
4. Register factory via META-INF/dubbo/internal/org.apache.dubbo.rpc.cluster.ConfiguratorFactory and use ConfigParser to deserialize rules (dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/parser/ConfigParser.java)

1. Multi-version support: The monorepo maintains 3.1, 3.2, and 3.3 concurrently (visible in build workflows); PRs must target the correct branch or trigger builds on multiple versions. 2. Registry dependency: Most examples assume Zookeeper/Nacos is running; local development without a registry requires custom mock registries or in-JVM testing. 3. SPI loading: Dubbo uses Java SPI (META-INF/services/) for plugin discovery; custom implementations must be registered there to be loaded. 4. Protocol negotiation: Triple vs. Dubbo2 protocol differences are significant; serialization behavior differs and can cause subtle bugs. 5. Async-first API: RPC calls return CompletableFuture or reactive types in 3.x; blocking code is discouraged and may cause thread pool exhaustion.

• Service Invocation Abstraction (Invoker/Invocation) — Dubbo's core abstraction that represents a callable RPC target; understanding Invoker chains (filters, cluster wrappers) is essential to grasping how calls flow through load balancers and routers.
• Cluster Failover and Load Balancing Strategies — Dubbo's Cluster interface implements multiple failover modes (failfast, failover, failsafe, forking); knowing when each applies prevents silently dropped requests in production.
• Java SPI (Service Provider Interface) — Dubbo heavily uses Java SPI for plugin discovery (protocols, load balancers, routers, registries); understanding META-INF/services/ registration is mandatory for extending Dubbo.
• Router and Route Rule System — Dubbo's Router SPI allows dynamic traffic rules (e.g., route requests by tag, geographic region, or custom logic); critical for canary deployments and A/B testing in microservices.
• Protocol Abstraction (Triple/gRPC, Dubbo2, REST) — Dubbo abstracts transport protocols; Triple is gRPC-compatible with streaming and protobuf, while Dubbo2 is optimized for low-latency; protocol choice affects throughput, latency, and interoperability.
• CompletableFuture and Async RPC — Dubbo 3.x is async-first; RPC calls return CompletableFuture; synchronous code relies on blocking adapters, which can cause thread starvation under load.
• Service Registry and Dynamic Discovery — Dubbo integrates with registries (Zookeeper, Nacos, etc.) to dynamically discover provider instances; understanding registry events and address listeners is essential for handling instance churn.

• apache/dubbo-go — Official Go implementation of Dubbo; same protocol and service discovery model, enabling polyglot RPC in the same ecosystem.
• apache/dubbo-samples — Official example projects demonstrating Dubbo usage patterns (Spring Boot integration, Triple protocol, custom routers); essential reference for onboarding.
• alibaba/nacos — Popular service registry/config center deeply integrated with Dubbo for service discovery; many Dubbo deployments use Nacos instead of Zookeeper.
• apache/zookeeper — Classic registry backend for Dubbo service discovery; many legacy deployments rely on it.
• grpc/grpc-java — gRPC Java implementation; Dubbo's Triple protocol is gRPC-compatible and shares similar async RPC semantics and Protocol Buffer serialization.

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 RouterChain and SingleRouterChain

The dubbo-cluster module contains critical routing logic (RouterChain.java, SingleRouterChain.java, Router.java) that determines how requests are distributed. Currently, there's no evidence of dedicated integration tests for these components. These tests should verify router chaining, rule precedence, and edge cases like empty route lists or conflicting rules.

• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/RouterChainIntegrationTest.java
• [ ] Add test cases for sequential router execution, filter application, and state changes
• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/SingleRouterChainTest.java to test single-router scenarios
• [ ] Add tests for RuleConverter.java to ensure YAML/rule parsing works correctly
• [ ] Reference existing test patterns in the dubbo-cluster/src/test directory

Add Configurator implementation tests and edge case coverage

The configurator package (AbstractConfigurator.java, OverrideConfigurator.java, AbsentConfigurator.java, AbsentConfiguratorFactory.java) lacks visible test coverage for configuration merging, override logic, and factory instantiation. These are critical for dynamic configuration management in Dubbo.

• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/configurator/ConfiguratorFactoryTest.java to test factory pattern
• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/configurator/OverrideConfiguratorTest.java for override scenarios
• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/configurator/AbsentConfiguratorTest.java for absent-based configuration
• [ ] Add tests for URL merging, parameter overrides, and conflict resolution
• [ ] Verify ConfiguratorFactory.java correctly instantiates the right configurator types

Add LoadBalance algorithm implementation tests and benchmarks

LoadBalance.java is a critical SPI interface in dubbo-cluster with multiple implementations that determine request distribution. While implementations likely exist, there's no evidence of comprehensive algorithm-specific tests validating load distribution fairness, weight handling, and performance under different scenarios.

• [ ] Create dubbo-cluster/src/test/java/org/apache/dubbo/rpc/cluster/LoadBalanceTest.java with base test suite
• [ ] Add separate test classes for each LoadBalance implementation (e.g., RandomLoadBalanceTest, RoundRobinLoadBalanceTest, LeastActiveLoadBalanceTest)
• [ ] Test weighted distribution correctness, empty invoker list handling, and single invoker scenarios
• [ ] Add performance/benchmark tests to verify algorithm efficiency with 100+ invokers
• [ ] Test integration with AddressListener.java to ensure dynamic address updates are handled correctly

• Add load balancer tests for the RoundRobinLoadBalancer in dubbo-cluster/src/test/ covering edge cases like single-instance failover and zero-weight provider handling—currently likely has gaps given the complexity of distributed scenarios.: LoadBalancer is core to Dubbo's value; robust test coverage prevents production routing bugs.
• Document Router SPI extensions in the main README or CONTRIBUTING.md with a concrete example (e.g., custom router that routes by geographic region)—currently only high-level architecture is shown, not implementation guides.: Routers are a key extension point but lack practical examples for adopters.
• Add integration tests in dubbo-cluster/src/test/ for the AddressListener that verify provider instance updates propagate correctly to ClusterInvoker when Zookeeper events fire—currently likely tested only in isolation.: The bridge between discovery and routing is critical; integration gaps can cause inconsistent provider lists in live systems.

• High · SnakeYAML Dependency Without Version Pinning — dubbo-cluster/pom.xml - snakeyaml dependency. The pom.xml declares snakeyaml as a dependency without an explicit version, inheriting from parent POM. SnakeYAML has a history of critical deserialization vulnerabilities (CVE-2017-18640, CVE-2020-14343, CVE-2022-1471). Without explicit version management and validation, the application could be vulnerable to arbitrary code execution through malicious YAML payloads. Fix: 1) Pin SnakeYAML to the latest patched version (>= 2.0+). 2) Implement input validation and sanitization for all YAML parsing. 3) Configure SnakeYAML with restrictive constructor to prevent deserialization of arbitrary classes. 4) Consider using safe YAML parsers or alternative serialization formats.
• High · Nashorn JavaScript Engine Dependency — dubbo-cluster/pom.xml - nashorn-core.version property. The pom.xml includes nashorn-core (version 15.7) which is an outdated JavaScript engine. Nashorn was deprecated in Java 11 and removed in Java 15. It has known security issues and is no longer actively maintained. Using deprecated and unmaintained dependencies introduces security risks from unpatched vulnerabilities. Fix: 1) Remove Nashorn dependency if possible. 2) If dynamic script execution is required, migrate to GraalVM JavaScript or Rhino with security policies. 3) Evaluate if Dubbo actually needs dynamic script evaluation - consider removing this feature. 4) If retained, implement sandboxing and strict input validation.
• Medium · Dynamic Configuration Parser Without Input Validation — dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/configurator/parser/. The ConfigParser.java in the configurator/parser package suggests dynamic configuration parsing. Combined with YAML support, there is a risk of configuration injection attacks if untrusted configuration sources are processed without proper validation, especially given the presence of ConditionMatch and ParamMatch model classes that could be exploited. Fix: 1) Implement strict schema validation for all configuration inputs. 2) Use allowlists for configuration keys and values. 3) Implement comprehensive input sanitization. 4) Log and monitor configuration changes. 5) Restrict configuration sources to trusted origins only.
• Medium · Incomplete Dependency Declaration — dubbo-cluster/pom.xml - dubbo-rpc-injvm dependency. The pom.xml dependency for dubbo-rpc-injvm appears to be truncated (version property is incomplete: ${project.parent.vers). This could indicate incomplete or corrupted build configuration that might allow incorrect versions to be resolved, potentially including vulnerable dependency versions. Fix: 1) Fix the truncated version declaration immediately. 2) Ensure all dependencies explicitly declare complete versions. 3) Add dependency validation in CI/CD pipeline. 4) Use Maven dependency management to enforce version consistency.
• Medium · RPC Framework Attack Surface — dubbo-cluster/src/main/java/org/apache/dubbo/rpc/cluster/filter/. The codebase is an RPC framework with multiple invocation and filter chains (ProtocolFilterWrapper, FilterChainBuilder, InvocationInterceptorBuilder). RPC frameworks are high-value targets for deserialization attacks, remote code execution, and privilege escalation. The complexity of the filter chain could introduce bypass vulnerabilities. Fix: 1) Implement strict input validation on all RPC method parameters. 2) Use serialization allow-lists to prevent deserialization of untrusted classes. 3) Implement authentication and authorization on all RPC endpoints. 4) Apply rate limiting and DoS protections. 5) Regular security audits of the invocation chain.
• Low · Missing Security Documentation — SECURITY.md. While SECURITY.md exists, the provided excerpt shows incomplete information. Security policies should clearly document threat model, secure communication requirements, and cryptographic standards used. Fix: 1) Expand SECURITY.md with complete vulnerability reporting guidelines. 2) Document security architecture and threat model. 3) Specify required TLS versions and cipher suites. 4) Define authentication mechanisms. 5) Provide security best practices for users.
• Low · Potential Unvalidated Redirects in Routing — undefined. undefined 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.