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/CodisLabs/codis 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.

WAIT — Stale — last commit 2y ago

• 16 active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 68% of recent commits
• ⚠ No test directory detected

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "cmd/dashboard/main.go" \\
  && ok "cmd/dashboard/main.go" \\
  || miss "missing critical file: cmd/dashboard/main.go"
test -f "cmd/admin/main.go" \\
  && ok "cmd/admin/main.go" \\
  || miss "missing critical file: cmd/admin/main.go"
test -f "cmd/fe/assets/dashboard-fe.js" \\
  && ok "cmd/fe/assets/dashboard-fe.js" \\
  || miss "missing critical file: cmd/fe/assets/dashboard-fe.js"
test -f "Godeps/Godeps.json" \\
  && ok "Godeps/Godeps.json" \\
  || miss "missing critical file: Godeps/Godeps.json"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 782 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~752d)"
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/CodisLabs/codis"
  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).

Codis is a proxy-based Redis cluster solution written in Go that enables dynamic resharding and scaling without stopping the cluster. It sits between clients and Redis instances, routing commands through slot-based partitioning, and offers pipeline support and multi-key operations during resharding—capabilities that Redis Cluster and Twemproxy lack. Modular Go monorepo: cmd/dashboard contains the admin UI (Go + Angular/JavaScript frontend in cmd/fe/assets), cmd/admin wraps CLI tooling, ansible/ provides deployment automation with roles for codis-dashboard, codis-proxy, codis-fe, codis-server, and redis-sentinel. The proxy intercepts Redis commands at cmd/proxy (not shown in detail but inferred from admin scripts), delegating to slot-mapped backend instances.

DevOps engineers and backend teams running high-traffic Redis deployments who need to scale horizontally without downtime, and organizations using wandoujia.com's infrastructure patterns. Contributors are primarily Go developers maintaining distributed systems and proxy infrastructure.

Production-ready and actively maintained as of the repo data shown. The project is widely deployed at wandoujia.com and other companies, has CI/CD via Travis CI (.travis.yml), uses Godeps for Go dependency management, and includes comprehensive deployment tooling (Ansible roles, admin scripts). Active commits and release history indicate ongoing support, though the codebase appears to be in stable maintenance rather than rapid feature expansion.

The Go codebase dominates (466KB), but the project depends on external services (Zookeeper/etcd for proxy registration, Redis instances). Limited visible test fixtures in the file list suggest test coverage may be sparse for critical resharding logic. Single-maintainer risk exists with primary authors @spinlock and @yangzhe1991. Breaking changes during resharding or slot migration could be difficult to debug without comprehensive logging.

The repo shows a mature, stable project in maintenance mode. The Godeps dependency lock and .travis.yml CI setup indicate focus on stability rather than rapid iteration. Ansible roles suggest active deployment automation work. The 'Donation' section in README hints at sustainability efforts for ongoing maintenance.

Clone and build with: git clone https://github.com/CodisLabs/codis.git && cd codis && make. Dependencies are locked in Godeps/Godeps.json (Go) and package.json (JavaScript/Node for frontend). No explicit npm install shown, but cmd/fe/assets uses angular-ui-bootstrap, suggesting npm install in that directory. Start via admin scripts: ./admin/codis-dashboard-admin.sh, ./admin/codis-proxy-admin.sh after configuration.

Daily commands: Build: make (Makefile drives Go compilation). Deploy via Ansible: ansible-playbook site.yml with hosts configured in ansible/hosts. Or manually: start codis-dashboard (reads dashboard.toml), then codis-proxy instances (proxy.toml), then register Redis servers as groups via dashboard UI. Admin scripts (admin/codis-*-admin.sh) wrap lifecycle management.

• cmd/dashboard/main.go — Dashboard service entry point—manages cluster state, slot allocation, and resharding logic; every contributor must understand how slot distribution works.
• cmd/admin/main.go — Admin CLI entry point; critical for understanding how operators interact with the cluster via dashboard, proxy, and server admin commands.
• cmd/fe/assets/dashboard-fe.js — Frontend UI controller using AngularJS; essential for understanding the user-facing API and real-time cluster monitoring interface.
• Godeps/Godeps.json — Go dependency manifest; defines all external libraries Codis relies on (Redis client, etcd, etc.)—must be consulted when adding features.
• Makefile — Build orchestration for all four core binaries (dashboard, proxy, fe, admin); explains how the project compiles and what the targets are.
• ansible/site.yml — Infrastructure-as-code for automated deployment; defines how all components (dashboard, proxy, servers, sentinel) are provisioned and configured.
• README.md — Architecture overview and feature comparison; establishes design goals (dynamic resharding, pipeline support, no restart required).

