@3sln/trove 0.0.2

package/packages/core/src/sqlite.js

@@ -0,0 +1,162 @@
+// A tiny SQLite abstraction that every backend conforms to, so stores don't care
+// whether they run on local files (bun:sqlite / node:sqlite), Cloudflare D1, a
+// Durable Object, or an in-browser wasm build. The handle is ASYNC — the only
+// shape D1/DO/wasm can satisfy — and the local backend just wraps its synchronous
+// driver in resolved promises.
+//
+//   const db = await provider.obtain({ key: 'metadata' });
+//   await db.exec('CREATE TABLE t (x)');
+//   await db.all('SELECT * FROM t WHERE x = ?', x);
+//
+// The provider is a keyed pool: obtain() lazily creates (and memoizes) the DB for
+// a key, so per-plugin / per-domain databases are just distinct keys. The shell
+// injects whichever provider fits the runtime.
+
+import { TroveError } from './errors.js';
+
+/** The database handle. All methods are async so every backend can implement it. */
+export class SqliteDatabase {
+  async exec(sql) { throw TroveError.unsupported('SqliteDatabase.exec'); }
+  async run(sql, ...params) { throw TroveError.unsupported('SqliteDatabase.run'); }
+  async get(sql, ...params) { throw TroveError.unsupported('SqliteDatabase.get'); }
+  async all(sql, ...params) { throw TroveError.unsupported('SqliteDatabase.all'); }
+  /** Run statements atomically. @param {{sql:string, params?:any[]}[]} statements */
+  async batch(statements) { throw TroveError.unsupported('SqliteDatabase.batch'); }
+  async close() {}
+}
+
+// Plugin SQL safety lives in ./plugins/sql.js so the browser can use it without
+// pulling a database driver in behind it. Re-exported here, where callers expect it.
+export { assertSafePluginSql, stripSqlLiterals } from './plugins/sql.js';
+
+/** A keyed pool/factory of databases. The shell injects one. */
+export class SqliteProvider {
+  /**
+   * Does data written through this provider survive a restart? False unless a backend
+   * says otherwise, so "durable" is something a provider claims rather than something
+   * callers assume. The server asks before putting the search index in SQLite: an
+   * index in an ephemeral database is worse than one in memory, because it looks
+   * persistent right up until the restart that proves it isn't.
+   */
+  get durable() { return false; }
+  async init() {}
+  /** @returns {Promise<SqliteDatabase>} the lazily-created, memoized db for `key`. */
+  async obtain({ key }) { throw TroveError.unsupported('SqliteProvider.obtain'); }
+  /** Destroy the db for `key` (close + delete its backing store). */
+  async drop({ key }) {}
+  async close() {}
+}
+
+// --- local backend (bun:sqlite / node:sqlite) --------------------------------
+// Kept in this module but with all node-specific bits (fs) imported lazily inside
+// obtain(), so importing the interfaces stays safe in a Worker that never uses it.
+
+const CORE_KEYS = new Set(['metadata', 'kv', 'plugins']); // these share one main db file
+
+class LocalSqliteDatabase extends SqliteDatabase {
+  constructor(raw) {
+    super();
+    this.raw = raw;
+  }
+  async exec(sql) { this.raw.exec(sql); }
+  async run(sql, ...params) { return this.raw.prepare(sql).run(...params); }
+  async get(sql, ...params) { return this.raw.prepare(sql).get(...params) ?? null; }
+  async all(sql, ...params) { return this.raw.prepare(sql).all(...params); }
+  async batch(statements) {
+    this.raw.exec('BEGIN');
+    try {
+      for (const { sql, params = [] } of statements) this.raw.prepare(sql).run(...params);
+      this.raw.exec('COMMIT');
+    } catch (err) {
+      try { this.raw.exec('ROLLBACK'); } catch { /* already rolled back */ }
+      throw err;
+    }
+  }
+  async close() { this.raw.close?.(); }
+}
+
+export class LocalSqliteProvider extends SqliteProvider {
+  /**
+   * @param {{ path?: string }} opts Main db file. Core keys (metadata, kv) share it;
+   *   other keys (e.g. plugin scopes) get an isolated sibling file under `stores/`.
+   *   Use ':memory:' for an ephemeral shared in-memory db (tests).
+   */
+  constructor(opts = {}) {
+    super();
+    this.path = opts.path || ':memory:';
+    this._pool = new Map(); // resolvedPath -> LocalSqliteDatabase
+  }
+
+  get durable() { return this.path !== ':memory:'; }
+
+  // Resolve a key to a pool token. In-memory: core keys share one db, every other
+  // key gets its own isolated in-memory db (so plugin scopes never collide). On
+  // disk: core keys share the main file, others get isolated sibling files.
+  #resolve(key) {
+    if (this.path === ':memory:') return CORE_KEYS.has(key) ? ':memory:#core' : ':memory:#' + key;
+    if (CORE_KEYS.has(key)) return this.path;
+    return join(dirname(this.path), 'stores', sanitize(key) + '.db');
+  }
+
+  async obtain({ key }) {
+    const resolved = this.#resolve(key);
+    let db = this._pool.get(resolved);
+    if (!db) {
+      const file = resolved.startsWith(':memory:') ? ':memory:' : resolved;
+      if (file !== ':memory:') {
+        const { mkdir } = await import('node:fs/promises');
+        await mkdir(dirname(file), { recursive: true });
+      }
+      const { openDatabase } = await import('./sqlite-driver.js');
+      db = new LocalSqliteDatabase(await openDatabase(file));
+      this._pool.set(resolved, db);
+    }
+    return db;
+  }
+
+  async drop({ key }) {
+    const resolved = this.#resolve(key);
+    const db = this._pool.get(resolved);
+    if (db) { await db.close(); this._pool.delete(resolved); }
+    if (!resolved.startsWith(':memory:')) {
+      const { rm } = await import('node:fs/promises');
+      for (const suffix of ['', '-wal', '-shm']) await rm(resolved + suffix, { force: true }).catch(() => {});
+    }
+  }
+
+  async close() {
+    for (const db of this._pool.values()) await db.close();
+    this._pool.clear();
+  }
+}
+
+// Pure path helpers (no node:path, so this module loads anywhere).
+function dirname(p) {
+  const i = p.lastIndexOf('/');
+  return i <= 0 ? '.' : p.slice(0, i);
+}
+function join(...parts) {
+  return parts.join('/').replace(/\/{2,}/g, '/');
+}
+// Map a store key to a filename that is safe AND unique.
+//
+// Sanitizing alone is lossy: every disallowed character collapses to `_`, so
+// `pstore:alice@x.com:plg:p` and `pstore:alice_x.com:plg:p` land on the same file —
+// two principals sharing one database. Since a principal id is often an email, and
+// with a JWT it is whatever `sub` the IdP mints, that is a collision an attacker can
+// sometimes choose. The hash suffix makes the mapping injective; the readable prefix
+// is kept only so the directory is browsable.
+function sanitize(key) {
+  return key.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) + '.' + fnv1a(key);
+}
+
+// FNV-1a, 32-bit. Not a security hash — it only has to be collision-resistant enough
+// to separate keys that sanitize to the same string, which are near-identical inputs.
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}

