Skip to content

Report Neko connection timeouts to parent frame - #362

Open
robertjamesprior wants to merge 4 commits into
mainfrom
hypeship/neko-timeout-telemetry
Open

Report Neko connection timeouts to parent frame#362
robertjamesprior wants to merge 4 commits into
mainfrom
hypeship/neko-timeout-telemetry

Conversation

@robertjamesprior

@robertjamesprior robertjamesprior commented Sep 2, 2026

Copy link
Copy Markdown

Summary

  • post a parent-frame message when the Neko client connection watchdog times out
  • include ICE, peer connection, signaling, websocket state, transport policy, and recent ICE candidate-family summaries in the timeout payload
  • retry failed embedded live-view attempts with iceTransportPolicy: relay when the dashboard passes a retry attempt
  • accept parent-frame read-only updates so embedders can lock and unlock controls without remounting the live-view iframe
  • bump the pinned Neko server dependency to the branch that logs ICE candidates, state changes, and nominated pairs

Latest investigation

  • A canary showed that a server-side IPv6 STUN warning can appear in healthy live-view connects.
  • The useful signal is whether the client reaches ICE/media state before the 15s watchdog.
  • This PR adds the client-side timeout event needed for the dashboard to classify that failure path and recover promptly, plus enough candidate-family detail to separate IPv4-only, IPv6, host, srflx, and relay patterns.
  • Retry attempts now force relay candidates, which gives stalled direct ICE setup a different path instead of repeating the same failed selection.
  • The Neko server pin depends on Log WebRTC ICE candidate selection neko#18.

Test plan

  • bunx eslint src/neko/base.ts
  • bun run build
  • GOCACHE=/tmp/go-build-cache go test ./lib/nekoclient ./cmd/api/api from server

Note

Medium Risk
Changes WebRTC connection policy on retries and embed parent/child messaging for timeouts and remote control; mis-handled messages or relay-only retries could affect live-view connectivity, but scope is limited to the embedded client.

Overview
Improves embedded Neko live-view observability and recovery when WebRTC stalls, and lets the parent dashboard toggle input lock without reloading the iframe.

On connection timeout, the client now postMessages a KERNEL_CONNECTION_TIMEOUT event to the parent with ICE/peer/signaling/WebSocket state, the active iceTransportPolicy, and summaries of recent local/remote ICE candidates (type, protocol, IPv4/IPv6). When kernelLiveViewAttempt is greater than zero, peer creation uses iceTransportPolicy: 'relay' so retries can take a TURN path instead of repeating the same direct ICE failure.

Read-only behavior is centralized in applyReadOnlyMode: URL params still apply at startup, but the parent can send KERNEL_SET_READ_ONLY to override hosting lock, release control when enabling read-only, and restore implicit hosting when disabling it. The server go.mod replace pin for kernel/neko/server is bumped to match.

Reviewed by Cursor Bugbot for commit b3ee84c. Bugbot is set up for automated code reviews on this repo. Configure here.

@robertjamesprior
robertjamesprior marked this pull request as ready for review September 2, 2026 15:24
robertjamesprior and others added 3 commits September 2, 2026 16:11
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@sjmiller609
sjmiller609 removed their request for review September 3, 2026 15:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant