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/shenyu 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 the board

• Last commit today
• 30+ active contributors
• Distributed ownership (top contributor 24% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

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

What it runs against: a local clone of apache/shenyu — 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/shenyu | 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 ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/shenyu(\\.git)?\\b" \\
  && ok "origin remote is apache/shenyu" \\
  || miss "origin remote is not apache/shenyu (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 "pom.xml" \\
  && ok "pom.xml" \\
  || miss "missing critical file: pom.xml"
test -f "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java" \\
  && ok "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java" \\
  || miss "missing critical file: shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java"
test -f "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractDataChangedInit.java" \\
  && ok "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractDataChangedInit.java" \\
  || miss "missing critical file: shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractDataChangedInit.java"
test -f "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/service/SyncDataService.java" \\
  && ok "shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/service/SyncDataService.java" \\
  || miss "missing critical file: shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/service/SyncDataService.java"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/shenyu"
  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 ShenYu is a Java-native API gateway that provides service proxy, protocol conversion, and API governance for microservices architectures. It handles request routing, load balancing, plugin-based request/response transformation, and dynamic configuration management across multiple communication protocols (HTTP, gRPC, WebSocket, Dubbo, MQTT). Maven multi-module monorepo: shenyu-admin (UI/config mgmt), shenyu-bootstrap (gateway runtime), shenyu-client (service registration), shenyu-plugin (plugin interface & implementations), shenyu-sync-data-center (config distribution), shenyu-register-center (service registry), shenyu-protocol (protocol handlers). Plugin-driven architecture via shenyu-spi module; stateless bootstrap nodes sync config from admin via sync-data-center.

Platform engineers and DevOps teams who need to deploy and manage API gateways in microservices environments; Java backend developers building gateway plugins and custom request processing logic; teams running on-premises or cloud Kubernetes clusters who want an open-source alternative to commercial API gateway solutions.

Actively maintained Apache project with 2.7.1 in active development. Requires JDK 17+, has comprehensive CI/CD via GitHub Actions (ci.yml, e2e-k8s.yml, integrated-test.yml), CodeQL security scanning, and Docker Hub publishing. Production-ready with established release cycles, though the -SNAPSHOT version indicates ongoing active development.

Large monorepo (13.4M Java LOC across 13 modules) means changes ripple across plugin system, admin panel, bootstrap server, and sync-data-center. Dependency on external databases (MySQL, OceanBase, OceanGate per db/init/) and message brokers requires operational expertise. Single language (Java/Maven) creates JVM ecosystem lock-in; verify plugin compatibility before upgrading.

Active CI/CD with automated Docker publishing (docker-publish.yml, docker-publish-dockerhub.yml), Kubernetes integration testing (e2e-k8s.yml, k8s-examples-http.yml), and CodeQL security analysis running on commits. Version 2.7.1-SNAPSHOT in development suggests post-2.7.0 feature work and bug fixes in progress.

git clone https://github.com/apache/shenyu.git && cd shenyu && mvn clean install -DskipTests. Then start admin UI: mvn -pl shenyu-admin spring-boot:run and bootstrap gateway: mvn -pl shenyu-bootstrap spring-boot:run. Admin console typically runs on :9095.

Daily commands: Build: mvn clean install. Run admin: mvn -pl shenyu-admin spring-boot:run (default :9095). Run gateway: mvn -pl shenyu-bootstrap spring-boot:run (default :9095 with REWRITE mode). Database init scripts in db/init/{mysql,ob,og}/ must be executed first.

• pom.xml — Root Maven POM defining the multi-module build structure, dependency versions, and plugins for the entire Apache ShenYu gateway project
• shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java — Core listener interface that all data change event handlers must implement; foundation for admin-to-gateway synchronization architecture
• shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractDataChangedInit.java — Abstract base class for initializing gateway data from admin on startup; critical for consistent state propagation across distributed nodes
• shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/service/SyncDataService.java — Service interface defining the contract for synchronizing route, rule, and plugin configuration changes from admin to gateway instances
• .github/workflows/ci.yml — Primary CI/CD pipeline orchestrating builds, tests, code analysis, and Docker image publishing for every commit
• db/init/mysql/schema.sql — MySQL database schema initialization defining all tables for routes, rules, plugins, and admin state persistence
• README.md — Project overview and quick-start guide explaining ShenYu's role as a scalable API Gateway for microservice proxy and governance

Add a new data synchronization transport backend (e.g., new config store)

1. Create a new implementation module under shenyu-admin-listener/, e.g., shenyu-admin-listener-redis/ (shenyu-admin-listener/pom.xml)
2. Implement DataChangedListener interface for your transport (subscribe to config changes) (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java)
3. Implement DataChangedInit interface to load initial gateway state on startup (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractDataChangedInit.java)
4. Register your listener in Spring bean configuration (create autoconfiguration under your module) (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/service/SyncDataService.java)
5. Add integration tests in shenyu-admin-listener/src/test validating data propagation (shenyu-admin-listener/shenyu-admin-listener-api/src/test)

Add support for a new database backend

1. Create schema initialization script in db/init/{database-name}/ following existing pattern (mysql/, pg/, oracle/) (db/init/mysql/schema.sql)
2. Define all required tables: route, selector, rule, rule_condition, plugin, plugin_handle, auth (db/init/pg/create-table.sql)
3. Add upgrade migration scripts in db/upgrade/ for each prior version (e.g., 2.7.0-upgrade-2.7.1-{dbname}.sql) (db/upgrade/upgrade-guide.md)
4. Update CI pipeline in .github/workflows/ci.yml to test against your database (.github/workflows/ci.yml)

Add a new admin listener implementation (WebSocket, HTTP polling, etc.)

1. Create new module shenyu-admin-listener-{protocol}/ with its own pom.xml (shenyu-admin-listener/pom.xml)
2. Extend AbstractNodeDataChangedListener or AbstractPathDataChangedListener based on your data model (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/AbstractNodeDataChangedListener.java)
3. Implement protocol-specific subscription and event delivery (e.g., WebSocket connect, HTTP polling loop) (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/DataChangedListener.java)
4. Use NodeDataPathUtils to construct paths consistently with other transports (shenyu-admin-listener/shenyu-admin-listener-api/src/main/java/org/apache/shenyu/admin/listener/utils/NodeDataPathUtils.java)

• Java + Spring Boot — Mature ecosystem for enterprise API Gateways; strong microservice support and production readiness
• Event-driven listener pattern (DataChangedListener) — Decouples admin configuration from gateway ingestion; enables pluggable transport backends (Zookeeper, Consul, HTTP, WebSocket)
• Multi-database support (MySQL, PostgreSQL, Oracle, OceanBase) — Enterprise customer flexibility; leverages existing database infrastructure without lock-in
• Kubernetes-native (E2E tests, examples, Ingress support) — Aligns with cloud-native deployment trends; validates workload on container orchestration
• Maven multi-module build — Enables independent versioning and releases of listener implementations; clear module boundaries

• Listener-based push vs. polling-based pull for config sync

  • Why: Push (listener) minimizes latency and database load; pull requires periodic queries and eventual consistency windows
  • Consequence: Requires listener implementation for each transport backend; adds transport-specific complexity but eliminates polling overhead

• Centralized admin database vs. distributed consensus (Raft/Paxos)

  • Why: Single database is simpler to operate and reason about; distributed consensus adds operational complexity
  • Consequence: Database becomes single point of failure for admin writes; requires replication/HA at database layer, not protocol layer

• Support multiple database backends instead of single standard

  • Why: Accommodates enterprise customer requirements; no technology lock-in
  • Consequence: Requires maintaining schema across 4+ database dialects; upgrade scripts must test against all variants

• API authentication and authorization (gateway proxies traffic; auth delegated to upstream services)
• Real-time analytics and metrics aggregation (focus is routing/governance, not observability)
• Multi-region or geo-distributed gateway federation (each region runs independent gateway cluster)
• Support for non-microservice workloads (designed

Database schema must be initialized before starting admin/bootstrap (schema.sql in db/init/{mysql,ob,og}); bootstrap nodes poll admin for config updates, so network connectivity between them is required. SPI plugin discovery happens at startup — plugins must be on classpath or hot-reload fails silently. Plugin order matters: plugins execute in declared order, and filter-chain design assumes specific ordering (auth before rate-limit, for example). H2 in-memory DB not supported for production use (MySQL/OceanBase required). Maven property ${project.version} may differ between pom.xml and packaged artifacts during SNAPSHOT builds.

• Plugin SPI (Service Provider Interface) — Core extension mechanism in ShenYu — understanding how plugins are discovered and loaded via META-INF/shenyu/ is essential to adding custom request processing logic
• Data Change Event Push (Disruptor pattern) — ShenYu uses Disruptor (shenyu-disruptor module) for low-latency event publishing when routes/rules change; understanding event propagation is key to debugging config delays
• Long Polling for Config Sync — Bootstrap nodes use HTTP long polling (shenyu-sync-data-center-http) to receive config updates from admin; explains why changes sometimes take time and network issues cause outages
• Protocol Codec (Netty ChannelHandler chain) — Each protocol handler (HTTP, gRPC, WebSocket, Dubbo) uses Netty codecs to parse incoming bytes and generate outgoing frames; modifying protocol support requires codec understanding
• Selector/Rule matching engine — Routes are resolved via Selector (condition matchers like hostname/path) → Rule (action executors); config schema in schema.sql and matching logic determine which plugin chain handles a request
• Hot Reload / Dynamic Rule Update — ShenYu's killer feature — rules and plugins reload without restarting gateway nodes; achieved via watching DataChanged events from admin and updating in-memory route tables, critical for zero-downtime deployments
• Selector and Rule Caching Strategy — ShenYu caches selector/rule matches in memory with trie or hash indexes; understanding cache invalidation on config changes prevents route flapping and stale rule execution

• alibaba/nacos — Often used as the config center / service registry alternative to ShenYu's built-in admin for distributed config sync
• envoyproxy/envoy — Language-agnostic proxy alternative; ShenYu targets Java microservices while Envoy is polyglot, but both provide protocol translation and request filtering
• spring-cloud/spring-cloud-gateway — Spring ecosystem API gateway; lighter-weight than ShenYu but less feature-complete (fewer protocols, no admin UI, plugin system less mature)
• apache/dubbo — Common upstream service that ShenYu proxies via its Dubbo plugin (shenyu-protocol/shenyu-protocol-dubbo); shared RPC ecosystem integration

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 database schema validation and migration tests for multi-database support

Apache ShenYu supports multiple databases (MySQL, PostgreSQL, Oracle, OceanBase) as evidenced by db/init and db/upgrade directories. Currently, there are no visible CI tests validating schema consistency across databases or upgrade path integrity. This is critical for a production API Gateway that manages complex routing data.

• [ ] Create shenyu-admin/src/test/java/org/apache/shenyu/admin/database/ test directory
• [ ] Add SchemaConsistencyTest.java to validate all db/init schemas have equivalent structure across MySQL, PostgreSQL, Oracle, and OG
• [ ] Add UpgradePathTest.java to verify all db/upgrade scripts maintain data integrity and schema compatibility
• [ ] Create GitHub Action workflow .github/workflows/database-schema-validation.yml to run these tests against Docker containers for each database type
• [ ] Document findings in a new db/TESTING.md file

Add protocol-specific integration tests with CI coverage

The repo has shenyu-protocol module and supports multiple protocols for API Gateway (HTTP, gRPC, WebSocket, etc.), but .github/workflows lacks protocol-specific integration tests. The existing integrated-test.yml and integrated-test-k8s.yml workflows don't distinguish protocol coverage. This is a critical gap for a multi-protocol gateway.

• [ ] Create .github/workflows/protocol-integration-tests.yml to run protocol-specific test suites
• [ ] Add shenyu-protocol/src/test/java/org/apache/shenyu/protocol/*/ProtocolE2ETest.java for each protocol module
• [ ] Document protocol test requirements in shenyu-protocol/TESTING.md
• [ ] Update CI matrix to test against different protocol combinations and versions
• [ ] Add test coverage reporting to validate each protocol handler

Create comprehensive API documentation for SPI extensibility with examples

The repo has shenyu-spi module enabling plugin extensibility (critical for API Gateway customization), but there's no dedicated documentation or test examples showing how to implement custom plugins, filters, or load balancers. New contributors cannot easily understand the SPI contract.

• [ ] Create shenyu-spi/docs/SPI-DEVELOPMENT-GUIDE.md with detailed SPI architecture
• [ ] Add shenyu-spi/src/test/java/org/apache/shenyu/spi/example/ with reference implementations (CustomFilterExample.java, CustomPluginExample.java, CustomLoadBalancerExample.java)
• [ ] Document the SPI discovery mechanism and annotation requirements with working code examples
• [ ] Add integration tests in shenyu-plugin that verify custom SPI implementations can be loaded and function correctly
• [ ] Create a checklist template for contributors adding new SPI implementations

• Add missing unit tests for shenyu-sync-data-center-http HttpLongPollingDataChangedListener class, which handles config push but has minimal test coverage — good entry for understanding the sync mechanism
• Document the plugin SPI registration contract in a developer guide (currently only visible in code); add examples to shenyu-spi/README showing how to create a custom ratelimit plugin
• Add integration test in .github/workflows/ for the WebSocket protocol handler (shenyu-protocol/shenyu-protocol-websocket) with a simple echo server to verify bidirectional communication

Failed to generate security analysis.

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.