amethyst/nestsClient/plans/2026-04-26-tier4-coding-plan.md

Tier 4 — coding plan (token refresh, moq-lite reconnect backoff)

Tier 4 of 2026-04-26-nostrnests-integration-audit.md. Pure infrastructure hardening — no user-visible UX changes. Covers the items the audit flagged as "MAYBE GAP" or "worth confirming".

Step 1 — Token re-mint before expiry on long sessions (#16)

moq-auth tokens live 600 s and there's no refresh endpoint. A listener / speaker that stays in a room past the 10-minute mark needs to mint a fresh JWT and reopen the WT session — otherwise the moq-rs relay starts rejecting per-track auth checks.

Audit first

• Walk MoqLiteSession + MoqLiteNestsListener / MoqLiteNestsSpeaker to confirm the JWT is only consulted at WT CONNECT time (it is — moq-rs's auth check is per-session, not per-OBJECT). That means the only thing that needs re-minting is when the WT session itself dies and we reconnect — see Step 2.
• If the user stays in a room for hours without a transport blip, the relay never re-checks the JWT, so we don't strictly need a pro-active re-mint. Confirm against moq-rs: does the relay drop the session when its claims exp passes? If yes → step 2's reconnect path naturally re-mints.

If a pro-active re-mint IS needed

Implement in MoqLiteNestsListener / MoqLiteNestsSpeaker:

• Parse the JWT's exp claim from the response — extend OkHttpNestsClient.mintToken to return (token, expiresAt: Long) instead of just token.
• Schedule a coroutine in connectNests* that fires (expiresAt - now - 60s) before expiry and calls a private reauthorize() that mints a fresh token and...
  • either silently passes it to a (yet-to-exist) moq-lite "AUTH_REFRESH" message — moq-lite doesn't have one today,
  • or quietly tears down the current WT session + reconnects (matching the reconnect path in Step 2).

Open question

Does moq-rs honour a re-handshake on the same session? Almost certainly not — there's no in-band auth message. So the pro-active path collapses into "trigger a reconnect ~60 s before exp".

Recommendation

Treat this step as subsumed by Step 2 — once the reconnect backoff handles transport drops, an exp-driven self-disconnect is just another trigger. Schedule:

val refreshAt = expiresAt - now - REFRESH_LEAD_MS  // 60_000
scope.launch {
    delay(refreshAt.coerceAtLeast(0))
    triggerReconnect(reason = "JWT expiry")
}

in connectNestsListener / connectNestsSpeaker, where triggerReconnect(...) is the same entry point Step 2 builds.

---

Step 2 — moq-lite Connection.Reload-equivalent reconnect with backoff (#17)

The JS reference uses

delay: { initial: 1000, multiplier: 2, max: 30000 }

when the WT session drops. Confirm Amethyst's MoqLiteSession has equivalent backoff before adding it.

Audit

• nestsClient/.../moq/lite/MoqLiteSession.kt — does any flow on it actually reconnect on transport failure? Or does the session surface Closed and leave it to the caller (the NestsListener / NestsSpeaker connectors) to retry?
• nestsClient/.../NestsConnect.kt — connectNestsListener / connectNestsSpeaker walk the HTTP→WT→moq-lite handshake once and return a Listener/Speaker. No retry today.

The audit will almost certainly conclude: no auto-reconnect exists. Add it.

Design

Add at the orchestration layer (connectNestsListener / connectNestsSpeaker), not inside MoqLiteSession. The session is "this connection"; reconnect is "open another connection".

• nestsClient/.../NestsReconnectPolicy.kt (NEW) — pure data:

  data class NestsReconnectPolicy(
      val initialDelayMs: Long = 1_000,
      val multiplier: Double = 2.0,
      val maxDelayMs: Long = 30_000,
      val maxAttempts: Int = Int.MAX_VALUE,
  )
  

• nestsClient/.../NestsListener.kt — extend the state machine:
  • new NestsListenerState.Reconnecting(attempt: Int, delayMs: Long)
  • on the underlying session emitting Closed, walk the reconnect flow (mint fresh JWT → open WT → wrap in MoqLiteSession → re-issue every active SubscribeHandle).
• nestsClient/.../NestsSpeaker.kt — equivalent on the speaker side. Re-publish the broadcast suffix automatically; transparently resume capture after the new session opens.

Test

• New nestsClient/src/jvmTest/.../moq/lite/MoqLiteReconnectTest.kt — drive a FakeWebTransport that closes after the first frame, then assert the listener auto-reconnects within initialDelayMs + jitter.
• Update one of the interop tests (round-trip) to deliberately kill the WT session mid-broadcast and verify the listener resumes receiving frames.

Risk

• Re-issuing every active SubscribeHandle has to preserve the consumer-side Flow<MoqObject> so app code doesn't notice. Achievable by buffering the handle's flow upstream of the per-session adapter — likely a MutableSharedFlow per handle that the per-session pump emits into.

---

Suggested commit order

1. Audit + notes: open a small text note documenting whether the relay drops sessions on JWT exp (Step 1 dependency) — a ~2-paragraph file in nestsClient/plans/.
2. NestsReconnectPolicy + state machine extension (Step 2, listener side first).
3. Auto-reconnect tests against FakeWebTransport.
4. Speaker-side reconnect (Step 2 second half).
5. JWT-expiry-driven reconnect (Step 1, plumbing only — uses the Step 2 entry point).

Each step is independently merge-safe; the listener-only path is useful even if the speaker reconnect ships later.

Out of scope for Tier 4

• WebSocket fallback (useWebSocket: true) — only matters for browser clients without WebTransport. Android has WT via QUIC, so not a gap.
• Multi-track / video / fetch — confirmed not used by nostrnests.
• Bitrate probes — not used by nostrnests.
• Per-IP rate-limit smoothing for /auth — already handled at the user-action level (one mint per join). No need for client-side throttling.