fix: add ability to disable logs

Author: ivictbor

README.md

@@ -147,6 +147,8 @@ wait0 caches only `GET` responses with a `2xx` status, an allowed `Content-Type`
 
 An origin response that fails these checks is served as `X-Wait0: bypass` without being stored, with `X-Wait0-Reason` explaining why. If background revalidation receives a disallowed content type, either cache-control directive, or a non-`2xx` status, the existing entry is deleted; a network error leaves it available. A stale response is reported as `X-Wait0: hit`.
 
+`logging.debug_headers` controls wait0 diagnostic response headers and the markers sent to the origin during revalidation. Omit it to enable every supported header, use a subset to select individual headers, or set `debug_headers: []` to disable all diagnostics. Functional headers such as `X-Wait0-CSRF` and origin-provided `X-Wait0-Tag` are not controlled by this option.
+
 ### Query parameter caching
 
 Cache keys use only the URL path by default, so `/blog`, `/blog?page=1`, and `/blog?utm_source=email` share the same cached response. The first cold request reaches the origin with its complete query and fills the shared entry; later background refreshes omit query parameters that are not in `varyByQueryParams`.
@@ -249,6 +251,18 @@ rules:
       maxRequestsAtATime: 20
 
 logging:
+  # Diagnostic response headers and origin revalidation markers. Omit this
+  # option to enable all supported headers by default.
+  debug_headers:
+    - X-Wait0
+    - X-Wait0-Reason
+    - X-Wait0-Revalidated-At
+    - X-Wait0-Revalidated-By
+    - X-Wait0-Discovered-By
+    - X-Wait0-Revalidate-At
+    - X-Wait0-Revalidate-Entropy
+  # To disable every diagnostic header, replace the list above with:
+  # debug_headers: []
   # Logs a stats snapshot at this interval; omit to disable.
   log_stats_every: '1m'
   # Logs a summary after each warmup batch.

debug/wait0.yaml

@@ -49,6 +49,18 @@ rules:
       maxRequestsAtATime: 1000
 
 logging:
+  # Diagnostic response headers and origin revalidation markers.
+  # Omit debug_headers to enable all supported headers by default.
+  debug_headers:
+    - X-Wait0
+    - X-Wait0-Reason
+    - X-Wait0-Revalidated-At
+    - X-Wait0-Revalidated-By
+    - X-Wait0-Discovered-By
+    - X-Wait0-Revalidate-At
+    - X-Wait0-Revalidate-Entropy
+  # To disable every diagnostic header, replace the list above with:
+  # debug_headers: []
   # log stats when enabled logs
   log_stats_every: '10s'
   log_warmup: true

docs/api-endpoints.md

@@ -50,17 +50,19 @@ An origin response is cacheable only when:
 
 `cachableContentType` defaults to `text/html` and `application/xhtml+xml`. Matching is case-insensitive and ignores media-type parameters such as `charset=utf-8`. A missing or malformed `Content-Type` is not cacheable.
 
-## Response headers added by wait0
+## Diagnostic headers added by wait0
 
 | Header | When present | Meaning |
 |--------|--------------|---------|
-| `X-Wait0` | always on handled responses | Cache/proxy decision marker |
+| `X-Wait0` | handled responses when enabled | Cache/proxy decision marker |
 | `X-Wait0-Reason` | response bypassed or failed | Machine-readable reason the response was not cached |
 | `X-Wait0-Revalidated-At` | cache `hit` with revalidation metadata | Last revalidation timestamp (RFC3339Nano) |
 | `X-Wait0-Revalidated-By` | with `X-Wait0-Revalidated-At` | Revalidation source (`user`, `warmup`, `invalidate`, etc.) |
 | `X-Wait0-Discovered-By` | if entry was discovery seeded | Discovery source marker |
 | `Access-Control-Expose-Headers` | when wait0 headers exist | Exposes wait0 headers to browser clients |
 
