@pineliner/odb-client 1.2.0 → 1.5.0

package/src/database/adapters/socket/client.ts

@@ -7,6 +7,11 @@ import { FrameReader, FrameWriter, type StreamRequest, type StreamResult } from
  *
  * Bun-only (uses `Bun.connect`). app-router runs on Bun; the HTTP `odblite`
  * backend remains the universal fallback for non-Bun environments.
+ *
+ * Liveness invariant: an in-flight request must ALWAYS terminate. If the
+ * connection drops (close/error) or a reply never arrives, the pending promise
+ * is REJECTED — never left hanging. A hung pending request would wedge the
+ * caller's transaction, hold its write lane, and cascade into a 30s timeout.
  */
 export interface SocketTarget {
   unix?: string
@@ -14,12 +19,32 @@ export interface SocketTarget {
   port?: number
 }
 
+// Backstop: a request that gets neither a reply nor a disconnect (server wedged on
+// it) is rejected after this long, so the caller fails fast + can retry rather than
+// hang forever. Generous by default; tune via ODB_SOCKET_REQUEST_TIMEOUT_MS.
+const REQUEST_TIMEOUT_MS = Number((globalThis as any).process?.env?.ODB_SOCKET_REQUEST_TIMEOUT_MS) || 30000
+
+// Auto-reconnect: when the socket is down (router restarting), retry the CONNECT with
+// backoff so a request that lands during the restart window waits it out instead of
+// failing — a redeploy/restart becomes transparent. Bounded so a truly-dead server
+// still fails the request (caller retries / falls back to HTTP) rather than hanging.
+const RECONNECT_ATTEMPTS = Number((globalThis as any).process?.env?.ODB_SOCKET_RECONNECT_ATTEMPTS) || 6
+const RECONNECT_BASE_MS = Number((globalThis as any).process?.env?.ODB_SOCKET_RECONNECT_BASE_MS) || 50
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+interface Pending {
+  resolve: (r: StreamResult[]) => void
+  reject: (e: any) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
 export class SocketClient {
   private socket: any
   private reader = new FrameReader()
   private writer!: FrameWriter
-  private readonly pending = new Map<number, (r: StreamResult[]) => void>()
+  private readonly pending = new Map<number, Pending>()
   private nextId = 1
+  private nextStreamId = 1
   private ready: Promise<void>
 
   constructor(private readonly target: SocketTarget) {
@@ -29,6 +54,16 @@ export class SocketClient {
     void this.ready.catch(() => {})
   }
 
+  /** Reject + clear every in-flight request — called on disconnect/error/close so a
+   *  dropped connection FAILS its requests (the caller retries) instead of hanging. */
+  private failPending(err: Error): void {
+    for (const p of this.pending.values()) {
+      clearTimeout(p.timer)
+      p.reject(err)
+    }
+    this.pending.clear()
+  }
+
   private async connect(): Promise<void> {
     const Bun = (globalThis as any).Bun
     if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)')
@@ -38,41 +73,104 @@ export class SocketClient {
     this.socket = await Bun.connect({
       ...opts,
       socket: {
-        data: (_s: any, chunk: Buffer) => {
-          for (const frame of this.reader.push(chunk)) {
+        data: (s: any, chunk: Buffer) => {
+          // A framing error (oversized/corrupt length prefix from a buggy/hostile server) makes the byte
+          // stream unrecoverable — drop the connection and fail in-flight requests, exactly like a close.
+          // Without this the throw escapes the Bun `data` callback uncaught.
+          let frames: Buffer[]
+          try {
+            frames = this.reader.push(chunk)
+          } catch (err: any) {
+            this.socket = undefined
+            this.reader = new FrameReader()
+            try {
+              s.end?.()
+            } catch {}
+            this.failPending(err instanceof Error ? err : new Error(`odblite framing error: ${err}`))
+            return
+          }
+          for (const frame of frames) {
             const msg = JSON.parse(frame.toString('utf8')) as { id: number; results: StreamResult[] }
-            const resolve = this.pending.get(msg.id)
-            if (resolve) {
+            const p = this.pending.get(msg.id)
+            if (p) {
               this.pending.delete(msg.id)
-              resolve(msg.results)
+              clearTimeout(p.timer)
+              p.resolve(msg.results)
             }
           }
         },
         drain: (_s: any) => this.writer.flush(),
         close: () => {
-          // reconnect lazily on next pipeline()
+          // Connection gone → reconnect lazily on next pipeline(). A half-read frame
+          // in the buffer is invalid now, and EVERY in-flight request must fail (not
+          // hang) so its caller's transaction unwinds + releases the write lane.
+          this.socket = undefined
+          this.reader = new FrameReader()
+          this.failPending(new Error('odblite socket disconnected — request not completed'))
+        },
+        error: (_s: any, err: any) => {
           this.socket = undefined
+          this.reader = new FrameReader()
+          this.failPending(err instanceof Error ? err : new Error(`odblite socket error: ${err}`))
         },
       },
     })
     this.writer = new FrameWriter(this.socket)
   }
 
-  async pipeline(tenant: string, requests: StreamRequest[]): Promise<StreamResult[]> {
+  /** Reconnect with bounded backoff — bridges a router restart so a request landing in the down-window
+   *  waits it out instead of failing. After the last attempt the error propagates (caller retries / the
+   *  auto-adapter can fall back to HTTP). Backoff: 50·100·200·400·800·1600ms ≈ 3s total by default. */
+  private async connectWithRetry(): Promise<void> {
+    let lastErr: any
+    for (let attempt = 0; attempt < RECONNECT_ATTEMPTS; attempt++) {
+      try {
+        await this.connect()
+        return
+      } catch (err) {
+        lastErr = err
+        if (attempt < RECONNECT_ATTEMPTS - 1) await sleep(RECONNECT_BASE_MS * 2 ** attempt)
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(`odblite socket reconnect failed: ${lastErr}`)
+  }
+
+  /** Allocate a fresh stream id for an interactive transaction (unique per connection). The server
+   *  pins one SQLite connection per stream id, so all of a tx's statements run on it (read-your-own-
+   *  writes). The id is carried in every frame of that tx via pipeline()'s `stream` arg. */
+  allocStream(): number {
+    return this.nextStreamId++
+  }
+
+  async pipeline(tenant: string, requests: StreamRequest[], stream?: number): Promise<StreamResult[]> {
+    // Await the in-flight connect FIRST — only reconnect if it's actually gone
+    // (closed/failed). Checking `!this.socket` before awaiting would start a
+    // second connect while the first is still resolving (a leaked connection).
+    await this.ready.catch(() => {}) // a prior failed connect must not poison this await; we re-check below
     if (!this.socket) {
-      this.ready = this.connect()
+      // Reconnect with backoff (bridges a restart). Shared promise so concurrent pipeline() callers
+      // ride ONE reconnect, not N. If it ultimately fails, every caller rejects (then retries / HTTP).
+      this.ready = this.connectWithRetry()
       void this.ready.catch(() => {})
+      await this.ready
     }
-    await this.ready
     const id = this.nextId++
-    return new Promise<StreamResult[]>((resolve) => {
-      this.pending.set(id, resolve)
-      this.writer.send(Buffer.from(JSON.stringify({ id, tenant, requests }), 'utf8'))
+    return new Promise<StreamResult[]>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        // No reply AND no disconnect (server wedged) → reject so we never hang forever.
+        if (this.pending.delete(id)) reject(new Error(`odblite socket request ${id} timed out after ${REQUEST_TIMEOUT_MS}ms`))
+      }, REQUEST_TIMEOUT_MS)
+      ;(timer as any).unref?.()
+      this.pending.set(id, { resolve, reject, timer })
+      // `stream` present → the server routes this frame to that interactive tx's pinned connection.
+      const payload = stream != null ? { id, tenant, stream, requests } : { id, tenant, requests }
+      this.writer.send(Buffer.from(JSON.stringify(payload), 'utf8'))
     })
   }
 
   close(): void {
     this.socket?.end?.()
     this.socket = undefined
+    this.failPending(new Error('odblite socket closed'))
   }
 }

package/src/database/adapters/socket/protocol.ts

@@ -88,6 +88,7 @@ export type StreamRequest =
   | { type: 'batch'; batch: Batch }
   | { type: 'sequence'; sql: string }
   | { type: 'get_autocommit' }
+  | { type: 'get_version' } // connect-time wire-protocol handshake
   | { type: 'close' }
 export type StreamResult =
   | { type: 'ok'; response: any }
@@ -109,6 +110,15 @@ export function toBatch(steps: AtomicStep[]): Batch {
   }
 }
 
+// ── SQL classification (client-side heuristic) ────────────────────────────────
+// Mirrors router_v2/engine/sql-kind.ts (kept in lockstep, like the wire types).
+// The SERVER is authoritative (it checks the prepared statement's column count);
+// this only picks the `sql``` convenience tag's shape before the round-trip.
+const READ_ONLY_RE = /^\s*(?:SELECT|EXPLAIN|VALUES)\b/i
+export function mightReturnRows(sql: string): boolean {
+  return READ_ONLY_RE.test(sql) || /\bRETURNING\b/i.test(sql)
+}
+
 // ── length-prefixed framing with backpressure-safe writes ─────────────────────
 interface Writable {
   write(data: Uint8Array): number
@@ -131,6 +141,10 @@ export class FrameWriter {
     }
   }
 }
+// Reject an insane length prefix instead of buffering gigabytes for bytes that never arrive — a buggy or
+// hostile server shouldn't be able to OOM the client inside the Bun `data` callback. Matches the router's
+// frame cap; tune via ODB_MAX_FRAME_MB.
+const MAX_FRAME = (Number((globalThis as any).process?.env?.ODB_MAX_FRAME_MB) || 64) * 1024 * 1024
 export class FrameReader {
   private buf: Buffer = Buffer.alloc(0)
   push(chunk: Buffer): Buffer[] {
@@ -138,6 +152,7 @@ export class FrameReader {
     const out: Buffer[] = []
     while (this.buf.length >= 4) {
       const len = this.buf.readUInt32LE(0)
+      if (len > MAX_FRAME) throw new Error(`odblite reply frame too large: ${len} bytes (max ${MAX_FRAME})`)
       if (this.buf.length < 4 + len) break
       out.push(this.buf.subarray(4, 4 + len))
       this.buf = this.buf.subarray(4 + len)