webapp/docs/nostr-patterns/subscriptions.md

# Subscriptions & lifecycle

## Subscribe, store the unsubscribe handle, clean up on unmount

**Canonical:** `src/modules/events/composables/useRSVP.ts` —
`loadRSVPs()` (subscribe block) + the matching `onUnmounted(() => unsubscribe?.())`.

```ts
let unsubscribe: (() => void) | null = null

unsubscribe = relayHub.subscribe({
  id: `rsvps-${Date.now()}`,
  filters: [{ kinds: [NIP52_KINDS.RSVP], limit: 500 }],
  onEvent: …,
  onEose: () => { isLoaded.value = true },
})

onUnmounted(() => unsubscribe?.())
```

**Why:**
- The subscription ID must be unique per mount. Reusing a static id (e.g.
  `'rsvps'`) causes RelayHub to return the *previous* subscription on rapid
  re-mount, which leaks the old `onEvent` closure or skips the new one
  entirely. `Date.now()` (or a uuid) suffices.
- Forgetting `onUnmounted` cleanup leaks subscriptions across route changes;
  the relay keeps streaming events into a closure that updates a stale ref.

**Alternate implementation:** `src/modules/base/composables/useProfiles.ts`
uses the same shape; differs only in subscription id construction. If you
diverge, do it because the lifetime of the subscription differs (e.g.
session-long vs view-long), not by accident.

## EOSE means "backfill done", not "all events delivered"

**Canonical:** `src/modules/events/composables/useRSVP.ts` —
`onEose: () => { isLoaded.value = true }`.

`onEose` fires once, after the relay flushes everything stored that matches
the filter. Live events keep arriving on `onEvent` afterwards. Use the EOSE
flag to drop a "loading…" placeholder and let *partial* results render
during backfill — don't block the UI on EOSE.

If you want a one-shot snapshot (fetch profiles, build a one-time list), it
*is* fine to call `unsubscribe()` from inside `onEose` — see
`src/modules/base/nostr/ProfileService.ts` (the post-EOSE cleanup path).

## Visibility-aware reconnect

**Canonical:** `src/modules/base/nostr/relay-hub.ts` —
`registerWithVisibilityService` + `handleResume` / `handlePause` +
`restoreSubscriptions`.

When the tab is hidden / device sleeps, the websocket drops. RelayHub closes
stale subscriptions on pause and replays their `Filter` configs against
healthy relays on resume. Consumers don't need to do anything — the
subscription you registered survives the reconnect.

**Why callers should know this:** subscriptions don't transparently
guarantee replay. If you stash event IDs in a local `Set` to dedupe and the
tab is hidden for an hour, on resume the relay may re-stream events from
before the dedupe set existed (or after the set was reset). Treat the
dedupe state as best-effort, not authoritative — pair with the
`is_duplicate_event` style check on every incoming event regardless.

## Per-incoming-event dedup

When subscribing to an actively-published kind (reactions, RSVPs, market
orders), the relay can deliver the same event ID more than once across
reconnects, multiple connected relays, or filter overlaps. The cure is a
bounded `Set<eventId>` checked on every `onEvent`.

**Canonical:** `src/modules/base/nostr/ReactionService.ts` — `seenEventIds`
check at the top of `handleReactionEvent`.

**Why bounded:** the set otherwise grows unboundedly across a long session.
Use an `OrderedDict`-style eviction (insert order = oldest first) and cap at
~10k entries — events older than that are not going to come back through
the same subscription's lifetime in any realistic flow.

The events extension's Python `nostr/nostr_client.py` has the same pattern
(`is_duplicate_event` over an `OrderedDict`) for the server-side
subscription. If you build a new subscription consumer, copy the cap.