feat(api): add benchmark write endpoint and archive specs

Author: EvanNotFound

apps/api/README.md

@@ -7,18 +7,21 @@ Minimal Go service for the public `events.vercount.one` surface.
 - `/`
 - `/healthz`
 - `/js`
+- `/bench/write`
 - `/log`
 - `/api/v1/log`
 - `/api/v2/log`
 
+`GET /bench/write` is a public benchmark helper for external probe tools. It always writes to the fixed synthetic target `https://bench.vercount.one/gurt`, returns the same v2-style JSON envelope used by the modern public API, and sends no-store cache headers so latency checks hit the Go service instead of cached content.
+
 ## Internal structure
 
 The Go API stays intentionally small and is organized by runtime surface instead of generic web layers:
 
 - `internal/app/runtime.go` - env/config loading and logger setup
 - `internal/app/server.go` - dependency wiring and chi route registration
 - `internal/api/public.go` - `/`, `/healthz`, and `/js`
-- `internal/api/log.go` - `/log`, `/api/v1/log`, and `/api/v2/log`
+- `internal/api/log.go` - `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log`
 - `internal/counter/*` - counter reads/writes and Redis-backed counting behavior
 
 ## Environment
@@ -123,8 +126,9 @@ If GHCR creates the package with private visibility on first publish, update the
 
 1. Build the web app script so `apps/web/public/js/client.min.js` is up to date.
 2. Deploy this service behind `events.vercount.one`.
-3. Verify `/js`, `/log`, `/api/v1/log`, and `/api/v2/log` on the new host.
-4. Confirm the dashboard in `apps/web` still reads the shared Redis data correctly.
+3. Verify `/js`, `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log` on the new host.
+4. Confirm `/bench/write` writes only to the fixed synthetic benchmark target `https://bench.vercount.one/gurt` and returns an uncached v2-style success envelope.
+5. Confirm the dashboard in `apps/web` still reads the shared Redis data correctly.
 
 ## Rollback
 

apps/api/internal/api/log.go

@@ -19,8 +19,9 @@ import (
 )
 
 const (
-	rateLimitWindow = 60 * time.Second
-	rateLimitCount  = int64(80)
+	rateLimitWindow         = 60 * time.Second
+	rateLimitCount          = int64(80)
+	benchmarkWriteTargetURL = "https://bench.vercount.one/gurt"
 )
 
 var suspiciousUA = regexp.MustCompile(`python-requests|python/|requests/|curl/|wget/|go-http-client/|httpie/|postman/|axios/|node-fetch/|empty|unknown|bot|crawl|spider`)
@@ -226,6 +227,31 @@ func (h *LogHandler) V2Post(w http.ResponseWriter, r *http.Request) {
 	h.writeV2Success(w, http.StatusOK, "Data updated successfully", counts)
 }
 
