@reddb-io/client 1.6.0 → 1.8.0

package/src/core/serialization.js

@@ -0,0 +1,94 @@
+/**
+ * SQL query-parameter serialization — the wire encoding shared by every
+ * transport. Pure JS: value encoding, base64, UUID, Date, typed-array,
+ * and NaN/Infinity handling. Imports zero `node:` built-ins.
+ *
+ * `Buffer` is referenced only behind a `typeof Buffer !== 'undefined'`
+ * guard so the module loads unchanged on runtimes that have no `Buffer`
+ * (browsers, Deno without the node shim).
+ */
+
+import { RedDBError } from './errors.js'
+
+export function serializeParam(value) {
+  assertSupportedParam(value)
+  if (value instanceof Float32Array || value instanceof Float64Array) {
+    return Array.from(value)
+  }
+  if (value instanceof Date) {
+    return { $ts: String(BigInt(value.getTime()) * 1_000_000n) }
+  }
+  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && value instanceof Buffer)) {
+    return { $bytes: bytesToBase64(value) }
+  }
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    if (Number.isNaN(value)) return { $float: 'NaN' }
+    return { $float: value > 0 ? 'Infinity' : '-Infinity' }
+  }
+  if (typeof value === 'string' && isUuidString(value)) {
+    return { $uuid: value }
+  }
+  return value
+}
+
+export function assertSupportedParam(value) {
+  if (value == null) return
+  if (
+    typeof value === 'boolean'
+    || typeof value === 'number'
+    || typeof value === 'string'
+  ) {
+    return
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new RedDBError('UNSUPPORTED_PARAM', 'cannot encode invalid Date query parameter')
+    }
+    return
+  }
+  if (
+    value instanceof Uint8Array
+    || value instanceof Float32Array
+    || value instanceof Float64Array
+    || (typeof Buffer !== 'undefined' && value instanceof Buffer)
+  ) {
+    return
+  }
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item === 'number')) return
+    throw new RedDBError(
+      'UNSUPPORTED_PARAM',
+      'array query parameters must contain only numbers',
+    )
+  }
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return
+  }
+  throw new RedDBError(
+    'UNSUPPORTED_PARAM',
+    `cannot encode query parameter of type ${typeof value}`,
+  )
+}
+
+export function normalizeQueryParams(args) {
+  if (args.length === 0) return null
+  if (args.length === 1 && Array.isArray(args[0])) return args[0].map(serializeParam)
+  return args.map(serializeParam)
+}
+
+export function bytesToBase64(value) {
+  const bytes = value instanceof Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64')
+  }
+  let text = ''
+  for (const byte of bytes) text += String.fromCharCode(byte)
+  // eslint-disable-next-line no-undef
+  return btoa(text)
+}
+
+export function isUuidString(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+}

package/src/core/url.js

