refactor: Improve thread safety, resource management, and observability

Implement comprehensive improvements based on code quality review:

Thread Safety:
- Add shared_mutex to PostingList for thread-safe concurrent access
- Protect Roaring bitmap operations from data races
- Add dedicated thread safety tests for PostingList

Resource Management:
- Introduce FDGuard and ScopeGuard utilities for RAII patterns
- Fix FD leaks in ConnectionAcceptor and TcpServer
- Ensure proper cleanup on exceptions using scope guards
- Fix active_workers_ race condition in ThreadPool

Performance Optimization:
- Precompute cache keys in QueryParser to avoid redundant normalization
- Use precomputed keys in CacheManager for faster lookups
- Move cache key generation (md5, cache_key, query_normalizer) to query module
- Update module dependencies to reflect new architecture

Rate Limiting Integration:
- Integrate RateLimiter into TcpServer and HttpServer
- Add IP-based token bucket rate limiting
- Return 429 status code for HTTP rate limit violations
- Add configuration support for api.tcp.max_connections

API Completeness:
- Add POST /{table}/count endpoint to HTTP API
- Implement tcp.max_connections configuration support
- Add missing metrics to /health/detail endpoint (current_gtid, processed_events, queue_size)

Testing:
- Replace SUCCEED() with actual assertions in binlog filter validation tests
- Replace trivial EXPECT_TRUE(true) with meaningful assertions
- Add PostingList thread safety tests (5 test cases)
- Add HTTP COUNT endpoint tests (4 test cases)
- All 1,209 tests pass

CI/CD:
- Add GitHub Actions workflow for AddressSanitizer and ThreadSanitizer
- Configure ASAN with leak detection and initialization order checking
- Configure TSAN for data race and deadlock detection
- Add path filtering and caching for efficient CI runs
- Workflow initially disabled (manual trigger only)

This change addresses critical thread safety issues, prevents resource leaks,
and improves overall system reliability and observability.

Author: libraz

.github/workflows/sanitizers.yml

