Start improving architecture (part 1)

.gitignore

@@ -173,4 +173,6 @@ gcc_Release.h
 *.o
 *.a
 src/server/scache
-tests/tests
+tests/tests
+core.*
+tests/tests_db_load

AGENTS.md

@@ -0,0 +1,13 @@
+# simple-cache a C++ HTTP caching daemon
+
+Core Constraints:
+ - High Performance
+ - High Scalability
+ - Low overhead
+ - Trusted clients but crash safe
+
+Testing: run-test.sh`
+
+Building: `make`
+
+Running: ./src/server/scache

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,28 @@
+# Cache Thrash Improvements (Plan)
+
+This repo currently does a full index flush (and a blockfile snapshot) from the write path via `db_lru_gc()`. Under high churn this can devolve into near-continuous flush attempts. The changes implemented in this PR address flush storms and a potential infinite loop in LRU cleanup. The remaining items below are larger design changes.
+
+## 3. Move Expiration Work Off the Write Path
+
+Problem:
+`db_lru_gc()` calls `db_expire_cursor()` which can scan thousands of entries per invocation. When `db_lru_gc()` is triggered from inserts, this couples cache maintenance cost directly to write throughput and amplifies latency under load.
+
+Direction:
+1. Split `db_lru_gc()` into:
+   - a cheap write-path step: eviction only when over limit
+   - a periodic maintenance step: expiration cursor work
+2. Trigger maintenance periodically (timer-driven or a dedicated background loop) rather than per-insert.
+
+## 4. Add Hysteresis to Eviction Thresholds
+
+Problem:
+When `db.db_size_bytes` hovers around `settings.max_size`, the system can oscillate between inserting and evicting, repeatedly triggering maintenance and flushes.
+
+Direction:
+Introduce two thresholds:
+1. High watermark: start eviction when `db_size_bytes > max_size`.
+2. Low watermark: evict down to `max_size * (1 - clear_pct)` (or another tuned value).
+
+Optional enhancement:
+Do not start a new eviction pass until the high watermark is exceeded again. This reduces "thrash" oscillations and improves steady-state throughput.
+

run-test.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# run-test.sh - Build and run tests for simple-cache
+# Usage: ./run-test.sh [Release|Debug]
+# Default: Release
+
+set -e  # Exit on error
+
+# Parse configuration argument (case insensitive)
+CONFIG="${1:-Release}"
+CONFIG=$(echo "$CONFIG" | tr '[:lower:]' '[:upper:]')
+
+# Validate configuration
+if [ "$CONFIG" != "RELEASE" ] && [ "$CONFIG" != "DEBUG" ]; then
+    echo "Error: Invalid configuration '$1'"
+    echo "Usage: $0 [Release|Debug]"
+    exit 1
+fi
+
+echo "=========================================="
+echo "Building simple-cache in ${CONFIG} mode"
+echo "=========================================="
+
+# Clean previous builds
+echo "Cleaning previous builds..."
+make clean
+
+# Build the project with the specified configuration
+echo "Building project (CONFIG=${CONFIG})..."
+make CONFIG=${CONFIG}
+
+# Build the tests
+echo "Building tests (CONFIG=${CONFIG})..."
+make CONFIG=${CONFIG} tests
+
+echo ""
+echo "=========================================="
+echo "Running tests..."
+echo "=========================================="
+
+# Change to tests directory and run tests
+cd tests
+./tests ../src/server/scache ../testcases
+TEST_RESULT=$?
+
+cd ..
+
+echo ""
+echo "=========================================="
+if [ $TEST_RESULT -eq 0 ]; then
+    echo "All tests passed successfully!"
+else
+    echo "Tests failed with exit code: $TEST_RESULT"
+fi
+echo "=========================================="
+
+exit $TEST_RESULT

src/core/Makefile

@@ -6,6 +6,11 @@ CC	 = g++
 _CFLAGS	 = -g -c -Wall -fPIC -c $(CFLAGS)
 LFLAGS	 = -lpthread  -shared
 
+GIT_DESCRIBE := $(shell git describe --tags --always --dirty 2>/dev/null || echo 0.0.0)
+GIT_REV := $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown)
+
+_CFLAGS += -DSCACHE_VERSION=\"$(GIT_DESCRIBE)\" -DSCACHE_REVISION=\"$(GIT_REV)\"
+
 ifeq ($(CONFIG), Debug)
 	_CFLAGS += -DDEBUG_BUILD -O0
 else
@@ -53,4 +58,4 @@ timer.o: timer.cpp
 
 
 clean:
-	rm -f $(OBJS) $(OUT)
+	rm -f $(OBJS) $(OUT)

src/core/config.h

@@ -19,6 +19,16 @@
 #define DB_ENABLE_COPY_ON_WRITE true
 #endif
 
+#ifndef DB_FLUSH_MIN_INTERVAL_MS
+// Minimum interval between index flushes. This reduces flush storms under cache churn.
+// A value of 0 disables rate limiting.
+#define DB_FLUSH_MIN_INTERVAL_MS 1000
+#endif
+
+#ifndef SCACHE_BUILD_DATE
+#define SCACHE_BUILD_DATE __DATE__ " " __TIME__
+#endif
+
 #define DEFAULT_LISTING_LIMIT 10000
 #define HASH_SEED 13
 
@@ -33,4 +43,4 @@
 
 #ifndef SCACHE_REVISION
 #define SCACHE_REVISION "<unknown>"
-#endif
+#endif

src/core/connection.cpp

@@ -1,4 +1,6 @@
-#define _GNU_SOURCE    
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif    
 
 #include <string.h>
 #include <stdio.h>
@@ -35,6 +37,10 @@
 #include "db.h"
 #endif
 
+const char *state_action_string[] = {
+    "close_connection", "registered_write", "needs_more_read", "continue_processing"
+};
+
 /* Globals */
 listener_collection scache_listeners = { .listeners = NULL, .listener_count = 0 };
 
@@ -310,9 +316,11 @@ bool connection_remove(scache_connection* conn) {
 	return true;
 }
 
-static unsigned int connection_any() {\
+#ifdef DEBUG_BUILD
+static unsigned int connection_any() {
 	return connections.size();
 }
+#endif
 
 static void* connection_handle_accept(void *arg)
 {
@@ -453,17 +461,19 @@ void close_socket(int fd){
 }
 
 void close_fd(int fd, const char* descriptor_type){
-	int ret;
 #ifdef DEBUG_BUILD
+	int ret;
 	if(scache_listeners.listeners != NULL){
 		for (uint32_t i = 0; i < scache_listeners.listener_count; i++)
 		{
 			assert(scache_listeners.listeners[i].fd != fd);
 		}
 	}
-#endif
 	ret = close(fd);
 	assert(ret == 0);
+#else
+	close(fd);
+#endif
 	DEBUG("[#%d] Closed %s\n", fd, descriptor_type);
 }
 
@@ -472,7 +482,6 @@ void monitoring_check();
 void connection_event_loop(void (*connection_handler)(scache_connection* connection), int monitoring_fd) {
 	epfd = epoll_create1(EPOLL_CLOEXEC);
 	struct epoll_event events[NUM_EVENTS];
-	int max_listener = 0;
 	int res;
 	int efd;
 	pthread_t tid[2];

src/core/connection_structures.h

@@ -26,9 +26,7 @@ typedef enum {
 	close_connection, registered_write, needs_more_read, continue_processing
 } state_action;
 
-static const char *state_action_string[] = {
-    "close_connection", "registered_write", "needs_more_read", "continue_processing"
-};
+extern const char *state_action_string[];
 
 typedef enum {
 	cache_listener, mon_listener, cache_connection, mon_connection