Artstr-Studio/docs/STREAMING_RELAY_SYNC_FEATURE.md

# Streaming Relay Sync & Soft Cooldown Plan

## Goals
Make the Community template browser feel **fast and reliable** by rendering Nostr template events progressively as they arrive from each relay, instead of waiting for every relay (or a 4.5s timeout) before showing anything.

### Product goals
1. First template visible within ~300ms of opening Community (assuming any fast relay is reachable).
2. Slow or flaky relays no longer block the feed — their results trickle in late instead of being lost.
3. A single transient relay timeout does not silently shrink the relay pool for the next hour.
4. No regression in publish reliability or social action (react/follow/repost) flows.

### Non-goals (v1)
- Persistent local cache of fetched template events across sessions.
- Relay scoring / per-relay weighting beyond simple cooldown.
- Per-event retry on a different relay if its origin relay drops mid-stream.
- Switching to a Nostr library (e.g. NDK, nostr-tools pool). Stay with the in-file WebSocket implementation.

---

## Problem statement

**Symptoms reported:** Nostr designs (kind `30078` notes) often never appear in the template browser, or take very long to appear.

**Observed in `src/index.html`:**

1. `queryRelays()` (line 2980) opens a WebSocket per relay, sends a single `REQ`, and collects events into a `Map`. It uses `Promise.all` over every relay and only returns the merged result after **every relay either finishes (EOSE) or hits the timeout**. The default timeout is 3500ms; the template fetch uses 4500ms.
2. `fetchFeedAndReactions()` (line 5735) awaits that full result before populating `_feedCache.events`. `loadFeedTab()` (line 6217) waits for the entire cache to fill before building any rows.
3. `markRelayFailure()` (line 2685) is called on any timeout, error, or unexpected close, and pushes the relay into a cooldown that starts at **10 minutes** and escalates up to **1 hour**. State is persisted to `localStorage` under `casewrap-relay-health`, so failures bleed across sessions.

**Net effect:** if one or two relays are slow, the user stares at "Loading…" for the full timeout window, and any transient hiccup quietly removes that relay from the rotation for the rest of the hour — which compounds over time and explains the "sometimes never loads" report.

---

## Current architecture

```
loadFeedTab(tab)
  └── await fetchFeedAndReactions()
        ├── await Promise.all([
        │     queryRelays({ kinds:[30078], limit:200 }, 4500ms),   ← blocks until all relays settle
        │     queryRelays({ kinds:[5],     limit:100 }, 3500ms)
        │   ])
        ├── batch queryRelays({ kinds:[7], '#e':[...] })           ← reactions
        └── batch queryRelays({ kinds:[0], authors:[...] })        ← profiles
  └── buildRowsFromEvents(_feedCache.events, …)
  └── render
```

Single render at the end. No partial UI.

---

## Proposed architecture

```
loadFeedTab(tab)
  └── show skeleton
  └── start fetchFeedAndReactions({ onProgress: rerender })
        ├── queryRelays({ kinds:[30078] }, { onEvent }) ────────────┐
        │     onEvent → push into _feedCache.events Map            │
        │                trigger debounced onProgress              │
        │                                                          ├── render fires repeatedly as
        ├── queryRelays({ kinds:[5] },     { onEvent }) ────────────┘    new templates arrive
        ├── (await both relay sets to settle)
        ├── batch reactions  → onProgress
        └── batch profiles   → onProgress
```

Key shape changes:
- `queryRelays(relays, filters, { timeoutMs, onEvent, onRelayDone })` — new optional callbacks. Promise still resolves with the full event array when all relays settle, so non-streaming call sites are unchanged.
- `_feedCache.events` populated incrementally via a Map keyed by `event.id` (was: written once at the end).
- `fetchFeedAndReactions(opts)` accepts `{ onProgress }`. Calls it (debounced 150ms) whenever the cache changes.
- `loadFeedTab(tab)` passes an `onProgress` that re-runs `buildRowsFromEvents` and re-renders the current tab.

### Cooldown change (read vs publish)

`markRelayFailure(relay, error, { context })` gets a `context` param:
- `'publish'` (default, preserves current behavior): base **10 min**, max **1 hr**.
- `'read'`: base **30s**, max **5 min**.

`queryRelays` passes `{ context: 'read' }`. `publishToRelays` is unchanged (still defaults to `'publish'`).

Rationale: a single dropped read should not lock a relay out of the next 10 minutes of browsing. A repeated 30s skip is enough to deprioritize a genuinely-broken relay while keeping the pool wide for transient blips.

---

## Phased delivery plan

### Phase 1 — Soft cooldown for reads
Smallest, isolated change. High impact on its own because it stops the relay pool from silently shrinking.