+During background revalidation, wait0 can also send `X-Wait0-Revalidate-At` and `X-Wait0-Revalidate-Entropy` to the origin. `logging.debug_headers` controls all seven diagnostic headers. Omission enables all; an explicit `debug_headers: []` disables all. A configured subset enables only the named headers. `WAIT0_SEND_REVALIDATE_MARKERS=false` remains a master disable for the two origin markers.
+
 ## Example
 
 ```bash

docs/for-developers.md

@@ -157,6 +157,7 @@ For dashboard:
 
 | Field | Type | Notes |
 |-------|------|------|
+| `debug_headers` | string array | Diagnostic headers to emit; omitted enables all seven supported headers, while an explicit `[]` disables all |
 | `log_stats_every` | duration | Enables periodic stats logging (`> 0`) |
 | `log_warmup` | bool | Emits warmup batch summaries |
 | `log_url_autodiscover` | bool | Emits per-sitemap discovery logs |
@@ -174,6 +175,8 @@ For dashboard:
 - Keep static assets in CDN, Nginx, and browser caches; wait0 defaults to caching only dynamic HTML/XHTML SWR responses.
 - Origin `2xx` responses with `Cache-Control: no-cache` or `no-store` are not stored; either directive received during revalidation deletes the existing entry.
 - Warmup loops never overlap: wait0 completes the current rule snapshot, waits `pauseBetweenRuns`, then loads a fresh snapshot.
+- `logging.debug_headers` may select any of `X-Wait0`, `X-Wait0-Reason`, `X-Wait0-Revalidated-At`, `X-Wait0-Revalidated-By`, `X-Wait0-Discovered-By`, `X-Wait0-Revalidate-At`, and `X-Wait0-Revalidate-Entropy`.
+- Omit `logging.debug_headers` to enable all diagnostics; set `debug_headers: []` to disable all of them.
 - `X-Wait0` response header identifies behavior (`hit`, `miss`, `bypass`, `ignore-by-cookie`, `ignore-by-status`, `bad-gateway`).
 - `X-Wait0-Reason` identifies why a response was bypassed or failed (for example, `bypass-rule` or `non-cacheable-content-type`).
 

internal/wait0/config.go

@@ -48,6 +48,9 @@ type Config struct {
 	Logging struct {
 		LogStatsEvery    string        `yaml:"log_stats_every"`
 		logStatsEveryDur time.Duration `yaml:"-"`
+		// DebugHeaders controls wait0 diagnostic response headers and origin
+		// revalidation markers. Omitted enables all; an explicit [] disables all.
+		DebugHeaders []string `yaml:"debug_headers"`
 		// LogWarmUp prints a summary after each warmup batch drains.
 		LogWarmUp bool `yaml:"log_warmup"`
 
@@ -189,6 +192,12 @@ func LoadConfig(path string) (Config, error) {
 		cfg.Logging.logStatsEveryDur = d
 	}
 
+	debugHeaders, err := proxy.NormalizeDebugHeaders(cfg.Logging.DebugHeaders)
+	if err != nil {
+		return Config{}, fmt.Errorf("logging.debug_headers: %w", err)
+	}
+	cfg.Logging.DebugHeaders = debugHeaders
+
 	if strings.TrimSpace(cfg.Logging.LogRevalidationEvery) != "" {
 		// Backward compatible alias for the previous warmup logging setting.
 		_, err := time.ParseDuration(cfg.Logging.LogRevalidationEvery)

internal/wait0/config_test.go

@@ -8,6 +8,8 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"wait0/internal/wait0/proxy"
 )
 
 func TestLoadConfig_ValidAndCompiledFields(t *testing.T) {
@@ -56,6 +58,9 @@ rules:
 	if cfg.Logging.logStatsEveryDur != 10*time.Second {
 		t.Fatalf("logStatsEveryDur = %s", cfg.Logging.logStatsEveryDur)
 	}
+	if got, want := cfg.Logging.DebugHeaders, proxy.DefaultDebugHeaders(); !slicesEqual(got, want) {
+		t.Fatalf("default debug_headers = %v, want %v", got, want)
+	}
 	if cfg.URLsDiscover.initialDelayDur != 2*time.Second {
 		t.Fatalf("initialDelayDur = %s", cfg.URLsDiscover.initialDelayDur)
 	}
@@ -147,6 +152,7 @@ func TestLoadConfig_Errors(t *testing.T) {
 		{name: "bad warmup", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\nrules:\n  - match: \"PathPrefix(/)\"\n    warmUp:\n      pauseBetweenRuns: \"\"\n      maxRequestsAtATime: 1\n"},
 		{name: "both warmup intervals", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\nrules:\n  - match: \"PathPrefix(/)\"\n    warmUp:\n      pauseBetweenRuns: \"10s\"\n      runEvery: \"10s\"\n      maxRequestsAtATime: 1\n"},
 		{name: "bad log stats", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\nlogging:\n  log_stats_every: \"bad\"\nrules: []\n"},
+		{name: "bad debug header", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\nlogging:\n  debug_headers: [\"X-Wait0-Unknown\"]\nrules: []\n"},
 		{name: "duplicate auth token ids", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\n  invalidation:\n    enabled: true\nauth:\n  tokens:\n    - id: \"dup\"\n      token: \"a\"\n      scopes: [\"invalidation:write\"]\n    - id: \"dup\"\n      token: \"b\"\n      scopes: [\"invalidation:write\"]\nrules: []\n"},
 		{name: "invalidation enabled without auth scope", yaml: "storage:\n  ram: {max: \"1m\"}\n  disk: {max: \"1m\"}\nserver:\n  origin: \"http://x\"\n  invalidation:\n    enabled: true\nauth:\n  tokens:\n    - id: \"x\"\n      token: \"t\"\n      scopes: [\"other:scope\"]\nrules: []\n"},
 	}
@@ -164,6 +170,30 @@ func TestLoadConfig_Errors(t *testing.T) {
 	}
 }
 
+func TestLoadConfig_ExplicitEmptyDebugHeadersDisablesAll(t *testing.T) {
+	cfgPath := filepath.Join(t.TempDir(), "wait0.yaml")
+	yaml := `storage:
+  ram: {max: "1m"}
+  disk: {max: "1m"}
+server:
+  origin: "http://x"
+logging:
+  debug_headers: []
+rules: []
+`
+	if err := os.WriteFile(cfgPath, []byte(yaml), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	cfg, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+	if cfg.Logging.DebugHeaders == nil || len(cfg.Logging.DebugHeaders) != 0 {
+		t.Fatalf("debug_headers = %#v, want non-nil empty list", cfg.Logging.DebugHeaders)
+	}
+}
+
 func TestLoadConfig_AuthTokenEnvOverride(t *testing.T) {
 	t.Setenv("WAIT0_INV_TOKEN", "from-env-token")
 
@@ -205,6 +235,18 @@ rules: []
 	}
 }
 
+func slicesEqual(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
 func TestLoadConfig_DebugConfigHasFixedLocalAuthToken(t *testing.T) {
 	t.Setenv("WAIT0_API_AUTH_TOKEN", "must-not-override-debug-config")
 

internal/wait0/handler_test.go

@@ -45,6 +45,33 @@ func TestHandle_CacheMissThenHit(t *testing.T) {
 	}
 }
 
+func TestHandle_ExplicitEmptyDebugHeadersEmitsNone(t *testing.T) {
+	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		for _, name := range proxy.DefaultDebugHeaders() {
+			w.Header().Set(name, "origin-spoof")
+		}
+		fmt.Fprint(w, "ok")
+	}))
+	defer origin.Close()
+
+	rule := mustRule(t, "PathPrefix(/)")
+	s := newTestService(t, origin.URL, []Rule{rule})
+	s.debugHeaders = proxy.NewDebugHeaderSet([]string{})
+
+	w := httptest.NewRecorder()
+	s.Handler().ServeHTTP(w, httptest.NewRequest(http.MethodGet, "http://wait0.local/page", nil))
+
+	if got := w.Result().StatusCode; got != http.StatusOK {
+		t.Fatalf("status = %d, want 200", got)
+	}
+	for _, name := range proxy.DefaultDebugHeaders() {
+		if got := w.Result().Header.Get(name); got != "" {
+			t.Fatalf("disabled debug header %s = %q", name, got)
+		}
+	}
+}
+
 func TestHandle_NonCachableContentTypeByDefault(t *testing.T) {
 	var hits atomic.Int32
 	origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/wait0/proxy/controller.go

@@ -15,6 +15,7 @@ type Runtime interface {
 	FetchFromOrigin(r *http.Request) (Entry, bool, string, error)
 	Store(key string, ent Entry)
 	RevalidateAsync(key, path, query string)
+	DebugHeaders() DebugHeaderSet
 	WriteEntryWithStats(w http.ResponseWriter, ent Entry, wait0, reason string)
 }
 
@@ -80,7 +81,7 @@ func (c *Controller) Handle(w http.ResponseWriter, r *http.Request) {
 
 	respEnt, cacheable, statusKind, err := c.rt.FetchFromOrigin(r)
 	if err != nil {
-		SetWait0Headers(w.Header(), "bad-gateway", "origin-error")
+		SetWait0Headers(w.Header(), "bad-gateway", "origin-error", c.rt.DebugHeaders())
 		http.Error(w, "bad gateway", http.StatusBadGateway)
 		return
 	}
@@ -110,7 +111,7 @@ func (c *Controller) Handle(w http.ResponseWriter, r *http.Request) {
 func (c *Controller) proxyPass(w http.ResponseWriter, r *http.Request, wait0, reason string) {
 	ent, _, _, err := c.rt.FetchFromOrigin(r)
 	if err != nil {
-		SetWait0Headers(w.Header(), "bad-gateway", "origin-error")
+		SetWait0Headers(w.Header(), "bad-gateway", "origin-error", c.rt.DebugHeaders())
 		http.Error(w, "bad gateway", http.StatusBadGateway)
 		return
 	}

internal/wait0/proxy/controller_test.go

@@ -30,6 +30,7 @@ type fakeRuntime struct {
 	revalidated  []struct{ key, path, query string }
 	writeWait0   []string
 	writeReasons []string
+	debugHeaders DebugHeaderSet
 }
 
 func (f *fakeRuntime) HandleControl(http.ResponseWriter, *http.Request) bool {
@@ -56,13 +57,15 @@ func (f *fakeRuntime) RevalidateAsync(key, path, query string) {
 	f.revalidated = append(f.revalidated, struct{ key, path, query string }{key: key, path: path, query: query})
 }
 
+func (f *fakeRuntime) DebugHeaders() DebugHeaderSet { return f.debugHeaders }
+
 func (f *fakeRuntime) WriteEntryWithStats(w http.ResponseWriter, ent Entry, wait0, reason string) {
 	f.writeWait0 = append(f.writeWait0, wait0)
 	f.writeReasons = append(f.writeReasons, reason)
 	if ent.Status == 0 {
 		ent.Status = http.StatusOK
 	}
-	WriteEntry(w, ent, wait0, reason)
+	WriteEntry(w, ent, wait0, reason, f.debugHeaders)
 }
 
 func TestController_Handle_ShortCircuitsControl(t *testing.T) {
@@ -323,3 +326,24 @@ func TestController_Handle_OriginBranches(t *testing.T) {
 		})
 	}
 }
+
+func TestController_Handle_OriginErrorWithDebugHeadersDisabled(t *testing.T) {
+	rt := &fakeRuntime{
+		originErr:    errors.New("boom"),
+		debugHeaders: NewDebugHeaderSet([]string{}),
+	}
+	c := NewController(rt)
+	w := httptest.NewRecorder()
+	r := httptest.NewRequest(http.MethodGet, "http://wait0.local/origin", nil)
+
+	c.Handle(w, r)
+
+	if got := w.Result().StatusCode; got != http.StatusBadGateway {
+		t.Fatalf("status = %d, want %d", got, http.StatusBadGateway)
+	}
+	for _, name := range DefaultDebugHeaders() {
+		if got := w.Result().Header.Get(name); got != "" {
+			t.Fatalf("disabled header %s = %q", name, got)
+		}
+	}
+}