@reddb-io/client 1.0.1

package/README.md

@@ -0,0 +1,97 @@
+# @reddb-io/client
+
+Thin **remote-only** RedDB driver for JavaScript and TypeScript. Speaks
+RedWire (TCP + mTLS), gRPC, and HTTP straight to a remote RedDB
+server. Ships the `red_client` thin binary for an ad-hoc REPL — about
+10x smaller than `@reddb-io/sdk`.
+
+> Embedded engines (`memory://`, `file:///path`) are intentionally
+> rejected by this package. Use [`@reddb-io/sdk`](../js) instead if you
+> need an in-process database.
+
+## When to use this package
+
+| You want…                                         | Install              |
+| ------------------------------------------------- | -------------------- |
+| Connect to a running RedDB server (most apps)     | `@reddb-io/client`   |
+| Same, plus the ability to spin up a local engine  | `@reddb-io/sdk`      |
+| The CLI launcher (`reddb-cli`)                    | `@reddb-io/cli`      |
+
+All three packages stay version-locked.
+
+## Install
+
+```bash
+pnpm add @reddb-io/client
+# or
+npm install @reddb-io/client
+```
+
+The `postinstall` script downloads the matching `red_client` binary
+from GitHub Releases into `node_modules/@reddb-io/client/bin/`. If your
+environment blocks postinstall scripts or has no network, set
+`REDDB_CLIENT_BIN=/path/to/red_client` to point at a copy you've placed
+manually. The driver itself does **not** need the binary for `connect()`
+— it speaks the wire protocols directly from JS.
+
+## Quickstart
+
+```js
+import { connect } from '@reddb-io/client'
+
+const db = await connect('red://reddb.example.com:5050', {
+  auth: { token: process.env.REDDB_TOKEN },
+})
+
+await db.insert('users', { name: 'Alice' })
+const result = await db.query('SELECT * FROM users LIMIT 10')
+console.log(result.rows)
+
+await db.close()
+```
+
+## Accepted URI schemes
+
+| Scheme         | Transport                     | Default port |
+| -------------- | ----------------------------- | ------------ |
+| `red://`       | RedWire (TCP)                 | 5050         |
+| `reds://`      | RedWire over TLS              | 5050         |
+| `grpc://`      | gRPC                          | 5055         |
+| `grpcs://`     | gRPC over TLS                 | 5056         |
+| `http://`      | HTTP JSON                     | 8080         |
+| `https://`     | HTTPS JSON                    | 8443         |
+
+## Rejected URI schemes
+
+`memory://`, `memory:`, `file:///abs/path`, `red://`, `red:///path`,
+`red://:memory`, `red://:memory:` — all throw `EmbeddedNotSupported`
+with the same wording as the underlying `red_client` binary:
+
+> embedded schemes (memory:// / file://) are not supported. Use the
+> full `red` binary for in-memory or file-backed engines.
+
+## Authentication
+
+```js
+// Bearer / API key
+await connect('red://host:5050', { auth: { token: 'sk-abc' } })
+
+// or via the URI:
+await connect('red://host:5050?token=sk-abc')
+
+// Username + password (driver calls /auth/login first):
+await connect('red://user:pass@host:5050')
+```
+
+## Environment overrides
+
+| Variable                     | Effect                                                |
+| ---------------------------- | ----------------------------------------------------- |
+| `REDDB_CLIENT_BIN`           | Override path to `red_client` for spawn-style helpers |
+| `REDDB_SKIP_POSTINSTALL=1`   | Don't download the binary on install                  |
+| `REDDB_POSTINSTALL_VERSION`  | Pull a specific release tag                           |
+| `REDDB_POSTINSTALL_REPO`     | Pull from a fork (default `reddb-io/reddb`)           |
+
+## License
+
+MIT.

package/index.d.ts

@@ -0,0 +1,223 @@
+/**
+ * @reddb-io/client — TypeScript definitions for the thin remote-only
+ * RedDB driver. Hand-written, kept in sync with src/index.js.
+ */
+
+export type AuthOptions =
+  | { token: string }
+  | { apiKey: string }
+  | { username: string; password: string; loginUrl?: string }
+
+export interface TlsOptions {
+  ca?: string | Uint8Array
+  cert?: string | Uint8Array
+  key?: string | Uint8Array
+  servername?: string
+  rejectUnauthorized?: boolean
+}
+
+export interface ConnectOptions {
+  /** Authentication credentials for remote transports. */
+  auth?: AuthOptions
+  /** TLS options for `reds://` / `grpcs://` connections. */
+  tls?: TlsOptions
+}
+
+export interface QueryResult {
+  statement: string
+  affected: number
+  columns: string[]
+  rows: Array<Record<string, unknown>>
+}
+
+export interface InsertResult { affected: number; id?: string | number }
+export interface BulkInsertResult { affected: number }
+export interface GetResult { entity: Record<string, unknown> | null }
+export interface DeleteResult { affected: number }
+export interface HealthResult { ok: boolean; version: string }
+export interface VersionResult { version: string; protocol: string }
+
+export type Role = 'read' | 'write' | 'admin'
+
+export interface LoginResult {
+  token: string
+  username: string
+  role: Role
+  expires_at: number
+}
+
+export interface WhoamiResult { username: string; role: Role }
+export interface CreateApiKeyResult { key: string; role: Role; created_at: number }
+export interface ChangePasswordResult { ok: true }
+export interface RevokeApiKeyResult { ok: true }
+
+export class RedDBError extends Error {
+  readonly name: 'RedDBError'
+  readonly code: string
+  readonly data: unknown
+  constructor(code: string, message: string, data?: unknown)
+}
+
+// ---------------------------------------------------------------------------
+// Cache API
+// ---------------------------------------------------------------------------
+
+export interface CachePutOptions {
+  ttl_ms?: number
+  tags?: string[]
+  policy?: {
+    idle_evict_ms?: number
+    stale_while_revalidate_ms?: number
+    jitter_ms?: number
+  }
+}
+
+export type CacheExistsStatus = 'present' | 'absent' | 'maybe'
+
+export class CacheClient {
+  get(namespace: string, key: string): Promise<Uint8Array | null>
+  put(
+    namespace: string,
+    key: string,
+    value: Uint8Array | Buffer | string,
+    opts?: CachePutOptions,
+  ): Promise<void>
+  exists(namespace: string, key: string): Promise<CacheExistsStatus>
+  invalidate(namespace: string, key: string): Promise<void>
+  invalidatePrefix(namespace: string, prefix: string): Promise<number>
+  invalidateTags(namespace: string, tags: string[]): Promise<number>
+  flushNamespace(namespace: string): Promise<void>
+}
+
+export interface KvWatchEvent {
+  key: string
+  op: 'insert' | 'update' | 'delete'
+  before: unknown
+  after: unknown
+  lsn: number
+  committed_at: number
+  dropped_event_count: number
+}
+
+export class KvClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: { collection?: string; expireMs?: number; tags?: string[] },
+  ): Promise<QueryResult>
+  invalidateTags(tags: string[], options?: { collection?: string }): Promise<number>
+  watch(
+    key: string,
+    options?: { collection?: string; sinceLsn?: number; limit?: number },
+  ): AsyncIterable<KvWatchEvent>
+  watchPrefix(
+    prefix: string,
+    options?: { collection?: string; sinceLsn?: number; limit?: number },
+  ): AsyncIterable<KvWatchEvent>
+}
+
+export class ConfigClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: {
+      collection?: string
+      tags?: string[]
+      secretRef?: { collection: string; key: string }
+    },
+  ): Promise<QueryResult>
+  get(key: string, options?: { collection?: string }): Promise<QueryResult>
+  resolve(key: string, options?: { collection?: string }): Promise<QueryResult>
+}
+
+export class VaultClient {
+  put(
+    key: string,
+    value: unknown,
+    options?: { collection?: string; tags?: string[] },
+  ): Promise<QueryResult>
+  get(key: string, options?: { collection?: string }): Promise<QueryResult>
+  unseal(key: string, options?: { collection?: string }): Promise<QueryResult>
+}
+
+/**
+ * Specialised error thrown when an embedded URI is passed to the
+ * thin client. Always has `code === 'EmbeddedNotSupported'`. Use
+ * `@reddb-io/sdk` instead for in-memory or file-backed engines.
+ */
+export class EmbeddedNotSupported extends RedDBError {
+  readonly name: 'EmbeddedNotSupported'
+  readonly code: 'EmbeddedNotSupported'
+  readonly uri: string
+  constructor(uri: string)
+}
+
+export const EMBEDDED_REJECTION_MESSAGE: string
+
+/** Returns true when `uri` selects the embedded engine. */
+export function isEmbeddedUri(uri: string): boolean
+
+export class RedDB {
+  readonly cache: CacheClient
+  readonly kv: KvClient & ((collection?: string) => KvClient)
+  readonly config: (collection?: string) => ConfigClient
+  readonly vault: (collection?: string) => VaultClient
+
+  query(sql: string): Promise<QueryResult>
+  insert(collection: string, payload: Record<string, unknown>): Promise<InsertResult>
+  bulkInsert(
+    collection: string,
+    payloads: Array<Record<string, unknown>>,
+  ): Promise<BulkInsertResult>
+  get(collection: string, id: string | number): Promise<GetResult>
+  delete(collection: string, id: string | number): Promise<DeleteResult>
+  health(): Promise<HealthResult>
+  version(): Promise<VersionResult>
+
+  login(username: string, password: string): Promise<LoginResult>
+  whoami(): Promise<WhoamiResult>
+  changePassword(currentPassword: string, newPassword: string): Promise<ChangePasswordResult>
+  createApiKey(opts?: { username?: string; role?: Role }): Promise<CreateApiKeyResult>
+  revokeApiKey(key: string): Promise<RevokeApiKeyResult>
+
+  close(): Promise<void>
+}
+
+/**
+ * Connect to a remote RedDB instance.
+ *
+ * Accepted URI schemes:
+ *   - `red://host:port`        — RedWire TCP (default)
+ *   - `reds://host:port`       — RedWire over TLS
+ *   - `grpc://host:port`       — gRPC
+ *   - `grpcs://host:port`      — gRPC over TLS
+ *   - `http://host:port`       — HTTP JSON
+ *   - `https://host:port`      — HTTPS JSON
+ *
+ * Embedded URIs (`memory://`, `memory:`, `file:///path`, `red:///`,
+ * `red://:memory[:]`) throw `EmbeddedNotSupported`.
+ */
+export function connect(uri: string, options?: ConnectOptions): Promise<RedDB>
+
+/** Exchange username + password for a bearer token via /auth/login. */
+export function login(
+  loginUrl: string,
+  credentials: { username: string; password: string },
+): Promise<LoginResult>
+
+export interface ParsedUri {
+  kind: 'embedded' | 'http' | 'https' | 'red' | 'reds' | 'grpc' | 'grpcs' | 'pg'
+  host?: string
+  port?: number
+  path?: string
+  username?: string
+  password?: string
+  token?: string
+  apiKey?: string
+  loginUrl?: string
+  params?: URLSearchParams
+  originalUri: string
+}
+
+export function parseUri(uri: string): ParsedUri
+export function deriveLoginUrl(parsed: ParsedUri): string

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@reddb-io/client",
+  "version": "1.0.1",
+  "description": "Thin remote-only RedDB driver. Downloads the `red_client` binary on install. Speaks RedWire/gRPC/HTTP. Embedded URIs (memory://, file://, red:///path) are rejected — use @reddb-io/sdk for those.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts",
+    "postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "reddb",
+    "database",
+    "client",
+    "driver",
+    "remote",
+    "thin-client",
+    "redwire",
+    "grpc",
+    "http"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/reddb-io/reddb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reddb-io/reddb.git",
+    "directory": "drivers/js-client"
+  },
+  "bugs": {
+    "url": "https://github.com/reddb-io/reddb/issues"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/postinstall.js

@@ -0,0 +1,97 @@
+/**
+ * postinstall.js — download the matching `red_client` binary from
+ * GitHub Releases.
+ *
+ * Behaviour:
+ *   - Resolves `red_client-<platform>-<arch>` from process.platform +
+ *     process.arch via the vendored asset fetcher.
+ *   - Targets the GitHub release matching this package's version.
+ *   - Drops the binary at `<package>/bin/red_client[.exe]` and chmods
+ *     +x on Unix.
+ *   - On any failure, prints a warning to stderr but exits 0 — npm
+ *     install never breaks because of this script. The user gets a
+ *     clear error later when they call `connect()` if the binary is
+ *     missing AND the runtime needs to spawn it. (The remote-only
+ *     transports in @reddb-io/client don't actually need the binary
+ *     for `connect()` itself; the binary is provided as a CLI helper
+ *     for ad-hoc REPL / one-shot SQL.)
+ *
+ * Override hooks (env vars):
+ *   REDDB_SKIP_POSTINSTALL=1      do nothing
+ *   REDDB_POSTINSTALL_VERSION=…   pull a different release tag
+ *   REDDB_POSTINSTALL_REPO=…      pull from a fork (default: reddb-io/reddb)
+ *   REDDB_CLIENT_BIN=/path        runtime override consulted by callers
+ *                                 that spawn the binary; postinstall
+ *                                 still downloads to the package dir
+ *                                 unless REDDB_SKIP_POSTINSTALL=1.
+ */
+
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
+
+import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+const pkg = require('./package.json')
+
+const DEFAULT_REPO = 'reddb-io/reddb'
+const BIN_NAME = 'red_client'
+
+if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
+  process.stdout.write('@reddb-io/client: postinstall skipped (REDDB_SKIP_POSTINSTALL=1)\n')
+  process.exit(0)
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `@reddb-io/client: postinstall could not download red_client (${err.message}).\n`
+      + `       The package will still install. To use the binary you can:\n`
+      + `         - set REDDB_CLIENT_BIN=/path/to/red_client\n`
+      + `         - or install it manually from https://github.com/${DEFAULT_REPO}/releases\n`,
+  )
+  process.exit(0)
+})
+
+async function main() {
+  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
+  const tag = process.env.REDDB_POSTINSTALL_VERSION
+    ? normalizeTag(process.env.REDDB_POSTINSTALL_VERSION)
+    : `v${pkg.version}`
+
+  const binDir = join(HERE, 'bin')
+  const binaryPath = join(binDir, defaultBinaryName())
+
+  if (existsSync(binaryPath)) {
+    process.stdout.write(`@reddb-io/client: binary already present at ${binaryPath}\n`)
+    return
+  }
+
+  process.stdout.write(
+    `@reddb-io/client: downloading ${BIN_NAME} ${tag} for ${process.platform}/${process.arch} from ${repo}\n`,
+  )
+  const body = await fetchReleaseAsset({
+    repo,
+    tag,
+    platform: process.platform,
+    arch: process.arch,
+    binName: BIN_NAME,
+  })
+  mkdirSync(binDir, { recursive: true })
+  writeFileSync(binaryPath, body)
+  if (process.platform !== 'win32') {
+    chmodSync(binaryPath, 0o755)
+  }
+  process.stdout.write(`@reddb-io/client: installed binary at ${binaryPath}\n`)
+}
+
+function defaultBinaryName() {
+  return process.platform === 'win32' ? `${BIN_NAME}.exe` : BIN_NAME
+}
+
+function normalizeTag(value) {
+  const v = String(value).trim()
+  return v.startsWith('v') ? v : `v${v}`
+}

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/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, "''")}'`
+}