Browser recovery diagnostics
POST /api/v1/client-diagnostics accepts the bounded ClientDiagnosticRequest
in api/openapi.yaml and returns an empty 202. Send JSON with
Content-Type: application/json; sendBeacon should use an application/json Blob.
No session, X-Client-Build or CSRF header is required, including from old tabs.
Only this exact POST has the exemption. There are no database or money writes.
The maximum body is 8192 bytes. Cache arrays have at most 16 names of 128
characters; URL fields have at most 256 characters. Browser/worker/recovery enums
and build IDs are constrained by the schema. Production client builds are the
40-character lowercase Git SHA embedded by Vite; local builds use dev.
Unknown fields, duplicate keys and invalid/oversized payloads are refused without
logging or echoing the rejected payload. Use null when nullable facts are unknown.
Explicit Origin must equal the origin in CFG_APP_PUBLIC_BASE_URL; cross-site
Sec-Fetch-Site is refused. Missing Origin permits non-browser reports but does
not authenticate them. There are no CORS credentials grants. Admission allows
20 attempts per IP per minute and 200 globally per minute. Per-IP refusals also
consume the global budget. HTTP 429 supplies Retry-After in seconds (1–60).
The mutex-protected map has at most 1024 IP keys, clears after one minute and
inherits the router's trusted-edge IP convention. Neither IP nor raw headers
become diagnostic log fields.
The server reduces URLs to recognized /assets/<name>-<hash>.js, .css or
.woff2 paths, or /sw.js and /workbox-<hash>.js for worker scripts. Origins,
userinfo, queries and fragments are discarded; other paths become null. Cache
names retain only local-images, s3-images, workbox-precache and
workbox-runtime; everything else becomes redacted. Private Workbox suffixes
are discarded. Body player_id is shape-checked then dropped. Only an existing,
active player session with matching session version contributes user_id.
Missing, expired, revoked and stale cookies remain anonymous, without cookie or
session writes. Browser facts appear under reported_untrusted.
GET /version preserves backend version, commit and date, and adds optional
client_build. This is the trusted frontend marker read from
CFG_HTTP_CLIENT_BUILD_FILE, refreshed on every request. Unset, unreadable or
invalid markers produce an absent field; clients should interpret it as unknown.
Accepted log events independently read the same file into actual_client_build
(null when unknown). A client-reported latest build never supplies that field.
Accepted events have event_name=client_diagnostic. shown, exhausted and
navigation_failed warn and emit the trace event client.stuck_tab; other outcomes
are INFO and emit client.diagnostic. The monotonic OTel counter
playgo.client_diagnostics.events exports to Grafana PromQL as
playgo_client_diagnostics_events_total. Its bounded labels are status,
recovery_step, outcome, browser_family, display_mode, in_app_browser, in_app_browser_kind.
The kind is one of messenger, facebook, instagram, other, none. New
clients always send it and derive the boolean from kind != none. Older clients
may omit kind; intake normalizes true to other and false to none. Unknown app
markers are other; ordinary Safari/Chrome and generic WebViews are none.
Rejected counters carry only status (invalid, forbidden, rate_limited);
accepted counters carry status="accepted" and the report's bounded dimensions.
Builds, versions, URLs, cache names, player IDs and IPs never become metric or
Loki stream labels. Logs and counters remain available when traces are sampled out.
Example accepted warning volume over ten minutes:
sum by (outcome, browser_family, in_app_browser_kind) (
increase(playgo_client_diagnostics_events_total{status="accepted",outcome=~"shown|exhausted|navigation_failed"}[10m])
)
A conservative alert condition is at least five exhausted or
navigation_failed reports in ten minutes, sustained for five minutes. Reports
are public and untrusted, so investigate before taking action.
sum(increase(playgo_client_diagnostics_events_total{status="accepted",outcome=~"exhausted|navigation_failed"}[10m])) >= 5
To inspect release evidence in Loki without adding stream labels:
{app="neoplay", job="neoplay-docker"} | json | event_name="client_diagnostic"
Select the affected instance/service in Grafana, inspect reported_untrusted
and actual_client_build, then follow trace_id when a sampled trace exists.
Successful recovery progress does not create warning noise. Intake never
performs cleanup, refunds, retries or any other financial action on the server.
To count Messenger stuck-tab reports by browser kind over ten minutes:
sum by (in_app_browser_kind) (
increase(playgo_client_diagnostics_events_total{status="accepted",outcome=~"shown|exhausted|navigation_failed"}[10m])
)
Filter in_app_browser_kind="messenger" for Messenger only. The endpoint remains
POST /api/v1/client-diagnostics; rate limits and privacy rules are unchanged.