{"owner":"dragonflydb","repo":"dragonfly","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".cursorrules"],"skills":{"AGENTS.md":"# Dragonfly Development Guide\n\n> **Essential reference for working with the Dragonfly codebase**\n> Architecture, build system, testing infrastructure, and development workflows.\n\n---\n\n## Table of Contents\n\n1. [Critical Workflow Rules](#critical-workflow-rules)\n2. [Quick Command Reference](#quick-command-reference)\n3. [Project Overview](#project-overview)\n4. [Repository Structure](#repository-structure)\n5. [Build Instructions](#build-instructions)\n6. [Testing](#testing)\n7. [CI/CD Pipeline](#cicd-pipeline)\n8. [Code Style & Pre-commit Hooks](#code-style--pre-commit-hooks)\n9. [Third-Party Dependencies](#third-party-dependencies)\n10. [Platform Support](#platform-support)\n11. [CMake Build Options](#cmake-build-options)\n12. [Key Files Reference](#key-files-reference)\n13. [Common Pitfalls](#common-pitfalls)\n14. [Debugging Tips](#debugging-tips)\n15. [Validation Checklist](#validation-checklist)\n\n---\n\n## Critical Workflow Rules\n\n**MANDATORY - Always Follow This Order:**\n\n1. ✅ **Read Before Edit** - Always read files before modifying\n2. ✅ **Use Correct Build Commands** - See [Quick Command Reference](#quick-command-reference) below\n3. ✅ **Test After Changes** - Build and run a relevant unit test -\n   `ninja <unit_test> && ./unit_test`\n4. ✅ **Format Code** - `pre-commit run --files <files>`\n5. ✅ **Follow Architecture** - See [Architecture Patterns](#architecture-patterns) below\n6. ✅ **Never Push to Main** - Always create a feature branch and open a PR. Never run `git push origin main`.\n\n### Pull Request Guidelines\n\n**Conciseness is Key**: PR descriptions should be short, focused, and easy to scan.\n- **Title**: Imperative, descriptive (e.g., \"Fix fiber stack overflow in test_reply_guard_oom\")\n- **Summary**: 1-2 sentences explaining *what* changed and *why*\n- **Changes**: Bullet points for key changes\n- **Fixes**: Link issues (e.g., \"Fixes #123\")\n- **Commit messages**: Keep every line (subject and body) <= 100 characters; wrap long descriptions\n\n---\n\n## Quick Command Reference\n\n**CRITICAL: Read the full sections below for context. These are shortcuts only.**\n\n### Building (see [Build Instructions](#build-instructions) for details)\n\n```bash\n# Debug build (for development)\n./helio/blaze.sh -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-dbg && ninja dragonfly              # Build main binary\ncd build-dbg && ninja generic_family_test    # Build specific test\n\n# Release build for local benchmarking\n./helio/blaze.sh -release -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-opt && ninja dragonfly\n```\n\n### Testing (see [Testing](#testing) for details)\n\n```bash\n# C++ Unit Tests\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n### Code Formatting\n\n```bash\n# Setup (once)\npipx install pre-commit clang-format black\npre-commit install\n\n# Format code\npre-commit run --files <files>              # Format specific files\npre-commit run --all-files                  # Format all files\n```\n\n### Common Operations\n\n```bash\n# Check git status\ngit status\n\n# Check current branch\ngit branch\n\n# View recent commits\ngit log --oneline -10\n```\n\n---\n\n## Architecture Patterns\n\n**Code Style**: [.clang-format](.clang-format) - snake_case vars, PascalCase functions, kPascalCase constants\n\n**DO ✅**:\n- Fiber-aware: `util::fb2::Mutex`, `util::fb2::Fiber` → [helio/util/fibers/](helio/util/fibers/)\n- Per-shard ops (no global state) → [docs/df-share-nothing.md](docs/df-share-nothing.md)\n- Command pattern → [src/server/set_family.cc](src/server/set_family.cc)\n- Error handling: `OpStatus` → [src/server/common.h](src/server/common.h)\n- Test patterns → [tests/dragonfly/conftest.py](tests/dragonfly/conftest.py)\n\n**DON'T ❌**:\n- `std::thread`, `std::mutex` (deadlocks!)\n- Global mutable state\n- Edit without reading\n- Skip tests\n- Use `std::regex` in fiber/server paths (recursive implementation can overflow small fiber stacks)\n- Use `./tools/docker/build.sh` for local development (use `ninja` instead)\n- Use `make` for incremental builds (use `ninja` instead)\n\n---\n\n## Project Overview\n\n**Dragonfly** is a high-performance, Redis and Memcached compatible in-memory data store written in C++20. It delivers significantly higher throughput than traditional single-threaded Redis implementations through innovative architectural choices.\n\n### Key Characteristics\n\n- **Language**: C++20 (Google C++ Style Guide 2020 version)\n- **Architecture**: Shared-nothing multi-threaded design (via `helio` library)\n- **Performance**: Uses io_uring (Linux 5.11+) for high-performance async I/O, with epoll fallback\n- **Threading Model**: Fiber-based cooperative multitasking with lock-free data structures\n- **Build System**: CMake + Ninja via `helio/blaze.sh` wrapper script\n- **Target Platform**: Linux (kernel 5.11+ recommended), FreeBSD support available\n- **Protocols**: Redis RESP2/RESP3, Memcached binary protocol\n- **Compatibility**: Drop-in replacement for Redis API coverage\n\n### Architectural Highlights\n\n**For detailed architecture documentation, see [docs/df-share-nothing.md](docs/df-share-nothing.md)**\n\n1. **Shared-Nothing Design**: Each thread operates independently with its own data structures, minimizing lock contention\n2. **Helio Framework**: Custom I/O and threading library built on io_uring/epoll with fiber support\n3. **DashTable**: Novel hash table implementation optimized for multi-core systems - see [docs/dashtable.md](docs/dashtable.md)\n4. **Transaction Model**: Non-blocking optimistic transactions - see [docs/transaction.md](docs/transaction.md)\n5. **Tiering Support**: Optional disk-backed storage for large datasets\n6. **Search Module**: Full-text search capabilities (when enabled with WITH_SEARCH)\n\n---\n\n## Repository Structure\n\n```\ndragonfly/\n├── src/                      # Main C++ source code\n│   ├── server/               # Core server implementation\n│   │   ├── dfly_main.cc      # Main entry point\n│   │   ├── main_service.cc   # Service lifecycle & command routing\n│   │   ├── db_slice.cc       # Per-thread database shard\n│   │   ├── engine_shard_set.cc # Shard management\n│   │   ├── cluster/          # Cluster mode implementation\n│   │   ├── journal/          # Replication journal\n│   │   ├── tiering/          # Tiered storage\n│   │   ├── search/           # Search module\n│   │   └── acl/              # Access control lists\n│   ├── core/                 # Core data structures\n│   │   ├── dash.h            # DashTable hash table\n│   │   ├── dense_set.h       # Compact set implementation\n│   │   ├── string_map.h      # Optimized string-keyed maps\n│   │   ├── search/           # Search core algorithms\n│   │   └── json/             # JSON support\n│   ├── facade/               # Network & command handling\n│   │   ├── dragonfly_connection.cc # Connection management\n│   │   ├── redis_parser.cc   # RESP protocol parser\n│   │   └── memcache_parser.cc # Memcached protocol\n│   └── redis/                # Redis-specific implementations\n│       └── lua/              # Lua scripting support\n│\n├── helio/                    # Git submodule: I/O and threading library\n│   │                         # ** DO NOT EDIT unless contributing to helio **\n│   ├── util/                 # Utilities: fibers, I/O, synchronization\n│   ├── io/                   # io_uring & epoll abstraction\n│   └── blaze.sh              # Build configuration wrapper\n│\n├── tests/                    # Test suite\n│   ├── dragonfly/            # Python pytest integration/regression tests\n│   │   ├── conftest.py       # Pytest fixtures & configuration\n│   │   ├── requirements.txt  # Python test dependencies\n│   │   └── *.py              # Test files\n│   └── pytest.ini            # Pytest configuration & markers\n│\n├── docs/                     # Documentation\n│   ├── build-from-source.md  # Build instructions\n│   ├── dashtable.md          # DashTable internals\n│   ├── transaction.md        # Transaction model\n│   ├── df-share-nothing.md   # Shared-nothing architecture\n│   └── differences.md        # Differences from Redis\n│\n├── contrib/                  # Utilities\n│   ├── docker/               # Docker configurations\n│   └── charts/dragonfly/     # Helm chart for Kubernetes\n│\n├── tools/                    # Benchmarking & utility tools\n│   └── packaging/            # Packaging scripts\n│\n├── CMakeLists.txt            # Root CMake configuration\n├── .clang-format             # C++ formatting rules (clang-format v14.0.6)\n├── .pre-commit-config.yaml   # Pre-commit hooks configuration\n├── pyproject.toml            # Python formatting (Black, 100 chars)\n└── CONTRIBUTING.md           # Contribution guidelines\n```\n\n### Critical Paths to Remember\n\n- **Main entry**: `src/server/dfly_main.cc`\n- **Command dispatch**: `src/server/main_service.cc`\n- **Data storage**: `src/server/db_slice.cc`\n- **Networking**: `src/facade/dragonfly_connection.cc`\n- **Helio library**: `helio/` (I/O and threading library)\n\n---\n\n## Build Instructions\n\n**For complete build instructions, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Quick Start\n\n**Debug build** (for development):\n```bash\n./helio/blaze.sh\ncd build-dbg && ninja dragonfly\n./dragonfly --alsologtostderr\n```\n\n**Release build** (for production/benchmarking):\n```bash\n./helio/blaze.sh -release\ncd build-opt && ninja dragonfly\n```\n\n**Production release build** (static linking, optimized):\n```bash\nmake release           # Configure + build\nmake package           # Create release packages with debug symbols\n```\n\nThe [Makefile](Makefile) builds production releases with:\n- Static linking: libstdc++, libgcc, Boost, OpenSSL\n- Architecture optimizations (x86_64: `-march=core2 -msse4.1 -mtune=skylake`)\n- Debug symbols (compressed)\n- Output: `build-release/dragonfly-{arch}.tar.gz`\n\n**Common build options**:\n- See [docs/build-from-source.md](docs/build-from-source.md) for all options\n\n---\n\n## Testing\n\n**For complete testing documentation, see [tests/README.md](tests/README.md)**\n\n### Quick Reference\n\n**C++ Unit Tests**:\n```bash\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n**Python Integration Tests (pytest)**:\n```bash\n# Run from the repo root. The binary path defaults to build-dbg/dragonfly.\n# Override with the DRAGONFLY_PATH env var:\nDRAGONFLY_PATH=build-dbg/dragonfly python3 -m pytest tests/dragonfly/pymemcached_test.py -xvs\n\n# Run a single test:\npython3 -m pytest tests/dragonfly/pymemcached_test.py::TestMemcached::test_basic -xvs\n```\n\n- `DRAGONFLY_PATH` — sets the path to the Dragonfly binary the test harness starts. Defaults to `build-dbg/dragonfly` relative to the `tests/dragonfly/` directory.\n- `--df` — passes **extra flags to the Dragonfly process** (not the binary path). For example: `--df logtostdout --df \"vmodule=*=1\"`.\n\n---\n\n## CI/CD Pipeline\n\n**For complete CI configuration, see [.github/workflows/ci.yml](.github/workflows/ci.yml)**\n\nThe CI workflow runs on all PRs and includes:\n- **Pre-commit checks**: clang-format, black formatters\n- **Build matrix**: Multiple OS/compiler/sanitizer combinations (Ubuntu 20/24, Alpine, GCC/Clang, ASAN/UBSAN)\n- **Test execution**: C++ unit tests, Python integration tests, cluster mode tests\n- **Additional validations**: Helm charts, Docker image builds\n\n---\n\n## Code Style & Pre-commit Hooks\n\n**For complete contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)**\n\n**Code style configuration files**:\n- **C++**: [.clang-format](.clang-format) - Google C++ Style Guide (2020), clang-format v14.0.6, 100 char limit\n- **Python**: [pyproject.toml](pyproject.toml) - Black formatter, 100 char limit, PEP 8 compliant\n- **Pre-commit hooks**: [.pre-commit-config.yaml](.pre-commit-config.yaml) - Automated formatting checks\n\n**Quick setup**:\n```bash\npipx install pre-commit clang-format black\npre-commit install\npre-commit run --all-files                          # Run all formatters\n```\n\n---\n\n## Third-Party Dependencies\n\n**Key Libraries**: Abseil (strings/flags), Boost 1.71+ (context/intrusive), mimalloc (allocator), jsoncons (JSON), OpenSSL (TLS), libunwind (traces)\n\n**Build artifacts**: `build-dbg/third_party/` - DO NOT edit\n\n**For complete dependency info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## Platform Support\n\n**Linux**: Primary platform. Kernel 5.11+ (io_uring), 5.1+ (basic), < 5.1 (epoll fallback)\n- Check: `uname -r`\n- Force epoll: `--proactor_type=epoll`\n- Docker: `--security-opt seccomp=unconfined`\n\n**FreeBSD**: Supported (kqueue backend)\n\n**macOS**: Not supported for production (use Docker/Linux)\n\n**For complete platform info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## CMake Build Options\n\n**For complete list of build options, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Common Options\n\nPass options to `helio/blaze.sh` with `-D` prefix:\n\n```bash\n./helio/blaze.sh -DWITH_SEARCH=OFF -DWITH_AWS=ON\n```\n\n**Most useful options**:\n- `WITH_ASAN=ON` / `WITH_USAN=ON` - Enable sanitizers for debugging\n- `WITH_SEARCH=OFF` - Disable search module for faster builds\n- `WITH_AWS=OFF` / `WITH_GCP=OFF` - Disable cloud libraries\n- `WITH_TIERING=OFF` - Disable disk storage\n- `USE_MOLD=ON` - Faster linking with LTO (production builds)\n\n**Quick configurations**:\n```bash\n# Minimal build (fast compilation)\n./helio/blaze.sh -DWITH_GPERF=OFF -DWITH_AWS=OFF -DWITH_GCP=OFF -DWITH_TIERING=OFF -DWITH_SEARCH=OFF\n\n# Full-featured (all options ON by default)\n./helio/blaze.sh\n\n# Production optimized\n./helio/blaze.sh -release -DUSE_MOLD=ON\n```\n\n---\n\n## Key Files Reference\n\nQuick reference to the most important files in the codebase.\n\n| Purpose | File Path |\n|---------|-----------|\n| **Entry Points & Core** | |\n| Main entry point | `src/server/dfly_main.cc` |\n| Server lifecycle & command routing | `src/server/main_service.cc` |\n| Per-thread database shard | `src/server/db_slice.cc` |\n| Shard management | `src/server/engine_shard_set.cc` |\n| **Data Structures** | |\n| DashTable hash table | `src/core/dash.h` |\n| Dense set implementation | `src/core/dense_set.h` |\n| String map | `src/core/string_map.h` |\n| **Networking** | |\n| Connection handling | `src/facade/dragonfly_connection.cc` |\n| Redis protocol parser | `src/facade/redis_parser.cc` |\n| Memcached protocol parser | `src/facade/memcache_parser.cc` |\n| **Build System** | |\n| Root CMake config | `CMakeLists.txt` |\n| Build script wrapper | `helio/blaze.sh` |\n| Server CMake config | `src/server/CMakeLists.txt` |\n| **CI/CD** | |\n| Main CI workflow | `.github/workflows/ci.yml` |\n| Pre-commit config | `.pre-commit-config.yaml` |\n| **Code Style** | |\n| C++ formatting | `.clang-format` |\n| Python formatting | `pyproject.toml` |\n| **Testing** | |\n| Pytest configuration | `tests/pytest.ini` |\n| Pytest fixtures | `tests/dragonfly/conftest.py` |\n| Test requirements | `tests/dragonfly/requirements.txt` |\n| **Documentation** | |\n| Build instructions | `docs/build-from-source.md` |\n| Architecture overview | `docs/df-share-nothing.md` |\n| DashTable internals | `docs/dashtable.md` |\n| Transaction model | `docs/transaction.md` |\n| **Configuration** | |\n| Contributing guide | `CONTRIBUTING.md` |\n| CLA agreement | `CLA.txt` |\n\n---\n\n## Common Pitfalls\n\n1. **Pre-commit not installed**: `pipx install pre-commit clang-format black && pre-commit install`\n2. **Wrong binary**: Debug: `build-dbg/dragonfly`, Release: `build-opt/dragonfly`\n3. **Wrong build command**: Use `cd build-dbg && ninja <target>`, NOT `./tools/docker/build.sh`\n4. **Test timeouts**: `timeout 20m ctest -V -L DFLY`\n5. **ASAN leaks**: Check CI, suppress in `helio/util/asan_suppressions.txt`\n6. **Helio modifications**: DON'T edit `helio/` (it's a git submodule - changes go upstream)\n7. **CodeQL checks**: DON'T run codeql_checker when testing changes - it's slow and unnecessary for development\n\n---\n\n## Debugging Tips\n\n**Logging**: `--alsologtostderr --v=1 --vmodule=module=2`\n\n**ASAN**: `ASAN_OPTIONS=detect_leaks=1:symbolize=1`, suppressions: `helio/util/asan_suppressions.txt`\n\n**CI reproduction**: See [.github/workflows/ci.yml](.github/workflows/ci.yml)\n\n**Troubleshooting**: Check fiber deadlocks (use `util::fb2` not `std::mutex`), timeout issues (`--test_timeout`), ASAN reports\n\n---\n\n## Validation Checklist\n\nBefore claiming a task is complete, verify:\n\n### Code Quality\n\n- [ ] Code compiles without errors: `cd build-dbg && ninja dragonfly`\n- [ ] Code compiles without warnings (CI uses `-Werror`)\n- [ ] Code follows Google C++ Style Guide (run `clang-format`)\n- [ ] No new ASAN/UBSAN violations\n\n### Testing\n\n- [ ] All existing C++ unit tests pass: `ctest -V -L DFLY`\n- [ ] New feature has corresponding test coverage\n- [ ] Tests pass in both Debug and Release builds\n- [ ] Tests pass with ASAN/UBSAN enabled (if applicable)\n- [ ] **DO NOT run codeql_checker** - it's slow and unnecessary for development testing\n\n### Pre-commit & Style\n\n- [ ] Pre-commit hooks installed: `pre-commit install`\n- [ ] Code formatted with clang-format (C++) and black (Python)\n\n### Documentation\n\n- [ ] Public APIs have comments explaining purpose\n- [ ] Complex algorithms have explanatory comments\n- [ ] README or docs updated if behavior changes\n- [ ] No commented-out code left in final commit\n\n### Performance\n\n- [ ] No obvious performance regressions (run benchmarks if needed)\n- [ ] No unnecessary allocations in hot paths\n- [ ] Lock-free data structures used where appropriate\n",".cursorrules":"# Cursor AI Rules for Dragonfly\n\n**READ `AGENTS.md`**\n\nAll project information, workflows, patterns, and guidelines are in `AGENTS.md`.\n"},"files":{"AGENTS.md":"# Dragonfly Development Guide\n\n> **Essential reference for working with the Dragonfly codebase**\n> Architecture, build system, testing infrastructure, and development workflows.\n\n---\n\n## Table of Contents\n\n1. [Critical Workflow Rules](#critical-workflow-rules)\n2. [Quick Command Reference](#quick-command-reference)\n3. [Project Overview](#project-overview)\n4. [Repository Structure](#repository-structure)\n5. [Build Instructions](#build-instructions)\n6. [Testing](#testing)\n7. [CI/CD Pipeline](#cicd-pipeline)\n8. [Code Style & Pre-commit Hooks](#code-style--pre-commit-hooks)\n9. [Third-Party Dependencies](#third-party-dependencies)\n10. [Platform Support](#platform-support)\n11. [CMake Build Options](#cmake-build-options)\n12. [Key Files Reference](#key-files-reference)\n13. [Common Pitfalls](#common-pitfalls)\n14. [Debugging Tips](#debugging-tips)\n15. [Validation Checklist](#validation-checklist)\n\n---\n\n## Critical Workflow Rules\n\n**MANDATORY - Always Follow This Order:**\n\n1. ✅ **Read Before Edit** - Always read files before modifying\n2. ✅ **Use Correct Build Commands** - See [Quick Command Reference](#quick-command-reference) below\n3. ✅ **Test After Changes** - Build and run a relevant unit test -\n   `ninja <unit_test> && ./unit_test`\n4. ✅ **Format Code** - `pre-commit run --files <files>`\n5. ✅ **Follow Architecture** - See [Architecture Patterns](#architecture-patterns) below\n6. ✅ **Never Push to Main** - Always create a feature branch and open a PR. Never run `git push origin main`.\n\n### Pull Request Guidelines\n\n**Conciseness is Key**: PR descriptions should be short, focused, and easy to scan.\n- **Title**: Imperative, descriptive (e.g., \"Fix fiber stack overflow in test_reply_guard_oom\")\n- **Summary**: 1-2 sentences explaining *what* changed and *why*\n- **Changes**: Bullet points for key changes\n- **Fixes**: Link issues (e.g., \"Fixes #123\")\n- **Commit messages**: Keep every line (subject and body) <= 100 characters; wrap long descriptions\n\n---\n\n## Quick Command Reference\n\n**CRITICAL: Read the full sections below for context. These are shortcuts only.**\n\n### Building (see [Build Instructions](#build-instructions) for details)\n\n```bash\n# Debug build (for development)\n./helio/blaze.sh -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-dbg && ninja dragonfly              # Build main binary\ncd build-dbg && ninja generic_family_test    # Build specific test\n\n# Release build for local benchmarking\n./helio/blaze.sh -release -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-opt && ninja dragonfly\n```\n\n### Testing (see [Testing](#testing) for details)\n\n```bash\n# C++ Unit Tests\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n### Code Formatting\n\n```bash\n# Setup (once)\npipx install pre-commit clang-format black\npre-commit install\n\n# Format code\npre-commit run --files <files>              # Format specific files\npre-commit run --all-files                  # Format all files\n```\n\n### Common Operations\n\n```bash\n# Check git status\ngit status\n\n# Check current branch\ngit branch\n\n# View recent commits\ngit log --oneline -10\n```\n\n---\n\n## Architecture Patterns\n\n**Code Style**: [.clang-format](.clang-format) - snake_case vars, PascalCase functions, kPascalCase constants\n\n**DO ✅**:\n- Fiber-aware: `util::fb2::Mutex`, `util::fb2::Fiber` → [helio/util/fibers/](helio/util/fibers/)\n- Per-shard ops (no global state) → [docs/df-share-nothing.md](docs/df-share-nothing.md)\n- Command pattern → [src/server/set_family.cc](src/server/set_family.cc)\n- Error handling: `OpStatus` → [src/server/common.h](src/server/common.h)\n- Test patterns → [tests/dragonfly/conftest.py](tests/dragonfly/conftest.py)\n\n**DON'T ❌**:\n- `std::thread`, `std::mutex` (deadlocks!)\n- Global mutable state\n- Edit without reading\n- Skip tests\n- Use `std::regex` in fiber/server paths (recursive implementation can overflow small fiber stacks)\n- Use `./tools/docker/build.sh` for local development (use `ninja` instead)\n- Use `make` for incremental builds (use `ninja` instead)\n\n---\n\n## Project Overview\n\n**Dragonfly** is a high-performance, Redis and Memcached compatible in-memory data store written in C++20. It delivers significantly higher throughput than traditional single-threaded Redis implementations through innovative architectural choices.\n\n### Key Characteristics\n\n- **Language**: C++20 (Google C++ Style Guide 2020 version)\n- **Architecture**: Shared-nothing multi-threaded design (via `helio` library)\n- **Performance**: Uses io_uring (Linux 5.11+) for high-performance async I/O, with epoll fallback\n- **Threading Model**: Fiber-based cooperative multitasking with lock-free data structures\n- **Build System**: CMake + Ninja via `helio/blaze.sh` wrapper script\n- **Target Platform**: Linux (kernel 5.11+ recommended), FreeBSD support available\n- **Protocols**: Redis RESP2/RESP3, Memcached binary protocol\n- **Compatibility**: Drop-in replacement for Redis API coverage\n\n### Architectural Highlights\n\n**For detailed architecture documentation, see [docs/df-share-nothing.md](docs/df-share-nothing.md)**\n\n1. **Shared-Nothing Design**: Each thread operates independently with its own data structures, minimizing lock contention\n2. **Helio Framework**: Custom I/O and threading library built on io_uring/epoll with fiber support\n3. **DashTable**: Novel hash table implementation optimized for multi-core systems - see [docs/dashtable.md](docs/dashtable.md)\n4. **Transaction Model**: Non-blocking optimistic transactions - see [docs/transaction.md](docs/transaction.md)\n5. **Tiering Support**: Optional disk-backed storage for large datasets\n6. **Search Module**: Full-text search capabilities (when enabled with WITH_SEARCH)\n\n---\n\n## Repository Structure\n\n```\ndragonfly/\n├── src/                      # Main C++ source code\n│   ├── server/               # Core server implementation\n│   │   ├── dfly_main.cc      # Main entry point\n│   │   ├── main_service.cc   # Service lifecycle & command routing\n│   │   ├── db_slice.cc       # Per-thread database shard\n│   │   ├── engine_shard_set.cc # Shard management\n│   │   ├── cluster/          # Cluster mode implementation\n│   │   ├── journal/          # Replication journal\n│   │   ├── tiering/          # Tiered storage\n│   │   ├── search/           # Search module\n│   │   └── acl/              # Access control lists\n│   ├── core/                 # Core data structures\n│   │   ├── dash.h            # DashTable hash table\n│   │   ├── dense_set.h       # Compact set implementation\n│   │   ├── string_map.h      # Optimized string-keyed maps\n│   │   ├── search/           # Search core algorithms\n│   │   └── json/             # JSON support\n│   ├── facade/               # Network & command handling\n│   │   ├── dragonfly_connection.cc # Connection management\n│   │   ├── redis_parser.cc   # RESP protocol parser\n│   │   └── memcache_parser.cc # Memcached protocol\n│   └── redis/                # Redis-specific implementations\n│       └── lua/              # Lua scripting support\n│\n├── helio/                    # Git submodule: I/O and threading library\n│   │                         # ** DO NOT EDIT unless contributing to helio **\n│   ├── util/                 # Utilities: fibers, I/O, synchronization\n│   ├── io/                   # io_uring & epoll abstraction\n│   └── blaze.sh              # Build configuration wrapper\n│\n├── tests/                    # Test suite\n│   ├── dragonfly/            # Python pytest integration/regression tests\n│   │   ├── conftest.py       # Pytest fixtures & configuration\n│   │   ├── requirements.txt  # Python test dependencies\n│   │   └── *.py              # Test files\n│   └── pytest.ini            # Pytest configuration & markers\n│\n├── docs/                     # Documentation\n│   ├── build-from-source.md  # Build instructions\n│   ├── dashtable.md          # DashTable internals\n│   ├── transaction.md        # Transaction model\n│   ├── df-share-nothing.md   # Shared-nothing architecture\n│   └── differences.md        # Differences from Redis\n│\n├── contrib/                  # Utilities\n│   ├── docker/               # Docker configurations\n│   └── charts/dragonfly/     # Helm chart for Kubernetes\n│\n├── tools/                    # Benchmarking & utility tools\n│   └── packaging/            # Packaging scripts\n│\n├── CMakeLists.txt            # Root CMake configuration\n├── .clang-format             # C++ formatting rules (clang-format v14.0.6)\n├── .pre-commit-config.yaml   # Pre-commit hooks configuration\n├── pyproject.toml            # Python formatting (Black, 100 chars)\n└── CONTRIBUTING.md           # Contribution guidelines\n```\n\n### Critical Paths to Remember\n\n- **Main entry**: `src/server/dfly_main.cc`\n- **Command dispatch**: `src/server/main_service.cc`\n- **Data storage**: `src/server/db_slice.cc`\n- **Networking**: `src/facade/dragonfly_connection.cc`\n- **Helio library**: `helio/` (I/O and threading library)\n\n---\n\n## Build Instructions\n\n**For complete build instructions, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Quick Start\n\n**Debug build** (for development):\n```bash\n./helio/blaze.sh\ncd build-dbg && ninja dragonfly\n./dragonfly --alsologtostderr\n```\n\n**Release build** (for production/benchmarking):\n```bash\n./helio/blaze.sh -release\ncd build-opt && ninja dragonfly\n```\n\n**Production release build** (static linking, optimized):\n```bash\nmake release           # Configure + build\nmake package           # Create release packages with debug symbols\n```\n\nThe [Makefile](Makefile) builds production releases with:\n- Static linking: libstdc++, libgcc, Boost, OpenSSL\n- Architecture optimizations (x86_64: `-march=core2 -msse4.1 -mtune=skylake`)\n- Debug symbols (compressed)\n- Output: `build-release/dragonfly-{arch}.tar.gz`\n\n**Common build options**:\n- See [docs/build-from-source.md](docs/build-from-source.md) for all options\n\n---\n\n## Testing\n\n**For complete testing documentation, see [tests/README.md](tests/README.md)**\n\n### Quick Reference\n\n**C++ Unit Tests**:\n```bash\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n**Python Integration Tests (pytest)**:\n```bash\n# Run from the repo root. The binary path defaults to build-dbg/dragonfly.\n# Override with the DRAGONFLY_PATH env var:\nDRAGONFLY_PATH=build-dbg/dragonfly python3 -m pytest tests/dragonfly/pymemcached_test.py -xvs\n\n# Run a single test:\npython3 -m pytest tests/dragonfly/pymemcached_test.py::TestMemcached::test_basic -xvs\n```\n\n- `DRAGONFLY_PATH` — sets the path to the Dragonfly binary the test harness starts. Defaults to `build-dbg/dragonfly` relative to the `tests/dragonfly/` directory.\n- `--df` — passes **extra flags to the Dragonfly process** (not the binary path). For example: `--df logtostdout --df \"vmodule=*=1\"`.\n\n---\n\n## CI/CD Pipeline\n\n**For complete CI configuration, see [.github/workflows/ci.yml](.github/workflows/ci.yml)**\n\nThe CI workflow runs on all PRs and includes:\n- **Pre-commit checks**: clang-format, black formatters\n- **Build matrix**: Multiple OS/compiler/sanitizer combinations (Ubuntu 20/24, Alpine, GCC/Clang, ASAN/UBSAN)\n- **Test execution**: C++ unit tests, Python integration tests, cluster mode tests\n- **Additional validations**: Helm charts, Docker image builds\n\n---\n\n## Code Style & Pre-commit Hooks\n\n**For complete contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)**\n\n**Code style configuration files**:\n- **C++**: [.clang-format](.clang-format) - Google C++ Style Guide (2020), clang-format v14.0.6, 100 char limit\n- **Python**: [pyproject.toml](pyproject.toml) - Black formatter, 100 char limit, PEP 8 compliant\n- **Pre-commit hooks**: [.pre-commit-config.yaml](.pre-commit-config.yaml) - Automated formatting checks\n\n**Quick setup**:\n```bash\npipx install pre-commit clang-format black\npre-commit install\npre-commit run --all-files                          # Run all formatters\n```\n\n---\n\n## Third-Party Dependencies\n\n**Key Libraries**: Abseil (strings/flags), Boost 1.71+ (context/intrusive), mimalloc (allocator), jsoncons (JSON), OpenSSL (TLS), libunwind (traces)\n\n**Build artifacts**: `build-dbg/third_party/` - DO NOT edit\n\n**For complete dependency info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## Platform Support\n\n**Linux**: Primary platform. Kernel 5.11+ (io_uring), 5.1+ (basic), < 5.1 (epoll fallback)\n- Check: `uname -r`\n- Force epoll: `--proactor_type=epoll`\n- Docker: `--security-opt seccomp=unconfined`\n\n**FreeBSD**: Supported (kqueue backend)\n\n**macOS**: Not supported for production (use Docker/Linux)\n\n**For complete platform info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## CMake Build Options\n\n**For complete list of build options, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Common Options\n\nPass options to `helio/blaze.sh` with `-D` prefix:\n\n```bash\n./helio/blaze.sh -DWITH_SEARCH=OFF -DWITH_AWS=ON\n```\n\n**Most useful options**:\n- `WITH_ASAN=ON` / `WITH_USAN=ON` - Enable sanitizers for debugging\n- `WITH_SEARCH=OFF` - Disable search module for faster builds\n- `WITH_AWS=OFF` / `WITH_GCP=OFF` - Disable cloud libraries\n- `WITH_TIERING=OFF` - Disable disk storage\n- `USE_MOLD=ON` - Faster linking with LTO (production builds)\n\n**Quick configurations**:\n```bash\n# Minimal build (fast compilation)\n./helio/blaze.sh -DWITH_GPERF=OFF -DWITH_AWS=OFF -DWITH_GCP=OFF -DWITH_TIERING=OFF -DWITH_SEARCH=OFF\n\n# Full-featured (all options ON by default)\n./helio/blaze.sh\n\n# Production optimized\n./helio/blaze.sh -release -DUSE_MOLD=ON\n```\n\n---\n\n## Key Files Reference\n\nQuick reference to the most important files in the codebase.\n\n| Purpose | File Path |\n|---------|-----------|\n| **Entry Points & Core** | |\n| Main entry point | `src/server/dfly_main.cc` |\n| Server lifecycle & command routing | `src/server/main_service.cc` |\n| Per-thread database shard | `src/server/db_slice.cc` |\n| Shard management | `src/server/engine_shard_set.cc` |\n| **Data Structures** | |\n| DashTable hash table | `src/core/dash.h` |\n| Dense set implementation | `src/core/dense_set.h` |\n| String map | `src/core/string_map.h` |\n| **Networking** | |\n| Connection handling | `src/facade/dragonfly_connection.cc` |\n| Redis protocol parser | `src/facade/redis_parser.cc` |\n| Memcached protocol parser | `src/facade/memcache_parser.cc` |\n| **Build System** | |\n| Root CMake config | `CMakeLists.txt` |\n| Build script wrapper | `helio/blaze.sh` |\n| Server CMake config | `src/server/CMakeLists.txt` |\n| **CI/CD** | |\n| Main CI workflow | `.github/workflows/ci.yml` |\n| Pre-commit config | `.pre-commit-config.yaml` |\n| **Code Style** | |\n| C++ formatting | `.clang-format` |\n| Python formatting | `pyproject.toml` |\n| **Testing** | |\n| Pytest configuration | `tests/pytest.ini` |\n| Pytest fixtures | `tests/dragonfly/conftest.py` |\n| Test requirements | `tests/dragonfly/requirements.txt` |\n| **Documentation** | |\n| Build instructions | `docs/build-from-source.md` |\n| Architecture overview | `docs/df-share-nothing.md` |\n| DashTable internals | `docs/dashtable.md` |\n| Transaction model | `docs/transaction.md` |\n| **Configuration** | |\n| Contributing guide | `CONTRIBUTING.md` |\n| CLA agreement | `CLA.txt` |\n\n---\n\n## Common Pitfalls\n\n1. **Pre-commit not installed**: `pipx install pre-commit clang-format black && pre-commit install`\n2. **Wrong binary**: Debug: `build-dbg/dragonfly`, Release: `build-opt/dragonfly`\n3. **Wrong build command**: Use `cd build-dbg && ninja <target>`, NOT `./tools/docker/build.sh`\n4. **Test timeouts**: `timeout 20m ctest -V -L DFLY`\n5. **ASAN leaks**: Check CI, suppress in `helio/util/asan_suppressions.txt`\n6. **Helio modifications**: DON'T edit `helio/` (it's a git submodule - changes go upstream)\n7. **CodeQL checks**: DON'T run codeql_checker when testing changes - it's slow and unnecessary for development\n\n---\n\n## Debugging Tips\n\n**Logging**: `--alsologtostderr --v=1 --vmodule=module=2`\n\n**ASAN**: `ASAN_OPTIONS=detect_leaks=1:symbolize=1`, suppressions: `helio/util/asan_suppressions.txt`\n\n**CI reproduction**: See [.github/workflows/ci.yml](.github/workflows/ci.yml)\n\n**Troubleshooting**: Check fiber deadlocks (use `util::fb2` not `std::mutex`), timeout issues (`--test_timeout`), ASAN reports\n\n---\n\n## Validation Checklist\n\nBefore claiming a task is complete, verify:\n\n### Code Quality\n\n- [ ] Code compiles without errors: `cd build-dbg && ninja dragonfly`\n- [ ] Code compiles without warnings (CI uses `-Werror`)\n- [ ] Code follows Google C++ Style Guide (run `clang-format`)\n- [ ] No new ASAN/UBSAN violations\n\n### Testing\n\n- [ ] All existing C++ unit tests pass: `ctest -V -L DFLY`\n- [ ] New feature has corresponding test coverage\n- [ ] Tests pass in both Debug and Release builds\n- [ ] Tests pass with ASAN/UBSAN enabled (if applicable)\n- [ ] **DO NOT run codeql_checker** - it's slow and unnecessary for development testing\n\n### Pre-commit & Style\n\n- [ ] Pre-commit hooks installed: `pre-commit install`\n- [ ] Code formatted with clang-format (C++) and black (Python)\n\n### Documentation\n\n- [ ] Public APIs have comments explaining purpose\n- [ ] Complex algorithms have explanatory comments\n- [ ] README or docs updated if behavior changes\n- [ ] No commented-out code left in final commit\n\n### Performance\n\n- [ ] No obvious performance regressions (run benchmarks if needed)\n- [ ] No unnecessary allocations in hot paths\n- [ ] Lock-free data structures used where appropriate\n",".cursorrules":"# Cursor AI Rules for Dragonfly\n\n**READ `AGENTS.md`**\n\nAll project information, workflows, patterns, and guidelines are in `AGENTS.md`.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Dragonfly Development Guide\n\n> **Essential reference for working with the Dragonfly codebase**\n> Architecture, build system, testing infrastructure, and development workflows.\n\n---\n\n## Table of Contents\n\n1. [Critical Workflow Rules](#critical-workflow-rules)\n2. [Quick Command Reference](#quick-command-reference)\n3. [Project Overview](#project-overview)\n4. [Repository Structure](#repository-structure)\n5. [Build Instructions](#build-instructions)\n6. [Testing](#testing)\n7. [CI/CD Pipeline](#cicd-pipeline)\n8. [Code Style & Pre-commit Hooks](#code-style--pre-commit-hooks)\n9. [Third-Party Dependencies](#third-party-dependencies)\n10. [Platform Support](#platform-support)\n11. [CMake Build Options](#cmake-build-options)\n12. [Key Files Reference](#key-files-reference)\n13. [Common Pitfalls](#common-pitfalls)\n14. [Debugging Tips](#debugging-tips)\n15. [Validation Checklist](#validation-checklist)\n\n---\n\n## Critical Workflow Rules\n\n**MANDATORY - Always Follow This Order:**\n\n1. ✅ **Read Before Edit** - Always read files before modifying\n2. ✅ **Use Correct Build Commands** - See [Quick Command Reference](#quick-command-reference) below\n3. ✅ **Test After Changes** - Build and run a relevant unit test -\n   `ninja <unit_test> && ./unit_test`\n4. ✅ **Format Code** - `pre-commit run --files <files>`\n5. ✅ **Follow Architecture** - See [Architecture Patterns](#architecture-patterns) below\n6. ✅ **Never Push to Main** - Always create a feature branch and open a PR. Never run `git push origin main`.\n\n### Pull Request Guidelines\n\n**Conciseness is Key**: PR descriptions should be short, focused, and easy to scan.\n- **Title**: Imperative, descriptive (e.g., \"Fix fiber stack overflow in test_reply_guard_oom\")\n- **Summary**: 1-2 sentences explaining *what* changed and *why*\n- **Changes**: Bullet points for key changes\n- **Fixes**: Link issues (e.g., \"Fixes #123\")\n- **Commit messages**: Keep every line (subject and body) <= 100 characters; wrap long descriptions\n\n---\n\n## Quick Command Reference\n\n**CRITICAL: Read the full sections below for context. These are shortcuts only.**\n\n### Building (see [Build Instructions](#build-instructions) for details)\n\n```bash\n# Debug build (for development)\n./helio/blaze.sh -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-dbg && ninja dragonfly              # Build main binary\ncd build-dbg && ninja generic_family_test    # Build specific test\n\n# Release build for local benchmarking\n./helio/blaze.sh -release -DWITH_AWS=OFF -DWITH_GCP=OFF\ncd build-opt && ninja dragonfly\n```\n\n### Testing (see [Testing](#testing) for details)\n\n```bash\n# C++ Unit Tests\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n### Code Formatting\n\n```bash\n# Setup (once)\npipx install pre-commit clang-format black\npre-commit install\n\n# Format code\npre-commit run --files <files>              # Format specific files\npre-commit run --all-files                  # Format all files\n```\n\n### Common Operations\n\n```bash\n# Check git status\ngit status\n\n# Check current branch\ngit branch\n\n# View recent commits\ngit log --oneline -10\n```\n\n---\n\n## Architecture Patterns\n\n**Code Style**: [.clang-format](.clang-format) - snake_case vars, PascalCase functions, kPascalCase constants\n\n**DO ✅**:\n- Fiber-aware: `util::fb2::Mutex`, `util::fb2::Fiber` → [helio/util/fibers/](helio/util/fibers/)\n- Per-shard ops (no global state) → [docs/df-share-nothing.md](docs/df-share-nothing.md)\n- Command pattern → [src/server/set_family.cc](src/server/set_family.cc)\n- Error handling: `OpStatus` → [src/server/common.h](src/server/common.h)\n- Test patterns → [tests/dragonfly/conftest.py](tests/dragonfly/conftest.py)\n\n**DON'T ❌**:\n- `std::thread`, `std::mutex` (deadlocks!)\n- Global mutable state\n- Edit without reading\n- Skip tests\n- Use `std::regex` in fiber/server paths (recursive implementation can overflow small fiber stacks)\n- Use `./tools/docker/build.sh` for local development (use `ninja` instead)\n- Use `make` for incremental builds (use `ninja` instead)\n\n---\n\n## Project Overview\n\n**Dragonfly** is a high-performance, Redis and Memcached compatible in-memory data store written in C++20. It delivers significantly higher throughput than traditional single-threaded Redis implementations through innovative architectural choices.\n\n### Key Characteristics\n\n- **Language**: C++20 (Google C++ Style Guide 2020 version)\n- **Architecture**: Shared-nothing multi-threaded design (via `helio` library)\n- **Performance**: Uses io_uring (Linux 5.11+) for high-performance async I/O, with epoll fallback\n- **Threading Model**: Fiber-based cooperative multitasking with lock-free data structures\n- **Build System**: CMake + Ninja via `helio/blaze.sh` wrapper script\n- **Target Platform**: Linux (kernel 5.11+ recommended), FreeBSD support available\n- **Protocols**: Redis RESP2/RESP3, Memcached binary protocol\n- **Compatibility**: Drop-in replacement for Redis API coverage\n\n### Architectural Highlights\n\n**For detailed architecture documentation, see [docs/df-share-nothing.md](docs/df-share-nothing.md)**\n\n1. **Shared-Nothing Design**: Each thread operates independently with its own data structures, minimizing lock contention\n2. **Helio Framework**: Custom I/O and threading library built on io_uring/epoll with fiber support\n3. **DashTable**: Novel hash table implementation optimized for multi-core systems - see [docs/dashtable.md](docs/dashtable.md)\n4. **Transaction Model**: Non-blocking optimistic transactions - see [docs/transaction.md](docs/transaction.md)\n5. **Tiering Support**: Optional disk-backed storage for large datasets\n6. **Search Module**: Full-text search capabilities (when enabled with WITH_SEARCH)\n\n---\n\n## Repository Structure\n\n```\ndragonfly/\n├── src/                      # Main C++ source code\n│   ├── server/               # Core server implementation\n│   │   ├── dfly_main.cc      # Main entry point\n│   │   ├── main_service.cc   # Service lifecycle & command routing\n│   │   ├── db_slice.cc       # Per-thread database shard\n│   │   ├── engine_shard_set.cc # Shard management\n│   │   ├── cluster/          # Cluster mode implementation\n│   │   ├── journal/          # Replication journal\n│   │   ├── tiering/          # Tiered storage\n│   │   ├── search/           # Search module\n│   │   └── acl/              # Access control lists\n│   ├── core/                 # Core data structures\n│   │   ├── dash.h            # DashTable hash table\n│   │   ├── dense_set.h       # Compact set implementation\n│   │   ├── string_map.h      # Optimized string-keyed maps\n│   │   ├── search/           # Search core algorithms\n│   │   └── json/             # JSON support\n│   ├── facade/               # Network & command handling\n│   │   ├── dragonfly_connection.cc # Connection management\n│   │   ├── redis_parser.cc   # RESP protocol parser\n│   │   └── memcache_parser.cc # Memcached protocol\n│   └── redis/                # Redis-specific implementations\n│       └── lua/              # Lua scripting support\n│\n├── helio/                    # Git submodule: I/O and threading library\n│   │                         # ** DO NOT EDIT unless contributing to helio **\n│   ├── util/                 # Utilities: fibers, I/O, synchronization\n│   ├── io/                   # io_uring & epoll abstraction\n│   └── blaze.sh              # Build configuration wrapper\n│\n├── tests/                    # Test suite\n│   ├── dragonfly/            # Python pytest integration/regression tests\n│   │   ├── conftest.py       # Pytest fixtures & configuration\n│   │   ├── requirements.txt  # Python test dependencies\n│   │   └── *.py              # Test files\n│   └── pytest.ini            # Pytest configuration & markers\n│\n├── docs/                     # Documentation\n│   ├── build-from-source.md  # Build instructions\n│   ├── dashtable.md          # DashTable internals\n│   ├── transaction.md        # Transaction model\n│   ├── df-share-nothing.md   # Shared-nothing architecture\n│   └── differences.md        # Differences from Redis\n│\n├── contrib/                  # Utilities\n│   ├── docker/               # Docker configurations\n│   └── charts/dragonfly/     # Helm chart for Kubernetes\n│\n├── tools/                    # Benchmarking & utility tools\n│   └── packaging/            # Packaging scripts\n│\n├── CMakeLists.txt            # Root CMake configuration\n├── .clang-format             # C++ formatting rules (clang-format v14.0.6)\n├── .pre-commit-config.yaml   # Pre-commit hooks configuration\n├── pyproject.toml            # Python formatting (Black, 100 chars)\n└── CONTRIBUTING.md           # Contribution guidelines\n```\n\n### Critical Paths to Remember\n\n- **Main entry**: `src/server/dfly_main.cc`\n- **Command dispatch**: `src/server/main_service.cc`\n- **Data storage**: `src/server/db_slice.cc`\n- **Networking**: `src/facade/dragonfly_connection.cc`\n- **Helio library**: `helio/` (I/O and threading library)\n\n---\n\n## Build Instructions\n\n**For complete build instructions, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Quick Start\n\n**Debug build** (for development):\n```bash\n./helio/blaze.sh\ncd build-dbg && ninja dragonfly\n./dragonfly --alsologtostderr\n```\n\n**Release build** (for production/benchmarking):\n```bash\n./helio/blaze.sh -release\ncd build-opt && ninja dragonfly\n```\n\n**Production release build** (static linking, optimized):\n```bash\nmake release           # Configure + build\nmake package           # Create release packages with debug symbols\n```\n\nThe [Makefile](Makefile) builds production releases with:\n- Static linking: libstdc++, libgcc, Boost, OpenSSL\n- Architecture optimizations (x86_64: `-march=core2 -msse4.1 -mtune=skylake`)\n- Debug symbols (compressed)\n- Output: `build-release/dragonfly-{arch}.tar.gz`\n\n**Common build options**:\n- See [docs/build-from-source.md](docs/build-from-source.md) for all options\n\n---\n\n## Testing\n\n**For complete testing documentation, see [tests/README.md](tests/README.md)**\n\n### Quick Reference\n\n**C++ Unit Tests**:\n```bash\ncd build-dbg\nctest -V -L DFLY                                    # Run all tests\n./generic_family_test                               # Run specific test binary\n./generic_family_test --gtest_filter=\"Set.*\"        # Run specific test case\n```\n\n**Python Integration Tests (pytest)**:\n```bash\n# Run from the repo root. The binary path defaults to build-dbg/dragonfly.\n# Override with the DRAGONFLY_PATH env var:\nDRAGONFLY_PATH=build-dbg/dragonfly python3 -m pytest tests/dragonfly/pymemcached_test.py -xvs\n\n# Run a single test:\npython3 -m pytest tests/dragonfly/pymemcached_test.py::TestMemcached::test_basic -xvs\n```\n\n- `DRAGONFLY_PATH` — sets the path to the Dragonfly binary the test harness starts. Defaults to `build-dbg/dragonfly` relative to the `tests/dragonfly/` directory.\n- `--df` — passes **extra flags to the Dragonfly process** (not the binary path). For example: `--df logtostdout --df \"vmodule=*=1\"`.\n\n---\n\n## CI/CD Pipeline\n\n**For complete CI configuration, see [.github/workflows/ci.yml](.github/workflows/ci.yml)**\n\nThe CI workflow runs on all PRs and includes:\n- **Pre-commit checks**: clang-format, black formatters\n- **Build matrix**: Multiple OS/compiler/sanitizer combinations (Ubuntu 20/24, Alpine, GCC/Clang, ASAN/UBSAN)\n- **Test execution**: C++ unit tests, Python integration tests, cluster mode tests\n- **Additional validations**: Helm charts, Docker image builds\n\n---\n\n## Code Style & Pre-commit Hooks\n\n**For complete contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md)**\n\n**Code style configuration files**:\n- **C++**: [.clang-format](.clang-format) - Google C++ Style Guide (2020), clang-format v14.0.6, 100 char limit\n- **Python**: [pyproject.toml](pyproject.toml) - Black formatter, 100 char limit, PEP 8 compliant\n- **Pre-commit hooks**: [.pre-commit-config.yaml](.pre-commit-config.yaml) - Automated formatting checks\n\n**Quick setup**:\n```bash\npipx install pre-commit clang-format black\npre-commit install\npre-commit run --all-files                          # Run all formatters\n```\n\n---\n\n## Third-Party Dependencies\n\n**Key Libraries**: Abseil (strings/flags), Boost 1.71+ (context/intrusive), mimalloc (allocator), jsoncons (JSON), OpenSSL (TLS), libunwind (traces)\n\n**Build artifacts**: `build-dbg/third_party/` - DO NOT edit\n\n**For complete dependency info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## Platform Support\n\n**Linux**: Primary platform. Kernel 5.11+ (io_uring), 5.1+ (basic), < 5.1 (epoll fallback)\n- Check: `uname -r`\n- Force epoll: `--proactor_type=epoll`\n- Docker: `--security-opt seccomp=unconfined`\n\n**FreeBSD**: Supported (kqueue backend)\n\n**macOS**: Not supported for production (use Docker/Linux)\n\n**For complete platform info, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n---\n\n## CMake Build Options\n\n**For complete list of build options, see [docs/build-from-source.md](docs/build-from-source.md)**\n\n### Common Options\n\nPass options to `helio/blaze.sh` with `-D` prefix:\n\n```bash\n./helio/blaze.sh -DWITH_SEARCH=OFF -DWITH_AWS=ON\n```\n\n**Most useful options**:\n- `WITH_ASAN=ON` / `WITH_USAN=ON` - Enable sanitizers for debugging\n- `WITH_SEARCH=OFF` - Disable search module for faster builds\n- `WITH_AWS=OFF` / `WITH_GCP=OFF` - Disable cloud libraries\n- `WITH_TIERING=OFF` - Disable disk storage\n- `USE_MOLD=ON` - Faster linking with LTO (production builds)\n\n**Quick configurations**:\n```bash\n# Minimal build (fast compilation)\n./helio/blaze.sh -DWITH_GPERF=OFF -DWITH_AWS=OFF -DWITH_GCP=OFF -DWITH_TIERING=OFF -DWITH_SEARCH=OFF\n\n# Full-featured (all options ON by default)\n./helio/blaze.sh\n\n# Production optimized\n./helio/blaze.sh -release -DUSE_MOLD=ON\n```\n\n---\n\n## Key Files Reference\n\nQuick reference to the most important files in the codebase.\n\n| Purpose | File Path |\n|---------|-----------|\n| **Entry Points & Core** | |\n| Main entry point | `src/server/dfly_main.cc` |\n| Server lifecycle & command routing | `src/server/main_service.cc` |\n| Per-thread database shard | `src/server/db_slice.cc` |\n| Shard management | `src/server/engine_shard_set.cc` |\n| **Data Structures** | |\n| DashTable hash table | `src/core/dash.h` |\n| Dense set implementation | `src/core/dense_set.h` |\n| String map | `src/core/string_map.h` |\n| **Networking** | |\n| Connection handling | `src/facade/dragonfly_connection.cc` |\n| Redis protocol parser | `src/facade/redis_parser.cc` |\n| Memcached protocol parser | `src/facade/memcache_parser.cc` |\n| **Build System** | |\n| Root CMake config | `CMakeLists.txt` |\n| Build script wrapper | `helio/blaze.sh` |\n| Server CMake config | `src/server/CMakeLists.txt` |\n| **CI/CD** | |\n| Main CI workflow | `.github/workflows/ci.yml` |\n| Pre-commit config | `.pre-commit-config.yaml` |\n| **Code Style** | |\n| C++ formatting | `.clang-format` |\n| Python formatting | `pyproject.toml` |\n| **Testing** | |\n| Pytest configuration | `tests/pytest.ini` |\n| Pytest fixtures | `tests/dragonfly/conftest.py` |\n| Test requirements | `tests/dragonfly/requirements.txt` |\n| **Documentation** | |\n| Build instructions | `docs/build-from-source.md` |\n| Architecture overview | `docs/df-share-nothing.md` |\n| DashTable internals | `docs/dashtable.md` |\n| Transaction model | `docs/transaction.md` |\n| **Configuration** | |\n| Contributing guide | `CONTRIBUTING.md` |\n| CLA agreement | `CLA.txt` |\n\n---\n\n## Common Pitfalls\n\n1. **Pre-commit not installed**: `pipx install pre-commit clang-format black && pre-commit install`\n2. **Wrong binary**: Debug: `build-dbg/dragonfly`, Release: `build-opt/dragonfly`\n3. **Wrong build command**: Use `cd build-dbg && ninja <target>`, NOT `./tools/docker/build.sh`\n4. **Test timeouts**: `timeout 20m ctest -V -L DFLY`\n5. **ASAN leaks**: Check CI, suppress in `helio/util/asan_suppressions.txt`\n6. **Helio modifications**: DON'T edit `helio/` (it's a git submodule - changes go upstream)\n7. **CodeQL checks**: DON'T run codeql_checker when testing changes - it's slow and unnecessary for development\n\n---\n\n## Debugging Tips\n\n**Logging**: `--alsologtostderr --v=1 --vmodule=module=2`\n\n**ASAN**: `ASAN_OPTIONS=detect_leaks=1:symbolize=1`, suppressions: `helio/util/asan_suppressions.txt`\n\n**CI reproduction**: See [.github/workflows/ci.yml](.github/workflows/ci.yml)\n\n**Troubleshooting**: Check fiber deadlocks (use `util::fb2` not `std::mutex`), timeout issues (`--test_timeout`), ASAN reports\n\n---\n\n## Validation Checklist\n\nBefore claiming a task is complete, verify:\n\n### Code Quality\n\n- [ ] Code compiles without errors: `cd build-dbg && ninja dragonfly`\n- [ ] Code compiles without warnings (CI uses `-Werror`)\n- [ ] Code follows Google C++ Style Guide (run `clang-format`)\n- [ ] No new ASAN/UBSAN violations\n\n### Testing\n\n- [ ] All existing C++ unit tests pass: `ctest -V -L DFLY`\n- [ ] New feature has corresponding test coverage\n- [ ] Tests pass in both Debug and Release builds\n- [ ] Tests pass with ASAN/UBSAN enabled (if applicable)\n- [ ] **DO NOT run codeql_checker** - it's slow and unnecessary for development testing\n\n### Pre-commit & Style\n\n- [ ] Pre-commit hooks installed: `pre-commit install`\n- [ ] Code formatted with clang-format (C++) and black (Python)\n\n### Documentation\n\n- [ ] Public APIs have comments explaining purpose\n- [ ] Complex algorithms have explanatory comments\n- [ ] README or docs updated if behavior changes\n- [ ] No commented-out code left in final commit\n\n### Performance\n\n- [ ] No obvious performance regressions (run benchmarks if needed)\n- [ ] No unnecessary allocations in hot paths\n- [ ] Lock-free data structures used where appropriate\n","category":"root","tokens":4407},{"name":".cursorrules","path":".cursorrules","title":".cursorrules","content":"# Cursor AI Rules for Dragonfly\n\n**READ `AGENTS.md`**\n\nAll project information, workflows, patterns, and guidelines are in `AGENTS.md`.\n","category":"root","tokens":34}]}