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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/zookeeper(\\.git)?\\b" \\
  && ok "origin remote is apache/zookeeper" \\
  || miss "origin remote is not apache/zookeeper (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 "zookeeper-server/src/main/java/org/apache/zookeeper/server/ZooKeeperServer.java" \\
  && ok "zookeeper-server/src/main/java/org/apache/zookeeper/server/ZooKeeperServer.java" \\
  || miss "missing critical file: zookeeper-server/src/main/java/org/apache/zookeeper/server/ZooKeeperServer.java"
test -f "zookeeper-client/src/main/java/org/apache/zookeeper/ZooKeeper.java" \\
  && ok "zookeeper-client/src/main/java/org/apache/zookeeper/ZooKeeper.java" \\
  || miss "missing critical file: zookeeper-client/src/main/java/org/apache/zookeeper/ZooKeeper.java"
test -f "zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/QuorumPeer.java" \\
  && ok "zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/QuorumPeer.java" \\
  || miss "missing critical file: zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/QuorumPeer.java"
test -f "zookeeper-server/src/main/java/org/apache/zookeeper/server/DataTree.java" \\
  && ok "zookeeper-server/src/main/java/org/apache/zookeeper/server/DataTree.java" \\
  || miss "missing critical file: zookeeper-server/src/main/java/org/apache/zookeeper/server/DataTree.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/zookeeper"
  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 ZooKeeper is a centralized coordination service for distributed systems that provides configuration management, naming services, distributed synchronization, and group membership. It's a production-grade, Java-based service (written in 7.4M lines of Java, plus C++ and C bindings) that maintains a replicated state machine and exposes it via a hierarchical namespace similar to a filesystem, enabling reliable coordination primitives like leader election, barriers, and queues across networked applications. Monolithic structure split by language: zookeeper-server/ contains core Java server (leader election, data replication, transaction log), zookeeper-jute/ is the binary protocol layer, bin/ holds operational scripts (zkServer.sh, zkCli.sh, zkCleanup.sh), and separate zookeeper-client modules for Java/Python/C++ language bindings. Transaction logs parsed by zkTxnLogToolkit.sh, snapshots managed by zkSnapShotToolkit.sh. Configuration via zoo_sample.cfg in conf/. Tests and CI integrated via Jenkinsfile and Maven pom.xml multi-module structure.

Distributed systems engineers and architects who need to coordinate state across multiple services (Kafka uses it for broker coordination, Hadoop uses it for NameNode HA). Backend platform teams building infrastructure that requires reliable consensus, configuration distribution, and service discovery. Contributors are typically engineers working on distributed systems, cluster management, or messaging platforms who need consensus mechanisms.

Highly mature and production-ready. Currently at v3.10.0-SNAPSHOT with active CI/CD pipelines (GitHub Actions workflows in .github/workflows/ for ci.yaml, e2e.yaml, scripts.yaml), comprehensive test coverage across Java, C++, and Python clients, and persistent maintenance by Apache PMC. Last indicated development activity shows ongoing version management (mvn release process documented in pom.xml). Used extensively in production by major distributed systems.

Low risk for core functionality but moderate complexity: the codebase spans multiple languages (Java, C++, C, Python) requiring diverse expertise for comprehensive contribution. The 3.10.0-SNAPSHOT version indicates active development but no visible SLA breakage. Primary risk is operational — ZooKeeper clusters require careful configuration (zoo_sample.cfg) and understanding of quorum consensus; misconfiguration impacts dependent systems catastrophically. Single points of knowledge around TLA+ specs (216KB of formal verification) and internal state machine serialization.

Active maintenance on v3.10.0-SNAPSHOT branch with CI pipelines for Linux, s390x architecture (Jenkinsfile-s390x), and automated OWASP dependency checking (Jenkinsfile-owasp). Recent work visible in shell formatting (tools/ci/run-shfmt.sh, tools/ci/run-shellcheck.sh), CMake build integration (tools/cmake/), and typo detection (.typos.toml). Docker support added (dev/docker/Dockerfile) suggesting containerization focus.

git clone https://github.com/apache/zookeeper.git
cd zookeeper
mvn clean install
# Core build output goes to zookeeper-assembly/target/apache-zookeeper-*-bin.tar.gz
# To run a standalone server: bin/zkServer.sh start conf/zoo_sample.cfg
# To connect with CLI: bin/zkCli.sh -server 127.0.0.1:2181