Add a new cluster admin command

1. Implement command logic in cmd/admin/ directory, e.g., create cmd/admin/newfeature.go with a function that parses flags and calls dashboard API (cmd/admin/newfeature.go)
2. Register the command handler in cmd/admin/main.go by adding a case to the subcommand dispatcher (cmd/admin/main.go)
3. Expose the corresponding REST or RPC endpoint in cmd/dashboard/main.go if the command needs to modify cluster state (cmd/dashboard/main.go)
4. Update the admin shell script template to document the new command (admin/codis-dashboard-admin.sh)

Add a new UI panel or metric to the dashboard

1. Add a new controller or service function in cmd/fe/assets/dashboard-fe.js to fetch and display the metric from the dashboard API (cmd/fe/assets/dashboard-fe.js)
2. Create a new HTML section in cmd/fe/assets/index.html with AngularJS bindings to display the metric (cmd/fe/assets/index.html)
3. Add CSS rules in cmd/fe/assets/css/main.css to style the new panel (cmd/fe/assets/css/main.css)
4. Expose a new REST endpoint in cmd/dashboard/main.go to serve the metric data to the frontend (cmd/dashboard/main.go)

Deploy a new Codis cluster via Ansible

1. Define target hosts and group variables in ansible/hosts and ansible/group_vars/all (ansible/hosts)
2. Customize proxy configuration by editing ansible/roles/codis-proxy/templates/proxy.toml (ansible/roles/codis-proxy/templates/proxy.toml)
3. Customize dashboard configuration by editing ansible/roles/codis-dashboard/templates/dashboard.toml (ansible/roles/codis-dashboard/templates/dashboard.toml)
4. Run the master playbook: ansible-playbook -i ansible/hosts ansible/site.yml to deploy all components (ansible/site.yml)

Add a new Redis backend server to the cluster

1. Execute the admin command to register the new server with the dashboard, e.g., codis-admin -dashboard localhost:18087 -server-add 127.0.0.1:6379 (cmd/admin/main.go)
2. The dashboard will read cmd/admin/dashboard.go logic to allocate slots to the new server and coordinate resharding (cmd/admin/dashboard.go)
3. Proxies will auto-sync the new slot mapping via the dashboard's API; monitor progress in the web UI at cmd/fe/assets/dashboard-fe.js (cmd/fe/assets/dashboard-fe.js)

• Go — High-performance, concurrent proxy and dashboard service; efficient goroutine-based request handling for thousands of clients
• Redis — Battle-tested in-memory data store; Codis acts as a sharding proxy to scale Redis horizontally without modifying client code
• AngularJS — Lightweight, real-time UI framework for cluster monitoring dashboard with live metric updates
• Ansible — Infrastructure-as-code for idempotent, repeatable deployments across multiple machines
• etcd / Zookeeper (via Godeps) — Distributed coordination for cluster topology, leader election, and state persistence across dashboard instances

• Proxy-based architecture instead of embedded sharding (like Redis Cluster)

  • Why: Allows zero-restart resharding, pipelining support, and easier debugging vs. peer-to-peer cluster consensus
  • Consequence: Adds single point of failure (proxy); requires HA setup with multiple proxies and load balancing

• Centralized dashboard for topology management instead of distributed consensus

  • Why: Simpler coordination logic, easier resharding orchestration, consistent view of slot allocation
  • Consequence: Dashboard must be highly available; cluster is read-only during dashboard outage

• Slot-based partitioning (similar to Redis Cluster) instead of consistent hashing

  • Why: Supports efficient dynamic resharding by moving slots; compatible with hash tags for multi-key operations
  • Consequence: Client must be aware of slot distribution; not compatible with older Redis clients

• Optional Redis Sentinel integration for HA instead of built-in replication

  • Why: Reuses proven Redis HA mechanism; operators familiar with Sentinel can apply existing knowledge
  • Consequence: Requires separate Sentinel instances; adds operational complexity for monitoring

• Real-time multi-consistency across distributed proxies (eventual consistency only)
• Automatic failover without Sentinel (cluster requires manual intervention or external monitoring)
• Support for Redis Lua scripts in multi-key operations during resharding (may error if keys migrate)
• Client libraries other than Redis (clients must implement Codis protocol adaptation)
• Encryption or authentication (assumed to run in trusted internal network)
• Windows support (Ansible and admin scripts target Unix/Linux)

