@preventive/triage 1.0.0-alpha.18 → 1.0.0-alpha.19

package/server-e2e/lifecycle.ts

@@ -1,207 +1,94 @@
-// Process lifecycle: the in-flight request tracker, the `shuttingDown`
-// gate, the graceful-shutdown choreography, and the signal / error /
-// uncaught-exception handlers that drive it. Two-phase so the bits the
-// HTTP + WS planes need (`track`, `isShuttingDown`) exist BEFORE those
-// servers are built, while the teardown is `install()`ed afterward —
-// once the server objects, heartbeat timer, and reaper exist.
-
+// Per-instance request tracking and graceful disposal. Process shutdown belongs
+// to the standalone launcher; embedded hosts retain their signals and errors.
 import type { Server } from 'node:http'
 import type { WebSocketServer } from 'ws'
 import type { SseSession } from './sse-session.ts'
-import { errStack } from './util.ts'
 
 export type ShutdownDeps = {
   httpServer: Server
   wss: WebSocketServer
   heartbeatTimer: ReturnType<typeof setInterval>
-  // The SSE keepalive-sweep timer (server-e2e/sse-server.ts). Cleared on
-  // shutdown alongside `heartbeatTimer` so a tick can't write a keepalive
-  // comment to a session the close loop below is already tearing down.
   sseKeepaliveTimer: ReturnType<typeof setInterval>
-  // Stops the periodic reaper AND awaits any in-flight sweep.
   stopReaper: () => Promise<void>
-  // Live SSE+POST session iterator (mirrors `wss.clients` for the SSE
-  // fallback transport). Walked alongside `wss.clients` to send the
-  // 1001 close frame and apply the terminate-grace timer to both
-  // transports uniformly.
   sseSessions: () => Iterable<SseSession>
-  // App-specific teardown, run AFTER the in-flight drain: close the DB.
-  // Swallows its own errors (a failed close shouldn't abort the exit).
   closeDb: () => Promise<void>
 }
 
 export type Lifecycle = {
-  // Collects in-flight async handlers so `shutdown` can drain them
-  // before closing the DB. Passed to the HTTP + WS planes.
   track: (promise: Promise<unknown>) => void
-  // Read by the REST shutdown gate + the WS message loop to drop new
-  // work once teardown began.
   isShuttingDown: () => boolean
-  // Wire the graceful shutdown + the error / signal / process-catchall
-  // handlers. Call once, after the server objects exist.
   install: (deps: ShutdownDeps) => void
 }
 