Daily commands: Start server: bin/zkServer.sh start. Connect CLI client: bin/zkCli.sh -server localhost:2181. For multi-node cluster, configure zoo.cfg with server.1=host1:2888:3888 entries, start each node independently. Standalone mode: create zoo.cfg from conf/zoo_sample.cfg, set dataDir, run bin/zkServer.sh start zoo.cfg. Logs go to ZOOKEEPER_LOG_DIR (default /var/log/zookeeper/). Debug mode: set ZOO_LOG4J_PROP=INFO,ROLLINGFILE in bin/zkEnv.sh.

• pom.xml — Root Maven configuration defining all project modules, dependencies, and build lifecycle for the entire ZooKeeper distribution.
• zookeeper-server/src/main/java/org/apache/zookeeper/server/ZooKeeperServer.java — Core ZooKeeper server implementation; every developer must understand the request processing pipeline and state management.
• zookeeper-client/src/main/java/org/apache/zookeeper/ZooKeeper.java — Main client API entry point; defines the contract between applications and the ZooKeeper cluster.
• zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/QuorumPeer.java — Leader election and quorum consensus mechanism; critical for cluster fault tolerance and split-brain prevention.
• zookeeper-server/src/main/java/org/apache/zookeeper/server/DataTree.java — In-memory data structure representing the ZooKeeper namespace tree; fundamental to all data operations.
• zookeeper-server/src/main/java/org/apache/zookeeper/server/persistence/FileTxnSnapLog.java — Transaction log and snapshot persistence layer; ensures durability and recovery across server restarts.
• Jenkinsfile — CI/CD pipeline configuration for automated builds, tests, and quality checks across all pull requests.

Add a new client-server request type

1. Define the request/response Jute serialization schema in zookeeper-jute/src/main/resources/ (zookeeper-jute/src/main/resources/org/apache/zookeeper/data/zookeeper.jute)
2. Create a new RequestProcessor subclass and add to pipeline in ZooKeeperServer.setupRequestProcessors() (zookeeper-server/src/main/java/org/apache/zookeeper/server/RequestProcessor.java)
3. Implement the public API method in the ZooKeeper client class (zookeeper-client/src/main/java/org/apache/zookeeper/ZooKeeper.java)
4. Add integration test in zookeeper-server/src/test/java/org/apache/zookeeper/test/ (zookeeper-server/src/test/java/org/apache/zookeeper/test/ZooKeeperTestCase.java)

Add a new server metric or admin command

1. Define command handler in FourLetterWordMain or add to the admin server interface (zookeeper-server/src/main/java/org/apache/zookeeper/server/admin/AdminServer.java)
2. Update the metric collection in ServerMetrics or create a new metrics provider (zookeeper-server/src/main/java/org/apache/zookeeper/server/ServerMetrics.java)
3. Add corresponding test case verifying output format (zookeeper-server/src/test/java/org/apache/zookeeper/server/admin/)

Modify quorum consensus behavior

1. Update FastLeaderElection algorithm or Leader/Follower message handlers (zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/FastLeaderElection.java)
2. Modify QuorumPeer state machine or message dispatching (zookeeper-server/src/main/java/org/apache/zookeeper/server/quorum/QuorumPeer.java)
3. Add protocol version field to ensure backward compatibility (zookeeper-server/src/main/java/org/apache/zookeeper/server/util/ZxidUtils.java)
4. Write quorum-mode integration test (requires 3+ servers) (zookeeper-server/src/test/java/org/apache/zookeeper/test/QuorumBase.java)

Add a persistence optimization or storage backend

1. Extend TxnLog and SnapShot interfaces for new storage layer (zookeeper-server/src/main/java/org/apache/zookeeper/server/persistence/TxnLog.java)
2. Create new FileTxnSnapLog variant or wrapper class (zookeeper-server/src/main/java/org/apache/zookeeper/server/persistence/FileTxnSnapLog.java)
3. Register in ServerCnxnFactory.createTxnLog() or DatadirCleanupManager (zookeeper-server/src/main/java/org/apache/zookeeper/server/ZooKeeperServerFactory.java)
4. Add persistence layer benchmarks and recovery tests (zookeeper-server/src/test/java/org/apache/zookeeper/server/persistence/)

1. Transaction log (snapshots + txn logs) must be on durable storage (dataDir) — in-memory only means data loss on restart. 2) Quorum requires strict clock synchronization (NTP) across all servers or leader election fails silently. 3) Default zoo.cfg from zoo_sample.cfg has server.1 pointing to localhost — must be updated for actual hostnames before distributed deployment. 4) C/C++ clients require libzookeeper compiled from zookeeper-client-c/ (not included in -bin distribution), separate CMake build needed. 5) Jute protocol serialization order is sensitive — changing message field order breaks wire compatibility. 6) Observer nodes (non-voting) still require valid server.N entries but with 'observer' suffix.