+func (h *LogHandler) BenchmarkWrite(w http.ResponseWriter, r *http.Request) {
+	applyCORSHeaders(w)
+	applyNoStoreHeaders(w)
+	if !h.allowV2Request(w, r) {
+		return
+	}
+
+	target, message := validateTargetURL(benchmarkWriteTargetURL)
+	if message != "" {
+		h.log.Error("benchmark target configuration invalid", requestLogFields(r, "benchmark.target.invalid", map[string]any{"status": http.StatusInternalServerError, "target_url": benchmarkWriteTargetURL, "reason": message}))
+		h.writeV2Error(w, http.StatusInternalServerError, "Benchmark target configuration invalid", nil)
+		return
+	}
+
+	counts, err := h.writeCounts(r.Context(), target.Host, target.Path, true)
+	if err != nil {
+		h.log.Error("benchmark counter update failed", requestLogFields(r, "counter.benchmark_write_failed", map[string]any{"status": http.StatusInternalServerError, "error": err.Error(), "target_url": benchmarkWriteTargetURL}))
+		h.writeV2Error(w, http.StatusInternalServerError, "Internal server error", nil)
+		return
+	}
+
+	h.log.Debug("benchmark counter update completed", requestLogFields(r, "counter.benchmark_write_completed", map[string]any{"host": target.Host, "target_path": target.Path, "target_url": benchmarkWriteTargetURL, "is_new_uv": true, "site_uv": counts.SiteUV, "site_pv": counts.SitePV, "page_pv": counts.PagePV}))
+	h.writeV2Success(w, http.StatusOK, "Benchmark data updated successfully", counts)
+}
+
 func (h *LogHandler) allowV1Request(w http.ResponseWriter, r *http.Request) bool {
 	result := h.limit.Check(r.Context(), r)
 	if !result.Success {

apps/api/internal/api/public.go

@@ -32,18 +32,19 @@ func NewPublicHandler(scriptPath string, log Logger, redisClient *redis.Client)
 
 func (h *PublicHandler) Root(w http.ResponseWriter, _ *http.Request) {
 	writeJSON(w, http.StatusOK, map[string]any{
-		"service": publicServiceName,
+		"service":     publicServiceName,
 		"description": "Straightforward, Fast, and Reliable Website Visitor Counter.",
-		"status":  "ok",
+		"status":      "ok",
 		"routes": []string{
 			"/",
 			"/healthz",
 			"/js",
+			"/bench/write",
 			// "/log", deprecated
 			"/api/v1/log",
 			"/api/v2/log",
 		},
-		"github": "https://github.com/EvanNotFound/vercount",
+		"github":   "https://github.com/EvanNotFound/vercount",
 		"homepage": "https://www.vercount.one",
 	})
 }
@@ -103,3 +104,9 @@ func applyCORSHeaders(w http.ResponseWriter) {
 	w.Header().Set("Access-Control-Allow-Headers", "X-CSRF-Token, X-Requested-With, Accept, Accept-Version, Content-Length, Content-MD5, Content-Type, Date, X-Api-Version, X-Browser-Token")
 	w.Header().Set("Access-Control-Max-Age", "86400")
 }
+
+func applyNoStoreHeaders(w http.ResponseWriter) {
+	w.Header().Set("Cache-Control", "no-store, max-age=0")
+	w.Header().Set("Pragma", "no-cache")
+	w.Header().Set("Expires", "0")
+}

apps/api/internal/app/server.go

@@ -34,6 +34,7 @@ func (s *Server) Routes() http.Handler {
 	r.Get("/healthz", s.public.Healthz)
 	r.Get("/js", s.public.Script)
 	r.Head("/js", s.public.Script)
+	r.Get("/bench/write", s.logAPI.BenchmarkWrite)
 
 	r.Options("/log", s.logAPI.V1Options)
 	r.Get("/log", s.logAPI.V1Get)

apps/api/internal/app/server_test.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
@@ -38,6 +39,10 @@ func TestRootEndpointReturnsServiceMetadata(t *testing.T) {
 	if !ok || len(routes) == 0 {
 		t.Fatalf("expected routes array, got %#v", payload["routes"])
 	}
+
+	if !containsRoute(routes, "/bench/write") {
+		t.Fatalf("expected benchmark route in metadata, got %#v", routes)
+	}
 }
 
 func TestHealthzReportsReadyWhenRedisReachable(t *testing.T) {
@@ -196,6 +201,146 @@ func TestOptionsRoutesStayAvailable(t *testing.T) {
 	}
 }
 
+func TestBenchmarkWriteRouteUsesFixedTargetAndNoStoreHeaders(t *testing.T) {
+	redisServer := mustStartMiniRedis(t)
+	handler := newTestHandler(t, redisServer.Addr())
+	client := redis.NewClient(&redis.Options{Addr: redisServer.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+	seedBenchmarkNamespace(t, client)
+
+	recorder := httptest.NewRecorder()
+	handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/bench/write", nil))
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", recorder.Code)
+	}
+
+	if recorder.Header().Get("Access-Control-Allow-Origin") != "*" {
+		t.Fatalf("expected CORS header, got %q", recorder.Header().Get("Access-Control-Allow-Origin"))
+	}
+
+	if !strings.Contains(recorder.Header().Get("Cache-Control"), "no-store") {
+		t.Fatalf("expected no-store cache header, got %q", recorder.Header().Get("Cache-Control"))
+	}
+
+	if recorder.Header().Get("Pragma") != "no-cache" {
+		t.Fatalf("expected pragma no-cache header, got %q", recorder.Header().Get("Pragma"))
+	}
+
+	if recorder.Header().Get("Expires") != "0" {
+		t.Fatalf("expected expires header 0, got %q", recorder.Header().Get("Expires"))
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(recorder.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("unmarshal benchmark response: %v", err)
+	}
+
+	if payload["status"] != "success" {
+		t.Fatalf("expected success envelope, got %#v", payload)
+	}
+
+	data, ok := payload["data"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected data envelope, got %#v", payload)
+	}
+
+	for field, want := range map[string]float64{"site_uv": 1, "site_pv": 1, "page_pv": 1} {
+		if data[field] != want {
+			t.Fatalf("expected %s=%v, got %#v", field, want, data[field])
+		}
+	}
+
+	keys, err := client.Keys(context.Background(), "*").Result()
+	if err != nil {
+		t.Fatalf("list redis keys: %v", err)
+	}
+
+	for _, key := range keys {
+		if strings.HasPrefix(key, "ratelimit:") {
+			continue
+		}
+		if !strings.Contains(key, "bench.vercount.one") {
+			t.Fatalf("expected only benchmark namespace keys, got %q in %#v", key, keys)
+		}
+	}
+
+	pageValue, err := client.Get(context.Background(), "pv:page:bench.vercount.one:/gurt").Result()
+	if err != nil {
+		t.Fatalf("read benchmark page key: %v", err)
+	}
+
+	if pageValue != "1" {
+		t.Fatalf("expected fixed /gurt page key to increment to 1, got %q", pageValue)
+	}
+}
+
+func TestBenchmarkWriteRouteUsesV2RateLimitErrors(t *testing.T) {
+	redisServer := mustStartMiniRedis(t)
+	handler := newTestHandler(t, redisServer.Addr())
+	client := redis.NewClient(&redis.Options{Addr: redisServer.Addr()})
+	t.Cleanup(func() { _ = client.Close() })
+	seedBenchmarkNamespace(t, client)
+
+	for i := 0; i < 80; i++ {
+		recorder := httptest.NewRecorder()
+		request := httptest.NewRequest(http.MethodGet, "/bench/write", nil)
+		request.RemoteAddr = "203.0.113.10:1234"
+		handler.ServeHTTP(recorder, request)
+
+		if recorder.Code != http.StatusOK {
+			t.Fatalf("expected warm-up request to succeed, got %d", recorder.Code)
+		}
+	}
+
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/bench/write", nil)
+	request.RemoteAddr = "203.0.113.10:1234"
+	handler.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusTooManyRequests {
+		t.Fatalf("expected 429, got %d", recorder.Code)
+	}
+
+	if !strings.Contains(recorder.Header().Get("Cache-Control"), "no-store") {
+		t.Fatalf("expected no-store cache header, got %q", recorder.Header().Get("Cache-Control"))
+	}
+
+	if recorder.Header().Get("Pragma") != "no-cache" {
+		t.Fatalf("expected pragma no-cache header, got %q", recorder.Header().Get("Pragma"))
+	}
+
+	if recorder.Header().Get("Expires") != "0" {
+		t.Fatalf("expected expires header 0, got %q", recorder.Header().Get("Expires"))
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(recorder.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("unmarshal rate-limit response: %v", err)
+	}
+
+	if payload["status"] != "error" {
+		t.Fatalf("expected error envelope, got %#v", payload)
+	}
+
+	if payload["code"] != float64(http.StatusTooManyRequests) {
+		t.Fatalf("expected 429 code, got %#v", payload["code"])
+	}
+
+	if payload["message"] != "Rate limit exceeded" {
+		t.Fatalf("expected rate-limit message, got %#v", payload["message"])
+	}
+
+	details, ok := payload["details"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected details payload, got %#v", payload)
+	}
+
+	if details["limit"] != float64(80) || details["remaining"] != float64(0) {
+		t.Fatalf("expected v2 rate-limit details, got %#v", details)
+	}
+}
+
 func TestRequestLoggingEmitsStructuredCompletionEvent(t *testing.T) {
 	redisServer := mustStartMiniRedis(t)
 	var logs bytes.Buffer
@@ -282,6 +427,33 @@ func findLogEntry(t *testing.T, output string, event string) map[string]any {
 	return nil
 }
 
+func containsRoute(routes []any, want string) bool {
+	for _, route := range routes {
+		if route == want {
+			return true
+		}
+	}
+
+	return false
+}
+
+func seedBenchmarkNamespace(t *testing.T, client *redis.Client) {
+	t.Helper()
+
+	ctx := context.Background()
+	seedValues := map[string]string{
+		"uv:site:count:bench.vercount.one": "0",
+		"pv:site:bench.vercount.one":       "0",
+		"pv:page:bench.vercount.one:/gurt": "0",
+	}
+
+	for key, value := range seedValues {
+		if err := client.Set(ctx, key, value, 0).Err(); err != nil {
+			t.Fatalf("seed %s: %v", key, err)
+		}
+	}
+}
+
 func mustStartMiniRedis(t *testing.T) *miniredis.Miniredis {
 	t.Helper()
 

…/changes/api-chi-refactor/.openspec.yaml …0-add-benchmark-endpoints/.openspec.yamlopenspec/changes/api-chi-refactor/.openspec.yaml renamed to openspec/changes/archive/2026-04-20-add-benchmark-endpoints/.openspec.yaml openspec/changes/api-chi-refactor/.openspec.yaml renamed to openspec/changes/archive/2026-04-20-add-benchmark-endpoints/.openspec.yaml

@@ -0,0 +1,74 @@
+## Context
+
+The Go events service currently exposes public metadata routes in `internal/api/public.go` and counter routes in `internal/api/log.go`. Real browser traffic writes counters through `POST /api/v2/log` with a JSON body, URL validation, rate limiting, Redis-backed UV/PV updates, and a v2 success envelope. External benchmarking tools such as itdog.cn can easily probe `GET` endpoints but cannot reproduce the browser's `POST` body flow, which makes existing public routes a poor fit for measuring real counter write latency from many regions.
+
+The benchmark route needs to stay public, stable, and safe. It should measure the same counter write hot path without polluting customer domains, and it must avoid cache hits that would hide application latency.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Expose a public `GET /bench/write` route on the Go events host.
+- Reuse the real Redis-backed counter write path so benchmark results reflect counter update latency rather than a no-op handler.
+- Keep benchmark traffic isolated under the fixed synthetic tracked URL `https://bench.vercount.one/gurt`.
+- Return a stable response contract that is easy to inspect from external benchmark tools.
+- Prevent intermediary caches from turning the benchmark route into a static response.
+
+**Non-Goals:**
+- Reproduce browser-only behavior such as CORS preflight or JSON body decoding.
+- Add a user-configurable benchmark target URL.
+- Replace `/api/v1/log` or `/api/v2/log` as the primary embed-facing public API.
+- Create a high-volume load-testing endpoint that bypasses the service's normal protections.
+
+## Decisions
+
+### Add a dedicated GET benchmark route that lives with the counter handlers
+
+`GET /bench/write` will be registered as a public route in the Go API and implemented alongside the counter handlers so it can reuse existing validation, write, logging, and response helpers. Keeping the route near `V2Post` avoids duplicating the counter write orchestration and makes the benchmark path a thin facade over the existing write flow.
+
+**Alternatives considered:**
+- Put `/bench/write` in `public.go`: rejected because the route is logically a counter write operation and would otherwise need cross-package helper exposure.
+- Ask probe tools to call `/api/v2/log` directly: rejected because the target tool only supports simple `GET` probes.
+
+### Use a fixed synthetic target URL and force the full write path
+
+The benchmark route will always target `https://bench.vercount.one/gurt` and will invoke the write flow with deterministic benchmark-owned inputs instead of reading query parameters. The route should execute the full counter write path, including the UV update branch, so the benchmark reflects the heavier real write path instead of a lighter read-mostly variation.
+
+**Alternatives considered:**
+- Accept a caller-supplied `url` parameter: rejected because it would mix benchmark traffic into customer namespaces and make results non-repeatable.
+- Treat benchmark requests as returning visitors only: rejected because it would skip the fully write-backed UV path and underrepresent the cost of a fresh write.
+
+### Return the v2-style success envelope and disable caching
+
+The benchmark route will return a v2-style success response with the current counter data so the response shape stays familiar and machine-readable. The route will also send no-store cache headers so CDN or intermediary caches do not collapse repeated benchmark requests into a static hit.
+
+**Alternatives considered:**
+- Return `204 No Content`: rejected because benchmark tools and manual checks benefit from a visible response payload.
+- Return plain v1 JSON: rejected because the benchmark route is modeling the modern public counter surface, which is v2-oriented.
+
+### Reuse the existing request protections and logging middleware
+
+The benchmark route will continue to flow through the existing request logging middleware and rate-limit checks. This keeps the route observable, preserves abuse protection, and keeps the benchmark representative of the public service path instead of introducing a privileged fast lane.
+
+**Alternatives considered:**
+- Exempt `/bench/write` from rate limiting: rejected because it increases abuse risk and makes the benchmark less representative of the public service path.
+- Add separate benchmark-only logging: rejected because the current request and counter event logging is already sufficient.
+
+## Risks / Trade-offs
+
+- [Synthetic benchmark traffic inflates benchmark namespace counters] → Keep all benchmark writes pinned to `bench.vercount.one/gurt` so no customer-owned domains are affected.
+- [GET benchmark results are not a byte-for-byte reproduction of browser POST behavior] → Document that `/bench/write` is a probe-friendly proxy for the real write path, not a full browser simulation.
+- [Rate limiting may affect aggressive probe schedules] → Preserve the existing limit for realism and safety, and document that the endpoint is intended for external latency probes rather than sustained load generation.
+- [Cache misconfiguration could hide real latency] → Require explicit no-store headers in the benchmark response.
+
+## Migration Plan
+
+1. Add the benchmark route and implementation in the Go events service.
+2. Update the public service metadata/documentation to include `/bench/write`.
+3. Deploy the Go API and verify repeated benchmark requests hit application logs rather than cache-only responses.
+4. Use itdog.cn or similar probes against `/bench/write` to establish baseline regional latency.
+
+Rollback is straightforward: remove the route from the router and documentation. The synthetic benchmark Redis keys can remain because they are isolated from customer traffic and expire under the existing counter TTL rules.
+
+## Open Questions
+
+- None for artifact readiness. The fixed route, target URL, and benchmark intent are now defined well enough to implement.