@reddb-io/client 1.7.0 → 1.8.0

package/src/core/auth.js

@@ -0,0 +1,102 @@
+/**
+ * Authentication helpers shared across transports.
+ *
+ *   - `login()`            — username/password → bearer-token exchange over
+ *                            the server's `POST /auth/login` HTTP endpoint.
+ *   - `mergeAuthFromUri()` — fold credentials parsed from the connection
+ *                            URI together with caller-supplied `options.auth`.
+ *
+ * Uses the global `fetch`; imports zero `node:` built-ins.
+ */
+
+import { RedDBError } from './errors.js'
+
+/**
+ * Exchange username + password for a bearer token via the server's
+ * `POST /auth/login` HTTP endpoint. Same flow used by `connect()` when
+ * the caller passes `auth: { username, password }`.
+ *
+ * @param {string} loginUrl Full URL of the server's auth endpoint.
+ * @param {{ username: string, password: string }} credentials
+ * @returns {Promise<{ token: string, username: string, role: string, expires_at: number }>}
+ */
+export async function login(loginUrl, { username, password }) {
+  if (typeof loginUrl !== 'string' || !loginUrl.startsWith('http')) {
+    throw new TypeError("login() requires an http(s):// URL pointing at /auth/login")
+  }
+  if (typeof username !== 'string' || username.length === 0) {
+    throw new TypeError('login() requires a non-empty username')
+  }
+  if (typeof password !== 'string' || password.length === 0) {
+    throw new TypeError('login() requires a non-empty password')
+  }
+  const response = await fetch(loginUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ username, password }),
+  })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok || body.ok === false) {
+    const code = body.error_code || `HTTP_${response.status}`
+    const message = body.error || `auth/login returned ${response.status}`
+    throw new RedDBError(code, message, body)
+  }
+  if (typeof body.token !== 'string') {
+    throw new RedDBError(
+      'AUTH_LOGIN_BAD_RESPONSE',
+      'auth/login response missing string token',
+      body,
+    )
+  }
+  return body
+}
+
+/**
+ * Fold credentials carried on the parsed URI together with the
+ * caller-supplied `options.auth`. `options.auth` wins on every field it
+ * sets; URI-derived values are the fallback. Returns a normalised
+ * `{ token, username, password, loginUrl }` shape.
+ *
+ * @param {object} parsed result of `parseUri()`.
+ * @param {object} [optionAuth] caller-supplied `options.auth`.
+ */
+export function mergeAuthFromUri(parsed, optionAuth) {
+  const out = {
+    token: parsed.token ?? parsed.apiKey ?? null,
+    username: parsed.username ?? null,
+    password: parsed.password ?? null,
+    loginUrl: parsed.loginUrl ?? null,
+  }
+  if (optionAuth == null) return out
+  if (typeof optionAuth !== 'object') {
+    throw new TypeError('options.auth must be an object')
+  }
+  if (optionAuth.token != null) {
+    if (typeof optionAuth.token !== 'string' || optionAuth.token.length === 0) {
+      throw new TypeError('options.auth.token must be a non-empty string')
+    }
+    out.token = optionAuth.token
+  }
+  if (optionAuth.apiKey != null) {
+    if (typeof optionAuth.apiKey !== 'string' || optionAuth.apiKey.length === 0) {
+      throw new TypeError('options.auth.apiKey must be a non-empty string')
+    }
+    out.token = optionAuth.apiKey
+  }
+  if (optionAuth.username != null) {
+    if (typeof optionAuth.username !== 'string' || optionAuth.username.length === 0) {
+      throw new TypeError('options.auth.username must be a non-empty string')
+    }
+    out.username = optionAuth.username
+  }
+  if (optionAuth.password != null) {
+    if (typeof optionAuth.password !== 'string' || optionAuth.password.length === 0) {
+      throw new TypeError('options.auth.password must be a non-empty string')
+    }
+    out.password = optionAuth.password
+  }
+  if (optionAuth.loginUrl != null) {
+    out.loginUrl = optionAuth.loginUrl
+  }
+  return out
+}

package/src/core/embedded-rejection.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+
+import { RedDBError } from './errors.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()
+}

