@reddb-io/sdk 1.0.1

package/src/binary.js

@@ -0,0 +1,66 @@
+/**
+ * Locate the `red` binary for SDK / CLI use.
+ *
+ * SDK lookup (`resolveSdkBinary`):
+ *   1. `REDDB_BIN` env var (the canonical override per ADR 0006).
+ *   2. `REDDB_BINARY_PATH` env var (legacy alias, deprecation window).
+ *   3. `<package>/bin/red[.exe]` — where postinstall.js dropped it.
+ *   4. Otherwise throw an actionable error.
+ *
+ *   PATH is **never** consulted. The wire-format coupling between the
+ *   SDK and the embedded engine is too tight to silently bind to
+ *   whatever `red` happens to be on PATH (see ADR 0006).
+ *
+ * CLI lookup (`resolveCliBinary`):
+ *   1. `REDDB_BIN` env var.
+ *   2. `<package>/bin/red[.exe]`.
+ *   3. PATH-resolved bare `red[.exe]` — appropriate for the CLI which
+ *      *targets* PATH.
+ */
+
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+
+import { resolveBin } from './internal/bin-resolver/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = resolve(HERE, '..')
+
+function defaultBinaryName() {
+  if (typeof process !== 'undefined' && process.platform === 'win32') {
+    return 'red.exe'
+  }
+  return 'red'
+}
+
+/** SDK runtime lookup. Throws actionable error when binary cannot be located. */
+export function resolveSdkBinary() {
+  const legacy = process.env?.REDDB_BINARY_PATH
+  if (typeof legacy === 'string' && legacy !== '' && !process.env?.REDDB_BIN) {
+    return legacy
+  }
+  return resolveBin({
+    name: defaultBinaryName(),
+    packageRoot: PACKAGE_ROOT,
+    envVar: 'REDDB_BIN',
+  })
+}
+
+/** CLI runtime lookup. Allowed to fall back to PATH per ADR 0006. */
+export function resolveCliBinary() {
+  const override = process.env?.REDDB_BIN
+  if (typeof override === 'string' && override !== '') {
+    return override
+  }
+  const local = join(PACKAGE_ROOT, 'bin', defaultBinaryName())
+  if (existsSync(local)) {
+    return local
+  }
+  return defaultBinaryName()
+}
+
+/** Used by postinstall.js to know where to drop the downloaded binary. */
+export function packageBinaryDir() {
+  return join(PACKAGE_ROOT, 'bin')
+}

package/src/cache.js

@@ -0,0 +1,137 @@
+/**
+ * Cache client — exposes cache.{get,put,exists,invalidate,invalidatePrefix,
+ * invalidateTags,flushNamespace} via the underlying HTTP transport.
+ *
+ * NOTE: These methods require server-side HTTP endpoints under /cache/ns/*.
+ * flushNamespace routes to the existing POST /admin/blob_cache/flush_namespace.
+ * All others target endpoints planned for a future server release.
+ *
+ * Values are base64-encoded in transit so binary payloads survive JSON.
+ */
+
+export class CacheClient {
+  /** @param {{ call: Function }} client */
+  constructor(client) {
+    this._client = client
+  }
+
+  /**
+   * Fetch a cached value. Returns a Uint8Array on hit, null on miss.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async get(namespace, key) {
+    const result = await this._client.call('cache.get', { namespace, key })
+    if (result == null || result.value == null) return null
+    return base64ToBytes(result.value)
+  }
+
+  /**
+   * Store a value in the cache.
+   * @param {string} namespace
+   * @param {string} key
+   * @param {Uint8Array | Buffer | string} value  String is UTF-8 encoded.
+   * @param {object} [opts]
+   * @param {number} [opts.ttl_ms]
+   * @param {string[]} [opts.tags]
+   * @param {object} [opts.policy]
+   * @returns {Promise<void>}
+   */
+  async put(namespace, key, value, opts = {}) {
+    const encoded = bytesToBase64(value)
+    await this._client.call('cache.put', {
+      namespace,
+      key,
+      value: encoded,
+      ...opts,
+    })
+  }
+
+  /**
+   * Check whether a key is present.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<'present' | 'absent' | 'maybe'>}
+   */
+  async exists(namespace, key) {
+    const result = await this._client.call('cache.exists', { namespace, key })
+    return result?.status ?? 'maybe'
+  }
+
+  /**
+   * Remove a single entry.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async invalidate(namespace, key) {
+    await this._client.call('cache.invalidate', { namespace, key })
+  }
+
+  /**
+   * Remove all entries whose key starts with `prefix`.
+   * @param {string} namespace
+   * @param {string} prefix
+   * @returns {Promise<number>} Number of entries removed.
+   */
+  async invalidatePrefix(namespace, prefix) {
+    const result = await this._client.call('cache.invalidate_prefix', { namespace, prefix })
+    return result?.removed ?? 0
+  }
+
+  /**
+   * Remove all entries tagged with any of the given tags.
+   * @param {string} namespace
+   * @param {string[]} tags
+   * @returns {Promise<number>} Number of entries removed.
+   */
+  async invalidateTags(namespace, tags) {
+    const result = await this._client.call('cache.invalidate_tags', { namespace, tags })
+    return result?.removed ?? 0
+  }
+
+  /**
+   * Remove all entries in a namespace.
+   * Routes to POST /admin/blob_cache/flush_namespace (live endpoint).
+   * @param {string} namespace
+   * @returns {Promise<void>}
+   */
+  async flushNamespace(namespace) {
+    await this._client.call('cache.flush_namespace', { namespace })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function bytesToBase64(value) {
+  if (typeof value === 'string') {
+    const bytes = new TextEncoder().encode(value)
+    return bufToBase64(bytes)
+  }
+  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))) {
+    return bufToBase64(value)
+  }
+  throw new TypeError('cache value must be a string, Uint8Array, or Buffer')
+}
+
+function bufToBase64(bytes) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin)
+}
+
+function base64ToBytes(b64) {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(b64, 'base64'))
+  }
+  const bin = atob(b64)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}

