feat: add keepalive controls to System Settings

- Introduced optional keepalive settings: `keepalive_idle` and `keepalive_count` in the Server struct.
- Implemented UI controls for keepalive settings in System Settings, including validation and persistence.
- Added localization support for new keepalive fields in multiple languages.
- Created a manual test tracking plan for verifying keepalive controls and their behavior.
- Updated existing tests to cover new functionality and ensure proper validation of keepalive inputs.
- Ensured safe defaults and fallback behavior for missing or invalid keepalive values.

Author: actions-user

backend/internal/api/handlers/settings_handler.go

@@ -5,6 +5,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"strconv"
 	"strings"
 	"time"
 
@@ -37,6 +38,15 @@ type SettingsHandler struct {
 	DataRoot     string
 }
 
+const (
+	settingCaddyKeepaliveIdle     = "caddy.keepalive_idle"
+	settingCaddyKeepaliveCount    = "caddy.keepalive_count"
+	minCaddyKeepaliveIdleDuration = time.Second
+	maxCaddyKeepaliveIdleDuration = 24 * time.Hour
+	minCaddyKeepaliveCount        = 1
+	maxCaddyKeepaliveCount        = 100
+)
+
 func NewSettingsHandler(db *gorm.DB) *SettingsHandler {
 	return &SettingsHandler{
 		DB:          db,
@@ -109,6 +119,11 @@ func (h *SettingsHandler) UpdateSetting(c *gin.Context) {
 		}
 	}
 
+	if err := validateOptionalKeepaliveSetting(req.Key, req.Value); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
 	setting := models.Setting{
 		Key:   req.Key,
 		Value: req.Value,
@@ -247,6 +262,10 @@ func (h *SettingsHandler) PatchConfig(c *gin.Context) {
 				}
 			}
 
+			if err := validateOptionalKeepaliveSetting(key, value); err != nil {
+				return err
+			}
+
 			setting := models.Setting{
 				Key:      key,
 				Value:    value,
@@ -284,6 +303,10 @@ func (h *SettingsHandler) PatchConfig(c *gin.Context) {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid admin_whitelist"})
 			return
 		}
+		if strings.Contains(err.Error(), "invalid caddy.keepalive_idle") || strings.Contains(err.Error(), "invalid caddy.keepalive_count") {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
 		if respondPermissionError(c, h.SecuritySvc, "settings_save_failed", err, h.DataRoot) {
 			return
 		}
@@ -401,6 +424,53 @@ func validateAdminWhitelist(whitelist string) error {
 	return nil
 }
 
+func validateOptionalKeepaliveSetting(key, value string) error {
+	switch key {
+	case settingCaddyKeepaliveIdle:
+		return validateKeepaliveIdleValue(value)
+	case settingCaddyKeepaliveCount:
+		return validateKeepaliveCountValue(value)
+	default:
+		return nil
+	}
+}
+
+func validateKeepaliveIdleValue(value string) error {
+	idle := strings.TrimSpace(value)
+	if idle == "" {
+		return nil
+	}
+
+	d, err := time.ParseDuration(idle)
+	if err != nil {
+		return fmt.Errorf("invalid caddy.keepalive_idle")
+	}
+
+	if d < minCaddyKeepaliveIdleDuration || d > maxCaddyKeepaliveIdleDuration {
+		return fmt.Errorf("invalid caddy.keepalive_idle")
+	}
+
+	return nil
+}
+
+func validateKeepaliveCountValue(value string) error {
+	raw := strings.TrimSpace(value)
+	if raw == "" {
+		return nil
+	}
+
+	count, err := strconv.Atoi(raw)
+	if err != nil {
+		return fmt.Errorf("invalid caddy.keepalive_count")
+	}
+
+	if count < minCaddyKeepaliveCount || count > maxCaddyKeepaliveCount {
+		return fmt.Errorf("invalid caddy.keepalive_count")
+	}
+
+	return nil
+}
+
 func (h *SettingsHandler) syncAdminWhitelist(whitelist string) error {
 	return h.syncAdminWhitelistWithDB(h.DB, whitelist)
 }

backend/internal/api/handlers/settings_handler_test.go

@@ -413,6 +413,58 @@ func TestSettingsHandler_UpdateSetting_InvalidAdminWhitelist(t *testing.T) {
 	assert.Contains(t, w.Body.String(), "Invalid admin_whitelist")
 }
 
+func TestSettingsHandler_UpdateSetting_InvalidKeepaliveIdle(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db := setupSettingsTestDB(t)
+
+	handler := handlers.NewSettingsHandler(db)
+	router := newAdminRouter()
+	router.POST("/settings", handler.UpdateSetting)
+
+	payload := map[string]string{
+		"key":   "caddy.keepalive_idle",
+		"value": "bad-duration",
+	}
+	body, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/settings", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Contains(t, w.Body.String(), "invalid caddy.keepalive_idle")
+}
+
+func TestSettingsHandler_UpdateSetting_ValidKeepaliveCount(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db := setupSettingsTestDB(t)
+
+	handler := handlers.NewSettingsHandler(db)
+	router := newAdminRouter()
+	router.POST("/settings", handler.UpdateSetting)
+
+	payload := map[string]string{
+		"key":      "caddy.keepalive_count",
+		"value":    "9",
+		"category": "caddy",
+		"type":     "number",
+	}
+	body, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/settings", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var setting models.Setting
+	err := db.Where("key = ?", "caddy.keepalive_count").First(&setting).Error
+	assert.NoError(t, err)
+	assert.Equal(t, "9", setting.Value)
+}
+
 func TestSettingsHandler_UpdateSetting_SecurityKeyInvalidatesCache(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	db := setupSettingsTestDB(t)
@@ -538,6 +590,64 @@ func TestSettingsHandler_PatchConfig_InvalidAdminWhitelist(t *testing.T) {
 	assert.Contains(t, w.Body.String(), "Invalid admin_whitelist")
 }
 
+func TestSettingsHandler_PatchConfig_InvalidKeepaliveCount(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db := setupSettingsTestDB(t)
+
+	handler := handlers.NewSettingsHandler(db)
+	router := newAdminRouter()
+	router.PATCH("/config", handler.PatchConfig)
+
+	payload := map[string]any{
+		"caddy": map[string]any{
+			"keepalive_count": 0,
+		},
+	}
+	body, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest(http.MethodPatch, "/config", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Contains(t, w.Body.String(), "invalid caddy.keepalive_count")
+}
+
+func TestSettingsHandler_PatchConfig_ValidKeepaliveSettings(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db := setupSettingsTestDB(t)
+
+	handler := handlers.NewSettingsHandler(db)
+	router := newAdminRouter()
+	router.PATCH("/config", handler.PatchConfig)
+
+	payload := map[string]any{
+		"caddy": map[string]any{
+			"keepalive_idle":  "30s",
+			"keepalive_count": 12,
+		},
+	}
+	body, _ := json.Marshal(payload)
+
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest(http.MethodPatch, "/config", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var idle models.Setting
+	err := db.Where("key = ?", "caddy.keepalive_idle").First(&idle).Error
+	assert.NoError(t, err)
+	assert.Equal(t, "30s", idle.Value)
+
+	var count models.Setting
+	err = db.Where("key = ?", "caddy.keepalive_count").First(&count).Error
+	assert.NoError(t, err)
+	assert.Equal(t, "12", count.Value)
+}
+
 func TestSettingsHandler_PatchConfig_ReloadFailureReturns500(t *testing.T) {
 	gin.SetMode(gin.TestMode)
 	db := setupSettingsTestDB(t)

backend/internal/caddy/config.go

@@ -857,6 +857,27 @@ func normalizeHeaderOps(headerOps map[string]any) {
 	}
 }
 
+func applyOptionalServerKeepalive(conf *Config, keepaliveIdle string, keepaliveCount int) {
+	if conf == nil || conf.Apps.HTTP == nil || conf.Apps.HTTP.Servers == nil {
+		return
+	}
+
+	server, ok := conf.Apps.HTTP.Servers["charon_server"]
+	if !ok || server == nil {
+		return
+	}
+
+	idle := strings.TrimSpace(keepaliveIdle)
+	if idle != "" {
+		server.KeepaliveIdle = &idle
+	}
+
+	if keepaliveCount > 0 {
+		count := keepaliveCount
+		server.KeepaliveCount = &count
+	}
+}
+
 // NormalizeAdvancedConfig traverses a parsed JSON advanced config (map or array)
 // and normalizes any headers blocks so that header values are arrays of strings.
 // It returns the modified config object which can be JSON marshaled again.

backend/internal/caddy/config_generate_test.go

@@ -103,3 +103,43 @@ func TestGenerateConfig_EmergencyRoutesBypassSecurity(t *testing.T) {
 		require.NotEqual(t, "crowdsec", name)
 	}
 }
+
+func TestApplyOptionalServerKeepalive_OmitsWhenUnset(t *testing.T) {
+	cfg := &Config{
+		Apps: Apps{
+			HTTP: &HTTPApp{Servers: map[string]*Server{
+				"charon_server": {
+					Listen: []string{":80", ":443"},
+					Routes: []*Route{},
+				},
+			}},
+		},
+	}
+
+	applyOptionalServerKeepalive(cfg, "", 0)
+
+	server := cfg.Apps.HTTP.Servers["charon_server"]
+	require.Nil(t, server.KeepaliveIdle)
+	require.Nil(t, server.KeepaliveCount)
+}
+
+func TestApplyOptionalServerKeepalive_AppliesValidValues(t *testing.T) {
+	cfg := &Config{
+		Apps: Apps{
+			HTTP: &HTTPApp{Servers: map[string]*Server{
+				"charon_server": {
+					Listen: []string{":80", ":443"},
+					Routes: []*Route{},
+				},
+			}},
+		},
+	}
+
+	applyOptionalServerKeepalive(cfg, "45s", 7)
+
+	server := cfg.Apps.HTTP.Servers["charon_server"]
+	require.NotNil(t, server.KeepaliveIdle)
+	require.Equal(t, "45s", *server.KeepaliveIdle)
+	require.NotNil(t, server.KeepaliveCount)
+	require.Equal(t, 7, *server.KeepaliveCount)
+}