fix(api): redirect events pages to canonical site

Author: EvanNotFound

apps/api/README.md

@@ -4,13 +4,12 @@ Minimal Go service for the public `events.vercount.one` surface.
 
 ## What it serves
 
-- `/`
-- `/healthz`
-- `/js`
-- `/bench/write`
-- `/log`
-- `/api/v1/log`
-- `/api/v2/log`
+- `/` redirects to the canonical homepage at `https://www.vercount.one/`
+- `/dashboard`, `/dashboard/analytics`, `/dashboard/domains`, and `/auth/signin` redirect to the same path on `https://www.vercount.one`
+- `/healthz` exposes Redis-backed readiness JSON
+- `/js` serves the public browser counter script
+- `/bench/write` exposes the benchmark write helper
+- `/log`, `/api/v1/log`, and `/api/v2/log` serve the public counter API
 
 `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.
 
@@ -20,7 +19,7 @@ The Go API stays intentionally small and is organized by runtime surface instead
 
 - `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/public.go` - canonical redirects, `/healthz`, and `/js`
 - `internal/api/log.go` - `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log`
 - `internal/counter/*` - counter reads/writes and Redis-backed counting behavior
 
@@ -126,7 +125,7 @@ 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`, `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log` on the new host.
+3. Verify `/` redirects to `https://www.vercount.one/`, and 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.
 

apps/api/internal/api/public.go

@@ -12,7 +12,10 @@ import (
 	redis "github.com/redis/go-redis/v9"
 )
 
-const publicServiceName = "vercount-events-api"
+const (
+	publicServiceName  = "vercount-events-api"
+	canonicalWebOrigin = "https://www.vercount.one"
+)
 
 type Logger interface {
 	Debug(message string, data any)
@@ -31,23 +34,17 @@ func NewPublicHandler(scriptPath string, log Logger, redisClient *redis.Client)
 	return &PublicHandler{scriptPath: scriptPath, log: log, redis: redisClient}
 }
 
-func (h *PublicHandler) Root(w http.ResponseWriter, _ *http.Request) {
-	writeJSON(w, http.StatusOK, map[string]any{
-		"service":     publicServiceName,
-		"description": "Straightforward, Fast, and Reliable Website Visitor Counter.",
-		"status":      "ok",
-		"routes": []string{
-			"/",
-			"/healthz",
-			"/js",
-			"/bench/write",
-			"/log",
-			"/api/v1/log",
-			"/api/v2/log",
-		},
-		"github":   "https://github.com/EvanNotFound/vercount",
-		"homepage": "https://www.vercount.one",
-	})
+func (h *PublicHandler) Root(w http.ResponseWriter, r *http.Request) {
+	h.CanonicalRedirect(w, r)
+}
+
+func (h *PublicHandler) CanonicalRedirect(w http.ResponseWriter, r *http.Request) {
+	target := canonicalWebOrigin + r.URL.EscapedPath()
+	if r.URL.RawQuery != "" {
+		target += "?" + r.URL.RawQuery
+	}
+
+	http.Redirect(w, r, target, http.StatusMovedPermanently)
 }
 
 func (h *PublicHandler) Healthz(w http.ResponseWriter, r *http.Request) {

apps/api/internal/app/server.go

@@ -31,6 +31,15 @@ func (s *Server) Routes() http.Handler {
 	r.Use(requestLoggingMiddleware(s.log))
 
 	r.Get("/", s.public.Root)
+	r.Head("/", s.public.Root)
+	r.Get("/dashboard", s.public.CanonicalRedirect)
+	r.Head("/dashboard", s.public.CanonicalRedirect)
+	r.Get("/dashboard/analytics", s.public.CanonicalRedirect)
+	r.Head("/dashboard/analytics", s.public.CanonicalRedirect)
+	r.Get("/dashboard/domains", s.public.CanonicalRedirect)
+	r.Head("/dashboard/domains", s.public.CanonicalRedirect)
+	r.Get("/auth/signin", s.public.CanonicalRedirect)
+	r.Head("/auth/signin", s.public.CanonicalRedirect)
 	r.Get("/healthz", s.public.Healthz)
 	r.Get("/js", s.public.Script)
 	r.Head("/js", s.public.Script)

apps/api/internal/app/server_test.go

@@ -16,37 +16,82 @@ import (
 	redis "github.com/redis/go-redis/v9"
 )
 
-func TestRootEndpointReturnsServiceMetadata(t *testing.T) {
+func TestRootRedirectsToCanonicalHomepage(t *testing.T) {
 	handler := newTestHandler(t, mustStartMiniRedis(t).Addr())
-	recorder := httptest.NewRecorder()
 
-	handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/", nil))
+	for _, method := range []string{http.MethodGet, http.MethodHead} {
+		t.Run(method, func(t *testing.T) {
+			recorder := httptest.NewRecorder()
+			handler.ServeHTTP(recorder, httptest.NewRequest(method, "/", nil))
 
-	if recorder.Code != http.StatusOK {
-		t.Fatalf("expected 200, got %d", recorder.Code)
+			assertRedirectLocation(t, recorder, "https://www.vercount.one/")
+		})
 	}
+}
 
-	var payload map[string]any
-	if err := json.Unmarshal(recorder.Body.Bytes(), &payload); err != nil {
-		t.Fatalf("unmarshal root response: %v", err)
-	}
+func TestSelectedPageRoutesRedirectToCanonicalWebHost(t *testing.T) {
+	handler := newTestHandler(t, mustStartMiniRedis(t).Addr())
 
-	if payload["service"] != "vercount-events-api" {
-		t.Fatalf("expected service name, got %#v", payload["service"])
+	for _, tc := range []struct {
+		path string
+		want string
+	}{
+		{path: "/dashboard", want: "https://www.vercount.one/dashboard"},
+		{path: "/dashboard/analytics", want: "https://www.vercount.one/dashboard/analytics"},
+		{path: "/dashboard/domains", want: "https://www.vercount.one/dashboard/domains"},
+		{path: "/auth/signin", want: "https://www.vercount.one/auth/signin"},
+		{
+			path: "/dashboard/domains?from=events&next=%2Fsettings",
+			want: "https://www.vercount.one/dashboard/domains?from=events&next=%2Fsettings",
+		},
+	} {
+		t.Run(tc.path, func(t *testing.T) {
+			recorder := httptest.NewRecorder()
+			handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, tc.path, nil))
+
+			assertRedirectLocation(t, recorder, tc.want)
+		})
 	}
+}
+
+func TestKnownMachineRoutesDoNotRedirectToCanonicalWebHost(t *testing.T) {
+	handler, scriptContents := newTestHandlerWithScript(t, mustStartMiniRedis(t).Addr(), "console.log('vercount');")
 
-	routes, ok := payload["routes"].([]any)
-	if !ok || len(routes) == 0 {
-		t.Fatalf("expected routes array, got %#v", payload["routes"])
+	for _, path := range []string{
+		"/healthz",
+		"/js",
+		"/log?url=file:///bad",
+		"/api/v1/log?url=file:///bad",
+		"/api/v2/log?url=file:///bad",
+	} {
+		t.Run(path, func(t *testing.T) {
+			recorder := httptest.NewRecorder()
+			handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, path, nil))
+
+			if recorder.Code == http.StatusMovedPermanently {
+				t.Fatalf("expected machine route not to redirect, got location %q", recorder.Header().Get("Location"))
+			}
+			if strings.HasPrefix(recorder.Header().Get("Location"), "https://www.vercount.one") {
+				t.Fatalf("expected no canonical redirect, got %q", recorder.Header().Get("Location"))
+			}
+			if path == "/js" && recorder.Body.String() != scriptContents {
+				t.Fatalf("expected script contents %q, got %q", scriptContents, recorder.Body.String())
+			}
+		})
 	}
+}
+
+func TestUnknownAPIPathDoesNotRedirectToCanonicalWebHost(t *testing.T) {
+	handler := newTestHandler(t, mustStartMiniRedis(t).Addr())
+	recorder := httptest.NewRecorder()
+
+	handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/api/v3/log", nil))
 
-	if !containsRoute(routes, "/bench/write") {
-		t.Fatalf("expected benchmark route in metadata, got %#v", routes)
+	if recorder.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d", recorder.Code)
 	}
-	for _, route := range []string{"/log", "/api/v1/log", "/api/v2/log"} {
-		if !containsRoute(routes, route) {
-			t.Fatalf("expected route %q in metadata, got %#v", route, routes)
-		}
+	if recorder.Header().Get("Location") != "" {
+		t.Fatalf("expected no redirect location, got %q", recorder.Header().Get("Location"))
 	}
 }
 
@@ -649,14 +694,15 @@ func hasLogEvent(output string, event string) bool {
 	return false
 }
 
-func containsRoute(routes []any, want string) bool {
-	for _, route := range routes {
-		if route == want {
-			return true
-		}
-	}
+func assertRedirectLocation(t *testing.T, recorder *httptest.ResponseRecorder, want string) {
+	t.Helper()
 
-	return false
+	if recorder.Code != http.StatusMovedPermanently {
+		t.Fatalf("expected 301, got %d", recorder.Code)
+	}
+	if recorder.Header().Get("Location") != want {
+		t.Fatalf("expected redirect to %q, got %q", want, recorder.Header().Get("Location"))
+	}
 }
 
 func seedBenchmarkNamespace(t *testing.T, client *redis.Client) {

openspec/changes/archive/2026-04-30-api-canonical-redirect/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-24

openspec/changes/archive/2026-04-30-api-canonical-redirect/design.md

@@ -0,0 +1,68 @@
+## Context
+
+The public events service now lives in `apps/api` and serves the machine-facing `events.vercount.one` surface for the browser script, counter writes/reads, readiness checks, and benchmarks. That host previously served the Next.js web app, so search engines may still treat routes on the events host as human-facing Vercount pages.
+
+The current Go root handler returns JSON metadata at `/`, and the current `public-service-meta-endpoints` spec requires that behavior. The canonical web experience is now `https://www.vercount.one`, so the events host should stop acting like an indexable page origin while preserving its public API contract.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Send browser and crawler traffic for the events-host root to `https://www.vercount.one/`.
+- Redirect known old web-app page paths from the events host to the same path on `https://www.vercount.one`.
+- Keep `/healthz`, `/js`, `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log` available on the events host without redirects.
+- Keep unknown API-style paths on the events host as misses instead of redirecting them to the web app.
+- Update docs so the events host is described as an API/script host, not a main website host.
+
+**Non-Goals:**
+
+- Do not change counter semantics, response shapes, CORS behavior, rate limiting, or Redis key usage.
+- Do not move the browser counter script or public counter endpoints to the web app.
+- Do not introduce a broad catch-all redirect for every unknown events-host path.
+- Do not change the web app routing implementation beyond documentation or canonical references needed for this behavior.
+
+## Decisions
+
+### Use permanent redirects for known human-facing routes
+
+`GET` and `HEAD` requests for `/` and selected old web-app paths should return a permanent redirect to the canonical web host. This directly addresses search indexing and avoids continuing to expose API metadata as the apparent homepage.
+
+Alternatives considered:
+
+- Keep root JSON and add `X-Robots-Tag: noindex`: lower product risk, but users and search results can still land on a JSON response instead of the website.
+- Redirect only `/`: simpler, but does not clean up old indexed Next.js page paths that may still exist under the events host.
+- Redirect all unknown paths: broader cleanup, but it can hide accidental API URL mistakes and make the events host less predictable for API clients.
+
+### Keep the redirect allowlist explicit
+
+The redirect set should include `/` plus the known web-app page surfaces that may have existed when the host served Next.js, currently `/dashboard`, `/dashboard/analytics`, `/dashboard/domains`, and `/auth/signin`. Redirect targets should preserve the path and query string so bookmarked or indexed URLs land on the equivalent canonical page.
+
+An explicit list keeps API-host behavior predictable and avoids turning unrelated unknown paths into web redirects. Future page paths can be added intentionally if they are found in search results or logs.
+
+### Preserve machine endpoints exactly
+
+The existing public events machine endpoints should remain registered before or alongside redirect handling so they continue to return their current API/script responses. Unknown `/api/*` paths should not redirect to the web app because API consumers benefit from clear misses on the API host.
+
+### Keep canonical host fixed and simple
+
+Use `https://www.vercount.one` as the canonical redirect base. A compile-time constant is enough for the current product need and avoids introducing new environment configuration for a stable public site URL.
+
+## Risks / Trade-offs
+
+- **Risk:** Permanent redirects are sticky in browsers and crawlers. → **Mitigation:** Limit redirects to the root and known human-facing paths, leaving machine endpoints untouched.
+- **Risk:** The old JSON root may have been used by ad-hoc health checks. → **Mitigation:** `/healthz` remains the supported readiness endpoint and documentation should point monitors there.
+- **Risk:** Some old indexed pages may not be covered by the initial allowlist. → **Mitigation:** Keep the list easy to extend based on logs or search console findings.
+- **Risk:** Dashboard redirects may send unauthenticated users to protected web routes. → **Mitigation:** The canonical web app already owns auth redirects for dashboard pages, so the events host should only move traffic to the correct origin.
+
+## Migration Plan
+
+1. Update the Go public handler/router so root and selected human-facing paths redirect to `https://www.vercount.one`.
+2. Verify the preserved machine endpoints still serve their existing responses without redirects.
+3. Update API documentation and route listings to describe `/` as a canonical redirect and `/healthz` as the machine-readable readiness endpoint.
+4. Deploy the Go API service and check search-console or access logs for additional old page paths that should be added later.
+
+Rollback is straightforward: restore the root metadata handler and remove the selected page redirects if the redirect behavior causes unexpected operational issues.
+
+## Open Questions
+
+- Should the web app metadata consistently use `https://www.vercount.one` as its metadata base if `www` is the canonical host? This is related SEO cleanup but can be handled separately if desired.

openspec/changes/archive/2026-04-30-api-canonical-redirect/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+Search engines still index the public Go events host as if it were the main Vercount web page because the host previously served the Next.js site and now returns API metadata at `/`. The public events host should keep serving machine endpoints, while human-facing and previously indexed page URLs should move users and crawlers to the canonical `https://www.vercount.one` site.
+
+## What Changes
+
+- Change `GET /` on the public events host from a JSON metadata response to a redirect to `https://www.vercount.one/`.
+- Redirect selected human-facing page paths that may have been indexed on the events host to the same path on the canonical web host.
+- Keep public machine endpoints on the events host available and non-redirecting, including `/healthz`, `/js`, `/bench/write`, `/log`, `/api/v1/log`, and `/api/v2/log`.
+- Keep unknown API-style paths as API-host misses rather than redirecting them to the web app.
+- Document the new split between canonical web pages and public events API endpoints.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `public-service-meta-endpoints`: replace the root JSON metadata behavior with canonical redirects for human-facing events-host pages while preserving Redis-backed readiness behavior.
+
+## Impact
+
+- Affected code: Go API router and public handler code under `apps/api/internal/app/server.go` and `apps/api/internal/api/public.go`.
+- Affected documentation: `apps/api/README.md` and any route listing that currently describes `/` as JSON metadata.
+- Public API compatibility: counter and script endpoints must continue to serve existing clients without redirects.
+- SEO behavior: crawlers and browser users requesting selected page URLs on `events.vercount.one` should be sent to `www.vercount.one`.

openspec/changes/archive/2026-04-30-api-canonical-redirect/specs/public-service-meta-endpoints/spec.md

@@ -0,0 +1,64 @@
+## ADDED Requirements
+
+### Requirement: Public events host SHALL redirect service root to canonical web homepage
+
+The system SHALL redirect `GET` and `HEAD` requests for `/` on the public Go API host to the canonical Vercount web homepage at `https://www.vercount.one/`.
+
+#### Scenario: Client requests the service root
+
+- **WHEN** a client sends a `GET` request to `/`
+- **THEN** the system SHALL return a permanent redirect to `https://www.vercount.one/`
+- **AND** the system SHALL NOT return the public Go API service metadata JSON
+
+#### Scenario: Client sends a HEAD request to the service root
+
+- **WHEN** a client sends a `HEAD` request to `/`
+- **THEN** the system SHALL return a permanent redirect to `https://www.vercount.one/`
+
+### Requirement: Public events host SHALL redirect known human-facing pages to the canonical web host
+
+The system SHALL redirect known human-facing page requests on the public events host to the same path on `https://www.vercount.one` so old indexed or bookmarked web-app URLs resolve to the canonical site.
+
+#### Scenario: Client requests an old dashboard page on the events host
+
+- **WHEN** a client sends a `GET` request to `/dashboard` on the public events host
+- **THEN** the system SHALL return a permanent redirect to `https://www.vercount.one/dashboard`
+
+#### Scenario: Client requests an old dashboard subpage on the events host
+
+- **WHEN** a client sends a `GET` request to `/dashboard/analytics` or `/dashboard/domains` on the public events host
+- **THEN** the system SHALL return a permanent redirect to the same path on `https://www.vercount.one`
+
+#### Scenario: Client requests an old auth page on the events host
+
+- **WHEN** a client sends a `GET` request to `/auth/signin` on the public events host
+- **THEN** the system SHALL return a permanent redirect to `https://www.vercount.one/auth/signin`
+
+#### Scenario: Client request includes a query string
+
+- **WHEN** a redirected human-facing request includes a query string
+- **THEN** the system SHALL preserve that query string on the canonical web-host redirect target
+
+### Requirement: Public events host SHALL preserve machine endpoint routing
+
+The system SHALL keep machine-facing events-host endpoints available without canonical web redirects.
+
+#### Scenario: Client requests a supported machine endpoint
+
+- **WHEN** a client sends a request to `/healthz`, `/js`, `/bench/write`, `/log`, `/api/v1/log`, or `/api/v2/log`
+- **THEN** the system SHALL serve the existing endpoint behavior on the public events host
+- **AND** the system SHALL NOT redirect the request to the canonical web host
+
+#### Scenario: Client requests an unknown API-style path
+
+- **WHEN** a client sends a request to an unsupported `/api/*` path on the public events host
+- **THEN** the system SHALL treat the request as an API-host miss
+- **AND** the system SHALL NOT redirect the request to the canonical web host
+
+## REMOVED Requirements
+
+### Requirement: Public events host SHALL expose a service metadata root endpoint
+
+**Reason**: The public events host is no longer the canonical human-facing site, and returning service metadata at `/` causes search engines and users to land on an API response instead of the Vercount homepage.
+
+**Migration**: Use `/healthz` for machine-readable service readiness and `https://www.vercount.one/` for the canonical homepage.