package/src/core/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Transport-agnostic error type shared by the whole driver.
+ *
+ * Lives in the core so every core module (serialization, auth, NDJSON
+ * helpers, the connection handle) can raise it without reaching for a
+ * transport-specific module. Imports zero `node:` built-ins.
+ */
+
+/**
+ * RedDB-shaped error. Drivers in other languages should expose an
+ * equivalent class with the same `code` field.
+ */
+export class RedDBError extends Error {
+  constructor(code, message, data) {
+    super(message)
+    this.name = 'RedDBError'
+    this.code = code
+    this.data = data ?? null
+  }
+}

package/src/core/index.js

@@ -0,0 +1,43 @@
+/**
+ * Transport-agnostic core of `@reddb-io/client`.
+ *
+ * Everything re-exported here is pure JS with **zero `node:` imports**: the
+ * `RedDB` connection handle (and `Collection` / transaction handles), SQL
+ * parameter serialization, the `login()` / auth-merge credential flow,
+ * insert-id normalization, embedded-URI rejection, the `red://` URL parser,
+ * and the NDJSON frame helpers.
+ *
+ * Streaming is injected, not imported: `RedDB` takes a streaming
+ * implementation as a constructor argument (see `core/reddb.js`). The Node
+ * entry (`../index.js`) supplies the `node:stream`-based one. A browser
+ * entry (separate slice) builds on this same seam.
+ */
+
+export { RedDBError } from './errors.js'
+export { RedDB, Collection } from './reddb.js'
+export {
+  serializeParam,
+  assertSupportedParam,
+  normalizeQueryParams,
+  bytesToBase64,
+  isUuidString,
+} from './serialization.js'
+export { login, mergeAuthFromUri } from './auth.js'
+export {
+  MIN_INSERT_ID_ENGINE_VERSION,
+  requireInsertId,
+  requireInsertIds,
+} from './insert-ids.js'
+export { classifyNdjsonFrame, splitLines } from './ndjson.js'
+export {
+  EMBEDDED_REJECTION_MESSAGE,
+  EmbeddedNotSupported,
+  isEmbeddedUri,
+  rejectEmbeddedUri,
+} from './embedded-rejection.js'
+export {
+  parseUri,
+  parseRedUrl,
+  parseLegacyUrl,
+  deriveLoginUrl,
+} from './url.js'

package/src/core/insert-ids.js

@@ -0,0 +1,45 @@
+/**
+ * Insert-id normalization for `insert()` / `bulkInsert()` results.
+ *
+ * The server returns either `rid`/`rids` (current) or `id`/`ids` (legacy);
+ * these helpers mirror one onto the other so callers see both, and raise
+ * `ENGINE_TOO_OLD` when neither is present. Imports zero `node:` built-ins.
+ */
+
+import { RedDBError } from './errors.js'
+
+export const MIN_INSERT_ID_ENGINE_VERSION = '1.0.9'
+
+export function requireInsertId(result, method) {
+  if (!result || typeof result !== 'object' || (result.rid == null && result.id == null)) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `${method}() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with insert id support`,
+    )
+  }
+  if (result.rid == null) result.rid = result.id
+  if (result.id == null) result.id = result.rid
+  return result
+}
+
+export function requireInsertIds(result, expected) {
+  if (
+    !result ||
+    typeof result !== 'object' ||
+    (!Array.isArray(result.rids) && !Array.isArray(result.ids))
+  ) {
+    throw new RedDBError(
+      'ENGINE_TOO_OLD',
+      `bulkInsert() requires RedDB engine >= ${MIN_INSERT_ID_ENGINE_VERSION} with bulk insert id support`,
+    )
+  }
+  if (!Array.isArray(result.rids)) result.rids = result.ids
+  if (!Array.isArray(result.ids)) result.ids = result.rids
+  if (result.rids.length !== expected) {
+    throw new RedDBError(
+      'INVALID_RESPONSE',
+      `bulkInsert() expected ${expected} rids, got ${result.rids.length}`,
+    )
+  }
+  return result
+}

package/src/core/ndjson.js