@@ -0,0 +1,161 @@
+name: Sanitizers (Disabled)
+
+# Workflow is disabled - only manual trigger available
+# To re-enable, uncomment the push and pull_request triggers below
+on:
+  workflow_dispatch:  # Manual trigger only
+  # push:
+  #   branches: [ main, develop ]
+  # pull_request:
+  #   branches: [ main, develop ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Detect which files have changed to skip unnecessary jobs
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      src: ${{ steps.filter.outputs.src }}
+      tests: ${{ steps.filter.outputs.tests }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            src:
+              - 'src/**'
+              - 'CMakeLists.txt'
+              - 'third_party/**'
+            tests:
+              - 'tests/**'
+
+  # AddressSanitizer - Detects memory errors (use-after-free, buffer overflows, etc.)
+  asan:
+    name: AddressSanitizer
+    needs: changes
+    if: needs.changes.outputs.src == 'true' || needs.changes.outputs.tests == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Cache CMake dependencies
+      uses: actions/cache@v4
+      with:
+        path: build/_deps
+        key: ${{ runner.os }}-cmake-deps-asan-${{ hashFiles('CMakeLists.txt', 'third_party/**') }}
+        restore-keys: |
+          ${{ runner.os }}-cmake-deps-
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          cmake \
+          build-essential \
+          libmysqlclient-dev \
+          libicu-dev \
+          libreadline-dev \
+          pkg-config
+
+    - name: Configure CMake with ASAN
+      run: |
+        mkdir -p build
+        cd build
+        cmake -DCMAKE_BUILD_TYPE=Debug \
+              -DBUILD_TESTS=ON \
+              -DENABLE_ASAN=ON \
+              -DUSE_ICU=ON \
+              -DUSE_MYSQL=ON \
+              ..
+
+    - name: Build
+      run: |
+        cd build
+        make -j$(nproc)
+
+    - name: Run tests with ASAN
+      run: |
+        cd build
+        # Set ASAN options for better error reporting
+        export ASAN_OPTIONS=detect_leaks=1:check_initialization_order=1:detect_stack_use_after_return=1
+        ctest --output-on-failure --parallel $(nproc)
+
+    - name: Upload build artifacts on failure
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: asan-build-logs
+        path: |
+          build/CMakeFiles/*.log
+          build/Testing/Temporary/
+
+  # ThreadSanitizer - Detects data races and thread safety issues
+  tsan:
+    name: ThreadSanitizer
+    needs: changes
+    if: needs.changes.outputs.src == 'true' || needs.changes.outputs.tests == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Cache CMake dependencies
+      uses: actions/cache@v4
+      with:
+        path: build/_deps
+        key: ${{ runner.os }}-cmake-deps-tsan-${{ hashFiles('CMakeLists.txt', 'third_party/**') }}
+        restore-keys: |
+          ${{ runner.os }}-cmake-deps-
+
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y \
+          cmake \
+          build-essential \
+          libmysqlclient-dev \
+          libicu-dev \
+          libreadline-dev \
+          pkg-config
+
+    - name: Configure CMake with TSAN
+      run: |
+        mkdir -p build
+        cd build
+        cmake -DCMAKE_BUILD_TYPE=Debug \
+              -DBUILD_TESTS=ON \
+              -DENABLE_TSAN=ON \
+              -DUSE_ICU=ON \
+              -DUSE_MYSQL=ON \
+              ..
+
+    - name: Build
+      run: |
+        cd build
+        make -j$(nproc)
+
+    - name: Run tests with TSAN
+      run: |
+        cd build
+        # Set TSAN options for better error reporting
+        export TSAN_OPTIONS=second_deadlock_stack=1:halt_on_error=0
+        ctest --output-on-failure --parallel $(nproc)
+
+    - name: Upload build artifacts on failure
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: tsan-build-logs
+        path: |
+          build/CMakeFiles/*.log
+          build/Testing/Temporary/

src/cache/CMakeLists.txt

@@ -1,7 +1,4 @@
 add_library(mygramdb_cache STATIC
-  md5.cpp
-  cache_key.cpp
-  query_normalizer.cpp
   result_compressor.cpp
   query_cache.cpp
   invalidation_manager.cpp
@@ -14,7 +11,7 @@ target_include_directories(mygramdb_cache PUBLIC
 )
 
 target_link_libraries(mygramdb_cache PUBLIC
-  mygramdb_query
+  mygramdb_query  # For Query AST types and cache key generation
   mygramdb_utils
   lz4              # For LZ4 compression
   spdlog::spdlog

src/cache/cache_entry.h

@@ -11,7 +11,7 @@
 #include <string>
 #include <vector>
 
-#include "cache/cache_key.h"
+#include "query/cache_key.h"
 #include "query/query_parser.h"
 
 namespace mygramdb::cache {

src/cache/cache_manager.cpp

@@ -5,7 +5,7 @@
 
 #include "cache/cache_manager.h"
 
-#include "cache/cache_key.h"
+#include "query/cache_key.h"
 #include "server/server_types.h"
 
 namespace mygramdb::cache {
@@ -52,14 +52,20 @@ std::optional<std::vector<DocId>> CacheManager::Lookup(const query::Query& query
     return std::nullopt;
   }
 
-  // Normalize query and generate cache key
-  const std::string normalized = QueryNormalizer::Normalize(query);
-  if (normalized.empty()) {
-    return std::nullopt;
+  // Use precomputed cache key if available (performance optimization)
+  CacheKey key;
+  if (query.cache_key.has_value()) {
+    key.hash_high = query.cache_key.value().first;
+    key.hash_low = query.cache_key.value().second;
+  } else {
+    // Fallback: compute cache key on-the-fly (for backwards compatibility)
+    const std::string normalized = QueryNormalizer::Normalize(query);
+    if (normalized.empty()) {
+      return std::nullopt;
+    }
+    key = CacheKeyGenerator::Generate(normalized);
   }
 
-  const CacheKey key = CacheKeyGenerator::Generate(normalized);
-
   // Lookup in cache
   return query_cache_->Lookup(key);
 }
@@ -74,14 +80,20 @@ std::optional<CacheLookupResult> CacheManager::LookupWithMetadata(const query::Q
     return std::nullopt;
   }
 
-  // Normalize query and generate cache key
-  const std::string normalized = QueryNormalizer::Normalize(query);
-  if (normalized.empty()) {
-    return std::nullopt;
+  // Use precomputed cache key if available (performance optimization)
+  CacheKey key;
+  if (query.cache_key.has_value()) {
+    key.hash_high = query.cache_key.value().first;
+    key.hash_low = query.cache_key.value().second;
+  } else {
+    // Fallback: compute cache key on-the-fly (for backwards compatibility)
+    const std::string normalized = QueryNormalizer::Normalize(query);
+    if (normalized.empty()) {
+      return std::nullopt;
+    }
+    key = CacheKeyGenerator::Generate(normalized);
   }
 
-  const CacheKey key = CacheKeyGenerator::Generate(normalized);
-
   // Lookup in cache with metadata
   QueryCache::LookupMetadata metadata;
   auto result = query_cache_->LookupWithMetadata(key, metadata);

src/cache/cache_manager.h

@@ -13,7 +13,7 @@
 #include "cache/invalidation_manager.h"
 #include "cache/invalidation_queue.h"
 #include "cache/query_cache.h"
-#include "cache/query_normalizer.h"
+#include "query/query_normalizer.h"
 #include "config/config.h"
 #include "query/query_parser.h"
 

src/cache/invalidation_manager.h

@@ -13,7 +13,7 @@
 #include <unordered_set>
 
 #include "cache/cache_entry.h"
-#include "cache/cache_key.h"
+#include "query/cache_key.h"
 
 namespace mygramdb::cache {
 

src/cache/invalidation_queue.h

@@ -15,7 +15,7 @@
 #include <unordered_map>
 #include <unordered_set>
 
-#include "cache/cache_key.h"
+#include "query/cache_key.h"
 
 namespace mygramdb::server {
 struct TableContext;

src/cache/query_cache.h

@@ -15,7 +15,7 @@
 #include <unordered_map>
 
 #include "cache/cache_entry.h"
-#include "cache/cache_key.h"
+#include "query/cache_key.h"
 #include "cache/result_compressor.h"
 
 namespace mygramdb::cache {

src/config/config.h

@@ -205,10 +205,12 @@ struct ApiConfig {
   static constexpr int kDefaultRateLimitCapacity = 100;      ///< Default burst size
   static constexpr int kDefaultRateLimitRefillRate = 10;     ///< Default tokens per second
   static constexpr int kDefaultRateLimitMaxClients = 10000;  ///< Default max tracked clients
+  static constexpr int kDefaultMaxConnections = 10000;       ///< Default maximum concurrent connections
 
   struct {
     std::string bind = "127.0.0.1";
     int port = defaults::kTcpPort;
+    int max_connections = kDefaultMaxConnections;  ///< Maximum concurrent connections
   } tcp;
 
   struct {

src/index/index.cpp

@@ -723,6 +723,7 @@ PostingList* Index::GetOrCreatePostingList(std::string_view term) {
 const PostingList* Index::GetPostingList(std::string_view term) const {
   // NOTE: This method assumes postings_mutex_ is already locked by the caller
   // C++17: unordered_map doesn't support heterogeneous lookup, so we convert to std::string
+  // TODO(performance): Consider upgrading to C++20 or using absl::flat_hash_map for heterogeneous lookup
   auto iterator = term_postings_.find(std::string(term));
   return iterator != term_postings_.end() ? iterator->second.get() : nullptr;
 }