package/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { resolveCliBinary } from './binary.js'
+
+const binary = resolveCliBinary()
+const args = process.argv.slice(2)
+
+const child = spawn(binary, args, {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+})
+
+child.on('error', (err) => {
+  process.stderr.write(`reddb-cli: ${err.message}\n`)
+  process.exit(1)
+})
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(1)
+  }
+  process.exit(code ?? 0)
+})

package/src/config.js

@@ -0,0 +1,66 @@
+export class ConfigClient {
+  constructor(client, collection = 'red.config') {
+    this.client = client
+    this.collection = collection
+  }
+
+  put(key, value, options = {}) {
+    rejectVolatileOptions(options, 'config')
+    const collection = options.collection ?? this.collection
+    const tags = Array.isArray(options.tags) && options.tags.length > 0
+      ? ` TAGS [${options.tags.map(keyedStringLiteral).join(', ')}]`
+      : ''
+    return this.client.call('query', {
+      sql: `PUT CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)} = ${configValueLiteral(value, options)}${tags}`,
+    })
+  }
+
+  get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `GET CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)}`,
+    })
+  }
+
+  resolve(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `RESOLVE CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)}`,
+    })
+  }
+}
+
+function configValueLiteral(value, options) {
+  if (options.secretRef) {
+    const { collection, key } = options.secretRef
+    return `SECRET_REF(vault, ${keyedIdentifier(collection)}.${keyedIdentifier(key)})`
+  }
+  return keyedValueLiteral(value)
+}
+
+function rejectVolatileOptions(options, domain) {
+  for (const field of ['ttl', 'ttlMs', 'ttl_ms', 'expireMs', 'expire_ms', 'expiresAt']) {
+    if (options[field] != null) {
+      throw new TypeError(`${domain} does not support TTL or expiration options`)
+    }
+  }
+}
+
+function keyedIdentifier(value) {
+  const out = String(value)
+  if (!/^[A-Za-z0-9_.]+$/.test(out)) {
+    throw new TypeError('keyed collection and key names must use letters, numbers, underscores, or dots')
+  }
+  return out
+}
+
+function keyedValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  if (Array.isArray(value) || typeof value === 'object') return JSON.stringify(value)
+  return keyedStringLiteral(value)
+}
+
+function keyedStringLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/src/http.js

