@reddb-io/client 1.0.1

package/src/internal/asset-fetcher/download.js

@@ -0,0 +1,89 @@
+import { request as httpsRequest } from 'node:https'
+import { request as httpRequest } from 'node:http'
+
+const MAX_REDIRECTS = 5
+
+export class AssetNotFoundError extends Error {
+  constructor(url) {
+    super(`asset not found (HTTP 404) at ${url}`)
+    this.name = 'AssetNotFoundError'
+    this.code = 'ASSET_NOT_FOUND'
+    this.url = url
+  }
+}
+
+export class HttpError extends Error {
+  constructor(status, url) {
+    super(`HTTP ${status} fetching ${url}`)
+    this.name = 'HttpError'
+    this.code = 'HTTP_ERROR'
+    this.status = status
+    this.url = url
+  }
+}
+
+export class TooManyRedirectsError extends Error {
+  constructor(url) {
+    super(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`)
+    this.name = 'TooManyRedirectsError'
+    this.code = 'TOO_MANY_REDIRECTS'
+    this.url = url
+  }
+}
+
+function pickRequest(url) {
+  return url.startsWith('http://') ? httpRequest : httpsRequest
+}
+
+function resolveLocation(currentUrl, location) {
+  if (/^https?:\/\//i.test(location)) return location
+  return new URL(location, currentUrl).toString()
+}
+
+export function downloadFollowingRedirects(url, { userAgent, originalUrl } = {}, depth = 0) {
+  const startUrl = originalUrl || url
+  if (depth > MAX_REDIRECTS) {
+    return Promise.reject(new TooManyRedirectsError(startUrl))
+  }
+  const request = pickRequest(url)
+  return new Promise((resolve, reject) => {
+    const req = request(
+      url,
+      {
+        method: 'GET',
+        headers: {
+          'User-Agent': userAgent || 'reddb-internal-asset-fetcher',
+          Accept: 'application/octet-stream',
+        },
+      },
+      (res) => {
+        const status = res.statusCode || 0
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume()
+          const next = resolveLocation(url, res.headers.location)
+          downloadFollowingRedirects(next, { userAgent, originalUrl: startUrl }, depth + 1).then(
+            resolve,
+            reject,
+          )
+          return
+        }
+        if (status === 404) {
+          res.resume()
+          reject(new AssetNotFoundError(startUrl))
+          return
+        }
+        if (status < 200 || status >= 300) {
+          res.resume()
+          reject(new HttpError(status, url))
+          return
+        }
+        const chunks = []
+        res.on('data', (chunk) => chunks.push(chunk))
+        res.on('end', () => resolve(Buffer.concat(chunks)))
+        res.on('error', reject)
+      },
+    )
+    req.on('error', reject)
+    req.end()
+  })
+}

package/src/internal/asset-fetcher/index.js

@@ -0,0 +1,52 @@
+/**
+ * @reddb-io/internal-asset-fetcher — fetch a `red`/`red_client` binary
+ * from a GitHub release.
+ *
+ * Public surface: one function.
+ *
+ *   fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256? }) → Buffer
+ *
+ * Steps:
+ *   1. Map (platform, arch, binName) → asset filename.
+ *   2. Compose the GitHub download URL: `https://github.com/<repo>/releases/download/<tag>/<asset>`.
+ *   3. Follow up to 5 redirects, returning the final body as a Buffer.
+ *   4. If `sha256` was supplied, verify before returning.
+ *
+ * Errors carry distinct `.code` values so callers can differentiate:
+ *   - UNSUPPORTED_PLATFORM   — no asset for this platform/arch
+ *   - ASSET_NOT_FOUND        — HTTP 404 (release/tag/asset name wrong)
+ *   - CHECKSUM_MISMATCH      — body downloaded but sha256 mismatched
+ *   - HTTP_ERROR             — any other non-2xx status
+ *   - TOO_MANY_REDIRECTS     — redirect chain longer than 5 hops
+ *
+ * Internal modules (`./asset-name.js`, `./download.js`, `./checksum.js`)
+ * are not part of the public contract — only `fetchReleaseAsset` is.
+ * They are imported directly in tests for focused coverage.
+ */
+
+import { composeAssetName } from './asset-name.js'
+import { downloadFollowingRedirects } from './download.js'
+import { verifySha256 } from './checksum.js'
+
+export async function fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256 } = {}) {
+  if (typeof repo !== 'string' || repo === '') {
+    throw new TypeError('fetchReleaseAsset: `repo` must be a non-empty string (e.g. "reddb-io/reddb")')
+  }
+  if (typeof tag !== 'string' || tag === '') {
+    throw new TypeError('fetchReleaseAsset: `tag` must be a non-empty string (e.g. "v0.2.9")')
+  }
+  if (typeof platform !== 'string' || platform === '') {
+    throw new TypeError('fetchReleaseAsset: `platform` must be a non-empty string')
+  }
+  if (typeof arch !== 'string' || arch === '') {
+    throw new TypeError('fetchReleaseAsset: `arch` must be a non-empty string')
+  }
+
+  const assetName = composeAssetName({ platform, arch, binName })
+  const url = `https://github.com/${repo}/releases/download/${tag}/${assetName}`
+  const body = await downloadFollowingRedirects(url)
+  if (sha256) {
+    verifySha256(body, sha256)
+  }
+  return body
+}

package/src/kv.js

@@ -0,0 +1,70 @@
+import { RedDBError } from './protocol.js'
+
+export class KvClient {
+  constructor(client, collection = 'kv_default') {
+    this.client = client
+    this.collection = collection
+  }
+
+  put(key, value, options = {}) {
+    const collection = options.collection ?? this.collection
+    const tags = Array.isArray(options.tags) && options.tags.length > 0
+      ? ` TAGS [${options.tags.map(kvTagLiteral).join(', ')}]`
+      : ''
+    const expire = options.expireMs != null ? ` EXPIRE ${Number(options.expireMs)} ms` : ''
+    return this.client.call('query', {
+      sql: `KV PUT ${kvPath(collection, key)} = ${kvValueLiteral(value)}${expire}${tags}`,
+    })
+  }
+
+  async invalidateTags(tags, options = {}) {
+    const collection = options.collection ?? this.collection
+    const result = await this.client.call('query', {
+      sql: `INVALIDATE TAGS [${tags.map(kvTagLiteral).join(', ')}] FROM ${kvIdentifier(collection)}`,
+    })
+    return result.affected ?? result.affected_rows ?? result.rows?.[0]?.invalidated ?? 0
+  }
+
+  async *watch(key, options = {}) {
+    if (!this.client.baseUrl) {
+      throw new RedDBError('UNSUPPORTED_TRANSPORT', 'kv.watch requires the HTTP transport')
+    }
+    const collection = options.collection ?? this.collection
+    const params = new URLSearchParams()
+    if (options.sinceLsn != null) params.set('since_lsn', String(options.sinceLsn))
+    if (options.limit != null) params.set('limit', String(options.limit))
+    const suffix = params.toString() ? `?${params}` : ''
+    const url = `${this.client.baseUrl}/collections/${encodeURIComponent(collection)}/kv/${encodeURIComponent(String(key))}/watch${suffix}`
+    const response = await fetch(url, this.client.attachAuth({ method: 'GET' }))
+    if (!response.ok) {
+      throw new RedDBError('HTTP_ERROR', `kv.watch failed with HTTP ${response.status}`)
+    }
+    const text = await response.text()
+    for (const block of text.split('\n\n')) {
+      const line = block.split('\n').find((entry) => entry.startsWith('data: '))
+      if (line) yield JSON.parse(line.slice(6))
+    }
+  }
+
+  watchPrefix(prefix, options = {}) {
+    return this.watch(`${prefix}.*`, options)
+  }
+}
+
+function kvPath(collection, key) {
+  return `${kvIdentifier(collection)}.${kvIdentifier(key)}`
+}
+
+function kvIdentifier(value) {
+  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+}
+
+function kvValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+function kvTagLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/src/protocol.js

@@ -0,0 +1,157 @@
+/**
+ * JSON-RPC 2.0 line-delimited client.
+ *
+ * Maintains a map of pending requests keyed by id. Reads stdout one
+ * line at a time, parses each line as a response envelope, looks up
+ * the pending promise by id and resolves/rejects it.
+ *
+ * Spec: PLAN_DRIVERS.md, "Spec do protocolo stdio".
+ */
+
+const NEWLINE = 0x0a // '\n'
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8')
+
+/**
+ * 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
+  }
+}
+
+export class RpcClient {
+  /** @param {import('./spawn.js').RedProcess} child */
+  constructor(child) {
+    this.child = child
+    this.nextId = 1
+    /** @type {Map<number|string, { resolve: Function, reject: Function }>} */
+    this.pending = new Map()
+    this.closed = false
+    this.closeReason = null
+    this.readerPromise = this.#readLoop()
+  }
+
+  /**
+   * Send a JSON-RPC 2.0 request and resolve with the result, or reject
+   * with a `RedDBError` if the server returned an error envelope.
+   */
+  call(method, params = {}) {
+    if (this.closed) {
+      return Promise.reject(
+        new RedDBError('CLIENT_CLOSED', `client is closed: ${this.closeReason ?? 'unknown'}`),
+      )
+    }
+    const id = this.nextId++
+    const envelope = JSON.stringify({ jsonrpc: '2.0', id, method, params })
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject })
+      this.child.stdin.write(encoder.encode(envelope + '\n')).catch((err) => {
+        this.pending.delete(id)
+        reject(err)
+      })
+    })
+  }
+
+  /** Drain pending requests, send `close`, wait for the binary to exit. */
+  async close() {
+    if (this.closed) return
+    try {
+      await this.call('close', {})
+    } catch {
+      // best effort — server may already be gone
+    }
+    this.#shutdown('close requested')
+    try {
+      this.child.stdin.end()
+    } catch {
+      // ignore
+    }
+    await this.child.wait()
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal: stdout reader loop
+  // -------------------------------------------------------------------------
+
+  async #readLoop() {
+    let buffer = new Uint8Array(0)
+    try {
+      for await (const chunk of this.child.stdout) {
+        const merged = new Uint8Array(buffer.length + chunk.length)
+        merged.set(buffer, 0)
+        merged.set(chunk, buffer.length)
+        buffer = merged
+
+        // Split on \n, dispatch each complete line.
+        let start = 0
+        for (let i = 0; i < buffer.length; i++) {
+          if (buffer[i] === NEWLINE) {
+            const lineBytes = buffer.subarray(start, i)
+            this.#dispatchLine(decoder.decode(lineBytes))
+            start = i + 1
+          }
+        }
+        if (start > 0) {
+          buffer = buffer.subarray(start)
+        }
+      }
+    } catch (err) {
+      this.#shutdown(`stdout reader error: ${err.message}`)
+      return
+    }
+    // EOF — server exited.
+    this.#shutdown('server stdout closed')
+  }
+
+  #dispatchLine(line) {
+    if (!line.trim()) return
+    let envelope
+    try {
+      envelope = JSON.parse(line)
+    } catch (err) {
+      // Malformed line from the server is fatal to the protocol —
+      // we cannot map it to any pending request.
+      this.#shutdown(`malformed server response: ${err.message}`)
+      return
+    }
+    const id = envelope.id
+    if (id === null || id === undefined) {
+      // No id → cannot route. Treat as protocol violation.
+      return
+    }
+    const pending = this.pending.get(id)
+    if (!pending) {
+      // Unknown id — server bug or duplicate response. Ignore.
+      return
+    }
+    this.pending.delete(id)
+    if (envelope.error) {
+      pending.reject(
+        new RedDBError(
+          envelope.error.code ?? 'UNKNOWN',
+          envelope.error.message ?? 'unknown error',
+          envelope.error.data,
+        ),
+      )
+    } else {
+      pending.resolve(envelope.result)
+    }
+  }
+
+  #shutdown(reason) {
+    if (this.closed) return
+    this.closed = true
+    this.closeReason = reason
+    const err = new RedDBError('CLIENT_CLOSED', reason)
+    for (const { reject } of this.pending.values()) {
+      reject(err)
+    }
+    this.pending.clear()
+  }
+}