• Quorum-based replication — ZooKeeper's core consensus mechanism — writes need acknowledgment from majority of servers to be durable, understanding this explains deployment requirements and failure modes
• State machine replication — ZooKeeper maintains an identical copy of the namespace on every server by replaying transaction logs in order, critical for understanding consistency and recovery
• Watch mechanism (client-side notifications) — Allows clients to subscribe to changes in specific znodes and receive async callbacks — the foundation for implementing leader election and configuration distribution
• Znode versioning and CAS operations — Each znode has version numbers and Compare-And-Swap semantics enabling optimistic concurrency without distributed locks, visible in DataTree.setData(path, data, version)
• Transaction log with snapshots — ZooKeeper's persistence model — snapshots provide fast startup but must be reconciled with transaction logs post-startup; understanding this is critical for operational debugging
• Leader election algorithm — ZooKeeper implements a custom leader election (not Raft or Paxos) — Leaders propose writes, followers acknowledge, observers replicate without voting; visible in Leader.java and Follower.java
• Jute binary protocol — Custom serialization format for all client-server communication with strict field ordering; changes require careful backwards-compatibility handling across language bindings

• etcd-io/etcd — Alternative distributed consensus system using Raft instead of ZooKeeper's quorum-based replication; solves same coordination problem with different protocol
• apache/kafka — Primary dependent project that uses ZooKeeper for broker coordination, leader election, and topic configuration management
• apache/hadoop — Uses ZooKeeper for NameNode HA (High Availability) and distributed coordination in YARN resource manager
• twitter/zookeeper — Twitter's fork with operational enhancements and monitoring integrations for large-scale ZooKeeper deployments
• HashiCorp/consul — Modern service mesh alternative providing service discovery and configuration with stronger consistency model than ZooKeeper 3.x

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 integration tests for C client snapshot and transaction log tools

The repo has shell wrapper scripts (zkSnapShotToolkit.sh, zkTxnLogToolkit.sh, zkSnapshotComparer.sh, zkSnapshotRecursiveSummaryToolkit.sh) in bin/ but no visible integration tests. These critical operational tools for debugging ZooKeeper state need test coverage to ensure they work correctly across different snapshot/transaction log formats. A new contributor could add e2e tests in a test suite that exercises these tools against real snapshot and transaction log files.

• [ ] Review existing test structure in zookeeper-client/zookeeper-client-c and identify test framework used
• [ ] Create integration tests in zookeeper-assembly or new test module that generate sample snapshots/txn logs
• [ ] Add test cases for zkSnapShotToolkit.sh, zkSnapshotComparer.sh, and zkTxnLogToolkit.sh covering normal and edge cases
• [ ] Wire tests into CI pipeline via .github/workflows/e2e.yaml or .github/workflows/ci.yaml
• [ ] Document test execution in README_packaging.md

Add GitHub Actions workflow for C client build validation on multiple platforms

The C client code (zookeeper-client/zookeeper-client-c) has CMakeLists.txt and Makefile.am but the CI workflows (.github/workflows/) don't explicitly validate C client builds. There's a Jenkinsfile-s390x suggesting multi-arch support is important, but no GitHub Actions workflow covers Linux/macOS/Windows C client compilation. A new contributor could add a dedicated workflow to catch C client build regressions early.

• [ ] Examine zookeeper-client/zookeeper-client-c/CMakeLists.txt and INSTALL for build requirements
• [ ] Create new .github/workflows/c-client-build.yaml with matrix strategy for ubuntu-latest, macos-latest, windows-latest
• [ ] Include steps to install build dependencies (CMake, compiler, Cyrus SASL per FindCyrusSASL.cmake)
• [ ] Run cmake and make commands, capturing any build warnings or failures
• [ ] Reference or integrate with existing tools/ci/run-shellcheck.sh for shell script validation in C client

Add missing unit tests for zkServer-initialize.sh edge cases

The zkServer-initialize.sh script is critical for cluster setup but there are no visible dedicated tests for its various initialization modes and failure scenarios. Contributors should add comprehensive unit tests covering initialization with different configuration scenarios, permission modes, and error conditions to prevent silent failures in production deployments.

• [ ] Examine bin/zkServer-initialize.sh for all conditional branches and initialization modes
• [ ] Create test suite (e.g., in a new tests/scripts/ directory or within existing test structure) using bash testing framework (BATS or similar)
• [ ] Add test cases for: valid config initialization, missing directories, permission issues, idempotent re-initialization, and invalid configuration paths
• [ ] Integrate test execution into .github/workflows/scripts.yaml which already exists for script validation
• [ ] Update bin/README.txt to document test execution for developers modifying initialization logic

