@reddb-io/client 1.9.0 → 1.10.0

package/src/redwire.js

@@ -1,769 +1,102 @@
 /**
- * RedWire client for Node / Bun / Deno.
+ * RedWire client for Node / Bun / Deno — the node-bound shim over the
+ * transport-agnostic codec.
  *
- * Speaks the binary TCP protocol from
- * `docs/adr/0001-redwire-tcp-protocol.md` directly — no spawn, no
- * HTTP. Mirrors `crates/reddb-client/src/redwire/` so the wire shape
- * stays in lockstep across drivers.
+ * The protocol itself (frame codec, `stream_id` multiplex, handshake,
+ * `RedWireClient`) lives in `./redwire-core.js`, which imports **no**
+ * `node:` built-in so the exact same code rides into the browser bundle
+ * (`./redwire-ws.js`, #937, ADR 0036). This module adds only what needs
+ * Node: the TCP / TLS socket openers and the `node:zlib` zstd provider,
+ * then exposes the historical `connectRedwire({ host, port, ... })`
+ * surface the Node entry and tools depend on.
  *
- * Public surface:
- *   - `connectRedwire(opts)` → returns a `RedWireClient`
- *   - `RedWireClient.query(sql)` → JSON envelope
- *   - `RedWireClient.ping()`
- *   - `RedWireClient.close()`
- *
- * Auth methods this cut supports: `anonymous`, `bearer`. SCRAM /
- * mTLS / OAuth land in subsequent PRs.
+ * Auth methods this cut supports: `anonymous`, `bearer`. SCRAM / mTLS /
+ * OAuth land in subsequent PRs.
  */
 
