diff --git a/deploy/caddy/Caddyfile b/deploy/caddy/Caddyfile index c335674..ffb17ed 100644 --- a/deploy/caddy/Caddyfile +++ b/deploy/caddy/Caddyfile @@ -53,7 +53,7 @@ # The game SPA and the Connect edge are served by the gateway. Strip any # client-supplied X-Scrabble-Honeypot here so the gateway only ever honours the # tag the honeypot block sets below (a client cannot self-tag a real request). - @gateway path /app /app/* /telegram /telegram/* /vk /vk/* /dict/* /scrabble.edge.v1.Gateway/* + @gateway path /app /app/* /telegram /telegram/* /vk /vk/* /dict/* /metrics/* /scrabble.edge.v1.Gateway/* handle @gateway { reverse_proxy gateway:8081 { header_up -X-Scrabble-Honeypot diff --git a/deploy/grafana/dashboards/users.json b/deploy/grafana/dashboards/users.json index 567538b..e7eb072 100644 --- a/deploy/grafana/dashboards/users.json +++ b/deploy/grafana/dashboards/users.json @@ -4,7 +4,7 @@ "tags": ["scrabble"], "timezone": "", "schemaVersion": 39, - "version": 1, + "version": 2, "refresh": "30s", "time": { "from": "now-7d", "to": "now" }, "panels": [ @@ -29,6 +29,33 @@ "gridPos": { "h": 8, "w": 24, "x": 0, "y": 8 }, "datasource": { "type": "prometheus", "uid": "prometheus" }, "targets": [{ "refId": "A", "expr": "sum(accounts_created_total) by (kind)", "legendFormat": "{{kind}}" }] + }, + { + "type": "timeseries", + "title": "App opens vs dictionary fills (cumulative)", + "description": "Local move-preview adoption. App opens are client cold starts; dictionary fills are IndexedDB downloads of a dawg. The gap between them is how many launches reuse an already-cached dictionary. Client-reported, best-effort (a batched beacon), so slightly lossy.", + "gridPos": { "h": 8, "w": 12, "x": 0, "y": 16 }, + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "targets": [ + { "refId": "A", "expr": "sum(local_eval_cold_start_total)", "legendFormat": "app opens (cold start)" }, + { "refId": "B", "expr": "sum(local_eval_dict_load_total{result=\"fetched\"})", "legendFormat": "dictionary fills (IndexedDB)" } + ] + }, + { + "type": "timeseries", + "title": "Dictionary loads by result (rate)", + "description": "Client dictionary loads for the local preview, by tier: fetched (network download), cache_hit (IndexedDB), miss (a warm-up that failed or timed out — trips the bad-connection breaker).", + "gridPos": { "h": 8, "w": 12, "x": 12, "y": 16 }, + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "targets": [{ "refId": "A", "expr": "sum(rate(local_eval_dict_load_total[1h])) by (result)", "legendFormat": "{{result}}" }] + }, + { + "type": "timeseries", + "title": "Move previews by path (rate)", + "description": "Where the move preview is computed: local (on-device, the accelerator) vs network (the fallback to game.evaluate). The local share is the backend load shed.", + "gridPos": { "h": 8, "w": 24, "x": 0, "y": 24 }, + "datasource": { "type": "prometheus", "uid": "prometheus" }, + "targets": [{ "refId": "A", "expr": "sum(rate(local_eval_preview_total[1h])) by (path)", "legendFormat": "{{path}}" }] } ] } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index eb0d3a1..2656fd0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -955,6 +955,20 @@ edits take effect on the next `profile.get` (open/reconnect/foreground), not mid distinct accounts that performed an authenticated edge action in the window. The gauge is single-process by design (single-instance MVP, §10): it is correct for one gateway, resets on restart, and is a live operational figure, not a billing count. +- **Local-preview adoption (client-reported):** three gateway counters measure uptake of + the local move-preview accelerator (§5), fed by a small, best-effort client beacon + (`POST /metrics/local-eval`, session-gated) that batches counter deltas and posts them + on a 60 s timer and when the app is backgrounded — **never on the gameplay path** (the + in-app counters are plain in-memory increments; only the periodic flush touches the + network, fire-and-forget). `local_eval_cold_start_total` counts app cold starts (the + adoption denominator); `local_eval_dict_load_total` (`result` = fetched/cache_hit/miss) + splits a dawg download that fills IndexedDB from a cache hit and from a warm-up that + failed or timed out; `local_eval_preview_total` (`path` = local/network) is the share of + previews computed on-device versus the network `evaluate` fallback — the backend load + shed. It answers the owner's adoption question — how often the app opens versus how often + it fills IndexedDB — and is surfaced on the **Scrabble — Users** dashboard. Lossy by + design (a dropped beacon just retries its batch on the next flush); it is telemetry, never + a game input. - **Rate-limit observability:** every limiter rejection increments the gateway counter `gateway_rate_limited_total` (`class` = user/public/email/admin — aggregate only, honouring the no-per-user-label discipline above) and logs one **Debug** line; diff --git a/gateway/internal/connectsrv/metrics.go b/gateway/internal/connectsrv/metrics.go index e74e4ac..9c619e7 100644 --- a/gateway/internal/connectsrv/metrics.go +++ b/gateway/internal/connectsrv/metrics.go @@ -28,6 +28,10 @@ type serverMetrics struct { rateLimited metric.Int64Counter banned metric.Int64Counter active *activeUsers + // Client-reported local move-preview adoption (see localEvalMetricsHandler). + localColdStart metric.Int64Counter + localDictLoad metric.Int64Counter + localPreview metric.Int64Counter } // newServerMetrics builds the instruments on meter (nil selects a no-op meter), @@ -54,7 +58,12 @@ func newServerMetrics(meter metric.Meter) *serverMetrics { if err != nil { b, _ = noop.NewMeterProvider().Meter(meterName).Int64Counter("gateway_abuse_banned_total") } - m := &serverMetrics{edge: h, rateLimited: c, banned: b, active: newActiveUsers()} + m := &serverMetrics{ + edge: h, rateLimited: c, banned: b, active: newActiveUsers(), + localColdStart: counterOf(meter, "local_eval_cold_start_total", "App cold starts reported by clients — the denominator for local-move-preview adoption."), + localDictLoad: counterOf(meter, "local_eval_dict_load_total", "Client dictionary loads for the local move preview, by result (fetched, cache_hit or miss)."), + localPreview: counterOf(meter, "local_eval_preview_total", "Client move previews, by path (local on-device, or network fallback)."), + } gauge, err := meter.Int64ObservableGauge("active_users", metric.WithDescription("Distinct accounts that performed an authenticated action within the window (in-memory, single gateway instance).")) @@ -98,3 +107,40 @@ func (m *serverMetrics) recordRateLimited(ctx context.Context, class string) { func (m *serverMetrics) recordBan(ctx context.Context, reason string) { m.banned.Add(ctx, 1, metric.WithAttributes(attribute.String("reason", reason))) } + +// localEvalReport is the client-reported local move-preview telemetry batch — deltas since +// the client's previous report. It backs the adoption dashboard: app cold starts vs cached +// dictionaries vs on-device previews. +type localEvalReport struct { + ColdStart int `json:"cold_start"` + DictFetched int `json:"dict_fetched"` + DictCacheHit int `json:"dict_cache_hit"` + DictMiss int `json:"dict_miss"` + PreviewLocal int `json:"preview_local"` + PreviewNetwork int `json:"preview_network"` +} + +// recordLocalEval folds one client report into the edge's local-eval counters. +func (m *serverMetrics) recordLocalEval(ctx context.Context, r localEvalReport) { + add := func(c metric.Int64Counter, n int, opts ...metric.AddOption) { + if n > 0 { + c.Add(ctx, int64(n), opts...) + } + } + add(m.localColdStart, r.ColdStart) + add(m.localDictLoad, r.DictFetched, metric.WithAttributes(attribute.String("result", "fetched"))) + add(m.localDictLoad, r.DictCacheHit, metric.WithAttributes(attribute.String("result", "cache_hit"))) + add(m.localDictLoad, r.DictMiss, metric.WithAttributes(attribute.String("result", "miss"))) + add(m.localPreview, r.PreviewLocal, metric.WithAttributes(attribute.String("path", "local"))) + add(m.localPreview, r.PreviewNetwork, metric.WithAttributes(attribute.String("path", "network"))) +} + +// counterOf builds an Int64Counter on meter, falling back to a no-op on the rare +// construction error so metrics never fail startup. +func counterOf(meter metric.Meter, name, desc string) metric.Int64Counter { + c, err := meter.Int64Counter(name, metric.WithDescription(desc)) + if err != nil { + c, _ = noop.NewMeterProvider().Meter(meterName).Int64Counter(name) + } + return c +} diff --git a/gateway/internal/connectsrv/server.go b/gateway/internal/connectsrv/server.go index c3d5588..ba84d07 100644 --- a/gateway/internal/connectsrv/server.go +++ b/gateway/internal/connectsrv/server.go @@ -9,7 +9,9 @@ package connectsrv import ( "context" "crypto/subtle" + "encoding/json" "errors" + "io" "net" "net/http" "strings" @@ -191,6 +193,8 @@ func (s *Server) HTTPHandler() http.Handler { // The client-side local move preview pulls each game's pinned dictionary blob // through this session-gated route (not public); see dictBytesHandler. mux.Handle("/dict/", s.dictBytesHandler()) + // The client posts its local-move-preview adoption telemetry here (session-gated). + mux.Handle("/metrics/local-eval", s.localEvalMetricsHandler()) // The embedded UI: the game SPA under /app/ (web), /telegram/ (the Telegram Mini // App) and /vk/ (the VK Mini App) — the single-origin model (docs/ARCHITECTURE.md // §13). All sit below the h2c wrap so the Connect edge (a more specific prefix) keeps @@ -474,6 +478,51 @@ func parseDictPath(p string) (variant, version string, ok bool) { return variant, version, true } +// localEvalMetricsHandler ingests a client's local move-preview telemetry batch into the +// edge's adoption counters (docs/ARCHITECTURE.md §11). Session-gated so only real clients +// report; the values are aggregate (no per-user attributes) and clamped against a spoofed +// inflation. Only POST; the body is a small JSON of per-metric deltas. +func (s *Server) localEvalMetricsHandler() http.Handler { + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.Method != http.MethodPost { + http.Error(w, "method not allowed", http.StatusMethodNotAllowed) + return + } + ip := peerIP(r.RemoteAddr, r.Header) + if _, _, err := s.resolve(r.Context(), r.Header, ip); err != nil { + http.Error(w, "unauthorized", http.StatusUnauthorized) + return + } + var rep localEvalReport + if err := json.NewDecoder(io.LimitReader(r.Body, 512)).Decode(&rep); err != nil { + http.Error(w, "bad request", http.StatusBadRequest) + return + } + clampReport(&rep) + s.metrics.recordLocalEval(r.Context(), rep) + w.WriteHeader(http.StatusNoContent) + }) +} + +// clampReport bounds each counter of a client report against a spoofed inflation — one batch +// reflects at most a few minutes of a single client's activity. +func clampReport(r *localEvalReport) { + const maxPerField = 1000 + clamp := func(n *int) { + if *n < 0 { + *n = 0 + } else if *n > maxPerField { + *n = maxPerField + } + } + clamp(&r.ColdStart) + clamp(&r.DictFetched) + clamp(&r.DictCacheHit) + clamp(&r.DictMiss) + clamp(&r.PreviewLocal) + clamp(&r.PreviewNetwork) +} + // resolve extracts and resolves the Authorization bearer token to an account id // and its guest flag, returning a Connect Unauthenticated error when it is missing // or unknown. diff --git a/ui/src/game/Game.svelte b/ui/src/game/Game.svelte index 2ebbd08..c100585 100644 --- a/ui/src/game/Game.svelte +++ b/ui/src/game/Game.svelte @@ -8,6 +8,7 @@ import Board from './Board.svelte'; import Rack from './Rack.svelte'; import { gateway } from '../lib/gateway'; + import { notePreviewLocal, notePreviewNetwork } from '../lib/localeval-metrics'; import { navigate } from '../lib/router.svelte'; import { app, handleError, showToast, markChatRead, seedChatUnread } from '../lib/app.svelte'; import { connection } from '../lib/connection.svelte'; @@ -725,6 +726,7 @@ if (reader && hasAlphabet(v.game.variant)) { try { preview = d.evaluateLocal(reader, v.game.variant, board, sub.tiles, v.game.multipleWordsPerTurn); + notePreviewLocal(); return; } catch { /* fall through to the network preview */ @@ -736,6 +738,7 @@ previewTimer = setTimeout(async () => { try { preview = await gateway.evaluate(id, sub.tiles, variant, ctrl.signal); + notePreviewNetwork(); } catch { /* best-effort (or aborted) */ } diff --git a/ui/src/lib/app.svelte.ts b/ui/src/lib/app.svelte.ts index 99c870b..80deed6 100644 --- a/ui/src/lib/app.svelte.ts +++ b/ui/src/lib/app.svelte.ts @@ -9,6 +9,7 @@ import { GatewayError } from './client'; import { navigate, router } from './router.svelte'; import { errorKey, localeFrom, setLocale, t, type Locale } from './i18n/index.svelte'; import { languageNeedsServerSync } from './language'; +import { startLocalEvalMetrics } from './localeval-metrics'; import { applyReduceMotion, applyTelegramTheme, applyTheme, type ThemePref, type TelegramThemeParams } from './theme'; import { insideTelegram, @@ -637,6 +638,10 @@ function applyTelegramChrome(launch: TelegramLaunch): void { const TELEGRAM_SDK_TIMEOUT_MS = 10000; export async function bootstrap(): Promise { + // Record the cold start and start the adoption beacon (skipped under the mock harness, which + // has no real backend). Deliberately before any await, so even an early-return launch path + // (e.g. the Telegram launch-error screen) still counts as an app open. + if (import.meta.env.MODE !== 'mock') startLocalEvalMetrics(); const prefs = await loadPrefs(); app.theme = prefs.theme ?? 'auto'; app.reduceMotion = prefs.reduceMotion ?? false; diff --git a/ui/src/lib/client.ts b/ui/src/lib/client.ts index 3f0d82b..b9bcfbf 100644 --- a/ui/src/lib/client.ts +++ b/ui/src/lib/client.ts @@ -103,6 +103,9 @@ export interface GatewayClient { * opts.signal aborts a stalled download; opts.reload bypasses the browser HTTP cache (the * debug reset, for testing a cold load). */ fetchDict(variant: Variant, version: string, opts?: { signal?: AbortSignal; reload?: boolean }): Promise; + /** Post the client's local move-preview adoption telemetry — a small batch of counter deltas, + * session-gated and fire-and-forget (never on the gameplay path). */ + reportLocalEval(counts: Record): Promise; // --- draft --- /** The player's server-persisted client-side composition (rack order + board tiles), so a diff --git a/ui/src/lib/dict/loader.ts b/ui/src/lib/dict/loader.ts index 15a64db..31c63ce 100644 --- a/ui/src/lib/dict/loader.ts +++ b/ui/src/lib/dict/loader.ts @@ -8,6 +8,7 @@ import { Dawg } from './dawg'; import { dictKey, idbGetDawg, idbPutDawg, idbDelDawg, requestPersist } from './store'; import { gateway } from '../gateway'; +import { noteDictFetched, noteDictCacheHit, noteDictMiss as noteDictMissMetric } from '../localeval-metrics'; import type { Variant } from '../model'; // Loaded readers by key. A dictionary is immutable, so an instance is reused for @@ -31,6 +32,7 @@ let dictDisabled = false; */ export function noteDictMiss(): void { if (!dictDisabled && ++misses >= MISS_LIMIT) dictDisabled = true; + noteDictMissMetric(); } /** dictLoadingDisabled reports whether the bad-connection breaker has tripped for this @@ -73,6 +75,7 @@ async function load(variant: Variant, version: string, key: string, signal?: Abo if (cached) { const reader = new Dawg(new Uint8Array(cached)); instances.set(key, reader); + noteDictCacheHit(); return reader; } } catch { @@ -101,6 +104,7 @@ async function load(variant: Variant, version: string, key: string, signal?: Abo return null; // not a dawg — do not cache it } instances.set(key, reader); + noteDictFetched(); void idbPutDawg(key, buf); void requestPersist(); return reader; diff --git a/ui/src/lib/localeval-metrics.ts b/ui/src/lib/localeval-metrics.ts new file mode 100644 index 0000000..513cdd0 --- /dev/null +++ b/ui/src/lib/localeval-metrics.ts @@ -0,0 +1,84 @@ +// Client-side accumulator + beacon for local move-preview adoption telemetry. It counts a +// few events — the app cold start, dictionary loads by result, and move previews by path — +// and posts the running deltas to the edge periodically and when the app is backgrounded, +// so the backend can chart adoption (docs/ARCHITECTURE.md §11). Best-effort throughout: a +// failed beacon keeps its counts to retry, and nothing here throws into the caller. It lives +// outside the lazy dict subsystem so the cold start is recorded even when no game is opened. + +import { gateway } from './gateway'; + +interface Counts { + cold_start: number; + dict_fetched: number; + dict_cache_hit: number; + dict_miss: number; + preview_local: number; + preview_network: number; +} + +function zero(): Counts { + return { cold_start: 0, dict_fetched: 0, dict_cache_hit: 0, dict_miss: 0, preview_local: 0, preview_network: 0 }; +} + +let counts = zero(); +let started = false; + +function total(c: Counts): number { + return c.cold_start + c.dict_fetched + c.dict_cache_hit + c.dict_miss + c.preview_local + c.preview_network; +} + +// flush posts the accumulated deltas and resets them; on failure it folds the batch back in +// so the next flush retries. Best-effort. +async function flush(): Promise { + if (total(counts) === 0) return; + const batch = counts; + counts = zero(); + try { + await gateway.reportLocalEval({ ...batch }); + } catch { + counts.cold_start += batch.cold_start; + counts.dict_fetched += batch.dict_fetched; + counts.dict_cache_hit += batch.dict_cache_hit; + counts.dict_miss += batch.dict_miss; + counts.preview_local += batch.preview_local; + counts.preview_network += batch.preview_network; + } +} + +/** + * startLocalEvalMetrics records the app cold start and begins the periodic beacon. Called once + * at launch (a repeat call is a no-op). It also flushes when the app is backgrounded, so a + * batch is not lost when the tab is closed. + */ +export function startLocalEvalMetrics(): void { + if (started) return; + started = true; + counts.cold_start += 1; + setInterval(() => void flush(), 60_000); + if (typeof document !== 'undefined') { + document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') void flush(); + }); + } +} + +/** noteDictFetched: a dictionary was downloaded and cached (an IndexedDB fill). */ +export function noteDictFetched(): void { + counts.dict_fetched += 1; +} +/** noteDictCacheHit: a dictionary loaded from the IndexedDB cache (no download). */ +export function noteDictCacheHit(): void { + counts.dict_cache_hit += 1; +} +/** noteDictMiss: a warm-up did not produce a usable dictionary (failed or timed out). */ +export function noteDictMiss(): void { + counts.dict_miss += 1; +} +/** notePreviewLocal: a move preview was computed on-device. */ +export function notePreviewLocal(): void { + counts.preview_local += 1; +} +/** notePreviewNetwork: a move preview fell back to the network. */ +export function notePreviewNetwork(): void { + counts.preview_network += 1; +} diff --git a/ui/src/lib/mock/client.ts b/ui/src/lib/mock/client.ts index d08656f..d17087d 100644 --- a/ui/src/lib/mock/client.ts +++ b/ui/src/lib/mock/client.ts @@ -166,6 +166,10 @@ export class MockGateway implements GatewayClient { throw new Error('fetchDict unsupported in mock'); } + async reportLocalEval(_counts: Record): Promise { + // Telemetry is a no-op in mock mode. + } + async gamesList(): Promise { return { games: [...this.games.values()].map((g) => structuredClone(g.view)), diff --git a/ui/src/lib/transport.ts b/ui/src/lib/transport.ts index 892b982..ffa9f44 100644 --- a/ui/src/lib/transport.ts +++ b/ui/src/lib/transport.ts @@ -80,6 +80,18 @@ export function createTransport(baseUrl: string): GatewayClient { return res.arrayBuffer(); }, + async reportLocalEval(counts) { + if (!token) throw new Error('reportLocalEval: no session'); + // keepalive so a batch flushed as the app is backgrounded still reaches the edge. + const res = await fetch(`${origin}/metrics/local-eval`, { + method: 'POST', + headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, + body: JSON.stringify(counts), + keepalive: true, + }); + if (!res.ok) throw new Error(`reportLocalEval: HTTP ${res.status}`); + }, + async authTelegram(initData) { return codec.decodeSession(await exec('auth.telegram', codec.encodeTelegramLogin(initData, browserOffset()))); },