@@ -0,0 +1,200 @@
+/**
+ * HTTP transport for the JS driver.
+ *
+ * Mirrors the public surface of `RpcClient` (call, close) but talks
+ * straight to the RedDB HTTP server via fetch() — no binary spawn.
+ * Each `RedDB` method is mapped to a REST endpoint; method names
+ * stay identical to the JSON-RPC ones so `RedDB` doesn't need to
+ * know which transport it's using.
+ *
+ * Endpoint mapping (server-side defined in src/server/routing.rs):
+ *
+ *   query / explain     → POST /query, POST /query/explain
+ *   insert              → POST /collections/:name/rows
+ *   bulk_insert         → POST /collections/:name/bulk/rows
+ *   get                 → GET  /collections/:name/{id}      (entity scan + filter)
+ *   delete              → DELETE /collections/:name/{id}
+ *   health              → GET  /health
+ *   version             → GET  /admin/version
+ *   auth.login          → POST /auth/login
+ *   auth.whoami         → GET  /auth/whoami
+ *   auth.create_api_key → POST /auth/api-keys
+ *   auth.revoke_api_key → DELETE /auth/api-keys/:key
+ *   auth.change_password→ POST /auth/change-password
+ *
+ *   cache.get               → GET    /cache/ns/:ns/:key
+ *   cache.put               → PUT    /cache/ns/:ns/:key
+ *   cache.exists            → GET    /cache/ns/:ns/:key/exists
+ *   cache.invalidate        → DELETE /cache/ns/:ns/:key
+ *   cache.invalidate_prefix → DELETE /cache/ns/:ns?prefix=...
+ *   cache.invalidate_tags   → DELETE /cache/ns/:ns/tags  (body: {tags})
+ *   cache.flush_namespace   → POST   /admin/blob_cache/flush_namespace
+ *
+ * Auth: every request after construction carries `Authorization:
+ * Bearer <token>` (when set). `setToken(token)` updates it in
+ * place — used by the login flow that exchanges credentials for
+ * a fresh bearer.
+ */
+
+import { RedDBError } from './protocol.js'
+
+export class HttpRpcClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl   Server origin, e.g. 'https://reddb.example.com:8443'
+   * @param {string} [opts.token]   Bearer token / API key
+   */
+  constructor({ baseUrl, token }) {
+    if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
+      throw new TypeError('HttpRpcClient: baseUrl required')
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, '')
+    this.token = token ?? null
+  }
+
+  setToken(token) {
+    this.token = token
+  }
+
+  async close() {
+    // HTTP is stateless — nothing to close.
+  }
+
+  /**
+   * Generic RPC entry point. Routes the named method to the
+   * corresponding HTTP endpoint and returns the parsed JSON body.
+   */
+  async call(method, params = {}) {
+    const route = ROUTES[method]
+    if (!route) {
+      throw new RedDBError(
+        'UNKNOWN_METHOD',
+        `HTTP transport has no route for method '${method}'`,
+      )
+    }
+    const { url, init } = route(this.baseUrl, params)
+    const response = await fetch(url, this.attachAuth(init))
+    return parseResponse(response)
+  }
+
+  attachAuth(init) {
+    const headers = new Headers(init.headers || {})
+    if (this.token && !headers.has('authorization')) {
+      headers.set('authorization', `Bearer ${this.token}`)
+    }
+    if (init.body && !headers.has('content-type')) {
+      headers.set('content-type', 'application/json')
+    }
+    return { ...init, headers }
+  }
+}
+
+async function parseResponse(response) {
+  const text = await response.text()
+  let body = null
+  if (text) {
+    try {
+      body = JSON.parse(text)
+    } catch {
+      body = { raw: text }
+    }
+  }
+  if (!response.ok) {
+    const code = body?.error_code || `HTTP_${response.status}`
+    const message = body?.error || body?.message || `request failed with status ${response.status}`
+    throw new RedDBError(code, message, body)
+  }
+  // RedDB envelope is `{ ok, result, error? }` for some endpoints
+  // and bare JSON for others. Unwrap the envelope when present.
+  if (body && typeof body === 'object' && 'ok' in body) {
+    if (body.ok === false) {
+      const code = body.error_code || 'RPC_ERROR'
+      throw new RedDBError(code, body.error || 'unknown error', body)
+    }
+    return body.result ?? body
+  }
+  return body
+}
+
+// ---------------------------------------------------------------------------
+// Method → HTTP route mapping
+// ---------------------------------------------------------------------------
+
+const ROUTES = {
+  health: (base) => ({ url: `${base}/health`, init: { method: 'GET' } }),
+  version: (base) => ({ url: `${base}/admin/version`, init: { method: 'GET' } }),
+  query: (base, { sql }) => ({
+    url: `${base}/query`,
+    init: { method: 'POST', body: JSON.stringify({ query: sql }) },
+  }),
+  insert: (base, { collection, payload }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/rows`,
+    init: { method: 'POST', body: JSON.stringify(payload) },
+  }),
+  bulk_insert: (base, { collection, payloads }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/bulk/rows`,
+    init: { method: 'POST', body: JSON.stringify({ rows: payloads }) },
+  }),
+  get: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'GET' },
+  }),
+  delete: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.login': (base, { username, password }) => ({
+    url: `${base}/auth/login`,
+    init: { method: 'POST', body: JSON.stringify({ username, password }) },
+  }),
+  'auth.whoami': (base) => ({
+    url: `${base}/auth/whoami`,
+    init: { method: 'GET' },
+  }),
+  'auth.create_api_key': (base, params = {}) => ({
+    url: `${base}/auth/api-keys`,
+    init: { method: 'POST', body: JSON.stringify(params) },
+  }),
+  'auth.revoke_api_key': (base, { key }) => ({
+    url: `${base}/auth/api-keys/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.change_password': (base, { current_password, new_password }) => ({
+    url: `${base}/auth/change-password`,
+    init: {
+      method: 'POST',
+      body: JSON.stringify({
+        current_password,
+        new_password,
+      }),
+    },
+  }),
+  'cache.get': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'GET' },
+  }),
+  'cache.put': (base, { namespace, key, value, ttl_ms, tags, policy }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'PUT', body: JSON.stringify({ value, ttl_ms, tags, policy }) },
+  }),
+  'cache.exists': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}/exists`,
+    init: { method: 'GET' },
+  }),
+  'cache.invalidate': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_prefix': (base, { namespace, prefix }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}?prefix=${encodeURIComponent(prefix)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_tags': (base, { namespace, tags }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/tags`,
+    init: { method: 'DELETE', body: JSON.stringify({ tags }) },
+  }),
+  'cache.flush_namespace': (base, { namespace }) => ({
+    url: `${base}/admin/blob_cache/flush_namespace`,
+    init: { method: 'POST', body: JSON.stringify({ namespace }) },
+  }),
+}