PragmaTwice commented on code in PR #3369: URL: https://github.com/apache/kvrocks/pull/3369#discussion_r2796858776
########## AGENTS.md: ########## @@ -0,0 +1,163 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (e.g., Claude Code, Cursor, ChatGPT Codex, Gemini) when working with code in this repository. + +While working on Apache Kvrocks, please remember: + +- Always use English in code and comments. +- Only add meaningful comments when the code's behavior is difficult to understand. +- Add or update tests to cover externally observable behavior and regressions when you change or add functionality. +- Always run the formatter before submitting changes. + +## Build and Development Commands + +### Building + +```bash +# Build kvrocks and utilities +./x.py build # Build to ./build directory +./x.py build -j N # Build with N parallel jobs +./x.py build --unittest # Build with unit tests +./x.py build -DENABLE_OPENSSL=ON # Build with TLS support +./x.py build --ninja # Use Ninja build system +./x.py build --skip-build # Only run CMake configure +./x.py build -DCMAKE_BUILD_TYPE=Debug # Debug build + +# Run a local server +./build/kvrocks -c kvrocks.conf + +# Fetch dependencies +./x.py fetch-deps # Fetch dependency archives +``` + +### Testing + +```bash +# Build and run C++ unit tests +./x.py build --unittest +./x.py test cpp + +# Run Go integration tests +./x.py test go + +# Run specific Go test by path +./x.py test go tests/gocase/unit/... +``` + +### Lint + +You must run the formatter and linters before submitting code changes. This ensures code quality and consistency across the project. It requires installing `clang-format`, `clang-tidy`, and `golangci-lint` locally. Please refer to the CONTRIBUTING.md for setup instructions. + +```bash +# Format code (must pass before submitting) +./x.py format + +# Check code format (fails if not formatted) +./x.py check format + +# Run clang-tidy +./x.py check tidy + +# Run golangci-lint for Go tests +./x.py check golangci-lint +``` + +## Architecture Overview + +Apache Kvrocks is a distributed key-value NoSQL database compatible with the Redis protocol, using RocksDB as its storage engine. + +### Core Structure + +- **`src/server/`**: Main server orchestration, connection handling, and worker threads. The `Server` class manages the event loop, worker threads, and coordinates all components. +- **`src/storage/`**: RocksDB integration layer. Key classes: + - `Storage`: Manages RocksDB instance, column families, and write batches + - `Context`: Passes snapshot and batch between APIs for transactional consistency +- **`src/commands/`**: Redis protocol command implementations. Each command type has a corresponding `Commander` subclass. +- **`src/types/`**: Redis data structure implementations (String, Hash, List, Set, ZSet, Stream, etc.) +- **`src/cluster/`**: Cluster management, slot migration, and replication. +- **`src/search/`**: Full-text search and vector search (HNSW) implementation. +- **`src/config/`**: Server configuration parsing and management. +- **`src/cli/`**: Command-line interface utilities. +- **`src/common/`**: Shared utilities and helper functions. +- **`src/stats/`**: Statistics and metrics collection. + +### Key Patterns + +- **Column Families**: 8 column families are used - PrimarySubkey, Metadata, SecondarySubkey, PubSub, Propagate, Stream, Search, Index. +- **Command Registration**: Commands are registered via the `REDIS_REGISTER_COMMANDS` macro with flags like `kCmdWrite`, `kCmdReadOnly`, `kCmdBlocking`, etc. +- **Write Batch with Index**: Used for transactional mode to group writes before commit. +- **Worker Thread Model**: Libevent-based async I/O with dedicated worker threads. +- **Namespace Isolation**: Token-based multi-tenancy using the `__namespace` column family. + +### Data Encoding + +- `METADATA_ENCODING_VERSION=1` (default): Encodes 64-bit size and expire time in milliseconds. +- `METADATA_ENCODING_VERSION=0`: Legacy encoding. Review Comment: ```suggestion ### Data Encoding - `METADATA_ENCODING_VERSION=1` (default): Encodes 64-bit size and expire time in milliseconds. - `METADATA_ENCODING_VERSION=0`: Legacy encoding. Refer to https://kvrocks.apache.org/community/data-structure-on-rocksdb for more details. ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