• Add missing integration tests for zkSnapshotComparer.sh tool (bin/zkSnapshotComparer.cmd exists but no corresponding .sh version test coverage in zookeeper-it/)
• Document environment variable requirements in README.md beyond Java 8 mention — zkEnv.sh sets many undocumented variables (ZOO_LOG4J_PROP, CLIENT_JVMFLAGS, SERVER_JVMFLAGS) that affect behavior
• Extend shell script validation: tools/ci/run-shellcheck.sh currently validates syntax, but add semantic checks for all bin/*.sh scripts calling zookeeper-server or using dataDir (security-relevant paths)

Apache ZooKeeper demonstrates a mature security posture with OWASP scanning integration (Jenkinsfile-owasp present)

• Medium · Dependency Management Without Explicit Security Constraints — pom.xml. The pom.xml file shows version 3.10.0-SNAPSHOT without visible dependency locking or explicit security vulnerability scanning configurations. The parent POM references Apache parent v23, but there's no evidence of OWASP dependency-check or similar security scanning integrated into the build process in the visible portions. Fix: Implement Maven dependency-check plugin to scan for known CVEs. Use dependency locking (Maven 3.9+) or bill-of-materials (BOM) to ensure reproducible, vetted dependency versions.
• Medium · Shell Script Security Hardening Not Evident — bin/*.sh files and tools/ci/run-shellcheck.sh. Multiple shell scripts in bin/ directory (zkServer.sh, zkCli.sh, etc.) are present without visible security hardening indicators such as set -euo pipefail, input validation, or ShellCheck integration verification in the repository root. The tools/ci/run-shellcheck.sh exists but effectiveness depends on CI/CD enforcement. Fix: Enforce strict shell script standards: use 'set -euo pipefail', validate all user inputs, add ShellCheck to mandatory CI gates, and implement proper quoting for variables throughout all shell scripts.
• Medium · C Client Library Build Configuration Exposure — zookeeper-client/zookeeper-client-c/CMakeLists.txt, configure.ac, tools/cmake/Modules/FindCyrusSASL.cmake. The C client library (zookeeper-client/zookeeper-client-c/) includes CMakeLists.txt and configure.ac without visible security-focused CMake flags or sanitizer configurations. The FindCyrusSASL.cmake module is present but SASL/authentication configuration enforcement is unclear. Fix: Add CMake security flags (-fstack-protector-strong, -D_FORTIFY_SOURCE=2), enable address/undefined behavior sanitizers in test builds, and enforce strict SASL configuration requirements. Document secure configuration options.
• Low · Missing Security Documentation — Root directory - missing SECURITY.md. While the README.md and README_packaging.md exist, there is no visible SECURITY.md file in the root directory that would document security policy, vulnerability reporting procedures, or security-related best practices for users. Fix: Create a SECURITY.md file following standard practices (similar to GitHub's recommended template) that includes: vulnerability reporting procedures, supported versions for security updates, security contact information, and any known limitations.
• Low · Docker Build Best Practices Not Verified — dev/docker/Dockerfile. A dev/docker/Dockerfile exists but cannot be fully analyzed from the file listing. Without viewing the content, best practices such as multi-stage builds, non-root user execution, and minimal base image usage cannot be verified. Fix: Review and enforce: use minimal base images (alpine/distroless), implement multi-stage builds, run services as non-root user, keep image layers minimal, scan with Trivy/Grype for vulnerabilities, and document all exposed ports.
• Low · Configuration File Permissions Not Enforced — conf/zoo_sample.cfg, zookeeper-assembly/src/main/assembly/. The conf/zoo_sample.cfg file suggests configuration templates exist. Without explicit permission management in the build/installation process, sensitive configuration files could be world-readable during deployment. Fix: Ensure deployment scripts (zkServer.sh, etc.) set restrictive permissions (600 or 640) on configuration files. Document required file permissions in SECURITY.md and installation guides.
• Low · Third-Party Build Tool Integrity — tools/ci/install-shfmt.sh, zk-merge-pr.py. tools/ci/install-shfmt.sh downloads and installs tooling without visible signature verification or hash checking. The zk-merge-pr.py Python script is present but dependency/safety checking isn't evident. Fix: Verify checksums/signatures when downloading external tools. Use pinned versions for all tool installations. Add Python safety checks to CI pipeline for all Python scripts. Consider pre-building tools into CI containers.

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.