-import { RedDBError } from './protocol.js'
-
-const MAGIC = 0xfe
-const SUPPORTED_VERSION = 0x01
-const FRAME_HEADER_SIZE = 16
-const MAX_FRAME_SIZE = 16 * 1024 * 1024
-const KNOWN_FLAGS = 0b00000011
-
-export const MessageKind = Object.freeze({
-  Query: 0x01,
-  Result: 0x02,
-  Error: 0x03,
-  BulkInsert: 0x04,
-  BulkOk: 0x05,
-  Hello: 0x10,
-  HelloAck: 0x11,
-  AuthRequest: 0x12,
-  AuthResponse: 0x13,
-  AuthOk: 0x14,
-  AuthFail: 0x15,
-  Bye: 0x16,
-  Ping: 0x17,
-  Pong: 0x18,
-  Get: 0x19,
-  Delete: 0x1A,
-  DeleteOk: 0x1B,
-  BulkInsertBinary: 0x06,
-  QueryBinary: 0x07,
-  BulkInsertPrevalidated: 0x08,
-  QueryWithParams: 0x28,
-  // Output/input streaming lifecycle (PRD #759). Mirrors
-  // `reddb_wire::redwire::frame::MessageKind` so the JS streaming surface
-  // talks the same multiplexed-stream vocabulary as the Rust server.
-  RowDescription: 0x24,
-  StreamEnd: 0x25,
-  OpenStream: 0x29,
-  OpenAck: 0x2A,
-  StreamChunk: 0x2B,
-  StreamError: 0x2C,
-  StreamCancel: 0x2D,
-})
-
-export const Features = Object.freeze({ PARAMS: 0x0000_0001 })
-
-export const ValueTag = Object.freeze({
-  Null: 0x00, Bool: 0x01, Int: 0x02, Float: 0x03, Text: 0x04,
-  Bytes: 0x05, Vector: 0x06, Json: 0x07, Timestamp: 0x08, Uuid: 0x09,
-})
-
-/**
- * Typed value tags for the binary fast path. Identical to the
- * engine-side `wire::protocol::VAL_*` table.
- */
-export const BinaryTag = Object.freeze({
-  Null: 0,
-  I64: 1,
-  F64: 2,
-  Text: 3,
-  Bool: 4,
-  U64: 5,
-})
-
-const KIND_NAME = Object.fromEntries(
-  Object.entries(MessageKind).map(([k, v]) => [v, k]),
-)
-
-export const Flags = Object.freeze({
-  COMPRESSED: 0b00000001,
-  MORE_FRAMES: 0b00000010,
-})
-
-/** zstd level for outbound compressed frames. Override via env. */
-const ZSTD_LEVEL = (() => {
-  const env = typeof process !== 'undefined' ? process.env?.RED_REDWIRE_ZSTD_LEVEL : null
-  const n = env ? Number(env) : NaN
-  return Number.isFinite(n) && n >= 1 && n <= 22 ? n : 1
-})()
-
-/**
- * Compress / decompress shim. Tries Node 22+'s native zstd
- * bindings first; if unavailable returns null and the codec
- * falls back to plaintext (operators still see the
- * COMPRESSED flag bit when peers offer it, but encode is a
- * no-op until the runtime ships native zstd).
- */
-let _zstdMod = undefined
-async function zstdMod() {
-  if (_zstdMod !== undefined) return _zstdMod
+import {
+  connectRedwireOverSocket,
+  setZstdProvider,
+} from './redwire-core.js'
+
+// Re-export the codec surface so existing `./redwire.js` importers
+// (index.js, the redwire-result test, JSDoc type refs) keep resolving.
+export {
+  MessageKind,
+  Features,
+  ValueTag,
+  BinaryTag,
+  Flags,
+  RedWireClient,
+  decodeResultPayload,
+  encodeQueryWithParams,
+  encodeValue,
+  connectRedwireOverSocket,
+  setZstdProvider,
+} from './redwire-core.js'
+
+// Resolve the native zstd binding once per process and install it into
+// the codec. Node 22+ ships `zstdCompressSync`; Deno / older Node lack it
+// and the codec stays plaintext (it still honours the COMPRESSED flag bit
+// peers offer). Cached so repeated connects don't re-import.
+let _zstdLoaded = false
+async function ensureZstd() {
+  if (_zstdLoaded) return
+  _zstdLoaded = true
   try {
     const zlib = await import('node:zlib')
     if (typeof zlib.zstdCompressSync === 'function') {
-      _zstdMod = zlib
-      return _zstdMod
+      setZstdProvider(zlib)
     }
   } catch {
     // node:zlib missing — Deno (no-zstd) or restricted runtime.
   }
-  _zstdMod = null
-  return null
 }
 
 /**
- * Open a RedWire connection.
+ * Open a RedWire connection over a TCP / TLS / Unix socket.
  *
  * @param {object} opts
  * @param {string} opts.host
  * @param {number} opts.port
  * @param {{ kind: 'anonymous' } | { kind: 'bearer', token: string }} [opts.auth]
  * @param {string} [opts.clientName]
+ * @param {object} [opts.socket] Pre-connected duplex to use as-is. When
+ *   set, `host`/`port`/`tls` are ignored — the byte transport is supplied
+ *   by the caller (the browser WS transport rides this seam).
  * @param {object} [opts.tls] When set, wraps the socket in TLS.
  * @param {string|Buffer} [opts.tls.ca] Trusted CA bundle (PEM).
  * @param {string|Buffer} [opts.tls.cert] Client cert for mTLS (PEM).
  * @param {string|Buffer} [opts.tls.key] Client key for mTLS (PEM).
  * @param {boolean} [opts.tls.rejectUnauthorized=true] Verify server cert.
  * @param {string} [opts.tls.servername] SNI override.
- * @returns {Promise<RedWireClient>}
+ * @returns {Promise<import('./redwire-core.js').RedWireClient>}
  */
 export async function connectRedwire(opts) {
-  const { host, port } = opts
-  if (typeof host !== 'string' || host.length === 0) {
-    throw new TypeError('connectRedwire: host required')
-  }
-  if (typeof port !== 'number' || port <= 0 || port > 0xffff) {
-    throw new TypeError('connectRedwire: port required (1-65535)')
-  }
-  const auth = opts.auth ?? { kind: 'anonymous' }
-  // Resolve the zstd shim once per process — this populates the
-  // shared `_zstdMod` cache so encode/decode hot paths are sync.
-  await zstdMod()
-
-  const socket = opts.tls
-    ? await openTlsSocket(host, port, opts.tls)
-    : await openSocket(host, port)
-  const reader = new FrameReader(socket)
-
-  // Discriminator + minor-version byte.
-  await writeAll(socket, Uint8Array.from([MAGIC, SUPPORTED_VERSION]))
-
-  // Hello.
-  const methods = auth.kind === 'bearer' ? ['bearer'] : ['anonymous', 'bearer']
-  const helloPayload = jsonBytes({
-    versions: [SUPPORTED_VERSION],
-    auth_methods: methods,
-    features: 0,
-    client_name: opts.clientName ?? `reddb-js/0.2`,
-  })
-  await writeFrame(socket, MessageKind.Hello, 1n, helloPayload)
-
-  const ack = await reader.next()
-  if (ack.kind === MessageKind.AuthFail) {
-    socket.end()
-    const reason = jsonReason(ack.payload) ?? 'AuthFail at HelloAck'
-    throw new RedDBError('AUTH_REFUSED', `redwire: ${reason}`)
-  }
-  if (ack.kind !== MessageKind.HelloAck) {
-    socket.end()
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected HelloAck, got ${KIND_NAME[ack.kind] ?? ack.kind}`,
-    )
-  }
-  const ackParsed = jsonOf(ack.payload)
-  const chosenAuth = ackParsed?.auth
-  if (typeof chosenAuth !== 'string') {
-    socket.end()
-    throw new RedDBError('PROTOCOL', 'HelloAck missing `auth` field')
-  }
+  await ensureZstd()
 
-  // AuthResponse.
-  let respPayload
-  if (chosenAuth === 'anonymous') {
-    respPayload = new Uint8Array()
-  } else if (chosenAuth === 'bearer') {
-    if (auth.kind !== 'bearer') {
-      socket.end()
-      throw new RedDBError(
-        'AUTH_REFUSED',
-        'server demanded bearer but no token was supplied',
-      )
+  let socket = opts.socket
+  if (!socket) {
+    const { host, port } = opts
+    if (typeof host !== 'string' || host.length === 0) {
+      throw new TypeError('connectRedwire: host required')
     }
-    respPayload = jsonBytes({ token: auth.token })
-  } else {
-    socket.end()
-    throw new RedDBError(
-      'PROTOCOL',
-      `server picked unsupported auth method: ${chosenAuth}`,
-    )
-  }
-  await writeFrame(socket, MessageKind.AuthResponse, 2n, respPayload)
-
-  const final = await reader.next()
-  if (final.kind === MessageKind.AuthFail) {
-    socket.end()
-    const reason = jsonReason(final.payload) ?? 'auth refused'
-    throw new RedDBError('AUTH_REFUSED', reason)
-  }
-  if (final.kind !== MessageKind.AuthOk) {
-    socket.end()
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected AuthOk, got ${KIND_NAME[final.kind] ?? final.kind}`,
-    )
-  }
-  const session = jsonOf(final.payload) ?? {}
-  const features = numberOr(session.features, numberOr(ackParsed?.features, 0))
-
-  return new RedWireClient(socket, reader, session, features)
-}
-
-function numberOr(v, fallback) {
-  return typeof v === 'number' && Number.isFinite(v) ? v : fallback
-}
-
-/**
- * Returned by `connectRedwire`. Methods map 1:1 to RedWire frame
- * kinds. Reuses the same `RedDB`-shaped envelope as the other
- * transports so the surface above this is uniform.
- */
-export class RedWireClient {
-  constructor(socket, reader, session, serverFeatures = 0) {
-    this.socket = socket
-    this.reader = reader
-    this.session = session
-    this.serverFeatures = serverFeatures >>> 0
-    this.nextCorr = 1n
-    this.nextStream = 1
-    this.closed = false
-  }
-
-  /** Raw advertised server feature bitmask. */
-  features() {
-    return this.serverFeatures
-  }
-
-  /** True when server advertised `FEATURE_PARAMS` (#357). */
-  supportsParams() {
-    return (this.serverFeatures & Features.PARAMS) === Features.PARAMS
-  }
-
-  async call(method, params = {}) {
-    if (method === 'query') return this.#query(params.sql ?? '', params.params)
-    if (method === 'insert') return this.#insert({ collection: params.collection, payload: params.payload })
-    if (method === 'bulk_insert') return this.#insert({ collection: params.collection, payloads: params.payloads })
-    if (method === 'bulk_insert_binary') {
-      return this.bulkInsertBinary(params.collection, params.columns, params.rows)
-    }
-    if (method === 'get') return this.#getOrDelete(MessageKind.Get, MessageKind.Result, params)
-    if (method === 'delete') return this.#getOrDelete(MessageKind.Delete, MessageKind.DeleteOk, params)
-    if (method === 'health' || method === 'version') return this.#ping()
-    throw new RedDBError(
-      'UNKNOWN_METHOD',
-      `RedWire transport doesn't bridge '${method}' yet`,
-    )
-  }
-
-  /**
-   * Bulk-insert via the binary fast path (frame kind 0x06).
-   * Same hot-loop perf as the engine's `MSG_BULK_INSERT_BINARY`
-   * stress tests. Each row is an array of `[tag, value]` pairs
-   * matching the column order; tag values come from `BinaryTag`.
-   *
-   * Example:
-   *   client.bulkInsertBinary('users', ['name', 'age'], [
-   *     [[BinaryTag.Text, 'alice'], [BinaryTag.I64, 30n]],
-   *     [[BinaryTag.Text, 'bob'],   [BinaryTag.I64, 25n]],
-   *   ])
-   */
-  async bulkInsertBinary(collection, columns, rows) {
-    if (!Array.isArray(columns) || !Array.isArray(rows)) {
-      throw new TypeError('bulkInsertBinary: columns and rows must be arrays')
-    }
-    const buf = encodeBinaryBulk(collection, columns, rows)
-    const corr = this.#corr()
-    await writeFrame(this.socket, MessageKind.BulkInsertBinary, corr, buf)
-    const resp = await this.reader.next()
-    if (resp.kind === MessageKind.BulkOk) {
-      // v1 BulkOk body is an 8-byte little-endian count.
-      if (resp.payload.length < 8) {
-        throw new RedDBError('PROTOCOL', 'BulkOk truncated: expected 8-byte count')
-      }
-      const view = new DataView(
-        resp.payload.buffer,
-        resp.payload.byteOffset,
-        resp.payload.byteLength,
-      )
-      return Number(view.getBigUint64(0, true))
-    }
-    if (resp.kind === MessageKind.Error) {
-      throw new RedDBError('ENGINE', new TextDecoder().decode(resp.payload))
-    }
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected BulkOk/Error, got ${KIND_NAME[resp.kind] ?? resp.kind}`,
-    )
-  }
-
-  async #getOrDelete(reqKind, okKind, params) {
-    const corr = this.#corr()
-    const payload = jsonBytes({ collection: params.collection, id: String(params.id) })
-    await writeFrame(this.socket, reqKind, corr, payload)
-    const resp = await this.reader.next()
-    if (resp.kind === okKind) return jsonOf(resp.payload) ?? {}
-    if (resp.kind === MessageKind.Error) {
-      throw new RedDBError('ENGINE', new TextDecoder().decode(resp.payload))
-    }
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected ${KIND_NAME[okKind]}/Error, got ${KIND_NAME[resp.kind] ?? resp.kind}`,
-    )
-  }
-
-  async #insert(body) {
-    const corr = this.#corr()
-    const payload = jsonBytes(body)
-    await writeFrame(this.socket, MessageKind.BulkInsert, corr, payload)
-    const resp = await this.reader.next()
-    if (resp.kind === MessageKind.BulkOk) {
-      return jsonOf(resp.payload) ?? { affected: 0 }
+    if (typeof port !== 'number' || port <= 0 || port > 0xffff) {
+      throw new TypeError('connectRedwire: port required (1-65535)')
     }
-    if (resp.kind === MessageKind.Error) {
-      throw new RedDBError('ENGINE', new TextDecoder().decode(resp.payload))
-    }
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected BulkOk/Error, got ${KIND_NAME[resp.kind] ?? resp.kind}`,
-    )
+    socket = opts.tls
+      ? await openTlsSocket(host, port, opts.tls)
+      : await openSocket(host, port)
   }
 
-  async #query(sql, params) {
-    const corr = this.#corr()
-    const hasParams = Array.isArray(params) && params.length > 0
-    let kind
-    let payload
-    if (hasParams) {
-      if (!this.supportsParams()) {
-        throw new RedDBError(
-          'PARAMS_UNSUPPORTED',
-          'server did not advertise FEATURE_PARAMS — upgrade the server '
-            + 'to one that supports parameterized queries.',
-        )
-      }
-      kind = MessageKind.QueryWithParams
-      payload = encodeQueryWithParams(sql, params)
-    } else {
-      kind = isSelectQuery(sql) ? MessageKind.QueryBinary : MessageKind.Query
-      payload = new TextEncoder().encode(sql)
-    }
-    await writeFrame(this.socket, kind, corr, payload)
-    const resp = await this.reader.next()
-    if (resp.kind === MessageKind.Result) {
-      return decodeResultPayload(resp.payload)
-    }
-    if (resp.kind === MessageKind.Error) {
-      throw new RedDBError(
-        'ENGINE',
-        new TextDecoder().decode(resp.payload),
-      )
-    }
-    throw new RedDBError(
-      'PROTOCOL',
-      `expected Result/Error, got ${KIND_NAME[resp.kind] ?? resp.kind}`,
-    )
-  }
-
-  async #ping() {
-    const corr = this.#corr()
-    await writeFrame(this.socket, MessageKind.Ping, corr, new Uint8Array())
-    const resp = await this.reader.next()
-    if (resp.kind !== MessageKind.Pong) {
-      throw new RedDBError(
-        'PROTOCOL',
-        `expected Pong, got ${KIND_NAME[resp.kind] ?? resp.kind}`,
-      )
-    }
-    return { ok: true }
-  }
-
-  /**
-   * Open a streaming read over RedWire. Sends `OpenStream` and returns an
-   * async iterable of typed frames (see streaming.js) plus a
-   * `cancel(reason)` that emits a `StreamCancel` for this stream_id. The
-   * `OpenAck` is consumed internally; rows arrive as `StreamChunk`s and
-   * the stream closes on `StreamEnd`. A `StreamError` rejects iteration.
-   *
-   * @param {{ sql?: string, cursor?: string }} opts
-   */
-  async streamSelect({ sql, cursor } = {}) {
-    if (cursor != null) {
-      throw new RedDBError(
-        'STREAM_CURSOR_UNSUPPORTED',
-        'resumable cursors are only available over the HTTP transport in this release',
-      )
-    }
-    const streamId = this.#stream()
-    const corr = this.#corr()
-    await this.#writeStreamFrame(MessageKind.OpenStream, corr, jsonBytes({ sql }), streamId)
-
-    const reader = this.reader
-    const client = this
-    return {
-      async *[Symbol.asyncIterator]() {
-        for (;;) {
-          const resp = await reader.next()
-          if (resp.streamId !== 0 && resp.streamId !== streamId) {
-            continue
-          }
-          if (resp.kind === MessageKind.OpenAck) {
-            continue
-          }
-          if (resp.kind === MessageKind.StreamChunk) {
-            const chunk = jsonOf(resp.payload) ?? {}
-            const rows = Array.isArray(chunk.rows) ? chunk.rows : []
-            for (const row of rows) {
-              yield { type: 'row', value: row }
-            }
-            continue
-          }
-          if (resp.kind === MessageKind.StreamEnd) {
-            const end = jsonOf(resp.payload) ?? {}
-            yield { type: 'end', value: end.stats ?? end }
-            return
-          }
-          if (resp.kind === MessageKind.StreamError || resp.kind === MessageKind.Error) {
-            const err = jsonOf(resp.payload) ?? {}
-            throw new RedDBError(
-              err.code || 'STREAM_ERROR',
-              err.message || new TextDecoder().decode(resp.payload),
-              err,
-            )
-          }
-          throw new RedDBError(
-            'STREAM_PROTOCOL',
-            `unexpected frame in stream: ${KIND_NAME[resp.kind] ?? resp.kind}`,
-          )
-        }
-      },
-      async cancel(reason) {
-        await client.#cancelStream(streamId, reason)
-      },
-    }
-  }
-
-  /**
-   * Open a streaming write over RedWire. The `OpenStream {direction:"in"}`
-   * frame is sent on the first `write()` (so columns can be inferred from
-   * the first row); each row is shipped as a one-row `StreamChunk` and the
-   * terminal chunk closes the input phase. `close()` resolves with the
-   * server's `StreamEnd` stats.
-   *
-   * @param {{ target: string, columns?: string[] }} opts
-   */
-  async streamInput({ target, columns } = {}) {
-    const streamId = this.#stream()
-    const corr = this.#corr()
-    const client = this
-    let opened = false
-    let seq = 0
-    let cols = Array.isArray(columns) && columns.length > 0 ? columns.slice() : null
-
-    const ensureOpen = async (row) => {
-      if (opened) return
-      if (!cols) {
-        cols = row && typeof row === 'object' ? Object.keys(row) : null
-      }
-      if (!cols || cols.length === 0) {
-        throw new RedDBError(
-          'INVALID_STREAM_COLUMNS',
-          'inputStream() needs a non-empty column set — pass { columns } or write at least one object row',
-        )
-      }
-      await client.#writeStreamFrame(
-        MessageKind.OpenStream,
-        corr,
-        jsonBytes({ direction: 'in', target, columns: cols }),
-        streamId,
-      )
-      const ack = await client.reader.next()
-      if (ack.kind === MessageKind.StreamError || ack.kind === MessageKind.Error) {
-        const err = jsonOf(ack.payload) ?? {}
-        throw new RedDBError(err.code || 'STREAM_ERROR', err.message || 'input stream refused', err)
-      }
-      if (ack.kind !== MessageKind.OpenAck) {
-        throw new RedDBError(
-          'STREAM_PROTOCOL',
-          `expected OpenAck, got ${KIND_NAME[ack.kind] ?? ack.kind}`,
-        )
-      }
-      opened = true
-    }
-
-    return {
-      async write(row) {
-        await ensureOpen(row)
-        await client.#writeStreamFrame(
-          MessageKind.StreamChunk,
-          corr,
-          jsonBytes({ seq: seq++, rows: [row], terminal: false }),
-          streamId,
-        )
-      },
-      async close() {
-        await ensureOpen(null)
-        await client.#writeStreamFrame(
-          MessageKind.StreamChunk,
-          corr,
-          jsonBytes({ seq: seq++, rows: [], terminal: true }),
-          streamId,
-        )
-        const end = await client.reader.next()
-        if (end.kind === MessageKind.StreamError || end.kind === MessageKind.Error) {
-          const err = jsonOf(end.payload) ?? {}
-          throw new RedDBError(err.code || 'STREAM_ERROR', err.message || 'input stream failed', err)
-        }
-        if (end.kind !== MessageKind.StreamEnd) {
-          throw new RedDBError(
-            'STREAM_PROTOCOL',
-            `expected StreamEnd, got ${KIND_NAME[end.kind] ?? end.kind}`,
-          )
-        }
-        const parsed = jsonOf(end.payload) ?? {}
-        return parsed.stats ?? parsed
-      },
-      async cancel(reason) {
-        await client.#cancelStream(streamId, reason)
-      },
-    }
-  }
-
-  async #cancelStream(streamId, reason) {
-    if (this.closed) return
-    const payload = typeof reason === 'string' && reason.length > 0
-      ? jsonBytes({ reason })
-      : new Uint8Array()
-    try {
-      await this.#writeStreamFrame(MessageKind.StreamCancel, this.#corr(), payload, streamId)
-    } catch {
-      // best-effort — the socket may already be torn down.
-    }
-  }
-
-  #writeStreamFrame(kind, corr, payload, streamId) {
-    const buf = encodeFrame(kind, corr, payload, 0, streamId)
-    return writeAll(this.socket, buf)
-  }
-
-  async close() {
-    if (this.closed) return
-    this.closed = true
-    try {
-      const corr = this.#corr()
-      await writeFrame(this.socket, MessageKind.Bye, corr, new Uint8Array())
-    } catch {
-      // best-effort
-    }
-    this.socket.end()
-  }
-
-  #corr() {
-    const c = this.nextCorr
-    this.nextCorr = this.nextCorr + 1n
-    return c
-  }
-
-  #stream() {
-    const id = this.nextStream
-    // stream_id 0 is reserved for handshake/lifecycle frames; wrap past it.
-    this.nextStream = this.nextStream >= 0xffff ? 1 : this.nextStream + 1
-    return id
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Framing helpers
-// ---------------------------------------------------------------------------
-
-function encodeFrame(kind, correlationId, payload, flags = 0, streamId = 0) {
-  if (!(payload instanceof Uint8Array)) {
-    payload = new Uint8Array(payload)
-  }
-  let onWire = payload
-  let outFlags = flags & KNOWN_FLAGS
-  // We compress synchronously when the flag is set AND the
-  // runtime ships native zstd. Async flag-flip happens at
-  // session level (see RedWireClient construction); per-frame
-  // call here is a fast Buffer roundtrip.
-  if (outFlags & Flags.COMPRESSED && _zstdMod && typeof _zstdMod.zstdCompressSync === 'function') {
-    try {
-      const compressed = _zstdMod.zstdCompressSync(payload, {
-        params: { [_zstdMod.constants?.ZSTD_c_compressionLevel ?? 100]: ZSTD_LEVEL },
-      })
-      onWire = compressed instanceof Uint8Array ? compressed : new Uint8Array(compressed)
-    } catch {
-      // Fallback: ship plaintext, drop the flag so the peer
-      // doesn't try to decompress.
-      outFlags &= ~Flags.COMPRESSED
-    }
-  }
-  const length = FRAME_HEADER_SIZE + onWire.length
-  if (length > MAX_FRAME_SIZE) {
-    throw new RedDBError('FRAME_TOO_LARGE', `frame ${length} > ${MAX_FRAME_SIZE}`)
-  }
-  const buf = new Uint8Array(length)
-  const view = new DataView(buf.buffer)
-  view.setUint32(0, length, true)
-  buf[4] = kind
-  buf[5] = outFlags
-  view.setUint16(6, streamId, true)
-  view.setBigUint64(8, BigInt(correlationId), true)
-  buf.set(onWire, FRAME_HEADER_SIZE)
-  return buf
-}
-
-function writeFrame(socket, kind, correlationId, payload) {
-  const buf = encodeFrame(kind, correlationId, payload)
-  return writeAll(socket, buf)
-}
-
-function decodeFrame(buf) {
-  if (buf.length < FRAME_HEADER_SIZE) return null
-  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
-  const length = view.getUint32(0, true)
-  if (length < FRAME_HEADER_SIZE || length > MAX_FRAME_SIZE) {
-    throw new RedDBError('FRAME_INVALID_LENGTH', `length=${length}`)
-  }
-  if (buf.length < length) return null
-  const kind = buf[4]
-  const flags = buf[5]
-  if (flags & ~KNOWN_FLAGS) {
-    throw new RedDBError('FRAME_UNKNOWN_FLAGS', `flags=0x${flags.toString(16)}`)
-  }
-  const streamId = view.getUint16(6, true)
-  const correlationId = view.getBigUint64(8, true)
-  let payload = buf.slice(FRAME_HEADER_SIZE, length)
-  if (flags & Flags.COMPRESSED) {
-    if (!_zstdMod || typeof _zstdMod.zstdDecompressSync !== 'function') {
-      throw new RedDBError(
-        'COMPRESSED_BUT_NO_ZSTD',
-        'incoming frame has COMPRESSED flag but runtime has no zstd support — upgrade Node >= 22',
-      )
-    }
-    try {
-      const plain = _zstdMod.zstdDecompressSync(payload)
-      payload = plain instanceof Uint8Array ? plain : new Uint8Array(plain)
-    } catch (err) {
-      throw new RedDBError('FRAME_DECOMPRESS_FAILED', err.message)
-    }
-  }
-  return { kind, flags, streamId, correlationId, payload, consumed: length }
-}
-
-/**
- * Buffered frame reader — TCP delivers byte streams, frames may
- * cross or share `data` events. Maintains a rolling accumulator
- * and yields one frame per `next()` call.
- */
-class FrameReader {
-  constructor(socket) {
-    this.chunks = []
-    this.totalLen = 0
-    this.waiters = []
-    this.error = null
-    this.eof = false
-    socket.on('data', (chunk) => {
-      // chunk is Buffer (Node) or Uint8Array (Bun/Deno)
-      const u8 = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk)
-      this.chunks.push(u8)
-      this.totalLen += u8.length
-      this.#tryDeliver()
-    })
-    socket.on('error', (err) => {
-      this.error = err
-      this.#flushWaiters()
-    })
-    socket.on('end', () => {
-      this.eof = true
-      this.#flushWaiters()
-    })
-    socket.on('close', () => {
-      this.eof = true
-      this.#flushWaiters()
-    })
-  }
-
-  next() {
-    if (this.error) return Promise.reject(this.error)
-    return new Promise((resolve, reject) => {
-      this.waiters.push({ resolve, reject })
-      this.#tryDeliver()
-    })
-  }
-
-  #tryDeliver() {
-    while (this.waiters.length > 0 && this.totalLen > 0) {
-      const flat = this.#flatten()
-      let frame
-      try {
-        frame = decodeFrame(flat)
-      } catch (err) {
-        const w = this.waiters.shift()
-        w.reject(err)
-        return
-      }
-      if (frame == null) {
-        // Need more bytes — put the flattened buffer back as a
-        // single chunk so we don't keep flattening repeatedly.
-        this.chunks = [flat]
-        return
-      }
-      this.chunks = [flat.subarray(frame.consumed)]
-      this.totalLen = this.chunks[0].length
-      const w = this.waiters.shift()
-      w.resolve(frame)
-    }
-    if (this.eof && this.waiters.length > 0 && this.totalLen === 0) {
-      const err = this.error ?? new RedDBError('CONNECTION_CLOSED', 'redwire: connection closed')
-      while (this.waiters.length > 0) {
-        this.waiters.shift().reject(err)
-      }
-    }
-  }
-
-  #flushWaiters() {
-    if (this.waiters.length === 0) return
-    if (this.totalLen > 0) {
-      this.#tryDeliver()
-      return
-    }
-    const err = this.error ?? new RedDBError('CONNECTION_CLOSED', 'redwire: connection closed')
-    while (this.waiters.length > 0) {
-      this.waiters.shift().reject(err)
-    }
-  }
-
-  #flatten() {
-    if (this.chunks.length === 1) return this.chunks[0]
-    const out = new Uint8Array(this.totalLen)
-    let off = 0
-    for (const c of this.chunks) {
-      out.set(c, off)
-      off += c.length
-    }
-    this.chunks = [out]
-    return out
-  }
+  return await connectRedwireOverSocket(socket, {
+    auth: opts.auth,
+    clientName: opts.clientName,
+  })
 }
 
 // ---------------------------------------------------------------------------
-// Socket helpers — node:net works on Node, Bun, and Deno via shim
+// Socket helpers — node:net / node:tls work on Node, Bun, and Deno via shim
 // ---------------------------------------------------------------------------
 
 async function openSocket(host, port) {
@@ -821,402 +154,3 @@ async function openTlsSocket(host, port, tlsOpts) {
     sock.once('secureConnect', onOk)
   })
 }
-
-function writeAll(socket, bytes) {
-  return new Promise((resolve, reject) => {
-    socket.write(bytes, (err) => (err ? reject(err) : resolve()))
-  })
-}
-
-// ---------------------------------------------------------------------------
-// JSON helpers — handshake payloads use JSON for now (CBOR follow-up)
-// ---------------------------------------------------------------------------
-
-function jsonBytes(obj) {
-  return new TextEncoder().encode(JSON.stringify(obj))
-}
-
-function jsonOf(bytes) {
-  if (!bytes || bytes.length === 0) return null
-  try {
-    return JSON.parse(new TextDecoder().decode(bytes))
-  } catch {
-    return null
-  }
-}
-
-function isSelectQuery(sql) {
-  return typeof sql === 'string' && /^\s*select\b/i.test(sql)
-}
-
-export function decodeResultPayload(payload) {
-  const json = jsonOf(payload)
-  if (json) return json
-  return decodeBinaryResultPayload(payload)
-}
-
-function decodeBinaryResultPayload(payload) {
-  if (!(payload instanceof Uint8Array)) {
-    payload = new Uint8Array(payload)
-  }
-  const view = new DataView(payload.buffer, payload.byteOffset, payload.byteLength)
-  const dec = new TextDecoder()
-  let pos = 0
-
-  const read = (n, label) => {
-    if (pos + n > payload.length) {
-      throw new RedDBError('PROTOCOL', `Result payload truncated while reading ${label}`)
-    }
-    const start = pos
-    pos += n
-    return start
-  }
-  const readU16 = (label) => view.getUint16(read(2, label), true)
-  const readU32 = (label) => view.getUint32(read(4, label), true)
-  const readI64 = (label) => safeBigIntToJs(view.getBigInt64(read(8, label), true))
-  const readU64 = (label) => safeBigIntToJs(view.getBigUint64(read(8, label), true))
-  const readF64 = (label) => view.getFloat64(read(8, label), true)
-  const readText = (n, label) => dec.decode(payload.subarray(read(n, label), pos))
-
-  const columnCount = readU16('column count')
-  const columns = []
-  for (let i = 0; i < columnCount; i += 1) {
-    const len = readU16(`column ${i} length`)
-    columns.push(readText(len, `column ${i} name`))
-  }
-
-  const rowCount = readU32('row count')
-  const rows = []
-  for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
-    const row = {}
-    for (const column of columns) {
-      row[column] = readBinaryValue()
-    }
-    rows.push(row)
-  }
-
-  return {
-    ok: true,
-    statement: 'SELECT',
-    affected: 0,
-    columns,
-    rows,
-  }
-
-  function readBinaryValue() {
-    const tag = payload[read(1, 'value tag')]
-    switch (tag) {
-      case BinaryTag.Null:
-        return null
-      case BinaryTag.I64:
-        return readI64('i64 value')
-      case BinaryTag.U64:
-        return readU64('u64 value')
-      case BinaryTag.F64:
-        return readF64('f64 value')
-      case BinaryTag.Text: {
-        const len = readU32('text length')
-        return readText(len, 'text value')
-      }
-      case BinaryTag.Bool:
-        return payload[read(1, 'bool value')] !== 0
-      default:
-        throw new RedDBError('PROTOCOL', `Result payload has unknown value tag ${tag}`)
-    }
-  }
-}
-
-function safeBigIntToJs(value) {
-  if (
-    value >= BigInt(Number.MIN_SAFE_INTEGER)
-    && value <= BigInt(Number.MAX_SAFE_INTEGER)
-  ) {
-    return Number(value)
-  }
-  return value
-}
-
-/**
- * Encode the binary bulk-insert payload body (raw, no RedWire frame
- * header — the body is wrapped by the caller as a `BulkInsertBinary`
- * frame).
- * Layout: `[coll_len u16][coll_bytes][ncols u16]
- *          [(name_len u16)(name_bytes)]*ncols
- *          [nrows u32]
- *          [(tag u8)(value)]*ncols * nrows`
- */
-function encodeBinaryBulk(collection, columns, rows) {
-  const enc = new TextEncoder()
-  const collBytes = enc.encode(collection)
-  // Pre-encode column names + their length prefixes.
-  const colChunks = columns.map((c) => enc.encode(c))
-  let total = 2 + collBytes.length + 2
-  for (const cb of colChunks) total += 2 + cb.length
-  total += 4
-  // Estimate row size — we'll resize if needed.
-  for (const row of rows) {
-    if (!Array.isArray(row) || row.length !== columns.length) {
-      throw new TypeError(
-        `bulkInsertBinary: each row must be an array of length ${columns.length}`,
-      )
-    }
-    for (const cell of row) {
-      total += sizeOfBinaryCell(cell)
-    }
-  }
-  const buf = new Uint8Array(total)
-  const view = new DataView(buf.buffer)
-  let pos = 0
-  view.setUint16(pos, collBytes.length, true); pos += 2
-  buf.set(collBytes, pos); pos += collBytes.length
-  view.setUint16(pos, colChunks.length, true); pos += 2
-  for (const cb of colChunks) {
-    view.setUint16(pos, cb.length, true); pos += 2
-    buf.set(cb, pos); pos += cb.length
-  }
-  view.setUint32(pos, rows.length, true); pos += 4
-  for (const row of rows) {
-    for (const cell of row) {
-      pos = writeBinaryCell(buf, view, pos, cell, enc)
-    }
-  }
-  return buf
-}
-
-function sizeOfBinaryCell(cell) {
-  if (!Array.isArray(cell) || cell.length !== 2) {
-    throw new TypeError('bulkInsertBinary cell must be [tag, value]')
-  }
-  const [tag] = cell
-  switch (tag) {
-    case 0: return 1
-    case 1: return 1 + 8
-    case 2: return 1 + 8
-    case 3: {
-      const v = cell[1]
-      const bytes = typeof v === 'string' ? new TextEncoder().encode(v).length : 0
-      return 1 + 4 + bytes
-    }
-    case 4: return 1 + 1
-    case 5: return 1 + 8
-    default: throw new RedDBError('UNKNOWN_BINARY_TAG', `tag=${tag}`)
-  }
-}
-
-function writeBinaryCell(buf, view, pos, cell, enc) {
-  const [tag, value] = cell
-  buf[pos++] = tag
-  switch (tag) {
-    case 0: // Null
-      return pos
-    case 1: { // I64
-      const bi = typeof value === 'bigint' ? value : BigInt(value)
-      view.setBigInt64(pos, bi, true)
-      return pos + 8
-    }
-    case 2: { // F64
-      view.setFloat64(pos, Number(value), true)
-      return pos + 8
-    }
-    case 3: { // Text
-      const bytes = enc.encode(String(value))
-      view.setUint32(pos, bytes.length, true); pos += 4
-      buf.set(bytes, pos)
-      return pos + bytes.length
-    }
-    case 4: { // Bool
-      buf[pos] = value ? 1 : 0
-      return pos + 1
-    }
-    case 5: { // U64
-      const bi = typeof value === 'bigint' ? value : BigInt(value)
-      view.setBigUint64(pos, bi, true)
-      return pos + 8
-    }
-    default:
-      throw new RedDBError('UNKNOWN_BINARY_TAG', `tag=${tag}`)
-  }
-}
-
-// ---------------------------------------------------------------------------
-// QueryWithParams payload codec — mirrors `reddb_wire::query_with_params`
-// ---------------------------------------------------------------------------
-
-const MAX_VALUE_PAYLOAD_LEN = MAX_FRAME_SIZE
-const MAX_PARAM_COUNT = 65_536
-
-/**
- * Encode the `QueryWithParams` payload body.
- * Layout: `[u32 sql_len LE][utf-8 sql][u32 param_count LE][N encoded values]`
- */
-export function encodeQueryWithParams(sql, params) {
-  if (typeof sql !== 'string') throw new TypeError('encodeQueryWithParams: sql must be a string')
-  if (!Array.isArray(params)) throw new TypeError('encodeQueryWithParams: params must be an array')
-  if (params.length > MAX_PARAM_COUNT) {
-    throw new RedDBError('PARAM_COUNT_OVER_LIMIT', `param_count ${params.length} > ${MAX_PARAM_COUNT}`)
-  }
-  const sqlBytes = new TextEncoder().encode(sql)
-  if (sqlBytes.length > MAX_VALUE_PAYLOAD_LEN) {
-    throw new RedDBError('PAYLOAD_TOO_LARGE', `sql_len ${sqlBytes.length} > ${MAX_VALUE_PAYLOAD_LEN}`)
-  }
-  const valueBlobs = params.map(encodeValue)
-  let total = 4 + sqlBytes.length + 4
-  for (const vb of valueBlobs) total += vb.length
-  const buf = new Uint8Array(total)
-  const view = new DataView(buf.buffer)
-  let pos = 0
-  view.setUint32(pos, sqlBytes.length, true); pos += 4
-  buf.set(sqlBytes, pos); pos += sqlBytes.length
-  view.setUint32(pos, valueBlobs.length, true); pos += 4
-  for (const vb of valueBlobs) { buf.set(vb, pos); pos += vb.length }
-  return buf
-}
-
-/**
- * Encode a single wire `Value`. Mirrors `reddb_wire::value::encode`.
- *
- * Accepts native JS values + the JSON envelopes produced by
- * `serializeParam` so the SDK can pass through a single shape:
- *   - `null` / `undefined`               → Null
- *   - `boolean`                          → Bool
- *   - `bigint`                           → Int (i64)
- *   - `number` integer (safe range)      → Int; otherwise → Float
- *   - `string`                           → Text
- *   - `Uint8Array` / `Buffer`            → Bytes
- *   - `Float32Array` / `Array<number>`   → Vector (f32)
- *   - `{ $bytes: <base64> }`             → Bytes
- *   - `{ $ts: <unix-seconds> }`          → Timestamp
- *   - `{ $uuid: <hyphenated> }`          → Uuid
- *   - other plain object/array           → Json (canonical bytes)
- */
-export function encodeValue(v) {
-  if (v === null || v === undefined) return Uint8Array.of(ValueTag.Null)
-  if (typeof v === 'boolean') return Uint8Array.of(ValueTag.Bool, v ? 1 : 0)
-  if (typeof v === 'bigint') {
-    const out = new Uint8Array(1 + 8)
-    out[0] = ValueTag.Int
-    new DataView(out.buffer).setBigInt64(1, v, true)
-    return out
-  }
-  if (typeof v === 'number') {
-    if (Number.isInteger(v) && v >= -(2 ** 53) && v <= 2 ** 53) {
-      const out = new Uint8Array(1 + 8)
-      out[0] = ValueTag.Int
-      new DataView(out.buffer).setBigInt64(1, BigInt(v), true)
-      return out
-    }
-    const out = new Uint8Array(1 + 8)
-    out[0] = ValueTag.Float
-    new DataView(out.buffer).setFloat64(1, v, true)
-    return out
-  }
-  if (typeof v === 'string') return encodeLenPrefixed(ValueTag.Text, new TextEncoder().encode(v))
-  if (v instanceof Uint8Array) return encodeLenPrefixed(ValueTag.Bytes, v)
-  if (typeof Buffer !== 'undefined' && v instanceof Buffer) {
-    return encodeLenPrefixed(ValueTag.Bytes, new Uint8Array(v.buffer, v.byteOffset, v.byteLength))
-  }
-  if (v instanceof Float32Array) return encodeVector(v)
-  if (v instanceof Float64Array) return encodeVector(Float32Array.from(v))
-  if (Array.isArray(v) && v.every((x) => typeof x === 'number')) {
-    return encodeVector(Float32Array.from(v))
-  }
-  if (typeof v === 'object') {
-    const keys = Object.keys(v)
-    if (keys.length === 1) {
-      const k = keys[0]
-      if (k === '$bytes' && typeof v.$bytes === 'string') {
-        return encodeLenPrefixed(ValueTag.Bytes, base64ToBytes(v.$bytes))
-      }
-      if (k === '$ts' && (
-        (typeof v.$ts === 'number' && Number.isFinite(v.$ts))
-        || typeof v.$ts === 'string'
-      )) {
-        const out = new Uint8Array(1 + 8)
-        out[0] = ValueTag.Timestamp
-        const raw = typeof v.$ts === 'string' ? BigInt(v.$ts) : BigInt(Math.trunc(v.$ts))
-        new DataView(out.buffer).setBigInt64(1, raw, true)
-        return out
-      }
-      if (k === '$uuid' && typeof v.$uuid === 'string') {
-        const bytes = parseUuidHyphenated(v.$uuid)
-        const out = new Uint8Array(1 + 16)
-        out[0] = ValueTag.Uuid
-        out.set(bytes, 1)
-        return out
-      }
-    }
-    return encodeLenPrefixed(ValueTag.Json, new TextEncoder().encode(canonicalJson(v)))
-  }
-  throw new RedDBError('UNSUPPORTED_PARAM', `cannot encode param of type ${typeof v}`)
-}
-
-function encodeLenPrefixed(tag, bytes) {
-  if (bytes.length > MAX_VALUE_PAYLOAD_LEN) {
-    throw new RedDBError('PAYLOAD_TOO_LARGE', `value len ${bytes.length} > ${MAX_VALUE_PAYLOAD_LEN}`)
-  }
-  const out = new Uint8Array(1 + 4 + bytes.length)
-  out[0] = tag
-  new DataView(out.buffer).setUint32(1, bytes.length, true)
-  out.set(bytes, 5)
-  return out
-}
-
-function encodeVector(f32) {
-  if (f32.length * 4 > MAX_VALUE_PAYLOAD_LEN) {
-    throw new RedDBError('PAYLOAD_TOO_LARGE', `vector bytes ${f32.length * 4} > ${MAX_VALUE_PAYLOAD_LEN}`)
-  }
-  const out = new Uint8Array(1 + 4 + f32.length * 4)
-  out[0] = ValueTag.Vector
-  const view = new DataView(out.buffer)
-  view.setUint32(1, f32.length, true)
-  for (let i = 0; i < f32.length; i++) {
-    view.setFloat32(5 + i * 4, f32[i], true)
-  }
-  return out
-}
-
-function base64ToBytes(s) {
-  if (typeof Buffer !== 'undefined') {
-    const b = Buffer.from(s, 'base64')
-    return new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
-  }
-  // eslint-disable-next-line no-undef
-  const bin = atob(s)
-  const out = new Uint8Array(bin.length)
-  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
-  return out
-}
-
-function parseUuidHyphenated(s) {
-  const hex = s.replace(/-/g, '')
-  if (hex.length !== 32 || /[^0-9a-fA-F]/.test(hex)) {
-    throw new RedDBError('UUID_INVALID', `bad uuid: ${s}`)
-  }
-  const out = new Uint8Array(16)
-  for (let i = 0; i < 16; i++) out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
-  return out
-}
-
-/** Stable JSON serialization with sorted keys — matches the server's
- * canonical `crate::json` output so round-tripped Json values compare
- * byte-equal. */
-function canonicalJson(v) {
-  if (v === null) return 'null'
-  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'null'
-  if (typeof v === 'string') return JSON.stringify(v)
-  if (typeof v === 'boolean') return v ? 'true' : 'false'
-  if (Array.isArray(v)) return '[' + v.map(canonicalJson).join(',') + ']'
-  if (typeof v === 'object') {
-    const keys = Object.keys(v).sort()
-    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(v[k])).join(',') + '}'
-  }
-  return 'null'
-}
-
-function jsonReason(bytes) {
-  const v = jsonOf(bytes)
-  if (v && typeof v === 'object' && typeof v.reason === 'string') {
-    return v.reason
-  }
-  return null
-}