Slot migration during resharding requires careful ordering to avoid data loss or inconsistency—resharding logic must be studied carefully. Zookeeper/etcd must be running for HA and proxy registration; local testing without it will fail discovery. Configuration files (dashboard.toml, proxy.toml, redis.conf in ansible/roles/) must match deployed environment; mismatches cause silent failures. Go 1.x versions are locked in Godeps; using a newer Go version may fail. Multi-key operations across slots require hash tags to work, adding client-side complexity not visible in the repo structure. The dashboard UI is bound to specific slot counts (1024 typical); changing this requires code changes, not just config.

• Consistent Hashing with Slots — Codis partitions the key space into 1024 fixed slots (not dynamic hash rings); understanding slot-based partitioning is critical for resharding, multi-key operations, and debugging routing failures.
• Online Data Migration / Resharding — Codis's core differentiator is live resharding without stopping the cluster; you must understand how slot ownership transitions from one server to another while requests are in flight.
• Redis Protocol Proxy — The proxy intercepts Redis RESP (Serialization Protocol) commands and routes them; understanding RESP parsing and command dispatch is essential for modifying proxy behavior.
• Hash Tags for Multi-Key Operations — Codis supports multi-key commands (MGET, MSET) by requiring clients to use hash tags (e.g., {user:1}:key1) to pin keys to the same slot; critical for correctness during resharding.
• Zookeeper/etcd Coordination — Proxies register themselves with Zookeeper or etcd for client discovery and failover; understanding distributed consensus and watch mechanisms is needed for HA debugging.
• Pipeline Command Batching — Codis supports Redis pipelining, allowing multiple commands in one request; the proxy must parse, batch, and multiplex pipelined commands across backend slots efficiently.
• Group Replication and Failover — Each slot is managed by a group (master + slaves via Redis Sentinel); understanding group topology and Sentinel integration is essential for high-availability operations.

• twitter/twemproxy — Direct predecessor and comparison point: stateless Redis proxy without dynamic resharding; Codis improves upon it by supporting live slot migration.
• redis/redis — The core storage engine that Codis proxies to; understanding Redis protocol and commands is essential for proxy development.
• etcd-io/etcd — Alternative to Zookeeper for proxy coordination and cluster metadata storage in Codis HA deployments.
• apache/zookeeper — Primary coordination service for Codis proxy registration and high-availability leader election (referenced in HA docs).
• google/protobuf — Likely serialization format for internal RPC between dashboard and proxies (common in Go distributed systems, though not explicit in file list).

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.

Migrate from deprecated Godeps to Go modules (go.mod)

The repo uses Godeps (evident from Godeps/Godeps.json and Godeps/Readme), which is deprecated for modern Go projects. Migrating to go.mod would improve dependency management, build reproducibility, and align with current Go best practices. This is especially critical for a production-ready proxy that many companies depend on.

• [ ] Run 'go mod init github.com/CodisLabs/codis' in the repo root
• [ ] Run 'go mod graph' to import existing Godeps dependencies into go.mod
• [ ] Remove the Godeps/ directory
• [ ] Update Makefile and build scripts to use 'go build' instead of godep-based builds
• [ ] Test all binaries (cmd/dashboard/main.go, cmd/fe/, cmd/admin/) build correctly
• [ ] Update .travis.yml to remove godep installation and use standard 'go build'
• [ ] Add go.sum to version control and document in README

Add missing unit tests for core proxy routing logic (cmd/proxy)

The repo structure shows cmd/dashboard, cmd/fe, and cmd/admin but the Makefile and test coverage for cmd/proxy (the critical routing component) are not evident. A production Redis proxy needs robust test coverage for slot assignment, request routing, and failover logic to catch regressions early.

• [ ] Create pkg/proxy/router_test.go for testing slot-to-backend mapping logic
• [ ] Create pkg/proxy/request_test.go for testing command parsing and routing decisions
• [ ] Add table-driven tests for edge cases (slots 0, 1023, 2047, 4095, 16383)
• [ ] Add benchmarks for hot path: BenchmarkSlotLookup, BenchmarkRequestRoute
• [ ] Update Makefile with 'test' target and ensure test coverage reporting (go test -cover ./...)
• [ ] Add test results to .travis.yml CI pipeline

Document Ansible deployment roles and add configuration validation

The repo includes comprehensive Ansible roles (codis-dashboard, codis-proxy, codis-server, redis-sentinel) in ansible/roles/ but lacks documentation on role dependencies, variable requirements, and configuration validation. Adding a README in ansible/ and input validation would significantly improve deployment reliability for operators.

• [ ] Create ansible/README.md documenting role purposes, required variables, and example inventory setup
• [ ] Add variable validation blocks to ansible/roles/codis-*/tasks/main.yml (e.g., check required ports are not in use)
• [ ] Create ansible/group_vars/all.example showing all configurable parameters with descriptions
• [ ] Add pre-flight checks in ansible/roles/common/tasks/main.yml (disk space, firewall rules, Go/Redis versions)
• [ ] Create a simple integration test playbook (ansible/test-deployment.yml) that validates the full stack
• [ ] Document in README.md how to run Ansible playbooks with example: 'ansible-playbook -i ansible/hosts ansible/site.yml'

