@hatk/hatk 0.0.1-alpha.79 → 0.0.1-alpha.80

package/dist/jetstream.d.ts

@@ -18,6 +18,24 @@ import { type CommitOp, type IndexerCoreOpts } from './indexer.ts';
 /** Server-side filter caps, rejected before the WebSocket upgrade. */
 export declare const MAX_COLLECTIONS = 100;
 export declare const MAX_DIDS = 10000;
+/**
+ * Refused handshakes before the next attempt drops its cursor and probes live.
+ *
+ * Jetstream retains roughly a day of seqs. A cursor older than that is refused
+ * at the handshake — a bare close 1006, no `open`, no message. Nothing arrives,
+ * so {@link getLastSeq} stays null and a plain resume offers the same dead
+ * cursor forever. Restarting does not clear it either: the boot cursor is read
+ * back from the row this stream never got to advance. The stream wedges for
+ * good, while records written through the AppView's own path keep indexing, so
+ * nothing looks broken from inside the app.
+ *
+ * A cursorless probe tells a dead cursor from a dead instance without guessing:
+ * a reachable instance always accepts a cursorless subscribe, so a probe that
+ * opens means the cursor was the problem, and a probe that is refused too means
+ * the instance is down and the cursor is still worth keeping. Probing every Nth
+ * attempt rather than once keeps that true across an outage of any length.
+ */
+export declare const CURSOR_PROBE_EVERY = 3;
 export interface JetstreamOpts extends IndexerCoreOpts {
     /** Instance base URL, e.g. `wss://jetstream.us-east.bsky.network`. */
     jetstreamUrl: string;
@@ -67,6 +85,18 @@ export declare function commitToOp(commit: JetstreamCommit, collections: Set<str
  * Exported for tests.
  */
 export declare function processEvent(payload: any, collections: Set<string>): void;
+/**
+ * The cursor a connection attempt should offer, given how many attempts in a
+ * row were refused before it.
+ *
+ * `refusals` counts consecutive closes that never reached `open`; it resets the
+ * moment one does. Every {@link CURSOR_PROBE_EVERY}th refusal answers null so
+ * the attempt subscribes to the live tip instead — see the constant for why
+ * that is the discriminator.
+ *
+ * Exported for tests.
+ */
+export declare function reconnectCursor(refusals: number, liveSeq: number | null, bootCursor: string | null | undefined): string | null | undefined;
 /**
  * Connect to a Jetstream v2 instance and begin indexing.
  *
@@ -75,8 +105,14 @@ export declare function processEvent(payload: any, collections: Set<string>): vo
  * inclusive and delivery is at-least-once, so the event at the resume point
  * arrives again — harmless, since writes upsert on the record's `at://` URI.
  *
+ * `opts.cursor` is the boot-time cursor and stays fixed across reconnects;
+ * what each attempt actually offers comes from {@link reconnectCursor}, so a
+ * live probe can drop the cursor for one attempt without losing it.
+ *
+ * @param refusals Consecutive refused handshakes so far. Internal — reconnects
+ *   pass their own count; callers start at 0.
  * @returns The WebSocket connection (for shutdown coordination)
  */
-export declare function startJetstreamIndexer(opts: JetstreamOpts): Promise<WebSocket>;
+export declare function startJetstreamIndexer(opts: JetstreamOpts, refusals?: number): Promise<WebSocket>;
 export {};
 //# sourceMappingURL=jetstream.d.ts.map

package/dist/jetstream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jetstream.d.ts","sourceRoot":"","sources":["../src/jetstream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EASL,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,cAAc,CAAA;AAGrB,sEAAsE;AACtE,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,eAAO,MAAM,QAAQ,QAAS,CAAA;AAO9B,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,wDAAwD;AACxD,UAAU,eAAe;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAalG;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,QAAQ,GAAG,IAAI,CAY7F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAuBzE;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAuCnF"}
+{"version":3,"file":"jetstream.d.ts","sourceRoot":"","sources":["../src/jetstream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EASL,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,cAAc,CAAA;AAGrB,sEAAsE;AACtE,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,eAAO,MAAM,QAAQ,QAAS,CAAA;AAO9B;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,wDAAwD;AACxD,UAAU,eAAe;IACvB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAalG;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,QAAQ,GAAG,IAAI,CAY7F;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAuBzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,MAAM,GAAG,IAAI,GAAG,SAAS,CAK3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,SAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CA0DjG"}

package/dist/jetstream.js

@@ -22,6 +22,24 @@ export const MAX_DIDS = 10_000;
 /** Event kinds hatk consumes. `commit` carries records; `identity` drives handle renames. */
 const KINDS = ['commit', 'identity'];
 const RECONNECT_DELAY_MS = 3000;
+/**
+ * Refused handshakes before the next attempt drops its cursor and probes live.
+ *
+ * Jetstream retains roughly a day of seqs. A cursor older than that is refused
+ * at the handshake — a bare close 1006, no `open`, no message. Nothing arrives,
+ * so {@link getLastSeq} stays null and a plain resume offers the same dead
+ * cursor forever. Restarting does not clear it either: the boot cursor is read
+ * back from the row this stream never got to advance. The stream wedges for
+ * good, while records written through the AppView's own path keep indexing, so
+ * nothing looks broken from inside the app.
+ *
+ * A cursorless probe tells a dead cursor from a dead instance without guessing:
+ * a reachable instance always accepts a cursorless subscribe, so a probe that
+ * opens means the cursor was the problem, and a probe that is refused too means
+ * the instance is down and the cursor is still worth keeping. Probing every Nth
+ * attempt rather than once keeps that true across an outage of any length.
+ */
+export const CURSOR_PROBE_EVERY = 3;
 /**
  * Build the subscribe URL.
  *
@@ -114,6 +132,24 @@ export function processEvent(payload, collections) {
         return;
     applyCommit(did, [op]);
 }
+/**
+ * The cursor a connection attempt should offer, given how many attempts in a
+ * row were refused before it.
+ *
+ * `refusals` counts consecutive closes that never reached `open`; it resets the
+ * moment one does. Every {@link CURSOR_PROBE_EVERY}th refusal answers null so
+ * the attempt subscribes to the live tip instead — see the constant for why
+ * that is the discriminator.
+ *
+ * Exported for tests.
+ */
+export function reconnectCursor(refusals, liveSeq, bootCursor) {
+    const resume = resumeCursor(liveSeq, bootCursor);
+    // Nothing to abandon — an attempt with no cursor is already a live tail.
+    if (!resume)
+        return resume;
+    return refusals > 0 && refusals % CURSOR_PROBE_EVERY === 0 ? null : resume;
+}
 /**
  * Connect to a Jetstream v2 instance and begin indexing.
  *
@@ -122,17 +158,26 @@ export function processEvent(payload, collections) {
  * inclusive and delivery is at-least-once, so the event at the resume point
  * arrives again — harmless, since writes upsert on the record's `at://` URI.
  *
+ * `opts.cursor` is the boot-time cursor and stays fixed across reconnects;
+ * what each attempt actually offers comes from {@link reconnectCursor}, so a
+ * live probe can drop the cursor for one attempt without losing it.
+ *
+ * @param refusals Consecutive refused handshakes so far. Internal — reconnects
+ *   pass their own count; callers start at 0.
  * @returns The WebSocket connection (for shutdown coordination)
  */
-export async function startJetstreamIndexer(opts) {
-    const { jetstreamUrl, collections, cursor } = opts;
+export async function startJetstreamIndexer(opts, refusals = 0) {
+    const { jetstreamUrl, collections } = opts;
     const pinnedRepos = opts.pinnedRepos || null;
     assertFilterLimits(collections, pinnedRepos);
     setCursorKey('jetstream');
     await configureIndexer(opts);
+    const cursor = reconnectCursor(refusals, getLastSeq(), opts.cursor);
     const wsUrl = buildSubscribeUrl(jetstreamUrl, collections, pinnedRepos, cursor);
     if (cursor)
         log(`[jetstream] Resuming from cursor ${cursor}`);
+    else if (refusals > 0)
+        log('[jetstream] Probing the live tip — the resume cursor keeps being refused');
     log(`[jetstream] Connecting to ${jetstreamUrl} (${collections.size} collections)...`);
     // The lexicon default is identical framing, so an empty subprotocol echo is
     // fine; we offer it so the server can pick the JSON arm explicitly.
@@ -150,12 +195,31 @@ export async function startJetstreamIndexer(opts) {
             emit('jetstream', 'decode_error', { error: err instanceof Error ? err.message : String(err) });
         }
     });
-    ws.addEventListener('open', () => log('[jetstream] Connected'));
-    ws.addEventListener('close', () => {
-        log(`[jetstream] Disconnected, reconnecting in ${RECONNECT_DELAY_MS / 1000}s...`);
-        // Read the seq at close time, not connect time — reusing the boot cursor on
-        // every reconnect would replay everything received since the process started.
-        setTimeout(() => startJetstreamIndexer({ ...opts, cursor: resumeCursor(getLastSeq(), opts.cursor) }), RECONNECT_DELAY_MS);
+    let opened = false;
+    ws.addEventListener('open', () => {
+        opened = true;
+        log('[jetstream] Connected');
+    });
+    ws.addEventListener('close', (event) => {
+        // A close that never reached `open` is a refused handshake, not a dropped
+        // stream, and the two want opposite things from the cursor.
+        const nextRefusals = opened ? 0 : refusals + 1;
+        if (opened) {
+            log(`[jetstream] Disconnected (${event.code}), reconnecting in ${RECONNECT_DELAY_MS / 1000}s...`);
+        }
+        else {
+            log(`[jetstream] Handshake refused (${event.code}${event.reason ? `: ${event.reason}` : ''}) ` +
+                `x${nextRefusals}, retrying in ${RECONNECT_DELAY_MS / 1000}s...`);
+            emit('jetstream', 'handshake_refused', {
+                code: event.code,
+                reason: event.reason || undefined,
+                cursor: cursor ?? null,
+                refusals: nextRefusals,
+            });
+        }
+        // `opts` goes back unchanged so the boot cursor survives a probe; the seq
+        // is read at reconnect time, not here, so a resume uses everything seen.
+        setTimeout(() => startJetstreamIndexer(opts, nextRefusals), RECONNECT_DELAY_MS);
     });
     return ws;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatk/hatk",
-  "version": "0.0.1-alpha.79",
+  "version": "0.0.1-alpha.80",
   "license": "MIT",
   "bin": {
     "hatk": "dist/cli.js"