@@ -0,0 +1,271 @@
+/**
+ * `red://` connection-string parser.
+ *
+ * One URL covers every transport RedDB speaks:
+ *
+ *   red://                                          embedded in-memory
+ *   red:///abs/path/data.rdb                        embedded persistent
+ *   red://user:pass@host:5050                       remote, default proto=red (wire)
+ *   red://host:8080?proto=https                     remote HTTPS
+ *   red://host:5432?proto=pg                        PostgreSQL wire
+ *   red://host:5055?proto=grpc&token=sk-abc         remote gRPC w/ bearer
+ *   red://host:8080?proto=https&apiKey=ak-xyz       remote HTTPS w/ api key
+ *
+ * Backwards-compat: legacy `memory://`, `file://`, `grpc://` URLs
+ * still work via `parseLegacyUrl`. New code should prefer `red://`
+ * because it carries auth + protocol selection in one place.
+ */
+
+import { RedDBError } from './errors.js'
+
+/**
+ * @typedef {object} ParsedUri
+ * @property {'embedded' | 'http' | 'https' | 'red' | 'reds' | 'grpc' | 'grpcs' | 'pg'} kind
+ * @property {string} [host]
+ * @property {number} [port]
+ * @property {string} [path]            // for embedded `file://`-equivalent
+ * @property {string} [username]
+ * @property {string} [password]
+ * @property {string} [token]
+ * @property {string} [apiKey]
+ * @property {string} [loginUrl]        // explicit override for login flow
+ * @property {URLSearchParams} [params] // remaining query params
+ * @property {string} originalUri
+ */
+
+/**
+ * Parse any URI string into a normalised `ParsedUri`.
+ * Accepts `red://`, `memory://`, `file://`, `grpc://` (the latter
+ * three for backwards compat).
+ *
+ * @param {string} uri
+ * @returns {ParsedUri}
+ */
+export function parseUri(uri) {
+  if (typeof uri !== 'string' || uri.length === 0) {
+    throw new TypeError(
+      "connect() requires a URI string (e.g. 'red://localhost:5050' or 'red:///data.rdb')",
+    )
+  }
+  if (uri.startsWith('red://') || uri === 'red:' || uri === 'red:/') {
+    return parseRedUrl(uri)
+  }
+  return parseLegacyUrl(uri)
+}
+
+/**
+ * Parse a `red://` URL.
+ *
+ * Authority shape: `[user[:pass]@]host[:port]`
+ * Path: optional, used as filesystem path when `host` is absent or
+ * is the special token `localhost-embedded` (rare).
+ * Query: `proto`, `token`, `apiKey`, `loginUrl`.
+ */
+export function parseRedUrl(uri) {
+  // The host might be missing (`red:///path`), the URL constructor
+  // requires *something* there. Re-write to a parse-friendly shape:
+  // - `red:///x`     → `red://embedded.local/x`   (embedded with path)
+  // - `red://memory` → `red://embedded.local`     (embedded in-memory)
+  // - `red://`       → `red://embedded.local`     (embedded in-memory)
+  let normalised = uri
+  if (uri === 'red:' || uri === 'red:/' || uri === 'red://') {
+    normalised = 'red://embedded.local'
+  } else if (uri.startsWith('red:///')) {
+    normalised = `red://embedded.local${uri.slice('red://'.length)}`
+  } else if (
+    uri === 'red://memory'
+    || uri === 'red://memory/'
+    || uri === 'red://:memory'
+    || uri === 'red://:memory:'  // SQLite-style ":memory:" alias
+  ) {
+    normalised = 'red://embedded.local'
+  }
+
+  let parsed
+  try {
+    parsed = new URL(normalised)
+  } catch (err) {
+    throw new RedDBError('UNPARSEABLE_URI', `failed to parse '${uri}': ${err.message}`)
+  }
+
+  const params = parsed.searchParams
+  const proto = (params.get('proto') || '').toLowerCase()
+  const path = parsed.pathname && parsed.pathname !== '/' ? parsed.pathname : ''
+
+  // Embedded: special host, OR `proto=embedded`, OR no proto + has path
+  // and the user clearly meant a file path (red:///abs/path).
+  if (parsed.hostname === 'embedded.local') {
+    if (path) {
+      return {
+        kind: 'embedded',
+        path,
+        params,
+        originalUri: uri,
+      }
+    }
+    return {
+      kind: 'embedded',
+      params,
+      originalUri: uri,
+    }
+  }
+
+  // Remote — default proto is red (wire).
+  const kind = resolveKind(proto)
+  const port = parsed.port ? Number(parsed.port) : defaultPortFor(kind)
+  const username = parsed.username ? decodeURIComponent(parsed.username) : undefined
+  const password = parsed.password ? decodeURIComponent(parsed.password) : undefined
+
+  return {
+    kind,
+    host: parsed.hostname,
+    port,
+    path: path || undefined,
+    username,
+    password,
+    token: params.get('token') ?? undefined,
+    apiKey: params.get('apiKey') ?? params.get('api_key') ?? undefined,
+    loginUrl: params.get('loginUrl') ?? params.get('login_url') ?? undefined,
+    params,
+    originalUri: uri,
+  }
+}
+
+/**
+ * Backwards-compat parser for the legacy URL shapes the driver
+ * accepted before `red://` existed. Returns the same `ParsedUri`
+ * shape so downstream code is uniform.
+ */
+export function parseLegacyUrl(uri) {
+  if (uri === 'memory://' || uri === 'memory:') {
+    return { kind: 'embedded', originalUri: uri }
+  }
+  if (uri.startsWith('file://')) {
+    const path = uri.slice('file://'.length)
+    if (!path) {
+      throw new TypeError(`invalid file:// URI: missing path in '${uri}'`)
+    }
+    return { kind: 'embedded', path, originalUri: uri }
+  }
+  if (
+    uri.startsWith('grpc://')
+    || uri.startsWith('grpcs://')
+    || uri.startsWith('reds://')
+  ) {
+    const scheme = uri.split('://', 1)[0]
+    const stripped = uri.slice(`${scheme}://`.length)
+    const [hostPort] = stripped.split(/[/?]/, 1)
+    const [host, portStr] = hostPort.split(':')
+    if (!host) {
+      throw new TypeError(`invalid ${scheme}:// URI: missing host in '${uri}'`)
+    }
+    const legacyKind = scheme === 'reds' ? 'reds' : scheme === 'grpcs' ? 'grpcs' : scheme === 'grpc' ? 'grpc' : 'red'
+    return {
+      kind: legacyKind,
+      host,
+      port: portStr ? Number(portStr) : defaultPortFor(legacyKind),
+      originalUri: uri,
+    }
+  }
+  if (uri.startsWith('http://') || uri.startsWith('https://')) {
+    let parsed
+    try {
+      parsed = new URL(uri)
+    } catch (err) {
+      throw new RedDBError('UNPARSEABLE_URI', `failed to parse '${uri}': ${err.message}`)
+    }
+    return {
+      kind: parsed.protocol === 'https:' ? 'https' : 'http',
+      host: parsed.hostname,
+      port: parsed.port ? Number(parsed.port) : defaultPortFor(parsed.protocol === 'https:' ? 'https' : 'http'),
+      path: parsed.pathname !== '/' ? parsed.pathname : undefined,
+      username: parsed.username ? decodeURIComponent(parsed.username) : undefined,
+      password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
+      token: parsed.searchParams.get('token') ?? undefined,
+      apiKey: parsed.searchParams.get('apiKey') ?? undefined,
+      params: parsed.searchParams,
+      originalUri: uri,
+    }
+  }
+  throw new RedDBError(
+    'UNSUPPORTED_SCHEME',
+    `unsupported URI: '${uri}'. Use 'red://...' or one of memory://, file://, grpc://, http(s)://`,
+  )
+}
+
+function resolveKind(protoQueryParam) {
+  switch (protoQueryParam) {
+    case '':
+    case 'red':
+      return 'red'
+    case 'reds':
+      return 'reds'
+    case 'grpc':
+      return 'grpc'
+    case 'grpcs':
+      return 'grpcs'
+    case 'http':
+      return 'http'
+    case 'https':
+      return 'https'
+    case 'pg':
+    case 'postgres':
+    case 'postgresql':
+      return 'pg'
+    default:
+      throw new RedDBError(
+        'UNSUPPORTED_PROTO',
+        `unknown proto='${protoQueryParam}'. Supported: red | reds | grpc | grpcs | http | https | pg`,
+      )
+  }
+}
+
+function defaultPortFor(kind) {
+  switch (kind) {
+    case 'http':
+      return 8080
+    case 'https':
+      return 8443
+    case 'red':
+    case 'reds':
+    case 'redwire':
+      return 5050
+    case 'grpc':
+      return 5055
+    case 'grpcs':
+      return 5056
+    case 'pg':
+    case 'postgres':
+    case 'postgresql':
+      return 5432
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Derive the HTTP login URL (`/auth/login`) from a parsed URI.
+ * Used by the auto-login flow when the user supplies `username:password@`
+ * but not an explicit `loginUrl`.
+ *
+ * Strategy: if proto is already http/https, just append `/auth/login`.
+ * For grpc/grpcs/pg, default to https://host:443 — operators that
+ * don't want that should pass `loginUrl=` explicitly.
+ */
+export function deriveLoginUrl(parsed) {
+  if (parsed.loginUrl) return parsed.loginUrl
+  if (!parsed.host) {
+    throw new RedDBError(
+      'AUTH_LOGIN_NEEDS_HOST',
+      'cannot derive loginUrl without a host; pass it explicitly via loginUrl=...',
+    )
+  }
+  if (parsed.kind === 'http' || parsed.kind === 'https') {
+    const scheme = parsed.kind
+    const port = parsed.port ?? defaultPortFor(parsed.kind)
+    return `${scheme}://${parsed.host}:${port}/auth/login`
+  }
+  // Non-HTTP transports — default to HTTPS on 443 unless the user
+  // tells us otherwise.
+  return `https://${parsed.host}/auth/login`
+}

package/src/embedded-rejection.js

@@ -1,90 +1,12 @@
 /**
- * Embedded-URI rejection for the thin remote-only client.
- *
- * The `@reddb-io/client` package ships only the `red_client` binary,
- * which has no embedded engine. Any URI that asks for an in-memory
- * or file-backed database must be rejected at parse time with the
- * same wording the Rust `red_client` binary prints, so users get a
- * uniform error across language drivers and the CLI.
- *
- * Mirrors `is_embedded_uri` in
- * `crates/reddb-client/src/bin/red_client.rs` (the rejected forms):
- *
- *   "red://"          — bare red:// with no host
- *   "red:"            — degenerate
- *   "red:///"         — explicit empty path
- *   "red:///<path>"   — any red:// URL with a leading-slash path
- *   "red://:memory"   — SQLite-style alias
- *   "red://:memory:"  — SQLite-style alias
- *
- * The legacy `memory://`, `memory:`, and `file://<path>` schemes are
- * also rejected because they were always shorthand for the embedded
- * engine.
+ * Compatibility shim. The embedded-URI rejection logic now lives in the
+ * transport-agnostic core (`core/embedded-rejection.js`); this file keeps
+ * the historical `./embedded-rejection.js` import path working.
  */
 
-import { RedDBError } from './protocol.js'
-
-/** Wording is intentionally identical to the Rust binary stderr message. */
-export const EMBEDDED_REJECTION_MESSAGE =
-  'embedded schemes (memory:// / file://) are not supported.\n'
-  + 'Use the full `red` binary for in-memory or file-backed engines.'
-
-/**
- * Specialised error raised when an embedded URI is passed to the
- * thin client. Always carries `code === 'EmbeddedNotSupported'` and
- * the wording from `EMBEDDED_REJECTION_MESSAGE`, surfacing the same
- * actionable hint as the underlying Rust binary.
- */
-export class EmbeddedNotSupported extends RedDBError {
-  constructor(uri) {
-    super('EmbeddedNotSupported', EMBEDDED_REJECTION_MESSAGE, { uri })
-    this.name = 'EmbeddedNotSupported'
-    this.uri = uri
-  }
-}
-
-/**
- * Return true when `uri` selects the embedded engine.
- *
- * @param {string} uri
- * @returns {boolean}
- */
-export function isEmbeddedUri(uri) {
-  if (typeof uri !== 'string') return false
-  const trimmed = uri.trim()
-  if (
-    trimmed === 'red://'
-    || trimmed === 'red:'
-    || trimmed === 'red:/'
-    || trimmed === 'red:///'
-    || trimmed === 'red://:memory'
-    || trimmed === 'red://:memory:'
-  ) {
-    return true
-  }
-  // Any `red:///<path>` form is the embedded persistent engine.
-  if (trimmed.startsWith('red:///')) return true
-  // Legacy shorthands that always meant embedded.
-  if (trimmed === 'memory://' || trimmed === 'memory:') return true
-  if (trimmed.startsWith('file://')) return true
-  return false
-}
-
-/**
- * Throws `EmbeddedNotSupported` if `uri` is an embedded shape.
- * Otherwise returns the trimmed URI for downstream consumption.
- *
- * @param {string} uri
- * @returns {string}
- */
-export function rejectEmbeddedUri(uri) {
-  if (typeof uri !== 'string' || uri.length === 0) {
-    throw new TypeError(
-      "connect() requires a URI string (e.g. 'red://localhost:5050' or 'grpc://host:5055')",
-    )
-  }
-  if (isEmbeddedUri(uri)) {
-    throw new EmbeddedNotSupported(uri)
-  }
-  return uri.trim()
-}
+export {
+  EMBEDDED_REJECTION_MESSAGE,
+  EmbeddedNotSupported,
+  isEmbeddedUri,
+  rejectEmbeddedUri,
+} from './core/embedded-rejection.js'

package/src/http.js

@@ -37,6 +37,7 @@
  */
 
 import { RedDBError } from './protocol.js'
+import { classifyNdjsonFrame, splitLines } from './core/ndjson.js'
 
 export class HttpRpcClient {
   /**
@@ -87,6 +88,196 @@ export class HttpRpcClient {
     }
     return { ...init, headers }
   }
+
+  authHeaders(extra = {}) {
+    const headers = new Headers(extra)
+    if (this.token && !headers.has('authorization')) {
+      headers.set('authorization', `Bearer ${this.token}`)
+    }
+    return headers
+  }
+
+  /**
+   * Open a streaming read against `POST /query/stream`. Returns an async
+   * iterable of typed frames (see streaming.js) plus a `cancel(reason)`
+   * that aborts the underlying fetch. A non-streaming refusal (e.g. a
+   * non-read-only statement) is surfaced as a rejected `RedDBError`
+   * before any frame is yielded, so callers can tell "never accepted"
+   * from a mid-stream failure.
+   *
+   * @param {{ sql?: string, cursor?: string, signal?: AbortSignal }} opts
+   */
+  async streamSelect({ sql, cursor, signal } = {}) {
+    const controller = new AbortController()
+    linkSignal(signal, controller)
+    const body = cursor != null ? { cursor } : { query: sql }
+    const response = await fetch(`${this.baseUrl}/query/stream`, {
+      method: 'POST',
+      headers: this.authHeaders({ 'content-type': 'application/json' }),
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+    if (!response.ok) {
+      await throwHttpStreamRefusal(response)
+    }
+    const reader = response.body?.getReader()
+    if (!reader) {
+      throw new RedDBError('STREAM_PROTOCOL', 'streaming response had no body')
+    }
+    return {
+      [Symbol.asyncIterator]() {
+        return ndjsonFrameIterator(reader, controller)
+      },
+      async cancel() {
+        controller.abort()
+        try {
+          await reader.cancel()
+        } catch {
+          // best-effort
+        }
+      },
+    }
+  }
+
+  /**
+   * Open a streaming write against `POST /streams/input`. The request
+   * body is an NDJSON stream: an `open` frame (target + columns), then
+   * one `row` frame per record. Backpressure flows through the request
+   * body's writer. The terminal envelope is returned by `close()`.
+   *
+   * @param {{ target: string, columns?: string[], signal?: AbortSignal }} opts
+   */
+  async streamInput({ target, columns, signal } = {}) {
+    const controller = new AbortController()
+    linkSignal(signal, controller)
+    const transform = new TransformStream()
+    const writer = transform.writable.getWriter()
+    const fetchPromise = fetch(`${this.baseUrl}/streams/input`, {
+      method: 'POST',
+      headers: this.authHeaders({ 'content-type': 'application/x-ndjson' }),
+      body: transform.readable,
+      duplex: 'half',
+      signal: controller.signal,
+    })
+    // Surface a connection/refusal failure on the write path too, rather
+    // than leaving the promise unhandled if the caller never calls close().
+    fetchPromise.catch(() => {})
+
+    let opened = false
+    let cols = Array.isArray(columns) && columns.length > 0 ? columns.slice() : null
+    const encodeLine = (obj) => writer.write(`${JSON.stringify(obj)}\n`)
+    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 writer.write(`${JSON.stringify({ open: { target, columns: cols } })}\n`)
+      opened = true
+    }
+
+    return {
+      async write(row) {
+        await ensureOpen(row)
+        await writer.ready
+        await encodeLine({ row })
+      },
+      async close() {
+        await ensureOpen(null)
+        await writer.close()
+        const response = await fetchPromise
+        return await readInputTerminal(response)
+      },
+      async cancel(reason) {
+        controller.abort()
+        try {
+          await writer.abort(reason)
+        } catch {
+          // best-effort — the abort above already tore the request down.
+        }
+      },
+    }
+  }
+}
+
+function linkSignal(signal, controller) {
+  if (!signal) return
+  if (signal.aborted) {
+    controller.abort(signal.reason)
+    return
+  }
+  signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true })
+}
+
+async function throwHttpStreamRefusal(response) {
+  const text = await response.text().catch(() => '')
+  let body = null
+  if (text) {
+    try {
+      body = JSON.parse(text)
+    } catch {
+      body = { raw: text }
+    }
+  }
+  const code = body?.code || body?.error_code || `HTTP_${response.status}`
+  const message =
+    body?.error || body?.message || `stream refused with status ${response.status}`
+  throw new RedDBError(code, message, body)
+}
+
+/** Async iterator over NDJSON frames from a web ReadableStream reader. */
+async function* ndjsonFrameIterator(reader, controller) {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  try {
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const { lines, rest } = splitLines(buffer)
+      buffer = rest
+      for (const line of lines) {
+        const frame = classifyNdjsonFrame(line)
+        if (frame) yield frame
+      }
+    }
+    const tail = buffer + decoder.decode()
+    const frame = classifyNdjsonFrame(tail)
+    if (frame) yield frame
+  } finally {
+    controller.abort()
+  }
+}
+
+/** Read the input-stream response body and return its terminal envelope. */
+async function readInputTerminal(response) {
+  const text = await response.text()
+  if (!response.ok) {
+    let body = null
+    try {
+      body = text ? JSON.parse(text) : null
+    } catch {
+      body = { raw: text }
+    }
+    const code = body?.code || body?.error_code || `HTTP_${response.status}`
+    const message = body?.error || body?.message || `input stream failed (${response.status})`
+    throw new RedDBError(code, message, body)
+  }
+  const lines = text.split('\n').map((l) => l.trim()).filter((l) => l.length > 0)
+  let end = null
+  for (const line of lines) {
+    const frame = classifyNdjsonFrame(line) // throws RedDBError on an {error} frame
+    if (frame && frame.type === 'end') end = frame.value
+  }
+  if (!end) {
+    throw new RedDBError('STREAM_PROTOCOL', 'input stream closed without a terminal end envelope')
+  }
+  return end
 }
 
 async function parseResponse(response) {