refactor: Restructure server architecture with isolated components

Fixes #3

This commit refactors the TCP server architecture to improve modularity,
testability, and maintainability by separating concerns into isolated
components.

## New Components

- **ConnectionAcceptor**: Network I/O layer (socket creation, accept loop)
- **RequestDispatcher**: Application logic (query parsing, routing)
- **TableCatalog**: Centralized table resource management
- **SnapshotScheduler**: Background snapshot scheduling
- **StatisticsService**: Metrics aggregation with separated side effects

## Key Improvements

- **Separation of concerns**: Network, application logic, and domain layers
- **Testability**: Each component can be tested independently
- **Code clarity**: Explicit side effects, clear data flow
- **Maintainability**: Reduced coupling, single responsibility principle

## API Changes

- Removed deprecated `ResponseFormatter::FormatInfoResponse(table_contexts, ServerStats&, ...)`
- Removed deprecated `ResponseFormatter::FormatPrometheusMetrics(table_contexts, ServerStats&, ...)`
- New pattern: Aggregate metrics → Update stats → Format response
- Applied modernize-pass-by-value for ServerConfig, DumpConfig

## Code Quality

- Fixed short variable names (it→iter, fd→client_fd/socket_fd)
- Applied clang-tidy suggestions (modernize-pass-by-value)
- Fixed unused variable warnings in tests
- Improved test file path uniqueness for parallel execution

## Testing

- All existing tests pass (tcp_server_test: 34/34, http_server_test: 21/21)
- Test modifications only for infrastructure improvements
- No changes to test logic or coverage

Author: libraz

src/server/CMakeLists.txt