@@ -0,0 +1,59 @@
+/**
+ * Pure-JS NDJSON frame helpers shared by every text-framed transport.
+ *
+ *   - `classifyNdjsonFrame()` — parse one NDJSON line into a typed
+ *     read-session frame (`descriptor` / `cursor` / `row` / `end`), throwing
+ *     `RedDBError` on an `{error}` frame or unrecognised shape.
+ *   - `splitLines()` — split a text buffer on `\n` into complete lines plus
+ *     the trailing remainder, the building block for incremental NDJSON
+ *     readers.
+ *
+ * Imports zero `node:` built-ins — no `node:stream`, no `Buffer`.
+ */
+
+import { RedDBError } from './errors.js'
+
+/**
+ * Parse an NDJSON line into a typed read-session frame, or `null` for a
+ * blank line. Shared by the HTTP and any text-framed transport.
+ * @param {string} line
+ * @returns {{type:string,value:unknown}|null}
+ */
+export function classifyNdjsonFrame(line) {
+  const trimmed = line.trim()
+  if (trimmed.length === 0) return null
+  let parsed
+  try {
+    parsed = JSON.parse(trimmed)
+  } catch (err) {
+    throw new RedDBError('STREAM_PROTOCOL', `stream frame is not JSON: ${err.message}`)
+  }
+  if (parsed && typeof parsed === 'object') {
+    if ('descriptor' in parsed) return { type: 'descriptor', value: parsed.descriptor }
+    if ('cursor' in parsed) return { type: 'cursor', value: parsed.cursor }
+    if ('row' in parsed) return { type: 'row', value: parsed.row }
+    if ('end' in parsed) return { type: 'end', value: parsed.end }
+    if ('error' in parsed) {
+      const e = parsed.error ?? {}
+      throw new RedDBError(e.code || 'STREAM_ERROR', e.message || 'stream error', e)
+    }
+  }
+  throw new RedDBError('STREAM_PROTOCOL', `unrecognised stream frame: ${trimmed.slice(0, 120)}`)
+}
+
+/**
+ * Split a text buffer on `\n` into complete lines plus the trailing
+ * remainder (the text after the last newline, which may be a partial
+ * line awaiting more bytes). Pure — no I/O, no streams.
+ * @param {string} buffer
+ * @returns {{ lines: string[], rest: string }}
+ */
+export function splitLines(buffer) {
+  const lines = []
+  let nl
+  while ((nl = buffer.indexOf('\n')) !== -1) {
+    lines.push(buffer.slice(0, nl))
+    buffer = buffer.slice(nl + 1)
+  }
+  return { lines, rest: buffer }
+}

package/src/core/reddb.js

