Rebuild: end-to-end fixes — spool accounting, keep-alive frames, resume point, overlapped worker

End to end (workstation, recent a.b.boneless ranges from the spool): a 2M
range in 10–12 s, 166k–202k headers/s per worker process (edge:bench on
one core: 215k).

- Prefetcher: spooled_at was set against a total counted from the range's
  resume point, which shrinks as the worker advances: the last chunks were
  never fetched and the worker waited. Now counted against the whole
  range, only new chunks counted, and leased ranges are always checked
  against the files. Planned ranges ahead are bounded (it had spooled ever
  more); the spool size is measured every 30 s (a stat per file).
- The stream sends an empty frame every 20 s while waiting for a chunk
  (Node's fetch gave up on a quiet body after 5 minutes).
- A range taken over midway: the first batch starts at the resume point
  (it started at the range's start and was refused).
- edge:node inflates the next chunk on the thread pool while indexing the
  current one, and doesn't wait for a post before indexing on (posts stay
  in order; a failed post stops the range).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/controllers/node_controller.ts

@@ -4,10 +4,12 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import Leases, { LeaseLost } from '#services/leases'
 import BatchStore, { StaleBatch } from '#services/batch_store'
 import Spool from '#services/spool'
-import { encodeFrame, fromWire, type WireBatch } from '#lib/edge/index'
+import { KEEPALIVE, encodeFrame, fromWire, type WireBatch } from '#lib/edge/index'
 
 /** How long the stream waits for a chunk the prefetcher hasn't spooled yet. */
 const CHUNK_WAIT_MS = 15 * 60 * 1000
+/** While waiting, an empty frame this often: an HTTP client gives up on a quiet body (Node's after 5 minutes). */
+const KEEPALIVE_MS = 20_000
 
 /**
  * The edge workers' API (REBUILD.md, parts 1–2): a lease, the range's
@@ -34,8 +36,14 @@ export default class NodeController {
     async function* frames() {
       for (const span of spans) {
         const waitUntil = Date.now() + CHUNK_WAIT_MS
+        let quietSince = Date.now()
         while (!(await Spool.has(rangeId, span))) {
           if (Date.now() > waitUntil) throw new Error(`Chunk ${span.from}–${span.to} of range ${rangeId} wasn't spooled in time`)
+          if (Date.now() - quietSince >= KEEPALIVE_MS) {
+            quietSince = Date.now()
+            yield encodeFrame(KEEPALIVE)
+            await Leases.heartbeat(rangeId, nodeId)
+          }
           await sleep(500)
         }
         yield encodeFrame({ ...span, data: await Spool.read(rangeId, span) })

app/services/prefetcher.ts

@@ -9,12 +9,14 @@ interface Target {
   group: string
   /** Chunks not spooled yet, in order. */
   missing: ChunkSpan[]
-  /** All of the range's chunks from its resume point. */
+  /** All of the range's chunks, from its start. */
   total: number
 }
 
 /** How often the targets are read again from the database. */
 const REFRESH_MS = 2000
+/** How often the spool's size is measured (a stat per file). */
+const SIZE_MS = 30_000
 
 /**
  * Keeps the news server busy ahead of the workers (REBUILD.md, prefetch).
@@ -31,6 +33,8 @@ export class Prefetcher {
   private running = 0
   private refreshedAt = 0
   private stopped = false
+  private spoolBytes = 0
+  private sizedAt = 0
 
   /** One round: refreshes the targets now and then, and puts idle connections to work. */
   async tick() {
@@ -65,7 +69,10 @@ export class Prefetcher {
           await client.group(target.group)
           return client.xoverRaw(span.from, span.to)
         })
+        const existed = await Spool.has(target.id, span)
         await Spool.write(target.id, span, data)
+        if (existed) continue
+        this.spoolBytes += data.length
         const { rows } = await db.rawQuery(
           `UPDATE ranges SET spooled_chunks = spooled_chunks + 1 WHERE id = ? RETURNING spooled_chunks`,
           [target.id]
@@ -94,20 +101,31 @@ export class Prefetcher {
   }
 
   private async readTargets(): Promise<Target[]> {
-    const rows = (q: any) =>
-      q.from('ranges as r').join('groups as g', 'g.id', 'r.group_id').whereNull('r.spooled_at').select('r.id', 'g.name as group', 'r.start_id', 'r.end_id', 'r.next_id')
-    // Leased ranges whose chunks aren't all there: a worker is waiting for them.
+    if (Date.now() - this.sizedAt >= SIZE_MS) {
+      this.sizedAt = Date.now()
+      this.spoolBytes = await Spool.size()
+    }
+    const rows = (q: any) => q.from('ranges as r').join('groups as g', 'g.id', 'r.group_id').select('r.id', 'g.name as group', 'r.start_id', 'r.end_id', 'r.next_id')
+    // Leased ranges, checked against the spool's files whatever spooled_at says: a worker waits for them.
     const leased = await rows(db.query()).where('r.status', 'leased').orderBy('r.leased_at')
-    const [{ leases }] = await db.from('ranges').where('status', 'leased').count('* as leases')
-    const ahead = Math.max(coordinatorConfig.spool.minAhead, coordinatorConfig.spool.aheadPerLease * Number(leases))
-    const room = (await Spool.size()) < coordinatorConfig.spool.maxBytes
-    const planned = room ? await rows(db.query()).where('r.status', 'planned').orderBy([{ column: 'r.priority' }, { column: 'r.id' }]).limit(ahead) : []
+    // Planned ranges ahead: those started already, then new ones up to SPOOL_AHEAD_PER_LEASE per lease.
+    const ahead = Math.max(coordinatorConfig.spool.minAhead, coordinatorConfig.spool.aheadPerLease * leased.length)
+    const started = await rows(db.query()).where('r.status', 'planned').where('r.spooled_chunks', '>', 0).whereNull('r.spooled_at').orderBy([{ column: 'r.priority' }, { column: 'r.id' }])
+    const [{ ready }] = await db.from('ranges').where('status', 'planned').where('spooled_chunks', '>', 0).count('* as ready')
+    const room = this.spoolBytes < coordinatorConfig.spool.maxBytes
+    const fresh = room && Number(ready) < ahead
+      ? await rows(db.query()).where('r.status', 'planned').where('r.spooled_chunks', 0).orderBy([{ column: 'r.priority' }, { column: 'r.id' }]).limit(ahead - Number(ready))
+      : []
     const targets: Target[] = []
-    for (const row of [...leased, ...planned]) {
-      const spans = Spool.chunksOf({ start: Number(row.start_id), end: Number(row.end_id) }, Number(row.next_id))
+    for (const row of [...leased, ...(room ? started : []), ...fresh]) {
+      const start = Number(row.start_id)
+      const end = Number(row.end_id)
+      const total = Spool.chunksOf({ start, end }).length
       const missing: ChunkSpan[] = []
-      for (const span of spans) if (!this.claimed.has(`${row.id}:${span.from}`) && !(await Spool.has(Number(row.id), span))) missing.push(span)
-      targets.push({ id: Number(row.id), group: row.group, missing, total: spans.length })
+      for (const span of Spool.chunksOf({ start, end }, Number(row.next_id))) {
+        if (!this.claimed.has(`${row.id}:${span.from}`) && !(await Spool.has(Number(row.id), span))) missing.push(span)
+      }
+      if (missing.length > 0) targets.push({ id: Number(row.id), group: row.group, missing, total })
     }
     return targets
   }