@@ -4,6 +4,11 @@ add_library(mygramdb_server STATIC
   thread_pool.cpp
   server_stats.cpp
   response_formatter.cpp
+  statistics_service.cpp
+  table_catalog.cpp
+  connection_acceptor.cpp
+  request_dispatcher.cpp
+  snapshot_scheduler.cpp
   handlers/command_handler.cpp
   handlers/search_handler.cpp
   handlers/document_handler.cpp

src/server/connection_acceptor.cpp

@@ -0,0 +1,220 @@
+/**
+ * @file connection_acceptor.cpp
+ * @brief Implementation of ConnectionAcceptor
+ */
+
+#include "server/connection_acceptor.h"
+
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <spdlog/spdlog.h>
+#include <sys/socket.h>
+#include <unistd.h>
+
+#include <cstring>
+
+#include "server/server_types.h"
+#include "server/thread_pool.h"
+
+namespace mygramdb::server {
+
+namespace {
+/**
+ * @brief Helper to safely cast sockaddr_in* to sockaddr* for socket API
+ *
+ * POSIX socket API requires sockaddr* but we use sockaddr_in for IPv4.
+ * This helper centralizes the required reinterpret_cast to a single location.
+ */
+inline struct sockaddr* ToSockaddr(struct sockaddr_in* addr) {
+  return reinterpret_cast<struct sockaddr*>(addr);  // NOLINT(cppcoreguidelines-pro-type-reinterpret-cast)
+}
+}  // namespace
+
+ConnectionAcceptor::ConnectionAcceptor(ServerConfig config, ThreadPool* thread_pool)
+    : config_(std::move(config)), thread_pool_(thread_pool) {
+  if (thread_pool_ == nullptr) {
+    spdlog::error("ConnectionAcceptor: thread_pool cannot be null");
+  }
+}
+
+ConnectionAcceptor::~ConnectionAcceptor() {
+  Stop();
+}
+
+bool ConnectionAcceptor::Start() {
+  if (running_) {
+    last_error_ = "ConnectionAcceptor already running";
+    return false;
+  }
+
+  // Create socket
+  server_fd_ = socket(AF_INET, SOCK_STREAM, 0);
+  if (server_fd_ < 0) {
+    last_error_ = "Failed to create socket: " + std::string(strerror(errno));
+    spdlog::error("{}", last_error_);
+    return false;
+  }
+
+  // Set socket options
+  if (!SetSocketOptions(server_fd_)) {
+    close(server_fd_);
+    server_fd_ = -1;
+    return false;
+  }
+
+  // Bind
+  struct sockaddr_in address = {};
+  std::memset(&address, 0, sizeof(address));
+  address.sin_family = AF_INET;
+  address.sin_addr.s_addr = INADDR_ANY;
+  address.sin_port = htons(config_.port);
+
+  if (bind(server_fd_, ToSockaddr(&address), sizeof(address)) < 0) {
+    last_error_ = "Failed to bind to port " + std::to_string(config_.port) + ": " + std::string(strerror(errno));
+    spdlog::error("{}", last_error_);
+    close(server_fd_);
+    server_fd_ = -1;
+    return false;
+  }
+
+  // Get actual port if port 0 was specified
+  if (config_.port == 0) {
+    socklen_t addr_len = sizeof(address);
+    if (getsockname(server_fd_, ToSockaddr(&address), &addr_len) == 0) {
+      actual_port_ = ntohs(address.sin_port);
+    }
+  } else {
+    actual_port_ = config_.port;
+  }
+
+  // Listen
+  if (listen(server_fd_, config_.max_connections) < 0) {
+    last_error_ = "Failed to listen: " + std::string(strerror(errno));
+    spdlog::error("{}", last_error_);
+    close(server_fd_);
+    server_fd_ = -1;
+    return false;
+  }
+
+  should_stop_ = false;
+  running_ = true;
+
+  // Start accept thread
+  accept_thread_ = std::make_unique<std::thread>(&ConnectionAcceptor::AcceptLoop, this);
+
+  spdlog::info("ConnectionAcceptor listening on {}:{}", config_.host, actual_port_);
+  return true;
+}
+
+void ConnectionAcceptor::Stop() {
+  if (!running_) {
+    return;
+  }
+
+  spdlog::info("Stopping ConnectionAcceptor...");
+  should_stop_ = true;
+  running_ = false;
+
+  // Close server socket to unblock accept()
+  if (server_fd_ >= 0) {
+    close(server_fd_);
+    server_fd_ = -1;
+  }
+
+  // Wait for accept thread to finish
+  if (accept_thread_ && accept_thread_->joinable()) {
+    accept_thread_->join();
+  }
+
+  // Close all active connections
+  {
+    std::lock_guard<std::mutex> lock(fds_mutex_);
+    for (int socket_fd : active_fds_) {
+      close(socket_fd);
+    }
+    active_fds_.clear();
+  }
+
+  spdlog::info("ConnectionAcceptor stopped");
+}
+
+void ConnectionAcceptor::SetConnectionHandler(ConnectionHandler handler) {
+  connection_handler_ = std::move(handler);
+}
+
+void ConnectionAcceptor::AcceptLoop() {
+  spdlog::info("Accept loop started");
+
+  while (!should_stop_) {
+    struct sockaddr_in client_addr = {};
+    socklen_t client_len = sizeof(client_addr);
+
+    int client_fd = accept(server_fd_, ToSockaddr(&client_addr), &client_len);
+    if (client_fd < 0) {
+      if (!should_stop_) {
+        spdlog::error("Accept failed: {}", strerror(errno));
+      }
+      continue;
+    }
+
+    // Track connection
+    {
+      std::lock_guard<std::mutex> lock(fds_mutex_);
+      active_fds_.insert(client_fd);
+    }
+
+    // Submit to thread pool
+    if (thread_pool_ != nullptr && connection_handler_) {
+      thread_pool_->Submit([this, client_fd]() {
+        connection_handler_(client_fd);
+        RemoveConnection(client_fd);
+      });
+    } else {
+      spdlog::error("No connection handler or thread pool configured");
+      close(client_fd);
+      RemoveConnection(client_fd);
+    }
+  }
+
+  spdlog::info("Accept loop exited");
+}
+
+bool ConnectionAcceptor::SetSocketOptions(int socket_fd) {
+  // SO_REUSEADDR: Allow reuse of local addresses
+  int opt = 1;
+  if (setsockopt(socket_fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) < 0) {
+    last_error_ = "Failed to set SO_REUSEADDR: " + std::string(strerror(errno));
+    spdlog::error("{}", last_error_);
+    return false;
+  }
+
+  // SO_KEEPALIVE: Enable TCP keepalive
+  if (setsockopt(socket_fd, SOL_SOCKET, SO_KEEPALIVE, &opt, sizeof(opt)) < 0) {
+    last_error_ = "Failed to set SO_KEEPALIVE: " + std::string(strerror(errno));
+    spdlog::error("{}", last_error_);
+    return false;
+  }
+
+  // SO_RCVBUF: Set receive buffer size
+  int rcvbuf = config_.recv_buffer_size;
+  if (setsockopt(socket_fd, SOL_SOCKET, SO_RCVBUF, &rcvbuf, sizeof(rcvbuf)) < 0) {
+    spdlog::warn("Failed to set SO_RCVBUF: {}", strerror(errno));
+    // Non-fatal, continue
+  }
+
+  // SO_SNDBUF: Set send buffer size
+  int sndbuf = config_.send_buffer_size;
+  if (setsockopt(socket_fd, SOL_SOCKET, SO_SNDBUF, &sndbuf, sizeof(sndbuf)) < 0) {
+    spdlog::warn("Failed to set SO_SNDBUF: {}", strerror(errno));
+    // Non-fatal, continue
+  }
+
+  return true;
+}
+
+void ConnectionAcceptor::RemoveConnection(int socket_fd) {
+  std::lock_guard<std::mutex> lock(fds_mutex_);
+  active_fds_.erase(socket_fd);
+}
+
+}  // namespace mygramdb::server

src/server/connection_acceptor.h

@@ -0,0 +1,139 @@
+/**
+ * @file connection_acceptor.h
+ * @brief Network connection acceptor
+ */
+
+#pragma once
+
+#include <atomic>
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <string>
+#include <thread>
+
+#include "server/server_types.h"
+
+namespace mygramdb::server {
+
+// Forward declarations
+class ThreadPool;
+
+/**
+ * @brief Network connection acceptor
+ *
+ * This class handles socket creation, accept loop, and connection dispatch.
+ * It is isolated from application logic for independent testing.
+ *
+ * Key responsibilities:
+ * - Create and configure server socket
+ * - Accept incoming connections
+ * - Dispatch connections to thread pool
+ * - Track active connections
+ * - Handle graceful shutdown
+ *
+ * Design principles:
+ * - Single responsibility: network I/O only
+ * - Testable without real network (can mock handler)
+ * - Reusable for HTTP server, gRPC, etc.
+ * - Thread-safe connection tracking
+ */
+class ConnectionAcceptor {
+ public:
+  /**
+   * @brief Connection handler callback type
+   *
+   * This callback is invoked for each accepted connection.
+   * The handler should process the connection and close the file descriptor.
+   */
+  using ConnectionHandler = std::function<void(int client_fd)>;
+
+  /**
+   * @brief Construct a ConnectionAcceptor
+   * @param config Server configuration
+   * @param thread_pool Thread pool for connection handling
+   */
+  ConnectionAcceptor(ServerConfig config, ThreadPool* thread_pool);
+
+  // Disable copy and move
+  ConnectionAcceptor(const ConnectionAcceptor&) = delete;
+  ConnectionAcceptor& operator=(const ConnectionAcceptor&) = delete;
+  ConnectionAcceptor(ConnectionAcceptor&&) = delete;
+  ConnectionAcceptor& operator=(ConnectionAcceptor&&) = delete;
+
+  ~ConnectionAcceptor();
+
+  /**
+   * @brief Start accepting connections
+   * @return true if started successfully
+   */
+  bool Start();
+
+  /**
+   * @brief Stop accepting connections
+   *
+   * Stops the accept loop and closes all active connections.
+   */
+  void Stop();
+
+  /**
+   * @brief Set connection handler callback
+   * @param handler Callback to handle accepted connections
+   */
+  void SetConnectionHandler(ConnectionHandler handler);
+
+  /**
+   * @brief Get actual port being listened on
+   * @return Port number (useful when config.port = 0)
+   */
+  uint16_t GetPort() const { return actual_port_; }
+
+  /**
+   * @brief Check if acceptor is running
+   * @return true if accepting connections
+   */
+  bool IsRunning() const { return running_; }
+
+  /**
+   * @brief Get last error message
+   * @return Error message
+   */
+  const std::string& GetLastError() const { return last_error_; }
+
+ private:
+  /**
+   * @brief Accept loop (runs in separate thread)
+   */
+  void AcceptLoop();
+
+  /**
+   * @brief Set socket options (SO_REUSEADDR, SO_KEEPALIVE, etc.)
+   * @param socket_fd Socket file descriptor
+   * @return true if successful
+   */
+  bool SetSocketOptions(int socket_fd);
+
+  /**
+   * @brief Remove connection from active list
+   * @param socket_fd Socket file descriptor
+   */
+  void RemoveConnection(int socket_fd);
+
+  ServerConfig config_;
+  ThreadPool* thread_pool_;
+  ConnectionHandler connection_handler_;
+
+  int server_fd_ = -1;
+  uint16_t actual_port_ = 0;
+  std::atomic<bool> running_{false};
+  std::atomic<bool> should_stop_{false};
+  std::unique_ptr<std::thread> accept_thread_;
+
+  std::set<int> active_fds_;
+  std::mutex fds_mutex_;
+
+  std::string last_error_;
+};
+
+}  // namespace mygramdb::server