+function closePeers({ wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    try { peer.close(1001, 'Server shutting down') } catch {}
+  }
+}
+
+function terminatePeers({ httpServer, wss, sseSessions }: ShutdownDeps): void {
+  for (const peer of [...wss.clients, ...sseSessions()]) {
+    if (peer.readyState === peer.OPEN || peer.readyState === peer.CLOSING) {
+      try { peer.terminate() } catch {}
+    }
+  }
+  httpServer.closeAllConnections()
+}
+
+async function drain(deps: ShutdownDeps, inFlight: Set<Promise<unknown>>): Promise<void> {
+  const { httpServer, wss, stopReaper, closeDb } = deps
+  // Bound unresponsive WS/SSE peers and HTTP keep-alives to a one-second
+  // grace period. Also works when the listeners are mounted on another host.
+  const terminateTimer = setTimeout(() => terminatePeers(deps), 1000)
+  terminateTimer.unref()
+  try {
+    await stopReaper()
+    httpServer.closeIdleConnections()
+    if (httpServer.listening) {
+      await new Promise<void>(resolve => { httpServer.close(() => resolve()) })
+    }
+    await new Promise<void>(resolve => { wss.close(() => resolve()) })
+    if (inFlight.size > 0) await Promise.allSettled([...inFlight])
+  } finally {
+    clearTimeout(terminateTimer)
+    await closeDb()
+  }
+}
+
 export function createLifecycle(): Lifecycle {
-  // In-flight async message handlers. `shutdown` awaits this set before
-  // closing the DB so a SIGINT mid-save can't resume against a closed
-  // handle (which would throw inside the commit's gated INSERT after
-  // the client believed its save was committed).
   const inFlight = new Set<Promise<unknown>>()
   function track(promise: Promise<unknown>): void {
     inFlight.add(promise)
-    // Trailing `.catch(() => {})` swallows the rejection that `.finally`
-    // propagates through its returned promise — without it, a tracked
-    // handler that rejects (or whose caller's catch handler itself
-    // throws) trips the `unhandledRejection` catchall below and crashes
-    // the process via `fireShutdown(1)`.
     promise.finally(() => inFlight.delete(promise)).catch(() => {})
   }
   let shuttingDown = false
-  // Live exit code the in-progress shutdown will pass to `process.exit`.
-  // Re-entry can ESCALATE it from 0 → 1 (e.g. a `wss.error` firing
-  // during a SIGTERM-driven graceful shutdown shouldn't leave the
-  // launcher seeing a clean exit code) but can never DE-escalate.
-  // Audit round-13.
-  let pendingExitCode = 0
 
   function install(deps: ShutdownDeps): void {
-    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer, stopReaper, sseSessions, closeDb } = deps
-
-    async function shutdown(exitCode: number = 0): Promise<void> {
-      // Re-entry: don't restart the teardown, but escalate the pending
-      // exit code if the new caller is non-zero (e.g. a wss.error during
-      // a SIGTERM-driven graceful shutdown). Without this, an error
-      // arriving mid-shutdown would silently exit 0 and the launcher
-      // would record a clean stop.
-      if (shuttingDown) {
-        if (exitCode !== 0 && pendingExitCode === 0) pendingExitCode = exitCode
-        return
-      }
-      shuttingDown = true
-      pendingExitCode = exitCode
-      console.log('Shutting down…')
-      // Stop both periodic timers (WS heartbeat + SSE keepalive) so neither
-      // fires mid-shutdown against a peer the close-loop is tearing down.
-      for (const timer of [heartbeatTimer, sseKeepaliveTimer]) clearInterval(timer)
-      // Send a 1001 (going away) close frame to every open socket BEFORE
-      // shutting the listener. Lets clients distinguish a server-initiated
-      // graceful shutdown from a network drop, so they can skip their
-      // reconnect backoff. Fire-and-forget — `process.exit` below would
-      // force-kill any in-progress flush anyway. `try/catch` shrugs at
-      // sockets already in CLOSING / CLOSED.
-      for (const socket of wss.clients) {
-        try { socket.close(1001, 'Server shutting down') } catch {}
+    const { httpServer, wss, heartbeatTimer, sseKeepaliveTimer } = deps
+    let disposal: Promise<void> | undefined
+    function dispose(): Promise<void> {
+      if (!disposal) {
+        shuttingDown = true
+        clearInterval(heartbeatTimer)
+        clearInterval(sseKeepaliveTimer)
+        // Store the promise before any close/error callback can re-enter.
+        disposal = Promise.resolve().then(() => drain(deps, inFlight)).finally(() => {
+          httpServer.off('close', onClose)
+          httpServer.off('error', onClose)
+          wss.off('error', onWsError)
+        })
+        closePeers(deps)
       }
-      // Same close frame on every SSE+POST session — the adapter
-      // translates `close(1001, …)` into a structured `event: close`
-      // record on the SSE stream so the client transport can read the
-      // code and skip its reconnect backoff (parity with the WS path).
-      for (const session of sseSessions()) {
-        try { session.close(1001, 'Server shutting down') } catch {}
-      }
-      // Force-terminate any client that doesn't ack the close frame
-      // within a short grace window. `wss.close()` waits for every client
-      // to emit `'close'`, and `ws` only TCP-RSTs unresponsive peers
-      // after its own ~30 s `closeTimeout`. A single dead/blackholed peer
-      // would otherwise stretch SIGTERM/SIGINT response by that full
-      // timeout. Audit round-11.
-      const TERMINATE_GRACE_MS = 1_000
-      const terminateTimer = setTimeout(() => {
-        for (const socket of wss.clients) {
-          const rs = socket.readyState
-          if (rs === socket.OPEN || rs === socket.CLOSING) {
-            try { socket.terminate() } catch {}
-          }
-        }
-        // SSE sessions are tracked separately from `wss.clients`; apply
-        // the same terminate-grace policy so a stranded SSE response
-        // can't pin the HTTP keep-alive shutdown branch below.
-        for (const session of sseSessions()) {
-          const rs = session.readyState
-          if (rs === session.OPEN || rs === session.CLOSING) {
-            try { session.terminate() } catch {}
-          }
-        }
-        // Same grace for HTTP keep-alive sockets that didn't respect the
-        // `Connection: close` hint, which would otherwise hold
-        // `httpServer.close()` until their TCP timeout.
-        try { httpServer.closeAllConnections() } catch {}
-      }, TERMINATE_GRACE_MS)
-      // Don't keep the event loop alive solely for the grace timer.
-      terminateTimer.unref?.()
-      // Stop the periodic reaper AND wait for any in-flight sweep (incl.
-      // the startup sweep) before the DB close — otherwise a
-      // readdir / unlink would race a closed DB.
-      await stopReaper()
-      // Free idle HTTP keep-alive sockets up front so close() below
-      // doesn't wait on them. Active in-flight requests still finish.
-      try { httpServer.closeIdleConnections() } catch {}
-      // Close http.Server first to stop accepting new upgrades + HTTP
-      // requests. Guard with `.listening` because `close()` throws
-      // ERR_SERVER_NOT_RUNNING when bind never succeeded (the http error
-      // handler is the path that invoked shutdown in that case).
-      if (httpServer.listening) {
-        await new Promise<void>((resolve) => { httpServer.close(() => resolve()) })
-      }
-      await new Promise<void>((resolve) => { wss.close(() => resolve()) })
-      clearTimeout(terminateTimer)
-      // Drain in-flight handlers so a save that's mid-pipeline finishes
-      // its commit before the DB closes. `handleSave` splits its
-      // canonical/id/dup-precheck/verify/commit work across awaits, so
-      // the window spans several yield points. `Promise.allSettled` so a
-      // single handler rejection doesn't abort the drain.
-      if (inFlight.size > 0) await Promise.allSettled([...inFlight])
-      // App teardown AFTER the drain: close the DB.
-      await closeDb()
-      // Read `pendingExitCode` (not the parameter) so a re-entrant
-      // `shutdown(1)` that landed during the drain wins over the original
-      // `shutdown(0)`. See round-13 escalation note.
-      process.exit(pendingExitCode)
+      return disposal
     }
-
-    // `.catch` defends against an unguarded `await` slipping into
-    // `shutdown`: an unhandled rejection there would skip the non-zero
-    // exit the launcher relies on.
-    function fireShutdown(code: number): void {
-      shutdown(code).catch((err) => {
-        console.warn('shutdown error:', errStack(err))
-        process.exit(code === 0 ? 1 : code)
-      })
+    function onClose(): void {
+      void dispose().catch(err => { console.error('Server cleanup failed:', err) })
     }
-
-    // Route bind / post-listen failures through `shutdown` so the
-    // in-flight drain + DB close still run before exit. Without this,
-    // `ws` re-emits the error as uncaughtException and the launcher sees
-    // a confusing crash rather than the bind failure. Audit round-9 M2.
-    httpServer.on('error', (err: Error) => {
-      console.error('Server error:', errStack(err))
-      fireShutdown(1)
-    })
-    // Symmetric with the http.Server error handler — route through
-    // `fireShutdown(1)` so the launcher sees a non-zero exit, and the
-    // re-entry escalation bumps `pendingExitCode` 0 → 1 for a `wss.error`
-    // arriving mid-graceful-SIGTERM.
-    wss.on('error', (err: Error) => {
-      console.error('WS server error:', errStack(err))
-      fireShutdown(1)
-    })
-    // Wrap signal handlers so the signal name (the listener's first arg)
-    // doesn't bleed into shutdown's `exitCode`.
-    process.on('SIGINT', () => fireShutdown(0))
-    process.on('SIGTERM', () => fireShutdown(0))
-    // Process-level catchalls so a stray rejection / uncaught exception
-    // doesn't bypass `shutdown()` — Node 20+ exits on unhandled
-    // rejection, which would skip the drain + DB close. Log forensically
-    // and route through `fireShutdown(1)`. Audit round-11 observability.
-    process.on('unhandledRejection', (reason) => {
-      console.error('Unhandled rejection:', errStack(reason))
-      fireShutdown(1)
-    })
-    process.on('uncaughtException', (err) => {
-      console.error('Uncaught exception:', errStack(err))
-      fireShutdown(1)
-    })
+    function onWsError(err: Error): void { httpServer.emit('error', err) }
+    httpServer[Symbol.asyncDispose] = dispose
+    httpServer.once('close', onClose)
+    httpServer.on('error', onClose)
+    wss.on('error', onWsError)
   }
 
   return { track, isShuttingDown: () => shuttingDown, install }

package/server-e2e/neon-driver.ts

@@ -13,10 +13,10 @@
 // so the absent peer dep is never loaded under test.
 //
 // In production the wrapper is only ever imported on the Neon path
-// (`DATABASE_URL` set), where the operator has installed the peer dep
+// (an e2e database URL set), where the operator has installed the peer dep
 // (`pnpm add @neondatabase/serverless`) so the re-export resolves. A
 // SQLite-only deploy never imports this module — the dynamic `import()`
-// sites are gated behind the `DATABASE_URL` branch in `index.ts`.
+// sites are gated behind the configured database URL branch in `index.ts`.
 //
 // `@ts-ignore` rather than `@ts-expect-error`: when the peer dep IS
 // installed the specifier resolves and tsc sees a real type, which

package/server-e2e/npm-proxy.ts

@@ -25,37 +25,23 @@
 //
 // Outbound fetch carries an `AbortController` so a hung upstream
 // (slow-loris response, TLS stall) tears down after
-// `UPSTREAM_TIMEOUT_MS`, and a client that closes its connection
+// `NPM_ADVISORIES_TIMEOUT_MS`, and a client that closes its connection
 // mid-fetch propagates an abort through the same controller — so a
 // stranded in-flight call doesn't block SIGTERM drain.
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { Buffer } from 'node:buffer'
 import { errStack } from './util.ts'
+import { NPM_ADVISORIES_TIMEOUT_MS, fetchNpmAdvisories } from '../server-common/npm-advisories.ts'
 
 type HasHeaders = { headers: IncomingMessage['headers'] }
 
 export const NPM_ADVISORIES_PATH = '/api/npm-advisories'
-const UPSTREAM_URL = 'https://registry.npmjs.org/-/npm/v1/security/advisories/bulk'
-
 // 1 MiB is generous: the bulk endpoint accepts `{ packageName:
 // [versions] }` maps, and even a bundle with thousands of pinned
 // versions serialises to well under this. Anything bigger is almost
 // certainly malformed input or a probe.
 const REQUEST_BODY_LIMIT = 1 * 1024 * 1024
-// 4 MiB caps the upstream response. The advisories endpoint
-// returns at most a few CVEs per package, so even a bundle with
-// hundreds of affected packages comes in well under this — a
-// runaway / hostile upstream gets cut off before we burn arbitrary
-// memory buffering it.
-const RESPONSE_BODY_LIMIT = 4 * 1024 * 1024
-// Hard deadline on the upstream call. The bulk endpoint typically
-// answers in well under a second; 30 s leaves plenty of headroom
-// for a slow path but caps a hung TLS / slow-loris connection so
-// a stranded fetch can't pin the inflight slot through SIGTERM
-// drain. Triggered via AbortController.
-const UPSTREAM_TIMEOUT_MS = 30_000
-
 export type NpmProxyDeps = {
   debug: boolean
 }
@@ -129,11 +115,12 @@ function deny(res: ServerResponse, status: number, reason: string): void {
 // Same shape as `deny` but for the richer multi-field envelopes
 // (upstream-not-json / upstream-too-large) — these can't reuse
 // `deny` because the body carries more than `{ error }`.
-function writeJsonEnvelope(res: ServerResponse, status: number, body: object): void {
+function writeJsonEnvelope(res: ServerResponse, status: number, body: unknown): void {
   if (!canWrite(res)) return
   try {
-    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
-    res.end(JSON.stringify(body))
+    const out = JSON.stringify(body)
+    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'content-length': Buffer.byteLength(out) })
+    res.end(out)
   } catch {}
 }
 
@@ -162,7 +149,7 @@ export async function handleNpmAdvisories(
   if (req.method !== 'POST') { deny(res, 405, 'method-not-allowed'); return }
   // Single controller drives both the upstream deadline timer AND
   // the client-disconnect propagation: a fetch hung past
-  // UPSTREAM_TIMEOUT_MS and a browser tab closed mid-fetch both end
+  // NPM_ADVISORIES_TIMEOUT_MS and a browser tab closed mid-fetch both end
   // up aborting the same signal, which undici threads through into
   // the body reader. Without this the inflight slot pinned by
   // `track()` could outlive both a dead client and a wedged
@@ -187,7 +174,7 @@ export async function handleNpmAdvisories(
   // doesn't fire a no-op abort — itself a no-op on a settled
   // controller, but skipping the log noise.)
   const controller = new AbortController()
-  const timer = setTimeout(() => { try { controller.abort() } catch {} }, UPSTREAM_TIMEOUT_MS)
+  const timer = setTimeout(() => { try { controller.abort() } catch {} }, NPM_ADVISORIES_TIMEOUT_MS)
   const onResClose = (): void => {
     if (!res.writableEnded) controller.abort()
   }
@@ -219,130 +206,10 @@ export async function handleNpmAdvisories(
       try { req.destroy() } catch {}
       return
     }
-    await handleNpmAdvisoriesInner(deps, body, res, controller.signal)
+    const result = await fetchNpmAdvisories(body, controller.signal, deps.debug)
+    writeJsonEnvelope(res, result.status, result.body)
   } finally {
     clearTimeout(timer)
     res.off('close', onResClose)
   }
 }
-
-async function handleNpmAdvisoriesInner(
-  deps: NpmProxyDeps,
-  body: Buffer,
-  res: ServerResponse,
-  signal: AbortSignal,
-): Promise<void> {
-  let upstream: Response
-  try {
-    upstream = await fetch(UPSTREAM_URL, {
-      method: 'POST',
-      // Force JSON — the bulk endpoint requires it. Drop every
-      // client-supplied header to keep an upstream fingerprint from
-      // leaking through (cookies, auth, custom UA, ...). The
-      // registry's bulk endpoint doesn't need any of them for a
-      // public lookup.
-      headers: { 'content-type': 'application/json', 'accept': 'application/json' },
-      // Re-wrap as a plain Uint8Array — Buffer's underlying
-      // ArrayBufferLike type doesn't satisfy fetch's BodyInit
-      // narrowing (it can't statically rule out SharedArrayBuffer),
-      // but a copy through Uint8Array is zero-cost in practice and
-      // unambiguously typed.
-      body: new Uint8Array(body),
-      signal,
-    })
-  } catch (err: unknown) {
-    if (deps.debug) console.warn('npm-advisories upstream error:', errStack(err))
-    // Client already gone — `canWrite` (inside `deny`) gates the
-    // write so a destroyed / writableEnded socket doesn't trip
-    // ERR_STREAM_DESTROYED on the way out.
-    deny(res, 502, 'upstream-unreachable')
-    return
-  }
-  // Assert JSON on the upstream body. The Content-Type header is
-  // unreliable (Cloudflare in front of registry.npmjs.org strips it
-  // from some responses; a captive portal / WAF can declare HTML on
-  // a body that's actually JSON or vice-versa), so we don't lean on
-  // it — instead we buffer the body and parse. A successful
-  // JSON.parse is the strongest guarantee we can hand the UI's
-  // `await res.json()`. Buffering is bounded by
-  // `RESPONSE_BODY_LIMIT`; the advisories endpoint's payloads sit
-  // well under that.
-  const upstreamContentType = upstream.headers.get('content-type') ?? ''
-  let buffered: Buffer | null
-  try {
-    buffered = await readUpstreamBody(upstream)
-  } catch (err: unknown) {
-    if (deps.debug) console.warn('npm-advisories upstream body error:', errStack(err))
-    deny(res, 502, 'upstream-unreachable')
-    return
-  }
-  if (buffered === null) {
-    if (deps.debug) console.warn(`npm-advisories upstream too large: status=${upstream.status}`)
-    writeJsonEnvelope(res, 502, { error: 'upstream-too-large', upstreamStatus: upstream.status })
-    return
-  }
-  // Treat the body as UTF-8 — `JSON.parse` operates on a string and
-  // the registry's responses are always UTF-8 in practice. A
-  // non-UTF-8 byte sequence still decodes (with U+FFFD
-  // substitution); the subsequent JSON.parse fails and routes
-  // through the error branch.
-  const text = buffered.toString('utf8')
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(text)
-  } catch {
-    if (deps.debug) console.warn(`npm-advisories upstream non-JSON: status=${upstream.status} ct=${upstreamContentType || '<none>'} bytes=${buffered.byteLength}`)
-    writeJsonEnvelope(res, 502, {
-      error: 'upstream-not-json',
-      upstreamStatus: upstream.status,
-      upstreamContentType: upstreamContentType || null,
-    })
-    return
-  }
-  if (!canWrite(res)) return
-  // Re-stringify rather than echoing `text` so the wire shape we
-  // emit is canonical (no upstream whitespace / BOM / trailing
-  // junk after the parsed value rides along), and so the client
-  // can rely on a single JSON document per response.
-  const out = JSON.stringify(parsed)
-  try {
-    res.writeHead(upstream.status, {
-      'content-type': 'application/json',
-      'cache-control': 'no-store',
-      'content-length': Buffer.byteLength(out),
-    })
-    res.end(out)
-  } catch {}
-}
-
-// Buffer the upstream response body up to RESPONSE_BODY_LIMIT.
-// Returns null if the cap is exceeded (caller maps to a 502
-// `upstream-too-large`), or the cumulative Buffer otherwise. A
-// transport error mid-read (e.g. AbortSignal fired by the deadline
-// timer or by `req` close) throws — the caller catches it.
-//
-// `finally { reader.cancel() }` is load-bearing on the error and
-// cap-exceeded paths: leaving the reader locked to the body holds
-// the underlying undici TCP socket out of the connection pool until
-// GC, and the cap-exceeded path explicitly needs to tear the
-// transfer down so we don't keep buffering bytes we'll never use.
-// On the clean-drain path (done:true), cancel() is a no-op.
-async function readUpstreamBody(upstream: Response): Promise<Buffer | null> {
-  if (!upstream.body) return Buffer.alloc(0)
-  const reader = upstream.body.getReader()
-  const chunks: Uint8Array[] = []
-  let received = 0
-  try {
-    for (;;) {
-      const { done, value } = await reader.read()
-      if (done) break
-      if (!value) continue
-      received += value.byteLength
-      if (received > RESPONSE_BODY_LIMIT) return null
-      chunks.push(value)
-    }
-    return Buffer.concat(chunks)
-  } finally {
-    try { await reader.cancel() } catch {}
-  }
-}

package/server-e2e/objstore/blob-vercel.ts

@@ -35,108 +35,10 @@
 // any single resource), and the stale-staging TTL sweep drops orphan
 // staging blobs.
 
-import { PassThrough, type Readable } from 'node:stream'
-import { Buffer } from 'node:buffer'
+import { PassThrough } from 'node:stream'
 import type { BlobBackend, OpenLiveResult, StagingWriter } from './blob.ts'
 import { errMsg } from '../util.ts'
-
-// Minimal structural shape of the bits of `@vercel/blob` we use.
-// Kept local so the optional peer dep doesn't have to type-resolve
-// for SQLite-only deployments. Real type details live in the
-// installed package; the fields/parameters we touch here are stable
-// per the SDK v2 public surface.
-//
-// `put` accepts the SDK's full `PutBody` union (string | Readable |
-// Buffer | Blob | ArrayBuffer | ReadableStream | File). We only ever
-// pass a Node `PassThrough` (a Readable), but the wider type lets
-// callers reuse this signature for future buffer/blob bodies without
-// type gymnastics. `copy` accepts `allowOverwrite` — REQUIRED for
-// version bumps since the live pathname is reused on re-upload.
-type VercelBlobBody = Readable | Buffer | string | Blob | ArrayBuffer | ReadableStream<Uint8Array>
-type VercelBlobSdk = {
-  put: (
-    pathname: string,
-    body: VercelBlobBody,
-    options: {
-      access: 'private' | 'public'
-      allowOverwrite?: boolean
-      contentType?: string
-      token?: string
-      multipart?: boolean
-      abortSignal?: AbortSignal
-      cacheControlMaxAge?: number
-    },
-  ) => Promise<{ url: string; pathname: string }>
-  head: (
-    pathname: string,
-    options?: { token?: string; abortSignal?: AbortSignal },
-  ) => Promise<{ size: number; pathname: string; url: string }>
-  get: (
-    pathname: string,
-    options: {
-      access: 'private' | 'public'
-      token?: string
-      useCache?: boolean
-      abortSignal?: AbortSignal
-    },
-  ) => Promise<{
-    statusCode: 200 | 304
-    stream: ReadableStream<Uint8Array> | null
-    blob: { size: number | null }
-  } | null>
-  copy: (
-    fromPathname: string,
-    toPathname: string,
-    options: {
-      access: 'private' | 'public'
-      allowOverwrite?: boolean
-      token?: string
-      contentType?: string
-      cacheControlMaxAge?: number
-    },
-  ) => Promise<{ url: string; pathname: string }>
-  del: (
-    urlOrPathname: string | string[],
-    options?: { token?: string; abortSignal?: AbortSignal },
-  ) => Promise<void>
-  list: (options: {
-    prefix?: string
-    cursor?: string
-    limit?: number
-    mode?: 'expanded' | 'folded'
-    token?: string
-  }) => Promise<{
-    // `uploadedAt` (a Date per the SDK v2 surface) is the blob's
-    // creation time — used by the reaper's GC grace window. Optional
-    // in the type because the `folded` listing path ignores it (only
-    // `listLiveBlobs` reads it, and it uses the default expanded mode).
-    blobs: Array<{ pathname: string; size: number; uploadedAt?: Date | string | number }>
-    folders?: string[]
-    cursor?: string
-    hasMore: boolean
-  }>
-}
-
-// Recognise "blob is gone" errors uniformly across read/write/delete
-// paths so callers can treat them as success (delete) or
-// not-found (read). The SDK exposes BlobNotFoundError as a class with
-// `.name === 'BlobNotFoundError'`; checking the name string avoids
-// importing the class at the top level (which would force the optional
-// peer dep to resolve).
-//
-// Class-name check ONLY — the SDK's internal mapper turns every API
-// `not_found` into BlobNotFoundError-by-name, so a bare-404 transport
-// leak doesn't reach here. A broader `/does not exist|\b404\b/` match
-// is DANGEROUS: it also matches BlobStoreNotFoundError's "This store
-// does not exist.", so a config fault (revoked token, deleted store)
-// would silently surface as every-blob-missing across reads/unlinks,
-// masking the fatal misconfiguration. The tight name check lets
-// BlobStoreNotFoundError / other classes propagate as real exceptions.
-function isNotFound(err: unknown): boolean {
-  if (err == null || typeof err !== 'object') return false
-  const name = (err as { name?: unknown }).name
-  return typeof name === 'string' && name === 'BlobNotFoundError'
-}
+import { type VercelBlobSdk, isNotFound, loadVercelBlobSdk } from '../../server-common/vercel-blob.ts'
 
 function liveBlobPath(tag: string, contentHash: string): string {
   return `${tag}/${contentHash}.bin`
@@ -493,7 +395,7 @@ export type VercelBlobBackendOptions = {
   // Vercel Blob R/W token, typically from BLOB_READ_WRITE_TOKEN.
   // The SDK also reads it from process.env, but passing it
   // explicitly here keeps the env-var → boot config path single-
-  // sourced through server-e2e/index.ts (matches the Neon DATABASE_URL
+  // sourced through server-e2e/index.ts (matches the Neon database URL
   // handling — env-read at boot, threaded as a parameter).
   token: string
   // Test seam: inject a stub of the @vercel/blob module to avoid
@@ -507,7 +409,7 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
   // dep. `@ts-ignore` (not `@ts-expect-error`) so an operator who
   // DOES install `@vercel/blob` doesn't trip TS2578 "unused
   // directive" — same pattern as db-neon.ts.
-  const sdk: VercelBlobSdk = opts.sdk ?? (await loadSdk())
+  const sdk: VercelBlobSdk = opts.sdk ?? (await loadVercelBlobSdk())
   const token = opts.token
   return {
     // No-op: Vercel Blob has no folder concept. The pathname's
@@ -533,9 +435,3 @@ export async function openVercelBlobBackend(opts: VercelBlobBackendOptions): Pro
     listStagingIds: buildListStagingIds(sdk, token, (tag) => `${tag}/.staging/`),
   }
 }
-
-async function loadSdk(): Promise<VercelBlobSdk> {
-  // @ts-ignore optional peer dep: '@vercel/blob'
-  const mod = (await import('@vercel/blob')) as VercelBlobSdk
-  return mod
-}