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/rocketmq 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 2d ago
• 28+ active contributors
• Distributed ownership (top contributor 21% 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/rocketmq repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/rocketmq.

What it runs against: a local clone of apache/rocketmq — 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/rocketmq | 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 develop exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/rocketmq"
  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 RocketMQ is a distributed messaging and streaming platform written in Java that provides low-latency, high-performance message delivery with trillion-level capacity. It supports multiple messaging patterns (publish/subscribe, request/reply, streaming), transactional messaging, and integrates with gRPC, MQTT, JMS, and OpenMessaging protocols. The codebase includes a comprehensive authentication/authorization module (in auth/) alongside core broker, client, and protocol implementations. Monorepo with Maven modules: auth/ contains authentication/authorization (context builders, evaluators, exception handlers); client/ and broker/ are sibling modules. Build system uses both Maven (primary, pom.xml files) and Bazel (BUILD.bazel, MODULE.bazel, .bazelrc) for polyglot support. Core architecture separates concerns into proto definitions (gRPC schemas), authentication chain handlers, context builders, and enums (SubjectType, UserStatus, UserType).

Enterprise developers and DevOps engineers building event-driven systems, microservices, or big-data streaming pipelines who need reliable message ordering, financial-grade transactional guarantees, and high throughput. Contributors are typically Java engineers working on distributed systems, message brokers, or cloud-native infrastructure.

Production-ready and actively maintained. RocketMQ is an Apache top-level project with structured CI/CD (Maven and Bazel builds, GitHub Actions workflows for integration tests, CodeQL analysis), comprehensive test coverage automation, and regular release cycles (currently at v5.5.0+). Active development is evident from the modular structure and multiple workflow files managing builds, snapshots, and license checks.

Low-to-moderate risk for a mature Apache project. The large Java codebase (15.8M LOC) has many dependencies managed via Maven; breaking changes are possible given the active development. Single points of failure exist in the broker architecture if NameServer or DLedger Controller go down, mitigated by documented HA configurations. ASF governance provides stability, but contributors should review CONTRIBUTING.md and expect strict code review practices.

Active development on authentication/authorization (multiple builder and handler classes in auth/src/main/java/org/apache/rocketmq/auth/), integration testing workflow automation, snapshot builds, and CI improvements. Workflows exist for license checking, CodeQL security scanning, and rerun logic. The presence of .bazelversion and Bazel configs suggests ongoing modernization of the build system alongside Maven.

Clone and build with Maven (primary build): git clone https://github.com/apache/rocketmq.git && cd rocketmq && mvn clean install. For local testing, see the README Quick Start: install Java 8+, download the binary release, then run bin/mqnamesrv (NameServer on 0.0.0.0:9876) followed by bin/mqbroker. Alternatively, use Bazel: bazel build //... (ensure .bazelversion matches your bazel installation).

Daily commands: Start NameServer: cd rocketmq-all-5.5.0-bin-release/bin && ./mqnamesrv (macOS/Linux) or mqnamesrv.cmd (Windows). Start Broker: ./mqbroker -n localhost:9876 (connects to NameServer). Send/Receive Messages: Use provided client tools or write Java code against rocketmq-client module. For development: mvn clean package -DskipTests to build without running tests, or mvn test to run full test suite. GitHub Actions run mvn clean install -U on pull requests.

• auth/src/main/java/org/apache/rocketmq/auth/authentication/AuthenticationEvaluator.java: Core interface defining how authentication decisions are made; entry point for auth logic
• auth/src/main/java/org/apache/rocketmq/auth/authentication/chain/DefaultAuthenticationHandler.java: Implements chain-of-responsibility pattern for processing authentication requests in order
• auth/src/main/java/org/apache/rocketmq/auth/authentication/builder/DefaultAuthenticationContextBuilder.java: Constructs AuthenticationContext objects from raw requests; bridges transport layer to auth logic
• auth/src/main/java/org/apache/rocketmq/auth/authentication/context/AuthenticationContext.java: Data model holding authentication state (subject type, user status, credentials); passed through the auth chain
• .github/workflows/maven.yaml: Primary CI pipeline; defines Maven build steps and test execution on every PR
• BUILD.bazel: Root Bazel build configuration; indicates polyglot build system alongside Maven
• CONTRIBUTING.md: Developer guidelines; must read before submitting PRs to understand ASF requirements and coding standards

Authentication logic: Edit auth/src/main/java/org/apache/rocketmq/auth/authentication/ — start with AuthenticationEvaluator.java for core logic, DefaultAuthenticationHandler.java for request chain handling, and DefaultAuthenticationContextBuilder.java to build context from requests. Protocol messages: Update rocketmq-proto module (Protocol Buffer definitions). Client behavior: Edit client/ module. New features: Follow Maven module structure; add pom.xml, organize under src/main/java/org/apache/rocketmq/*/. Check .github/workflows/maven.yaml and .github/workflows/integration-test.yml for CI expectations.

NameServer as single point of failure: Must be running before brokers; see BUILDING for exact startup order. DLedger Controller optional but recommended for HA: Default non-HA setup is for dev only. Proto dependencies: Changes to rocketmq-proto require full rebuild of dependent modules; mvn clean is safer than incremental builds. Bazel and Maven coexistence: Both build systems exist; ensure consistency (Bazel may cache differently than Maven). Java 8 minimum: Some newer features in auth module may not compile on older JDKs despite stated minimum. Authentication is pluggable: DefaultAuthenticationContextBuilder can be overridden; custom implementations must follow the builder contract exactly.

• Chain of Responsibility Pattern — RocketMQ's authentication system (DefaultAuthenticationHandler) chains multiple evaluators; understanding this pattern is crucial for adding custom auth logic or debugging auth failures
• Builder Pattern — AuthenticationContextBuilder and DefaultAuthenticationContextBuilder construct complex AuthenticationContext objects from raw requests; essential for understanding how transport-layer data becomes auth-logic-layer state
• Protocol Buffers (protobuf) — RocketMQ uses Protocol Buffers (rocketmq-proto module) for message serialization and gRPC service definitions; schema changes propagate across the entire system
• DLedger (Distributed Ledger) — RocketMQ's HA and Controller mechanism relies on DLedger for leader election and log replication; critical for understanding how the broker cluster maintains consistency
• Message Idempotency and Transactional Messaging — RocketMQ guarantees financial-grade transactional semantics (at-least-once delivery, exactly-once semantics for transactions); distinguishes it from simpler brokers and affects API design
• Broker Federation & NameServer Service Discovery — RocketMQ's distributed architecture separates NameServer (metadata, topic routing) from Brokers (data); understanding this separation is essential for debugging routing and scaling issues
• Multi-Protocol Abstraction (gRPC, MQTT, JMS, OpenMessaging) — RocketMQ abstracts multiple transport protocols through a unified internal model; new protocol support requires implementing adapters/bridges to core message format and auth system

• apache/kafka — Alternative distributed message broker with similar use cases (pub/sub, streaming); architectural comparison is useful for understanding RocketMQ design tradeoffs (DLedger vs. Zookeeper, protocol multiplexing)
• alibaba/nacos — Companion service discovery and configuration management system; RocketMQ NameServer is simpler but NACOS offers richer registration patterns many RocketMQ deployments rely on
• apache/pulsar — Alternative Apache messaging platform with similar multi-protocol support (MQTT, JMS); useful for comparing architectural approaches to protocol abstraction
• openmessaging/specification — Defines the OpenMessaging standard that RocketMQ implements; essential reference for understanding the protocol abstraction layer
• grpc/grpc-java — Underlying RPC framework used by RocketMQ for gRPC protocol support; needed to understand serialization and async handling in the codebase

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 AuthenticationStrategy implementations

The auth module contains multiple strategy implementations (StatefulAuthenticationStrategy, StatelessAuthenticationStrategy, AbstractAuthenticationStrategy) but there is no visible test directory in auth/src/test. This is critical for a security-focused authentication module where correctness directly impacts system security. New contributors can add tests covering edge cases, exception handling, and strategy switching logic.

• [ ] Create auth/src/test/java/org/apache/rocketmq/auth/authentication/strategy/ directory
• [ ] Add StatefulAuthenticationStrategyTest.java covering state transitions, session management, and concurrency
• [ ] Add StatelessAuthenticationStrategyTest.java covering stateless token validation and replay attack prevention
• [ ] Add AbstractAuthenticationStrategyTest.java for common contract validation across implementations
• [ ] Ensure tests cover AuthenticationException scenarios and edge cases

Add integration tests for AuthenticationMetadataProvider implementations

The LocalAuthenticationMetadataProvider and AuthenticationMetadataManager classes handle user metadata loading and persistence, but there are no visible integration tests. This is critical infrastructure that needs validation across different scenarios (local file loading, caching, concurrent access). A new contributor can build integration tests that validate the provider contract.

• [ ] Create auth/src/test/java/org/apache/rocketmq/auth/authentication/provider/ directory
• [ ] Add LocalAuthenticationMetadataProviderTest.java testing file loading, parsing, and refresh scenarios
• [ ] Add AuthenticationMetadataManagerImplTest.java for user CRUD operations and metadata consistency
• [ ] Add tests for edge cases: missing files, malformed data, concurrent reads/writes
• [ ] Include tests that verify integration with DefaultAuthenticationProvider

Add GitHub Actions workflow for auth module security scanning

While the repo has multiple CI workflows (.github/workflows/), there is no dedicated security scanning workflow for the sensitive auth module. This module handles authentication credentials and user management, making security scanning essential. A new contributor can create a specialized workflow that runs additional SAST tools, dependency vulnerability checks, and crypto validation specific to the auth module.

• [ ] Create .github/workflows/auth-security-scan.yml
• [ ] Add OWASP Dependency-Check step to scan auth/pom.xml for vulnerable dependencies
• [ ] Integrate Trivy or similar tool to scan for authentication-related vulnerabilities
• [ ] Add regex pattern checks to ensure hardcoded credentials aren't committed in auth/
• [ ] Configure workflow to run on PRs modifying files under auth/ and on schedule (e.g., weekly)

• Add unit tests for auth/src/main/java/org/apache/rocketmq/auth/authentication/context/DefaultAuthenticationContext.java — the context object lacks explicit test coverage; write parametrized tests for subject type transitions and user status validation.
• Document the authentication chain execution flow in a dedicated markdown file under docs/ with UML sequence diagrams showing how DefaultAuthenticationHandler invokes multiple evaluators; currently this flow is implicit in the code.
• Implement missing exception handlers in auth/src/main/java/org/apache/rocketmq/auth/authentication/exception/AuthenticationException.java — add typed subclasses for specific failures (InvalidCredentials, ExpiredToken, InsufficientPermissions) with proper stack trace preservation for debugging.

Apache RocketMQ's authentication and authorization modules demonstrate a structured approach to security with dedicated components for authentication strategies, authorization evaluation, and metadata management. However, several concerns exist: (1) Incomplete dependency information prevents full vulnerability assessment, (2) Lack of visible input validation in critical authentication components, (3) Potential credential exposure risks in local metadata providers without evidence of encryption, (4) Missing explicit HTTPS/TLS enforcement documentation, and (5) Incomplete security configuration guidelines. The codebase would benefit from enhanced input validation, mandatory transport encryption, secure credential storage documentation, and automated dependency scanning in the CI/CD pipeline. Overall security posture is moderate; core architectural separation of concerns is sound, but defense-in-depth implementation details require strengthening.

• Medium · Incomplete Dependency Information — auth/pom.xml - com.google.proto dependency. The pom.xml file shows a truncated dependency declaration for 'com.google.proto' that is incomplete. This makes it impossible to verify if the correct version is specified and whether known vulnerabilities exist in the dependency. Fix: Complete the dependency declaration with proper version specification and verify against known CVE databases. Ensure BOM or version management is properly defined.
• Medium · Missing Input Validation Framework — auth/src/main/java/org/apache/rocketmq/auth/authentication/model/. While the authentication and authorization modules are present, the codebase lacks visible input validation/sanitization utilities. Given this is a messaging platform handling user credentials and subject data, improper input validation could lead to authentication bypass or injection attacks. Fix: Implement comprehensive input validation for User, Subject, and authentication context objects. Validate all string inputs, apply whitelisting for allowed characters, and sanitize before use in any operations.
• Medium · Potential Credential Exposure in Configuration — auth/src/main/java/org/apache/rocketmq/auth/authentication/provider/LocalAuthenticationMetadataProvider.java. The presence of AuthenticationMetadataProvider and LocalAuthenticationMetadataProvider suggests local file-based credential storage. Without evidence of encryption, credentials stored in plaintext or weakly protected configuration files pose a risk. Fix: Ensure all credentials are encrypted at rest using industry-standard encryption (AES-256). Implement secure credential storage with proper access controls. Never store plaintext passwords or tokens.
• Medium · Missing HTTPS Enforcement Evidence — auth/ module and overall configuration. No visible TLS/SSL configuration or HTTPS enforcement mechanisms detected in the provided file structure. A messaging platform handling sensitive authentication data should mandate encrypted transport. Fix: Implement mandatory TLS 1.2+ for all client-server communications. Configure certificate pinning where applicable. Add security headers and enforce HTTPS redirects at the transport layer.
• Low · Missing Security Configuration Documentation — Repository root. The repository lacks explicit security configuration documentation or security.md file detailing authentication/authorization setup, credential management, and security best practices. Fix: Create a SECURITY.md file documenting: (1) Supported authentication strategies, (2) Credential management guidelines, (3) ACL configuration examples, (4) Security best practices, (5) Vulnerability disclosure process.
• Low · Potential Unvalidated Authorization Context — auth/src/main/java/org/apache/rocketmq/auth/authorization/context/. AuthorizationContext and DefaultAuthorizationContext classes exist, but without visible validation, there's a risk of privilege escalation through context manipulation. Fix: Implement strict validation of authorization context data. Use immutable context objects where possible. Validate all policy types and decisions against a whitelist of allowed values.
• Low · Missing OWASP Dependency Check Integration — .github/workflows/. No evidence of automated dependency vulnerability scanning (e.g., OWASP Dependency-Check) in the GitHub workflows, though CodeQL analysis is present. Fix: Add dependency vulnerability scanning to CI/CD pipeline. Integrate OWASP Dependency-Check or Snyk to automatically detect and report known vulnerabilities in dependencies.

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

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

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