@pineliner/odb-client 1.1.5 → 1.2.0

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

@@ -0,0 +1,78 @@
+import { FrameReader, FrameWriter, type StreamRequest, type StreamResult } from './protocol'
+
+/**
+ * Persistent socket client for the odblite-socket transport. One connection,
+ * length-prefixed frames, replies correlated by id. Batch many statements into
+ * one `requests[]` so N statements cost one round-trip.
+ *
+ * Bun-only (uses `Bun.connect`). app-router runs on Bun; the HTTP `odblite`
+ * backend remains the universal fallback for non-Bun environments.
+ */
+export interface SocketTarget {
+  unix?: string
+  hostname?: string
+  port?: number
+}
+
+export class SocketClient {
+  private socket: any
+  private reader = new FrameReader()
+  private writer!: FrameWriter
+  private readonly pending = new Map<number, (r: StreamResult[]) => void>()
+  private nextId = 1
+  private ready: Promise<void>
+
+  constructor(private readonly target: SocketTarget) {
+    this.ready = this.connect()
+    // A failed initial connect (e.g. socket not up) surfaces via pipeline()'s
+    // await — don't let the orphaned promise become an unhandled rejection.
+    void this.ready.catch(() => {})
+  }
+
+  private async connect(): Promise<void> {
+    const Bun = (globalThis as any).Bun
+    if (!Bun?.connect) throw new Error('odblite-socket backend requires Bun (Bun.connect)')
+    const opts: any = this.target.unix
+      ? { unix: this.target.unix }
+      : { hostname: this.target.hostname ?? '127.0.0.1', port: this.target.port ?? 8787 }
+    this.socket = await Bun.connect({
+      ...opts,
+      socket: {
+        data: (_s: any, chunk: Buffer) => {
+          for (const frame of this.reader.push(chunk)) {
+            const msg = JSON.parse(frame.toString('utf8')) as { id: number; results: StreamResult[] }
+            const resolve = this.pending.get(msg.id)
+            if (resolve) {
+              this.pending.delete(msg.id)
+              resolve(msg.results)
+            }
+          }
+        },
+        drain: (_s: any) => this.writer.flush(),
+        close: () => {
+          // reconnect lazily on next pipeline()
+          this.socket = undefined
+        },
+      },
+    })
+    this.writer = new FrameWriter(this.socket)
+  }
+
+  async pipeline(tenant: string, requests: StreamRequest[]): Promise<StreamResult[]> {
+    if (!this.socket) {
+      this.ready = this.connect()
+      void this.ready.catch(() => {})
+    }
+    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'))
+    })
+  }
+
+  close(): void {
+    this.socket?.end?.()
+    this.socket = undefined
+  }
+}

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