• Add comprehensive unit tests for slot migration logic: cmd/dashboard currently lacks isolated tests for the resharding state machine that handles slot movement between groups. Write tests in cmd/dashboard/*_test.go covering edge cases like partial migrations and rollback scenarios.
• Document the Redis command support matrix: README compares with Twemproxy and Redis Cluster but does not list which commands Codis proxies fully support, partially supports, or blocks. Create doc/commands.md with a table mapping Redis commands to Codis behavior.
• Extend Ansible playbooks for monitoring integration: ansible/roles lacks tasks for Prometheus or other monitoring; add a new role ansible/roles/monitoring/ with tasks to deploy node-exporter and custom exporters for Codis metrics (slot migration rate, proxy throughput, group health).

• High · Outdated Angular.js Dependency with Known XSS Vulnerabilities — cmd/fe/assets/node_modules/angular, cmd/fe/assets/node_modules/angular-ui-bootstrap. The codebase includes Angular.js (found in cmd/fe/assets/node_modules/angular) which is an older framework version. Angular versions prior to 1.6 have documented XSS vulnerabilities in expression handling and template compilation. The angular-ui-bootstrap version 0.14.3 (from 2015) is significantly outdated. Fix: Update Angular.js to the latest stable version (1.8.x) and angular-ui-bootstrap to a current version. Review and audit any custom template handling in cmd/fe/assets/dashboard-fe.js for potential XSS vectors.
• High · Insecure Docker Base Image — Dockerfile. The Dockerfile uses golang:1.8 which was released in February 2017. This version contains numerous known CVEs in the Go runtime and dependencies. Go 1.8 reached end-of-life in August 2017 and no longer receives security patches. Fix: Update to a supported Go version (1.21 or later recommended). Use golang:1.21-alpine or latest stable version to minimize attack surface and receive security updates.
• High · Unpatched NPM Dependencies — cmd/fe/assets/node_modules/. Multiple frontend dependencies in cmd/fe/assets/node_modules are severely outdated (angular 2013-2014 era, bootstrap-dialog, angular-ui-bootstrap 0.14.3 from 2015). These packages contain publicly disclosed vulnerabilities including XSS, prototype pollution, and other attacks. Fix: Regenerate package-lock.json and update all npm dependencies to current versions. Implement automated dependency scanning with tools like npm audit, Snyk, or OWASP Dependency-Check in CI/CD pipeline.
• Medium · Missing Security Headers Configuration — cmd/fe/assets/index.html, cmd/fe/. No evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the frontend assets or dashboard configuration. The web UI in cmd/fe could be vulnerable to clickjacking and XSS attacks. Fix: Implement HTTP security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection: 1; mode=block. Configure these in the HTTP server code.
• Medium · Potential Exposed Configuration in Ansible Templates — ansible/roles/codis-*/templates/, ansible/roles/redis-sentinel/templates/. Ansible role templates in ansible/roles/*/templates/ (proxy.toml, dashboard.toml, redis.conf, sentinel.conf) may contain sensitive information like passwords or API keys. These are often committed to version control and could expose credentials. Fix: Use Ansible Vault to encrypt sensitive configuration values. Never commit actual credentials. Use variable substitution with secure secret management (HashiCorp Vault, AWS Secrets Manager). Implement .gitignore rules for sensitive configs.
• Medium · Insufficient Input Validation in Web Admin Interface — cmd/admin/, admin/. Admin interface scripts (admin/codis-*-admin.sh, cmd/admin/) lack visible input validation. The dashboard and proxy administration endpoints could be vulnerable to command injection if user input is not properly sanitized. Fix: Implement strict input validation and sanitization for all admin endpoints. Use parameterized queries/commands. Validate all user inputs against whitelists. Implement rate limiting on admin endpoints.
• Medium · No Authentication Mechanism Visible in Codebase Structure — cmd/dashboard/, cmd/admin/, cmd/fe/. The file structure shows dashboard, admin, and frontend components but no visible authentication/authorization implementation. This suggests the system may lack access controls on critical management interfaces. Fix: Implement authentication (OAuth2, JWT, or similar) for all admin and dashboard endpoints. Add authorization checks based on user roles. Secure API endpoints with API keys or tokens. Enable TLS/SSL for all communications.
• Low · Git Metadata in Repository Structure — undefined. .gitignore and .travis.yml files present suggest potential 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.