feat(resources #71): cgroup-aware resource-limit observability + regression guard

Issue #71 proposed an opt-in --auto-memory flag on the premise that DuckDB
sizes max_memory from host RAM and ignores container cgroup limits, leading to
kernel OOM kills (exit 137). Empirical testing of the bundled DuckDB 1.5.2
shows that premise is obsolete: DuckDB already honors cgroup limits, sizing
max_memory to ~80% of the cgroup memory limit and threads from the CPU quota.
A ~3 GiB query in a 1 GiB container fails with a graceful "Out of Memory"
error and the server survives -- no kernel kill.

Rather than ship a redundant override, this adds observability and a guard:

- src/system_resources.{hpp,cpp}: cgroup v1/v2 memory + CPU detection with
  injectable /sys/fs/cgroup roots; unit-tested in system_resources_test.cpp.
- database_manager: log a startup "resource-limits:" line reporting the
  detected ceiling and source (cgroup-v2 / cgroup-v1 / meminfo / hardware),
  so the limit flApi runs under is visible. No DuckDB setting is changed;
  duckdb.max_memory / duckdb.threads still override when set explicitly.
- test/integration/smoke_resource_limits.sh + `make smoke-test-resources`:
  Docker regression guard asserting graceful degradation (HTTP 500 OOM,
  server survives) and the cgroup-detection startup log. Skips off Linux/Docker.
- docs: DESIGN_DECISIONS §10 records the finding; CONFIG_REFERENCE notes the
  cgroup behavior and how to pin explicit values.

Author: jrosskopf

CMakeLists.txt

@@ -272,6 +272,7 @@ add_library(flapi-lib STATIC
     src/sql_parameter_classifier.cpp
     src/sql_template_processor.cpp
     src/sql_utils.cpp
+    src/system_resources.cpp
     src/mcp_server.cpp
     src/mcp_tool_handler.cpp
     src/mcp_tool_rate_limiter.cpp

Makefile

@@ -1,7 +1,7 @@
 # Makefile for flAPI project
 
 # Phony targets
-.PHONY: all debug release clean run-debug run-release run-integration-tests docker-build web cli-build cli-test vscode-build vscode-dev integration-test integration-tests integration-test-rest integration-test-mcp integration-test-ducklake integration-test-examples integration-test-setup integration-test-ci test-all help
+.PHONY: all debug release clean run-debug run-release run-integration-tests docker-build web cli-build cli-test vscode-build vscode-dev integration-test integration-tests integration-test-rest integration-test-mcp integration-test-ducklake integration-test-examples integration-test-setup integration-test-ci smoke-test-resources test-all help
 
 # Check if Ninja is available
 NINJA := $(shell which ninja)
@@ -309,6 +309,13 @@ integration-test-ci: release integration-test-setup
 	echo "Integration tests completed with exit code: $$TEST_RESULT"; \
 	exit $$TEST_RESULT
 
+# Container smoke test for cgroup-aware memory sizing (#71).
+# Runs the release binary in a memory-limited Docker container and asserts
+# DuckDB honors the cgroup limit (graceful OOM, server survives). Skips on
+# non-Linux / no-Docker hosts. See test/integration/smoke_resource_limits.sh.
+smoke-test-resources: release
+	@bash test/integration/smoke_resource_limits.sh
+
 # Build Docker image
 docker: release
 	@echo "Building Docker image..."

docs/CONFIG_REFERENCE.md

@@ -300,8 +300,16 @@ duckdb:
 **Notes:**
 - Omit `db_path` or set to `:memory:` for an in-memory database
 - Any key-value pairs are passed directly as DuckDB settings
-
-> **Implementation:** `src/database_manager.cpp` | **Tests:** `test/cpp/database_manager_test.cpp`
+- **Containers (cgroup limits):** when `threads`/`max_memory` are omitted (the
+  default), DuckDB sizes them from the container's cgroup limits — `max_memory`
+  to ~80% of the cgroup memory limit and `threads` from the CPU quota (Kubernetes
+  limits, Docker `--memory`/`--cpus`, etc.). You normally do **not** need to set
+  these per deployment target. To pin explicit values, set them here and they are
+  passed straight through. flAPI logs the detected ceiling at startup as
+  `resource-limits: memory source=cgroup-v2 available=...MB` / `cpu source=...`,
+  so the limit it is actually running under is visible in the logs (#71).
+
+> **Implementation:** `src/database_manager.cpp`, `src/system_resources.cpp` | **Tests:** `test/cpp/database_manager_test.cpp`, `test/cpp/system_resources_test.cpp`
 
 ### 2.5 DuckLake Configuration
 

docs/spec/DESIGN_DECISIONS.md

@@ -416,6 +416,47 @@ four supported platforms (#49 / `.github/workflows/build.yaml`).
 
 ---
 
+## 10. Container memory/CPU limits: rely on DuckDB's cgroup awareness (#71)
+
+**Decision:** Do **not** add a flApi-side mechanism to size `max_memory` /
+`threads` from container cgroup limits. Instead, rely on DuckDB's own
+cgroup-aware detection and simply **log the detected limits at startup** for
+observability.
+
+**Context:** Issue #71 proposed an opt-in `--auto-memory` flag, on the premise
+that DuckDB reads *host* RAM (via `/proc/meminfo`, `sysconf`) and ignores
+container cgroup limits — so an unbounded buffer pool inside a small container
+would be kernel-OOM-killed (exit 137) rather than failing gracefully.
+
+**Finding (empirically verified, DuckDB 1.5.2):** that premise no longer holds.
+Running the binary in memory/CPU-limited containers shows DuckDB **already**
+honors cgroup limits:
+
+| Container limit | DuckDB `memory_limit` (no config) | DuckDB `threads` (no config) |
+|---|---|---|
+| `--memory=512m` | 409.5 MiB (≈80% of cgroup) | — |
+| `--memory=1g --cpus=2` | 819 MiB (≈80% of cgroup) | 2 (from CPU quota) |
+
+A ~3 GiB query in a 1 GiB container raises a **graceful** DuckDB "Out of Memory"
+error and the server survives — no kernel kill. (The `using 32 threads` startup
+line is Crow's HTTP thread pool, not DuckDB query parallelism — a red herring.)
+
+**Consequences:**
+- A flApi-side override would, at best, duplicate DuckDB's behavior; its only
+  unique value would be a tunable percentage (DuckDB hardcodes ~80%). That did
+  not justify the cross-platform detection/precedence surface area, so it was
+  dropped.
+- `src/system_resources.{hpp,cpp}` provides cgroup v1/v2 memory + CPU detection
+  (unit-tested with injectable `/sys/fs/cgroup` roots) used **only** to emit a
+  startup `resource-limits:` INFO log, so the ceiling flApi runs under is
+  visible and container misconfiguration is diagnosable.
+- **To override** the defaults, set `duckdb.max_memory` / `duckdb.threads`
+  explicitly in `flapi.yaml` (these are passed straight through to DuckDB).
+- `test/integration/smoke_resource_limits.sh` (`make smoke-test-resources`) is a
+  Docker regression guard asserting the graceful-degradation behavior.
+
+---
+
 ## Summary
 
 These design decisions prioritize:

src/database_manager.cpp

@@ -12,6 +12,7 @@
 #include "sql_utils.hpp"
 #include "database_manager.hpp"
 #include "duckdb_raii.hpp"
+#include "system_resources.hpp"
 
 namespace flapi {
 
@@ -259,7 +260,16 @@ void DatabaseManager::createAndInitializeDuckDBConfig(std::shared_ptr<ConfigMana
         throw std::runtime_error("Failed to set DuckDB configuration: autoload_known_extensions");
     }
 
-    // Apply settings from the configuration
+    // Observability (#71): log the memory / CPU limits we detect for this
+    // process (honoring container cgroup limits). This does NOT change any
+    // DuckDB setting -- DuckDB 1.5.2 is itself cgroup-aware and sizes
+    // max_memory (~80% of the limit) and threads from the same limits. The
+    // log makes container misconfiguration diagnosable and lets operators see
+    // the ceiling flAPI is actually running under. To override, set
+    // duckdb.max_memory / duckdb.threads explicitly in flapi.yaml.
+    logDetectedResourceLimits(config_manager);
+
+    // Apply settings from the configuration.
     const auto& duckdb_settings = config_manager->getDuckDBConfig().settings;
     for (const auto& [key, value] : duckdb_settings) {
         if (duckdb_set_config(config, key.c_str(), value.c_str()) == DuckDBError) {
@@ -269,6 +279,34 @@ void DatabaseManager::createAndInitializeDuckDBConfig(std::shared_ptr<ConfigMana
     }
 }
 
+void DatabaseManager::logDetectedResourceLimits(std::shared_ptr<ConfigManager> config_manager) {
+    const auto& settings = config_manager->getDuckDBConfig().settings;
+
+    flapi::MemoryDetection mem = flapi::DetectAvailableMemoryBytes();
+    if (mem.source != "unknown" && mem.bytes > 0) {
+        CROW_LOG_INFO << "resource-limits: memory source=" << mem.source
+                      << " available=" << (mem.bytes / (1024ull * 1024ull)) << "MB"
+                      << (settings.count("max_memory") > 0
+                              ? " (overridden by duckdb.max_memory=" + settings.at("max_memory") + ")"
+                              : " (DuckDB sizes max_memory from this limit)");
+    } else {
+        CROW_LOG_DEBUG << "resource-limits: could not detect a memory limit; "
+                       << "DuckDB will use its own detection.";
+    }
+
+    flapi::CpuDetection cpu = flapi::DetectAvailableCpuCount();
+    if (cpu.source != "unknown" && cpu.cores >= 1) {
+        CROW_LOG_INFO << "resource-limits: cpu source=" << cpu.source
+                      << " cores=" << cpu.cores
+                      << (settings.count("threads") > 0
+                              ? " (overridden by duckdb.threads=" + settings.at("threads") + ")"
+                              : " (DuckDB sizes threads from this limit)");
+    } else {
+        CROW_LOG_DEBUG << "resource-limits: could not detect a CPU quota; "
+                       << "DuckDB will use its own detection.";
+    }
+}
+
 void DatabaseManager::loadDefaultExtensions(std::shared_ptr<ConfigManager> config_manager) {
     auto extensions = config_manager->getDuckDBConfig().default_extensions;
 

src/include/database_manager.hpp

@@ -100,7 +100,12 @@ class DatabaseManager : public std::enable_shared_from_this<DatabaseManager> {
     void logDuckDBVersion();
 
     void createAndInitializeDuckDBConfig(std::shared_ptr<ConfigManager> config_manager, duckdb_config& config);
-   
+
+    // Observability (#71): log the cgroup-detected memory / CPU limits at
+    // startup. Does not change any DuckDB setting (DuckDB is itself
+    // cgroup-aware); purely diagnostic so the running ceiling is visible.
+    void logDetectedResourceLimits(std::shared_ptr<ConfigManager> config_manager);
+
 
     std::string processTemplate(const EndpointConfig& endpoint, std::map<std::string, std::string>& params);
     std::string processCacheTemplate(const EndpointConfig& endpoint, const CacheConfig& cacheConfig, std::map<std::string, std::string>& params);

src/include/system_resources.hpp

@@ -0,0 +1,47 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace flapi {
+
+// Result of probing the memory available to this process. `bytes` is the
+// detected ceiling (cgroup limit or host physical memory, whichever is
+// smaller); `source` names where the value came from so it can be logged.
+// On failure `bytes == 0` and `source == "unknown"`.
+struct MemoryDetection {
+    uint64_t bytes = 0;
+    std::string source = "unknown"; // cgroup-v2|cgroup-v1|meminfo|sysconf|sysctl|win-global|unknown
+};
+
+// Result of probing the CPU quota available to this process. `cores` is
+// clamped to at least 1 when a positive value is detected.
+struct CpuDetection {
+    uint32_t cores = 0;
+    std::string source = "unknown"; // cgroup-v2|cgroup-v1|hardware|unknown
+};
+
+// --- Pure parsers (no filesystem; unit-tested directly) ------------------
+
+// cgroup v2 `memory.max`. A literal "max" means unlimited -> nullopt.
+std::optional<uint64_t> ParseCgroupV2MemoryMax(const std::string& content);
+
+// cgroup v1 `memory.limit_in_bytes`. Absurdly large sentinel values
+// (PAGE_COUNTER_MAX, 0x7FFFFFFFFFFFF000, etc.) mean unlimited -> nullopt.
+std::optional<uint64_t> ParseCgroupV1MemoryLimit(const std::string& content);
+
+// cgroup v2 `cpu.max` == "<quota> <period>". "max ..." means unlimited ->
+// nullopt. Otherwise effective cores = ceil(quota / period), clamped >= 1.
+std::optional<uint32_t> ParseCgroupV2CpuMax(const std::string& content);
+
+// cgroup v1 `cpu.cfs_quota_us` / `cpu.cfs_period_us`. quota -1 means
+// unlimited -> nullopt. Otherwise ceil(quota / period), clamped >= 1.
+std::optional<uint32_t> ParseCgroupV1Cpu(const std::string& quota, const std::string& period);
+
+// --- Composing detectors (probe filesystem; `root` is injectable for tests) ---
+
+MemoryDetection DetectAvailableMemoryBytes(const std::string& root = "/");
+CpuDetection DetectAvailableCpuCount(const std::string& root = "/");
+
+} // namespace flapi