@@ -0,0 +1,147 @@
+/**
+ * odblite-socket wire protocol (CLIENT side).
+ *
+ * ⚠️ COUPLING: this must stay byte-compatible with the SERVER in
+ * `packages/odb-lite/router_v2/protocol/{hrana,framing}.ts`. They are deliberately
+ * separate copies (the client lib must not import the server engine) — same rule
+ * as the /ext test-service mirror: change one wire shape, change the other.
+ *
+ * Transport: `[u32 LE length][utf8 JSON]` frames over a unix socket / TCP. Each
+ * request is `{ id, tenant, requests }`; the reply is `{ id, results }`. The
+ * payload stays JSON on purpose (native JSON.parse beats a hand-rolled JS codec;
+ * a binary payload only pays off remote, via a native codec).
+ */
+
+// ── value encoding (64-bit-safe: integers travel as strings) ──────────────────
+export type HranaValue =
+  | { type: 'null' }
+  | { type: 'integer'; value: string }
+  | { type: 'float'; value: number }
+  | { type: 'text'; value: string }
+  | { type: 'blob'; base64: string }
+
+export function toHrana(v: any): HranaValue {
+  if (v === null || v === undefined) return { type: 'null' }
+  if (typeof v === 'bigint') return { type: 'integer', value: v.toString() }
+  if (typeof v === 'number') return Number.isInteger(v) ? { type: 'integer', value: String(v) } : { type: 'float', value: v }
+  if (typeof v === 'string') return { type: 'text', value: v }
+  if (v instanceof Uint8Array) return { type: 'blob', base64: Buffer.from(v).toString('base64') }
+  if (typeof v === 'boolean') return { type: 'integer', value: v ? '1' : '0' }
+  return { type: 'text', value: String(v) }
+}
+
+export function fromHrana(v: HranaValue): any {
+  switch (v.type) {
+    case 'null':
+      return null
+    case 'integer': {
+      const n = Number(v.value)
+      return Number.isSafeInteger(n) ? n : BigInt(v.value)
+    }
+    case 'float':
+      return v.value
+    case 'text':
+      return v.value
+    case 'blob':
+      return new Uint8Array(Buffer.from(v.base64, 'base64'))
+  }
+}
+
+// ── message types ─────────────────────────────────────────────────────────────
+export interface Stmt {
+  sql?: string
+  args?: HranaValue[]
+  named_args?: { name: string; value: HranaValue }[]
+  want_rows?: boolean
+}
+export type BatchCond =
+  | { type: 'ok'; step: number }
+  | { type: 'error'; step: number }
+  | { type: 'not'; cond: BatchCond }
+  | { type: 'and'; conds: BatchCond[] }
+  | { type: 'or'; conds: BatchCond[] }
+  | { type: 'is_autocommit' }
+export interface BatchStep {
+  condition?: BatchCond | null
+  stmt: Stmt
+  expect?: { affected: 'one' | 'atLeastOne' | number }
+}
+export interface Batch {
+  steps: BatchStep[]
+}
+export interface StmtResult {
+  cols: { name: string | null }[]
+  rows: HranaValue[][]
+  affected_row_count: number
+  last_insert_rowid: string | null
+}
+export interface BatchResult {
+  step_results: (StmtResult | null)[]
+  step_errors: ({ message: string; code?: string } | null)[]
+}
+export interface HranaError {
+  message: string
+  code?: string
+}
+export type StreamRequest =
+  | { type: 'execute'; stmt: Stmt }
+  | { type: 'batch'; batch: Batch }
+  | { type: 'sequence'; sql: string }
+  | { type: 'get_autocommit' }
+  | { type: 'close' }
+export type StreamResult =
+  | { type: 'ok'; response: any }
+  | { type: 'error'; error: HranaError }
+
+// ── guarded-batch helper (the §8g atomic primitive) ───────────────────────────
+export interface AtomicStep {
+  sql: string
+  params?: any[]
+  expect?: 'one' | 'atLeastOne' | number
+}
+export function toBatch(steps: AtomicStep[]): Batch {
+  return {
+    steps: steps.map((s, i) => ({
+      condition: i === 0 ? undefined : { type: 'ok', step: i - 1 },
+      stmt: { sql: s.sql, args: (s.params ?? []).map(toHrana) },
+      expect: s.expect ? { affected: s.expect } : undefined,
+    })),
+  }
+}
+
+// ── length-prefixed framing with backpressure-safe writes ─────────────────────
+interface Writable {
+  write(data: Uint8Array): number
+}
+export class FrameWriter {
+  private pending: Buffer = Buffer.alloc(0)
+  constructor(private readonly socket: Writable) {}
+  send(payload: Buffer): void {
+    const header = Buffer.allocUnsafe(4)
+    header.writeUInt32LE(payload.length, 0)
+    const frame = Buffer.concat([header, payload])
+    this.pending = this.pending.length ? Buffer.concat([this.pending, frame]) : frame
+    this.flush()
+  }
+  flush(): void {
+    while (this.pending.length > 0) {
+      const n = this.socket.write(this.pending)
+      if (n <= 0) return // backpressured — drain() re-calls flush()
+      this.pending = n < this.pending.length ? this.pending.subarray(n) : Buffer.alloc(0)
+    }
+  }
+}
+export class FrameReader {
+  private buf: Buffer = Buffer.alloc(0)
+  push(chunk: Buffer): Buffer[] {
+    this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk
+    const out: Buffer[] = []
+    while (this.buf.length >= 4) {
+      const len = this.buf.readUInt32LE(0)
+      if (this.buf.length < 4 + len) break
+      out.push(this.buf.subarray(4, 4 + len))
+      this.buf = this.buf.subarray(4 + len)
+    }
+    return out
+  }
+}

package/src/database/manager.ts

@@ -9,6 +9,7 @@ import type {
 import { BunSQLiteAdapter } from './adapters/bun-sqlite'
 import { LibSQLAdapter } from './adapters/libsql'
 import { ODBLiteAdapter } from './adapters/odblite'
+import { OdbliteSocketAdapter, OdbliteAutoAdapter } from './adapters/odblite-socket'
 import { parseSQL } from './sql-parser'
 import fs from 'node:fs'
 
@@ -67,7 +68,17 @@ export class DatabaseManager {
         if (!config.odblite) {
           throw new Error('odblite config required for odblite backend')
         }
-        this.adapter = new ODBLiteAdapter(config.odblite)
+        // Autodetect, zero-config: prefer the router_v2 socket if it's reachable
+        // (convention path / ODB_SOCKET, or config.odbliteSocket override), else
+        // HTTP. App config is unchanged — start the socket server and it upgrades.
+        this.adapter = new OdbliteAutoAdapter({ socket: config.odbliteSocket, http: config.odblite })
+        break
+
+      case 'odblite-socket':
+        if (!config.odbliteSocket) {
+          throw new Error('odbliteSocket config required for odblite-socket backend')
+        }
+        this.adapter = new OdbliteSocketAdapter(config.odbliteSocket)
         break
 
       default:
@@ -308,6 +319,13 @@ export class DatabaseManager {
           ...this.config.odblite
         }
 
+      case 'odblite-socket':
+        return {
+          databaseName: name,
+          databaseHash: name,
+          ...this.config.odbliteSocket
+        }
+
       default:
         throw new Error(`Unknown backend: ${this.config.backend}`)
     }

package/src/database/types.ts

@@ -14,7 +14,7 @@ export type TenancyMode =
 /**
  * Backend database types
  */
-export type BackendType = 'bun-sqlite' | 'libsql' | 'odblite'
+export type BackendType = 'bun-sqlite' | 'libsql' | 'odblite' | 'odblite-socket'
 
 /**
  * Query result from any backend
@@ -161,6 +161,13 @@ export interface DatabaseManagerConfig {
     nodeId?: string  // Optional: specific node to create databases on (server selects if not provided)
   }
 
+  // router_v2 raw-socket transport (the fast path; Bun-only). One of unix OR host:port.
+  odbliteSocket?: {
+    unix?: string        // unix socket path, e.g. /tmp/odblite-v2.sock
+    hostname?: string    // or TCP host (cross-container Docker)
+    port?: number        // and TCP port
+  }
+
   // Connection pooling
   connectionPoolSize?: number // Max connections per database (default: 10)
 }