Skip to main content

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.