**Changes**
- `src/index.html` constants block: add `RELAY_READ_FAILURE_COOLDOWN_MS = 30 * 1000` and `RELAY_READ_FAILURE_MAX_COOLDOWN_MS = 5 * 60 * 1000`.
- `markRelayFailure(relay, error, opts = {})`: accept `context`, pick cooldown base/max accordingly.
- `queryRelays`: pass `{ context: 'read' }` to every `markRelayFailure` call inside it.
- `publishToRelays`: no change (default `'publish'` context).

**Acceptance**
- Triggering a read-side timeout (e.g. by adding a known-dead relay URL) puts the relay in cooldown for ~30s, verifiable via `localStorage['casewrap-relay-health']`.
- Triggering a publish-side failure still produces a 10+ min cooldown.

### Phase 2 — Streaming `queryRelays`
Non-breaking extension of the existing function.

**Changes**
- Add `onEvent(event, relay)` and `onRelayDone({ relay, ok, error })` options to `queryRelays`.
- In the `message` handler, when a NEW `EVENT` arrives (not already in the dedupe Map), fire `onEvent` after inserting. Do not re-fire for duplicates.
- In `finish()`, fire `onRelayDone` once before resolving.
- Wrap callback calls in try/catch so a buggy listener can't kill the relay reader.
- Existing return value (sorted event array, resolves after all relays settle) is preserved.

**Acceptance**
- Existing call sites (publish verification, profile fetch, reaction batches, mute list, etc.) compile and behave identically.
- A new test invocation that passes `onEvent` receives events in arrival order across relays, with each `event.id` fired at most once.

### Phase 3 — Progressive feed render
Wire streaming into the template browser.

**Changes**
- Replace the array shape of `_feedCache.events` with a Map-backed accumulator. Add a getter helper `getFeedEvents()` that returns the merged array (cache + persisted templates) for use by `buildRowsFromEvents`.
- `fetchFeedAndReactions({ onProgress })`:
  - Reset the accumulator at start.
  - Run the template and deletion queries with `onEvent` callbacks that push into the accumulator and schedule a debounced `onProgress` (≈150ms).
  - After both queries settle, fire `onProgress` once more, then run reaction and profile batches (each followed by a final `onProgress`).
  - Continue to gate concurrent calls with `_feedCache.loading`.
- `loadFeedTab(tab)`:
  - Render a one-time skeleton.
  - Define `rerender()` that re-runs `buildRowsFromEvents`, sorts, paginates, and replaces the wall contents. Bail out if the user has switched to a different tab.
  - Call `await fetchFeedAndReactions({ onProgress: rerender })`.
  - One last `rerender()` after the await.
- Search and "Mine" tabs reuse the same pattern via a shared helper.

**Acceptance**
- With all six default relays in the list, first template appears in the wall before the slowest relay has responded.
- Switching tabs mid-stream cancels stale renders (no flicker into the wrong tab).
- Reaction counts and author avatars appear after the initial render without wiping the cards.
- "No templates found…" message only appears after both template-side relays have all settled with zero rows.

---

## Engineering notes

- **Debounce window:** 150ms is a balance between visible progressiveness and avoiding layout thrash when a fast relay dumps 50 events in one tick.
- **Dedupe:** must happen on `event.id`, not address — multiple relays will return the same event. Existing `events.set(id, …)` pattern already does this for the return value; the streaming callback must also gate on "not previously seen" to avoid double-rendering.
- **Cancellation:** if the user switches tabs, the in-flight queries keep running (they're cheap and we want the cache warm), but the `rerender` callback should check `state.community.currentTab` and no-op when stale.
- **Persisted templates:** `loadPersistedPublishedTemplateEvents()` should be merged once at the start (so the user's own published designs show even with zero relay results) and again each `onProgress`.
- **Backwards compat:** call sites that don't pass `onEvent` see no behavior change. `_feedCache.events` exposed as an array via the getter keeps `buildRowsFromEvents` callers unchanged.

---

## Risks and tradeoffs

| Risk | Mitigation |
|---|---|
| Re-render flicker as events stream in | Debounce + key cards by `event.id` so the diff is additive, not a full wipe |
| User clicks a card that gets re-sorted under their cursor | Sort key is stable (`created_at` desc, then `id` desc); new cards append to the end of the current sort, not above |
| Faster cooldown means a genuinely dead relay gets retried more often | Worst case is a 30s WebSocket open attempt every ~30s per dead relay, which is cheap. Failure count still escalates the cooldown up to 5 min |
| Streaming exposes payload-parse errors more loudly | Parse errors stay quietly skipped inside `buildRowsFromEvents`; no UI change |
| Long-running WebSockets leak if relay never sends EOSE | Existing per-relay `timeoutMs` still applies and calls `finish()` even with streaming |

---

## Out of scope / future enhancements

- Single-shot retry on a different relay when the original relay drops mid-stream.
- Background "warm" subscription that stays open while the modal is closed, so opening Community is instant.
- Per-relay latency surface in the relay settings UI (so users can see which relays are slowing them down).
- Caching template events across reloads with a TTL (would need careful invalidation against kind-5 deletions).