package/packages/core/src/storage/filesystem.js

@@ -0,0 +1,283 @@
+// Filesystem storage backend (Node). Also the "NAS" backend — point `root` at a
+// mounted network share. Stores each object as a file under a two-level sharded
+// directory (ab/cd/<key>) to avoid huge flat directories. Supports range reads
+// (media seeking, resumable downloads); no presigning, so the server proxies
+// bytes for these backends. Multipart is emulated with per-part temp files that
+// are concatenated on complete — writes are staged to a temp file and atomically
+// renamed so a crash mid-write never yields a half-written object.
+
+import { createReadStream, createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { StorageBackend, resolveRange } from './interface.js';
+import { TroveError, wrapError } from '../errors.js';
+import { newId } from '../util.js';
+
+// A key becomes a filename, so anything a filename can't hold has to be encoded —
+// REVERSIBLY. Replacing every disallowed character with `_` was not: `list()` could only
+// ever report the mangled name back, so a collection using bucket-and-prefix over a
+// filesystem (keys like `team-a/obj_9f…`) listed nothing at all, adopt and refresh
+// silently never ran, and every one of its items came back as an orphan — a durable
+// "your files are gone" warning on a drive where nothing was wrong.
+//
+// `~XX` over UTF-8 bytes, with `~` itself encoded, so decoding is exact. Keys made only
+// of safe characters — which is every key Trove mints (`obj_<hex>`) — encode to
+// themselves, so this changes no existing filename.
+function encodeKey(key) {
+  let out = '';
+  for (const byte of new TextEncoder().encode(key)) {
+    const c = String.fromCharCode(byte);
+    out += /[a-zA-Z0-9._-]/.test(c) ? c : '~' + byte.toString(16).padStart(2, '0');
+  }
+  return out;
+}
+function decodeKey(name) {
+  const bytes = [];
+  for (let i = 0; i < name.length; i++) {
+    if (name[i] === '~' && /^[0-9a-f]{2}$/i.test(name.slice(i + 1, i + 3))) {
+      bytes.push(parseInt(name.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else {
+      bytes.push(name.charCodeAt(i) & 0xff);
+    }
+  }
+  return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+function shardPath(root, key) {
+  const safe = encodeKey(key);
+  const a = (safe.slice(0, 2) || '__').padEnd(2, '_');
+  const b = (safe.slice(2, 4) || '__').padEnd(2, '_');
+  return path.join(root, 'objects', a, b, safe);
+}
+
+async function toNodeStream(body) {
+  if (body instanceof Readable) return body;
+  if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+    return Readable.from(Buffer.from(body instanceof ArrayBuffer ? new Uint8Array(body) : body));
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) {
+    return Readable.fromWeb(body.stream());
+  }
+  if (body instanceof ReadableStream || typeof body?.getReader === 'function') {
+    return Readable.fromWeb(body);
+  }
+  if (typeof body?.[Symbol.asyncIterator] === 'function') return Readable.from(body);
+  if (typeof body === 'string') return Readable.from(Buffer.from(body));
+  throw TroveError.invalid('Unsupported body type');
+}
+
+export class FilesystemStorage extends StorageBackend {
+  /** @param {{root: string}} opts */
+  constructor({ root }) {
+    super();
+    if (!root) throw TroveError.invalid('FilesystemStorage requires a root directory');
+    this.root = path.resolve(root);
+    this.tmp = path.join(this.root, 'tmp');
+  }
+
+  get capabilities() {
+    return { presignDownload: false, presignUpload: false, multipart: true, range: true, list: true, usage: true };
+  }
+
+  async #ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+  }
+
+  /**
+   * Space on the filesystem holding this root.
+   *
+   * Reports the FILESYSTEM's numbers, not the drive's — if Trove shares a disk with
+   * everything else on the machine, "12 GB free" is the fact that actually governs
+   * whether the next upload succeeds, and reporting only Trove's own footprint would
+   * leave someone confident with a full disk. `bavail` (free to a non-root user), not
+   * `bfree`, for the same reason: the reserved blocks are not available to us.
+   */
+  async usage() {
+    // statfs needs a path that EXISTS, and the root is created lazily on first write —
+    // so asking before anything has been uploaded would report "unknown" on exactly the
+    // empty drive where someone is most likely to be checking. Walk up to the nearest
+    // existing ancestor; it is on the same filesystem, which is what we are measuring.
+    let dir = this.root;
+    for (let i = 0; i < 8; i++) {
+      try {
+        const st = await fs.statfs(dir);
+        const total = st.blocks * st.bsize;
+        const available = st.bavail * st.bsize;
+        return { total, available, used: total - available };
+      } catch (err) {
+        if (err?.code !== 'ENOENT') return null; // old runtime, exotic mount: don't guess
+        const parent = path.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Walk the object tree so a scan can see files that arrived without Trove.
+   *
+   * Keys here are shard-mapped through a LOSSY sanitizer, so the mapping is only
+   * reversible for keys that survive it unchanged — which every key Trove writes does
+   * (`obj_<hex>`), and a hand-dropped `My Photo.jpg` does not. Rather than guess, this
+   * reports only files sitting at the exact path their own name maps to, and counts the
+   * rest as `unaddressable` so the caller can say so out loud instead of silently
+   * ignoring them.
+   */
+  async list({ prefix = '', cursor = null, limit = 1000 } = {}) {
+    const base = path.join(this.root, 'objects');
+    let found;
+    try {
+      found = await fs.readdir(base, { recursive: true, withFileTypes: true });
+    } catch (err) {
+      if (err.code === 'ENOENT') return { objects: [], nextCursor: null, unaddressable: 0 };
+      throw wrapError(err);
+    }
+    const entries = [];
+    let unaddressable = 0;
+    for (const d of found) {
+      if (!d.isFile()) continue;
+      const full = path.join(d.parentPath || d.path, d.name);
+      // Decode back to the real key first — the filename is an encoding of it, and the
+      // prefix a caller filters on is expressed in key space, not filename space.
+      const key = decodeKey(d.name);
+      // It is addressable only if it round-trips: a file dropped into the shard tree by
+      // hand, or left by an older layout, doesn't map back to a key we can serve.
+      if (shardPath(this.root, key) !== full) { unaddressable++; continue; }
+      if (prefix && !key.startsWith(prefix)) continue;
+      entries.push({ key, full });
+    }
+    entries.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const start = cursor ? entries.findIndex((e) => e.key > cursor) : 0;
+    const from = start === -1 ? entries.length : start;
+    const page = entries.slice(from, from + limit);
+    const objects = [];
+    for (const e of page) {
+      try {
+        const st = await fs.stat(e.full);
+        // etagOfStat, NOT a second hand-rolled format. An etag only means anything if
+        // it is computed identically everywhere: this listing is compared against the
+        // etag `put` recorded, and a different encoding of the same facts made every
+        // object look changed — a scan that re-read and re-indexed the entire drive.
+        objects.push({ key: e.key, size: st.size, etag: etagOfStat(st), modifiedAt: Math.floor(st.mtimeMs) });
+      } catch { /* vanished mid-walk; the next scan will see it */ }
+    }
+    return {
+      objects,
+      nextCursor: from + limit < entries.length ? page[page.length - 1].key : null,
+      // A figure about the WHOLE tree, so it is reported once — on the first page only.
+      // Returning it on every page made a caller that sums pages multiply it by the page
+      // count: one stray file in a 3,000-object drive was reported as seven.
+      ...(cursor ? {} : { unaddressable }),
+    };
+  }
+
+  async put(key, body, opts = {}) {
+    const dest = shardPath(this.root, key);
+    await this.#ensureDir(path.dirname(dest));
+    await this.#ensureDir(this.tmp);
+    const tmpFile = path.join(this.tmp, newId('put'));
+    let written = 0;
+    try {
+      const src = await toNodeStream(body);
+      if (opts.onProgress) {
+        src.on('data', (c) => {
+          written += c.length;
+          opts.onProgress(written);
+        });
+      }
+      const out = createWriteStream(tmpFile);
+      await pipeline(src, out, { signal: opts.signal });
+      await fs.rename(tmpFile, dest); // atomic within a filesystem
+    } catch (err) {
+      await fs.rm(tmpFile, { force: true }).catch(() => {});
+      throw wrapError(err);
+    }
+    const stat = await fs.stat(dest);
+    return { size: stat.size, contentType: opts.contentType, etag: etagOfStat(stat) };
+  }
+
+  async head(key) {
+    try {
+      const stat = await fs.stat(shardPath(this.root, key));
+      return { size: stat.size, etag: etagOfStat(stat) };
+    } catch (err) {
+      throw wrapError(err);
+    }
+  }
+
+  async get(key, opts = {}) {
+    const file = shardPath(this.root, key);
+    let stat;
+    try {
+      stat = await fs.stat(file);
+    } catch (err) {
+      throw wrapError(err);
+    }
+    const total = stat.size;
+    const range = resolveRange(opts.range, total);
+    const streamOpts = range ? { start: range.start, end: range.end } : {};
+    const nodeStream = createReadStream(file, { ...streamOpts, signal: opts.signal });
+    return {
+      stream: Readable.toWeb(nodeStream),
+      size: range ? range.end - range.start + 1 : total,
+      etag: etagOfStat(stat),
+      range,
+    };
+  }
+
+  async delete(key) {
+    await fs.rm(shardPath(this.root, key), { force: true });
+  }
+
+  // --- multipart (staged part files, concatenated on complete) --------------
+
+  async createMultipart(key) {
+    const uploadId = newId('mp');
+    await this.#ensureDir(path.join(this.tmp, uploadId));
+    return uploadId;
+  }
+
+  async putPart(key, uploadId, partNumber, body, opts = {}) {
+    const partFile = path.join(this.tmp, uploadId, String(partNumber));
+    const src = await toNodeStream(body);
+    await pipeline(src, createWriteStream(partFile), { signal: opts.signal });
+    const stat = await fs.stat(partFile);
+    return { partNumber, etag: etagOfStat(stat) };
+  }
+
+  async completeMultipart(key, uploadId, parts) {
+    const dir = path.join(this.tmp, uploadId);
+    const dest = shardPath(this.root, key);
+    await this.#ensureDir(path.dirname(dest));
+    const tmpFile = path.join(this.tmp, newId('complete'));
+    const out = createWriteStream(tmpFile);
+    const ordered = [...parts].sort((a, b) => a.partNumber - b.partNumber);
+    try {
+      for (const p of ordered) {
+        const partFile = path.join(dir, String(p.partNumber));
+        await pipeline(createReadStream(partFile), out, { end: false });
+      }
+      out.end();
+      await new Promise((res, rej) => out.on('finish', res).on('error', rej));
+      await fs.rename(tmpFile, dest);
+    } catch (err) {
+      await fs.rm(tmpFile, { force: true }).catch(() => {});
+      throw wrapError(err);
+    }
+    await fs.rm(dir, { recursive: true, force: true }).catch(() => {});
+    const stat = await fs.stat(dest);
+    return { size: stat.size, etag: etagOfStat(stat) };
+  }
+
+  async abortMultipart(key, uploadId) {
+    await fs.rm(path.join(this.tmp, uploadId), { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+function etagOfStat(stat) {
+  return `"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+}

package/packages/core/src/storage/interface.js

@@ -0,0 +1,222 @@
+// StorageBackend — the pluggable blob store contract.
+//
+// A backend stores opaque byte blobs addressed by a *storage key* (an internal
+// id, NOT the user-visible path — the VFS/metadata layer owns the path↔key map,
+// so rename/move is a metadata edit and never copies bytes).
+//
+// Backends advertise `capabilities` so higher layers degrade gracefully:
+//   - presignDownload/presignUpload: hand the client a direct, time-limited URL
+//     (S3) so big transfers bypass our server entirely.
+//   - multipart: parallel, resumable multi-part uploads.
+//   - range: byte-range reads (needed for media seeking / resumable downloads).
+// A backend that lacks presigning (filesystem, memory) still works — the server
+// proxies the bytes instead.
+//
+// Every method that can fail must throw a TroveError (use wrapError at the
+// boundary). Every long operation must honour an AbortSignal in `opts.signal`.
+
+import { TroveError } from '../errors.js';
+import { readAll, concatBytes } from '../util.js';
+
+// Re-exported for storage backends (memory.js) that assemble chunks themselves.
+export { concatBytes as concat };
+
+/**
+ * @typedef {object} StorageCapabilities
+ * @property {boolean} presignDownload
+ * @property {boolean} presignUpload   single-shot PUT via signed URL
+ * @property {boolean} multipart       parallel multipart uploads
+ * @property {boolean} range           byte-range GET
+ * @property {boolean} list            can enumerate what the store actually holds
+ * @property {boolean} usage           can report how much space is left
+ */
+
+/**
+ * @typedef {object} ObjectInfo
+ * @property {number} size
+ * @property {string} [contentType]
+ * @property {string} [etag]
+ */
+
+export class StorageBackend {
+  /** @type {StorageCapabilities} */
+  get capabilities() {
+    return { presignDownload: false, presignUpload: false, multipart: false, range: false, list: false, usage: false };
+  }
+
+  /**
+   * Store a whole object.
+   * @param {string} key
+   * @param {ReadableStream|Uint8Array|Blob|ArrayBuffer} body
+   * @param {{size?: number, contentType?: string, signal?: AbortSignal, onProgress?: (n:number)=>void}} [opts]
+   * @returns {Promise<ObjectInfo>}
+   */
+  async put(key, body, opts) {
+    throw TroveError.unsupported('put not implemented');
+  }
+
+  /**
+   * Read an object (optionally a byte range).
+   * @param {string} key
+   * @param {{range?: {start:number, end?:number}, signal?: AbortSignal}} [opts]
+   * @returns {Promise<{stream: ReadableStream, size: number, contentType?: string, etag?: string, range?: {start:number,end:number,total:number}}>}
+   */
+  async get(key, opts) {
+    throw TroveError.unsupported('get not implemented');
+  }
+
+  /** @returns {Promise<ObjectInfo>} throws NOT_FOUND if absent. */
+  async head(key) {
+    throw TroveError.unsupported('head not implemented');
+  }
+
+  /** @param {{signal?: AbortSignal}} [opts] */
+  async delete(key, opts) {
+    throw TroveError.unsupported('delete not implemented');
+  }
+
+  /**
+   * Page through the objects actually present in the store.
+   *
+   * Everything else here addresses a key the caller already knows. This is the one
+   * operation that asks the store what it HAS — which is what makes it possible to
+   * notice things that happened without Trove: a file dropped in the bucket by
+   * another tool, an object deleted out from under an item, bytes replaced in place.
+   * Without it the drive can only ever know what it did itself.
+   *
+   * Paged with an opaque cursor rather than returning everything, because a real
+   * bucket does not fit in memory. `capabilities.list` says whether a backend can
+   * answer at all.
+   *
+   * @param {{prefix?: string, cursor?: string|null, limit?: number, signal?: AbortSignal}} [opts]
+   * @returns {Promise<{objects: Array<{key: string, size: number, etag?: string, modifiedAt?: number}>, nextCursor: string|null}>}
+   */
+  async list(opts) {
+    throw TroveError.unsupported('list not implemented');
+  }
+
+  /**
+   * How much room is left.
+   *
+   * Only some backends can answer. A filesystem or a NAS mount knows exactly, and that
+   * is the case where it matters most: a disk fills up and every upload starts failing
+   * with no warning that anything was coming. An object store has no such number — S3
+   * is effectively unbounded and a bucket quota, if any, lives outside the API — so it
+   * returns null rather than inventing one. `capabilities.usage` says which you're
+   * dealing with, so a UI can show a real gauge or say nothing at all instead of
+   * displaying a meter that means nothing.
+   *
+   * @returns {Promise<{used: number, available: number, total: number}|null>}
+   */
+  async usage() {
+    return null;
+  }
+
+  // --- Optional: presigned direct access (S3) --------------------------------
+
+  /** @returns {Promise<string>} a URL the client GETs directly. */
+  async presignGet(key, opts) {
+    throw TroveError.unsupported('This backend cannot presign downloads');
+  }
+  /** @returns {Promise<string>} a URL the client PUTs a whole object to. */
+  async presignPut(key, opts) {
+    throw TroveError.unsupported('This backend cannot presign uploads');
+  }
+
+  // --- Optional: multipart (S3) ----------------------------------------------
+
+  /** @returns {Promise<string>} uploadId */
+  async createMultipart(key, opts) {
+    throw TroveError.unsupported('This backend does not support multipart uploads');
+  }
+  /** @returns {Promise<string>} a signed URL to PUT one part to. */
+  async presignPart(key, uploadId, partNumber, opts) {
+    throw TroveError.unsupported('This backend does not support multipart uploads');
+  }
+  /**
+   * Upload one part directly (non-presign backends).
+   * @returns {Promise<{partNumber:number, etag:string}>}
+   */
+  async putPart(key, uploadId, partNumber, body, opts) {
+    throw TroveError.unsupported('This backend does not support multipart uploads');
+  }
+  /** @param {{partNumber:number, etag:string}[]} parts */
+  async completeMultipart(key, uploadId, parts, opts) {
+    throw TroveError.unsupported('This backend does not support multipart uploads');
+  }
+  async abortMultipart(key, uploadId, opts) {
+    throw TroveError.unsupported('This backend does not support multipart uploads');
+  }
+}
+
+/** Coerce assorted body types into a Uint8Array (used by simple backends). */
+export async function toBytes(body) {
+  if (body == null) return new Uint8Array(0);
+  if (body instanceof Uint8Array) return body;
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  if (typeof Blob !== 'undefined' && body instanceof Blob) {
+    return new Uint8Array(await body.arrayBuffer());
+  }
+  if (typeof body === 'string') return new TextEncoder().encode(body);
+  if (body instanceof ReadableStream || typeof body?.getReader === 'function') {
+    return await readAll(body);
+  }
+  // Async iterable (Node stream)
+  if (typeof body?.[Symbol.asyncIterator] === 'function') {
+    const chunks = [];
+    for await (const c of body) chunks.push(c instanceof Uint8Array ? c : new Uint8Array(c));
+    return concatBytes(chunks);
+  }
+  throw TroveError.invalid('Unsupported body type');
+}
+
+/**
+ * Resolve a requested byte range against an object's real size.
+ *
+ * Two cases the per-backend copies of this arithmetic each got wrong:
+ *
+ * The SUFFIX form — `bytes=-500` means "the last 500 bytes" (RFC 9110 §14.1.4), and
+ * media players and container-footer probes send it routinely. Read as `{start: 0}`
+ * it served the FRONT of the file under a 206 that claimed to be what was asked for,
+ * which a client has no way to detect.
+ *
+ * An EMPTY object is deliberately not treated as unsatisfiable. A 0-byte file is a
+ * real file, and `end = total - 1 = -1` made every one of them throw: permanently
+ * un-indexable (a standing issue whose Retry re-runs the same failure) and unopenable
+ * in the text viewer, which reads through a range. The whole of it is zero bytes, so
+ * that is what we serve.
+ *
+ * @returns {{start:number,end:number,total:number}|null} null → serve the whole object
+ */
+export function resolveRange(range, total) {
+  if (!range || total === 0) return null;
+  let start;
+  let end;
+  if (range.suffix != null) {
+    const n = Math.min(range.suffix, total);
+    // `bytes=-0` asks for the last zero bytes, which is unsatisfiable by definition —
+    // and S3 answers it with the WHOLE object under a 200, so it has to be caught here
+    // rather than left to the backend.
+    if (n <= 0) throw TroveError.badRange('Range not satisfiable');
+    start = total - n;
+    end = total - 1;
+  } else {
+    start = range.start ?? 0;
+    end = range.end != null ? Math.min(range.end, total - 1) : total - 1;
+  }
+  if (start < 0 || start > end || start >= total) throw TroveError.badRange('Range not satisfiable');
+  return { start, end, total };
+}
+
+/** A ReadableStream over an in-memory byte array (with optional range). */
+export function bytesStream(bytes, range) {
+  const start = range?.start ?? 0;
+  const end = range?.end != null ? Math.min(range.end + 1, bytes.length) : bytes.length;
+  const slice = bytes.subarray(start, end);
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(slice);
+      controller.close();
+    },
+  });
+}