@@ -0,0 +1,314 @@
+/**
+ * Transport-agnostic connection handle.
+ *
+ * `RedDB` and its `Collection` / transaction handles own the request
+ * shaping (parameter serialization, insert-id normalization, transaction
+ * orchestration) that is identical regardless of which wire the underlying
+ * `client` speaks. The class is constructed with a low-level transport
+ * `client` (anything exposing `call(method, params)` / `close()`, and
+ * optionally `streamSelect` / `streamInput`) plus an injected `streaming`
+ * implementation.
+ *
+ * Streaming is **injected**, never imported: `stream()` / `inputStream()`
+ * delegate to `streaming.createSelectStream` / `streaming.createInputStream`
+ * supplied by the entrypoint, so this module never statically references
+ * `node:stream` (or Web streams). A connection built without a streaming
+ * implementation raises `STREAMING_UNSUPPORTED` if a stream is requested.
+ *
+ * Imports zero `node:` built-ins.
+ */
+
+import { RedDBError } from './errors.js'
+import { normalizeQueryParams } from './serialization.js'
+import { requireInsertId, requireInsertIds } from './insert-ids.js'
+import { CacheClient } from '../cache.js'
+import { KvClient } from '../kv.js'
+import { QueueClient } from '../queue.js'
+import { DocumentClient } from '../documents.js'
+import { ConfigClient } from '../config.js'
+import { VaultClient } from '../vault.js'
+import { TypedQueryBuilder, collectionExists, listCollections } from '../db-helpers.js'
+
+const NESTED_TX_NOT_SUPPORTED = 'NESTED_TX_NOT_SUPPORTED'
+
+/**
+ * Connection handle. Methods map 1:1 to JSON-RPC methods on the server.
+ * Identical surface to `@reddb-io/sdk`'s `RedDB`, minus the local-spawn
+ * lifecycle.
+ */
+class TransactionHandle {
+  constructor(db) {
+    this.db = db
+  }
+
+  query(sql, ...params) {
+    return this.db.query(sql, ...params)
+  }
+
+  execute(sql, ...params) {
+    return this.db.execute(sql, ...params)
+  }
+
+  insert(collection, payload) {
+    return this.db.insert(collection, payload)
+  }
+
+  bulkInsert(collection, payloads) {
+    return this.db.bulkInsert(collection, payloads)
+  }
+
+  async transaction() {
+    throw nestedTransactionError()
+  }
+}
+
+/**
+ * A streaming-capable collection/table handle (PRD #759 S11). `query()`
+ * stays a one-shot Promise so callers never accidentally pay streaming
+ * overhead for small reads; `stream()` / `inputStream()` are the explicit
+ * streaming surfaces. The bound `name` is the default ingest target.
+ */
+export class Collection {
+  /** @param {RedDB} db @param {string} name */
+  constructor(db, name) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new RedDBError('INVALID_COLLECTION', 'collection(name) requires a non-empty name')
+    }
+    this.db = db
+    this.name = name
+  }
+
+  /** One-shot Promise query — no streaming surface leakage. */
+  query(sql, ...params) {
+    return this.db.query(sql, ...params)
+  }
+
+  /** Stream a read-only SELECT as a Readable/AsyncIterable. */
+  stream(sql, opts = {}) {
+    return this.db.stream(sql, opts)
+  }
+
+  /** Open a streaming write into this collection. */
+  inputStream(opts = {}) {
+    return this.db.inputStream(this.name, opts)
+  }
+}
+
+export class RedDB {
+  /**
+   * @param {object} client transport exposing `call`/`close` (and optionally
+   *   `streamSelect`/`streamInput`).
+   * @param {{ createSelectStream: Function, createInputStream: Function }} [streaming]
+   *   injected streaming implementation. The entrypoint supplies the
+   *   `node:stream`-based one; omit it for transports that never stream.
+   */
+  constructor(client, streaming) {
+    this.client = client
+    this._streaming = streaming ?? null
+    this.cache = new CacheClient(client)
+    this.queue = new QueueClient(client)
+    this.documents = new DocumentClient(this)
+    const defaultKv = new KvClient(client)
+    this.kv = Object.assign((collection = 'kv_default') => new KvClient(client, collection), {
+      put: defaultKv.put.bind(defaultKv),
+      invalidateTags: defaultKv.invalidateTags.bind(defaultKv),
+      watch: defaultKv.watch.bind(defaultKv),
+      watchPrefix: defaultKv.watchPrefix.bind(defaultKv),
+    })
+    this.config = (collection = 'red.config') => new ConfigClient(client, collection)
+    this.vault = (collection = 'red.vault') => new VaultClient(client, collection)
+    this.inTransaction = false
+  }
+
+  /** Execute a SQL query. Returns `{ statement, affected, columns, rows }`. */
+  query(sql, ...params) {
+    const wireParams = normalizeQueryParams(params)
+    if (wireParams == null) {
+      return this.client.call('query', { sql })
+    }
+    return this.client.call('query', { sql, params: wireParams })
+  }
+
+  /** Execute a SQL statement. Alias for `query`, including parameter binding. */
+  execute(sql, ...params) {
+    return this.query(sql, ...params)
+  }
+
+  /** Insert one row. Returns `{ affected, rid, id }`; `id` is a legacy alias for `rid`. */
+  async insert(collection, payload) {
+    let result = await this.client.call('insert', { collection, payload })
+    if (
+      result &&
+      typeof result === 'object' &&
+      !('affected' in result) &&
+      ('rid' in result || 'id' in result)
+    ) {
+      result = { ...result, affected: 1 }
+    }
+    return requireInsertId(result, 'insert')
+  }
+
+  /** Insert many rows in one call. Returns `{ affected, rids, ids }`; `ids` is a legacy alias. */
+  async bulkInsert(collection, payloads) {
+    const result = await this.client.call('bulk_insert', { collection, payloads })
+    return requireInsertIds(result, payloads.length)
+  }
+
+  async transaction(callback) {
+    if (this.inTransaction) {
+      throw nestedTransactionError()
+    }
+    if (typeof callback !== 'function') {
+      throw new TypeError('transaction(callback) requires a function')
+    }
+
+    this.inTransaction = true
+    let began = false
+    try {
+      await this.query('BEGIN')
+      began = true
+      const result = await callback(new TransactionHandle(this))
+      await this.query('COMMIT')
+      return result
+    } catch (err) {
+      if (began) {
+        try {
+          await this.query('ROLLBACK')
+        } catch (rollbackErr) {
+          attachRollbackError(err, rollbackErr)
+        }
+      }
+      throw err
+    } finally {
+      this.inTransaction = false
+    }
+  }
+
+  /** Return true when a collection is visible in the catalog. */
+  exists(collection) {
+    return collectionExists(this, collection)
+  }
+
+  /** List visible collections using SHOW COLLECTIONS. */
+  list() {
+    return listCollections(this)
+  }
+
+  /** Return a caller-typed query builder for a collection. */
+  from(collection) {
+    return new TypedQueryBuilder(this, collection)
+  }
+
+  /**
+   * Return a streaming-capable handle for a collection/table. Exposes the
+   * explicit method separation of PRD #759: `.query()` is a one-shot
+   * Promise, `.stream()` is a streaming Readable, `.inputStream()` is a
+   * streaming Writable. The collection name binds the ingest target.
+   */
+  collection(name) {
+    return new Collection(this, name)
+  }
+
+  /**
+   * Stream a read-only SELECT. Returns a Node `Readable` in object mode
+   * that also conforms to `AsyncIterable<Row>`. Uses RedWire when the
+   * connection is RedWire, HTTP NDJSON when it is HTTP — identical surface
+   * either way. Call `.cancel(reason?)` to terminate mid-stream.
+   *
+   * Delegates to the injected streaming implementation.
+   */
+  stream(sql, opts = {}) {
+    return this.#streaming().createSelectStream(this.client, sql, opts)
+  }
+
+  /**
+   * Open a streaming write into `target`. Returns a Node `Writable` in
+   * object mode whose `.completion()` resolves with the server's terminal
+   * envelope. Call `.cancel(reason?)` to abandon the ingest.
+   *
+   * Delegates to the injected streaming implementation.
+   */
+  inputStream(target, opts = {}) {
+    return this.#streaming().createInputStream(this.client, target, opts)
+  }
+
+  #streaming() {
+    if (!this._streaming) {
+      throw new RedDBError(
+        'STREAMING_UNSUPPORTED',
+        'this connection was built without a streaming implementation',
+      )
+    }
+    return this._streaming
+  }
+
+  /** Get an entity by id. Returns `{ entity }` (entity is `null` if not found). */
+  get(collection, id) {
+    return this.client.call('get', { collection, id: String(id) })
+  }
+
+  /** Delete an entity by id. Returns `{ affected }`. */
+  delete(collection, id) {
+    return this.client.call('delete', { collection, id: String(id) })
+  }
+
+  /** Probe the server. Returns `{ ok: true, version }`. */
+  health() {
+    return this.client.call('health', {})
+  }
+
+  /** Server version + protocol version. */
+  version() {
+    return this.client.call('version', {})
+  }
+
+  /** Exchange username + password for a bearer token. */
+  login(username, password) {
+    return this.client.call('auth.login', { username, password })
+  }
+
+  /** Identify the current caller. */
+  whoami() {
+    return this.client.call('auth.whoami', {})
+  }
+
+  /** Change the current caller's password. */
+  changePassword(currentPassword, newPassword) {
+    return this.client.call('auth.change_password', {
+      current_password: currentPassword,
+      new_password: newPassword,
+    })
+  }
+
+  /** Mint a long-lived API key. */
+  createApiKey({ username, role } = {}) {
+    return this.client.call('auth.create_api_key', { username, role })
+  }
+
+  /** Revoke an API key by its public id. */
+  revokeApiKey(key) {
+    return this.client.call('auth.revoke_api_key', { key })
+  }
+
+  /** Close the underlying transport. */
+  close() {
+    return this.client.close()
+  }
+}
+
+function nestedTransactionError() {
+  return new RedDBError(
+    NESTED_TX_NOT_SUPPORTED,
+    `${NESTED_TX_NOT_SUPPORTED}: nested transactions are not supported on one connection`,
+  )
+}
+
+function attachRollbackError(err, rollbackErr) {
+  if (err && typeof err === 'object') {
+    try {
+      err.rollbackError = rollbackErr
+    } catch {
+      // Preserve the original callback/query error even for frozen errors.
+    }
+  }
+}