@romedb/node 0.2.12 → 0.2.13

package/THIRD_PARTY_CRATE_NOTICES.md

@@ -4,7 +4,7 @@ Generated from the pinned Cargo dependency inventory and checksummed source arch
 
 This is a partial notice collection. It supplements LICENSE.md and THIRD_PARTY_NOTICES.md. Inline attributions, unconventional filenames and other bundled components require further review before a complete distribution-notice claim.
 
-Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `f065eb377ff1eed208add1ebb20ee8039e125fcfb4dbd38cd663c4933167c709`.
+Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `092e973bbc52cf5defe48c0c1c1cf5bc8755b603f5a6ef47927c31bfa5276aa3`.
 
 ## Packages without collected archive or supplemental texts
 
@@ -703,13 +703,13 @@ Target: `x86_64-unknown-linux-gnu`. Cargo.lock SHA-256: `f065eb377ff1eed208add1e
 - `LICENSE-APACHE`: [source text a60eea817514531668d7e00765731449fe14d059d3249e0bc93b36de45f759f2](#text-a60eea817514531668d7e00765731449fe14d059d3249e0bc93b36de45f759f2)
 - `LICENSE-MIT`: [source text 42d3bf7e7d4d49d72c0555d14ed99c3ee7ce9ce3cbffbc38bbafe8c103f50969](#text-42d3bf7e7d4d49d72c0555d14ed99c3ee7ce9ce3cbffbc38bbafe8c103f50969)
 
-### romedb-node 0.2.12
+### romedb-node 0.2.13
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
-### romedb 0.2.12
+### romedb 0.2.13
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
-### romeql-parser 0.2.12
+### romeql-parser 0.2.13
 - Workspace `LICENSE.md`: [source text b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5](#text-b646f9ee8bcaf87e8de75153b9df7a2861c7ac445c87e741768b3c2bccf47bc5)
 
 ### rquickjs-core 0.13.0

package/client.cjs

@@ -7,6 +7,7 @@ const MAX_CLOUD_REQUEST = 1_048_576;
 const CLOUD_QUERY_VERSION = 3;
 const MAX_RESPONSE = 524_288;
 const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER - 1;
+const DATABASE_FILE_TYPE = 'application/vnd.romedb.database';
 const construction = Symbol('RemoteDatabase');
 const warmAtConnect = Symbol('warmAtConnect');
 const WARM_STATES = new Set(['ready', 'starting', 'skipped']);
@@ -74,7 +75,7 @@ class RemoteDatabase {
   async info(options = {}) {
     const info = await this.#request('', undefined, options, false);
     if (!plainObject(info) || typeof info.id !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(info.id) || !sequence(info.sequence, true) || (this.#id !== undefined && this.#id !== info.id)) {
-      throw new ClientError('FDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
+      throw new ClientError('RDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
     }
     if (this.#loopbackOrganization) this.#cloud = info.serviceVersion === undefined;
     const supported = capabilities(this.#url, info, !this.#cloud);
@@ -86,14 +87,14 @@ class RemoteDatabase {
   }
   async warm(options = {}) {
     this.#assertOpen();
-    if (!this.#cloud) throw new ClientError('FDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
+    if (!this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
     const reply = await this.#request('/warm', '{}', options, false);
-    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('FDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
+    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('RDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
     return { state: reply.state };
   }
   async read(statements, options = {}) {
     this.#assertOpen();
-    if (this.#capabilities.readVersion !== 2) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
+    if (this.#capabilities.readVersion !== 2) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
     if (options.ifSequence !== undefined) throw new TypeError('fresh reads do not accept ifSequence');
     const afterSequence = options.afterSequence ?? this.#sequence;
     checkSequence(afterSequence);
@@ -110,12 +111,12 @@ class RemoteDatabase {
   }
   prepareWrite(statements, options = {}) {
     this.#assertOpen();
-    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('FDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
+    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('RDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
     const afterSequence = options.afterSequence ?? this.#sequence;
     checkSequence(afterSequence);
     if (options.ifSequence !== undefined) {
-      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
+      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
       checkSequence(options.ifSequence);
       if (options.ifSequence < afterSequence) throw new RangeError('ifSequence must be at least afterSequence');
     }
@@ -130,8 +131,8 @@ class RemoteDatabase {
   async submit(prepared, options = {}) {
     this.#assertOpen();
     const request = validatePrepared(prepared);
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
-    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('FDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
+    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('RDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
     try {
       const reply = await this.#request('/query', prepared.body, options, true, prepared, preparedQueryVersion(prepared));
       const result = confirmReply(reply, request, false, prepared);
@@ -143,7 +144,7 @@ class RemoteDatabase {
         if (error.outcome === 'rolled-back') this.#sequence = Math.max(this.#sequence, error.sequence);
         throw error;
       }
-      throw new ClientError('FDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
+      throw new ClientError('RDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
     }
   }
   async recover(prepared, options = {}) {
@@ -157,22 +158,79 @@ class RemoteDatabase {
     if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) await this.info(options);
     return this.submit(this.prepareWrite(statements, options), options);
   }
+  async exportFile(options = {}) {
+    this.#assertOpen();
+    if (this.#transport) throw new ClientError('RDB_UNSUPPORTED', 'Export embedded databases through EmbeddedDatabase.exportFile', 'not-sent');
+    if (this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'Cloud databases do not export database files yet', 'not-sent');
+    if (!plainObject(options) || Object.keys(options).some(key => !['signal', 'timeoutMs'].includes(key))) throw new TypeError('export options take signal and timeoutMs');
+    const duration = timeout(options.timeoutMs ?? this.#timeout);
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
+    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent');
+    if (this.#active.size >= 32) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, duration);
+    this.#active.add(controller);
+    let open = true;
+    const finish = () => {
+      if (!open) return;
+      open = false;
+      clearTimeout(timer);
+      options.signal?.removeEventListener('abort', abort);
+      this.#active.delete(controller);
+    };
+    const credential = this.#token;
+    let status;
+    try {
+      const response = await this.#fetch(this.#url + '/file', {
+        method: 'GET',
+        headers: { authorization: `Bearer ${credential}`, accept: `${DATABASE_FILE_TYPE}, application/json`, ...(this.#id === undefined ? {} : { 'x-romedb-database-id': this.#id }) },
+        redirect: 'manual', signal: controller.signal,
+      });
+      // The deadline covers building the copy; the caller's signal still stops the download.
+      clearTimeout(timer);
+      status = response.status;
+      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', 'read-failed', { status });
+      if (!response.ok) {
+        const retryAfterMs = retryAfter(response.headers.get('retry-after'));
+        const reply = await boundedJson(response, MAX_RESPONSE).catch(() => undefined);
+        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
+        throw new ClientError(code, safeMessage(reply, credential), 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) });
+      }
+      const size = Number(/^\d{1,16}$/.exec(response.headers.get('content-length') ?? '')?.[0] ?? NaN);
+      const exported = Number(/^\d{1,16}$/.exec(response.headers.get('x-romedb-sequence') ?? '')?.[0] ?? NaN);
+      const identity = response.headers.get('x-romedb-database-id');
+      if ((response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() !== DATABASE_FILE_TYPE || !Number.isSafeInteger(size) || !sequence(exported, true) || !response.body) {
+        throw new ClientError('RDB_PROTOCOL', 'Invalid database file response', 'read-failed', { status });
+      }
+      if (identity === null || (this.#id !== undefined && identity !== this.#id)) throw new ClientError('RDB_REQUEST_IDENTITY', 'Database file belongs to another database', 'read-failed', { status });
+      this.#id ??= identity;
+      this.#sequence = Math.max(this.#sequence, exported);
+      this.#sequenceKnown = true;
+      return { sequence: exported, size, body: countedBody(response.body, size, controller, finish) };
+    } catch (error) {
+      finish();
+      if (error instanceof ClientError) throw new ClientError(error.code, redactMessage(error.message, credential), error.outcome, { ...(error.status === undefined ? {} : { status: error.status }), ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }) });
+      throw new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL', 'Database file request failed', 'read-failed', { ...(status === undefined ? {} : { status }), cause: error });
+    }
+  }
   async close() {
     this.#closed = true;
     for (const controller of this.#active) controller.abort();
     this.#token = '';
   }
   #assertOpen() {
-    if (this.#closed) throw new ClientError('FDB_CLOSED', 'Database client is closed', 'not-sent');
+    if (this.#closed) throw new ClientError('RDB_CLOSED', 'Database client is closed', 'not-sent');
   }
   #queryVersion() { return this.#cloud ? CLOUD_QUERY_VERSION : 2; }
   async #request(path, body, options, writing, prepared, queryVersion = 2) {
     this.#assertOpen();
     const duration = timeout(options.timeoutMs ?? this.#timeout);
     if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
-    if (options.signal?.aborted) throw new ClientError('FDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
+    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
     const bodyBytes = body === undefined ? 0 : byteLength(body);
-    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('FDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
+    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
     const controller = new AbortController();
     const abort = () => controller.abort();
     options.signal?.addEventListener('abort', abort, { once: true });
@@ -200,18 +258,18 @@ class RemoteDatabase {
       status = response.status;
       if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) {
         await response.body?.cancel().catch(() => {});
-        throw new ClientError('FDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+        throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
       }
       const retryAfterMs = retryAfter(response.headers.get('retry-after'));
       const replyVersion = response.headers.get('x-romedb-query-version');
       if ((path === '/query' || path === '/read') && replyVersion !== null && replyVersion !== '2' && replyVersion !== String(queryVersion)) {
         await response.body?.cancel();
-        throw new ClientError('FDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+        throw new ClientError('RDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
       }
       const reply = await boundedJson(response, MAX_RESPONSE);
       if (plainObject(reply?.error) && typeof reply.error.message === 'string') reply.error.message = redactMessage(reply.error.message, credential);
       if (!response.ok && !(writing && reply?.requestId && reply?.sequence !== undefined)) {
-        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
+        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
         throw new ClientError(code, safeMessage(reply, credential), writing ? 'unknown' : 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }), ...(prepared ? { request: prepared } : {}) });
       }
       return reply;
@@ -227,7 +285,7 @@ class RemoteDatabase {
           ...(prepared ? { request: prepared } : {}),
         });
       }
-      const code = controller.signal.aborted ? 'FDB_CANCELLED' : status === undefined ? 'FDB_TRANSPORT' : 'FDB_PROTOCOL';
+      const code = controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL';
       throw new ClientError(code, writing ? 'Write was not confirmed; recover the saved request' : 'Database request failed', writing ? 'unknown' : 'read-failed', { ...(status === undefined ? {} : { status }), ...(prepared ? { request: prepared } : {}), cause: error });
     } finally {
       clearTimeout(timer);
@@ -297,9 +355,9 @@ function validatePrepared(prepared) {
 }
 
 function confirmReply(reply, request, reading, prepared) {
-  const invalid = () => new ClientError('FDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
+  const invalid = () => new ClientError('RDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
   if (!plainObject(reply) || reply.requestId !== request.requestId || !sequence(reply.sequence, true) || (reading ? reply.readVersion !== 2 || reply.sequence < request.afterSequence : reply.readVersion !== undefined || reply.sequence <= request.afterSequence || reply.sequence - request.afterSequence > 64)) throw invalid();
-  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
+  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
   if (!Array.isArray(reply.results) || reply.results.length !== request.statements.length || reply.error !== undefined || byteLength(JSON.stringify(reply.results)) > 262_144) throw invalid();
   try {
     const results = reply.results.map(result => {
@@ -334,11 +392,39 @@ async function boundedJson(response, limit) {
   } finally { await reader.cancel().catch(() => {}); }
 }
 
+// Passes the download through and fails it unless exactly `size` bytes arrive.
+function countedBody(body, size, controller, finish) {
+  const reader = body.getReader();
+  let received = 0;
+  const failure = (message, cause) => new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : 'RDB_TRANSPORT', message, 'read-failed', cause === undefined ? {} : { cause });
+  return new ReadableStream({
+    async pull(stream) {
+      let chunk;
+      try { chunk = await reader.read(); }
+      catch (error) { finish(); stream.error(failure('Database file download failed', error)); return; }
+      if (chunk.done) {
+        finish();
+        if (received === size) stream.close();
+        else stream.error(failure('Database file ended before its declared size'));
+        return;
+      }
+      received += chunk.value.byteLength;
+      if (received > size) {
+        finish(); controller.abort();
+        stream.error(new ClientError('RDB_PROTOCOL', 'Database file is larger than its declared size', 'read-failed'));
+        return;
+      }
+      stream.enqueue(chunk.value);
+    },
+    cancel(reason) { finish(); controller.abort(); return reader.cancel(reason).catch(() => {}); },
+  }, { highWaterMark: 0 });
+}
+
 function loopbackHost(hostname) { return ['127.0.0.1', 'localhost', '[::1]'].includes(hostname); }
 
 function capabilities(url, info, local) {
   if (local) {
-    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('FDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
+    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('RDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
     return { ...info.capabilities, provenance: 'negotiated' };
   }
   return { provenance: 'documented', readVersion: 2, atomicWrites: true, replayWindow: 64, exactSequenceCondition: true, negotiatedLimits: false };
@@ -387,7 +473,7 @@ function pause(ms, signal) {
     signal.addEventListener('abort', stop, { once: true });
   });
 }
-function httpCode(status) { return status === 401 ? 'FDB_AUTH' : status === 403 ? 'FDB_FORBIDDEN' : status === 409 ? 'FDB_CONFLICT' : status === 429 || status === 413 ? 'FDB_LIMIT' : 'FDB_REMOTE'; }
+function httpCode(status) { return status === 401 ? 'RDB_AUTH' : status === 403 ? 'RDB_FORBIDDEN' : status === 409 ? 'RDB_CONFLICT' : status === 429 || status === 413 ? 'RDB_LIMIT' : 'RDB_REMOTE'; }
 function redactMessage(message, token) { return (token ? message.replaceAll(token, '[redacted]') : message).slice(0, 2048); }
 function safeMessage(reply, token) { return redactMessage(typeof reply?.error === 'string' ? reply.error : typeof reply?.error?.message === 'string' ? reply.error.message : 'Database request was rejected', token); }
 

package/client.d.ts

@@ -25,6 +25,15 @@ export interface ConnectOptions {
   warm?: boolean;
 }
 export interface WarmResult { state: 'ready' | 'starting' | 'skipped'; }
+/** A copy of the database at one sequence: a complete .romedb file that opens without a log beside it. */
+export interface DatabaseFile {
+  /** Every write up to and including this sequence is in the file, and none after it. */
+  sequence: number;
+  /** File size in bytes; the body fails unless exactly this many arrive. */
+  size: number;
+  /** Read it to the end or cancel it, so the copy's storage is freed. */
+  body: ReadableStream<Uint8Array>;
+}
 export type Outcome = 'not-sent' | 'read-failed' | 'unknown' | 'rolled-back';
 export class ClientError extends Error {
   readonly code: string;
@@ -34,7 +43,7 @@ export class ClientError extends Error {
   readonly sequence?: number;
   /** The server's Retry-After delay in milliseconds, on HTTP error replies that send one. */
   readonly retryAfterMs?: number;
-  /** For FDB_TRANSPORT, FDB_PROTOCOL and FDB_CANCELLED without a reply: the fetch or parse error underneath. */
+  /** For RDB_TRANSPORT, RDB_PROTOCOL and RDB_CANCELLED without a reply: the fetch or parse error underneath. */
   readonly cause?: unknown;
   constructor(code: string, message: string, outcome: Outcome, details?: { request?: PreparedWrite; status?: number; sequence?: number; retryAfterMs?: number; cause?: unknown });
 }
@@ -60,6 +69,11 @@ export class RemoteDatabase implements Client {
   readonly deferred: boolean;
   /** Ask Cloud to start the database's container and open the database without running a query. */
   warm(options?: RequestOptions): Promise<WarmResult>;
+  /**
+   * Download the database as a .romedb file (romedb serve and serve --directory; not Cloud yet).
+   * timeoutMs covers building the copy, until the file starts arriving; signal also stops the download.
+   */
+  exportFile(options?: RequestOptions): Promise<DatabaseFile>;
   readonly sequence: number;
   readonly databaseId: string;
   info(options?: RequestOptions): Promise<DatabaseInfo>;

package/client.mjs

@@ -12,6 +12,7 @@ const MAX_CLOUD_REQUEST = 1_048_576;
 const CLOUD_QUERY_VERSION = 3;
 const MAX_RESPONSE = 524_288;
 const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER - 1;
+const DATABASE_FILE_TYPE = 'application/vnd.romedb.database';
 const construction = Symbol('RemoteDatabase');
 const warmAtConnect = Symbol('warmAtConnect');
 const WARM_STATES = new Set(['ready', 'starting', 'skipped']);
@@ -79,7 +80,7 @@ class RemoteDatabase {
   async info(options = {}) {
     const info = await this.#request('', undefined, options, false);
     if (!plainObject(info) || typeof info.id !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(info.id) || !sequence(info.sequence, true) || (this.#id !== undefined && this.#id !== info.id)) {
-      throw new ClientError('FDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
+      throw new ClientError('RDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
     }
     if (this.#loopbackOrganization) this.#cloud = info.serviceVersion === undefined;
     const supported = capabilities(this.#url, info, !this.#cloud);
@@ -91,14 +92,14 @@ class RemoteDatabase {
   }
   async warm(options = {}) {
     this.#assertOpen();
-    if (!this.#cloud) throw new ClientError('FDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
+    if (!this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
     const reply = await this.#request('/warm', '{}', options, false);
-    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('FDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
+    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('RDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
     return { state: reply.state };
   }
   async read(statements, options = {}) {
     this.#assertOpen();
-    if (this.#capabilities.readVersion !== 2) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
+    if (this.#capabilities.readVersion !== 2) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
     if (options.ifSequence !== undefined) throw new TypeError('fresh reads do not accept ifSequence');
     const afterSequence = options.afterSequence ?? this.#sequence;
     checkSequence(afterSequence);
@@ -115,12 +116,12 @@ class RemoteDatabase {
   }
   prepareWrite(statements, options = {}) {
     this.#assertOpen();
-    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('FDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
+    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('RDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
     const afterSequence = options.afterSequence ?? this.#sequence;
     checkSequence(afterSequence);
     if (options.ifSequence !== undefined) {
-      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
+      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
       checkSequence(options.ifSequence);
       if (options.ifSequence < afterSequence) throw new RangeError('ifSequence must be at least afterSequence');
     }
@@ -135,8 +136,8 @@ class RemoteDatabase {
   async submit(prepared, options = {}) {
     this.#assertOpen();
     const request = validatePrepared(prepared);
-    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
-    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('FDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('RDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
+    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('RDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
     try {
       const reply = await this.#request('/query', prepared.body, options, true, prepared, preparedQueryVersion(prepared));
       const result = confirmReply(reply, request, false, prepared);
@@ -148,7 +149,7 @@ class RemoteDatabase {
         if (error.outcome === 'rolled-back') this.#sequence = Math.max(this.#sequence, error.sequence);
         throw error;
       }
-      throw new ClientError('FDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
+      throw new ClientError('RDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
     }
   }
   async recover(prepared, options = {}) {
@@ -162,22 +163,79 @@ class RemoteDatabase {
     if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) await this.info(options);
     return this.submit(this.prepareWrite(statements, options), options);
   }
+  async exportFile(options = {}) {
+    this.#assertOpen();
+    if (this.#transport) throw new ClientError('RDB_UNSUPPORTED', 'Export embedded databases through EmbeddedDatabase.exportFile', 'not-sent');
+    if (this.#cloud) throw new ClientError('RDB_UNSUPPORTED', 'Cloud databases do not export database files yet', 'not-sent');
+    if (!plainObject(options) || Object.keys(options).some(key => !['signal', 'timeoutMs'].includes(key))) throw new TypeError('export options take signal and timeoutMs');
+    const duration = timeout(options.timeoutMs ?? this.#timeout);
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
+    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent');
+    if (this.#active.size >= 32) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, duration);
+    this.#active.add(controller);
+    let open = true;
+    const finish = () => {
+      if (!open) return;
+      open = false;
+      clearTimeout(timer);
+      options.signal?.removeEventListener('abort', abort);
+      this.#active.delete(controller);
+    };
+    const credential = this.#token;
+    let status;
+    try {
+      const response = await this.#fetch(this.#url + '/file', {
+        method: 'GET',
+        headers: { authorization: `Bearer ${credential}`, accept: `${DATABASE_FILE_TYPE}, application/json`, ...(this.#id === undefined ? {} : { 'x-romedb-database-id': this.#id }) },
+        redirect: 'manual', signal: controller.signal,
+      });
+      // The deadline covers building the copy; the caller's signal still stops the download.
+      clearTimeout(timer);
+      status = response.status;
+      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', 'read-failed', { status });
+      if (!response.ok) {
+        const retryAfterMs = retryAfter(response.headers.get('retry-after'));
+        const reply = await boundedJson(response, MAX_RESPONSE).catch(() => undefined);
+        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
+        throw new ClientError(code, safeMessage(reply, credential), 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) });
+      }
+      const size = Number(/^\d{1,16}$/.exec(response.headers.get('content-length') ?? '')?.[0] ?? NaN);
+      const exported = Number(/^\d{1,16}$/.exec(response.headers.get('x-romedb-sequence') ?? '')?.[0] ?? NaN);
+      const identity = response.headers.get('x-romedb-database-id');
+      if ((response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() !== DATABASE_FILE_TYPE || !Number.isSafeInteger(size) || !sequence(exported, true) || !response.body) {
+        throw new ClientError('RDB_PROTOCOL', 'Invalid database file response', 'read-failed', { status });
+      }
+      if (identity === null || (this.#id !== undefined && identity !== this.#id)) throw new ClientError('RDB_REQUEST_IDENTITY', 'Database file belongs to another database', 'read-failed', { status });
+      this.#id ??= identity;
+      this.#sequence = Math.max(this.#sequence, exported);
+      this.#sequenceKnown = true;
+      return { sequence: exported, size, body: countedBody(response.body, size, controller, finish) };
+    } catch (error) {
+      finish();
+      if (error instanceof ClientError) throw new ClientError(error.code, redactMessage(error.message, credential), error.outcome, { ...(error.status === undefined ? {} : { status: error.status }), ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }) });
+      throw new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL', 'Database file request failed', 'read-failed', { ...(status === undefined ? {} : { status }), cause: error });
+    }
+  }
   async close() {
     this.#closed = true;
     for (const controller of this.#active) controller.abort();
     this.#token = '';
   }
   #assertOpen() {
-    if (this.#closed) throw new ClientError('FDB_CLOSED', 'Database client is closed', 'not-sent');
+    if (this.#closed) throw new ClientError('RDB_CLOSED', 'Database client is closed', 'not-sent');
   }
   #queryVersion() { return this.#cloud ? CLOUD_QUERY_VERSION : 2; }
   async #request(path, body, options, writing, prepared, queryVersion = 2) {
     this.#assertOpen();
     const duration = timeout(options.timeoutMs ?? this.#timeout);
     if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
-    if (options.signal?.aborted) throw new ClientError('FDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
+    if (options.signal?.aborted) throw new ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
     const bodyBytes = body === undefined ? 0 : byteLength(body);
-    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('FDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
+    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
     const controller = new AbortController();
     const abort = () => controller.abort();
     options.signal?.addEventListener('abort', abort, { once: true });
@@ -205,18 +263,18 @@ class RemoteDatabase {
       status = response.status;
       if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) {
         await response.body?.cancel().catch(() => {});
-        throw new ClientError('FDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+        throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
       }
       const retryAfterMs = retryAfter(response.headers.get('retry-after'));
       const replyVersion = response.headers.get('x-romedb-query-version');
       if ((path === '/query' || path === '/read') && replyVersion !== null && replyVersion !== '2' && replyVersion !== String(queryVersion)) {
         await response.body?.cancel();
-        throw new ClientError('FDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+        throw new ClientError('RDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
       }
       const reply = await boundedJson(response, MAX_RESPONSE);
       if (plainObject(reply?.error) && typeof reply.error.message === 'string') reply.error.message = redactMessage(reply.error.message, credential);
       if (!response.ok && !(writing && reply?.requestId && reply?.sequence !== undefined)) {
-        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
+        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
         throw new ClientError(code, safeMessage(reply, credential), writing ? 'unknown' : 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }), ...(prepared ? { request: prepared } : {}) });
       }
       return reply;
@@ -232,7 +290,7 @@ class RemoteDatabase {
           ...(prepared ? { request: prepared } : {}),
         });
       }
-      const code = controller.signal.aborted ? 'FDB_CANCELLED' : status === undefined ? 'FDB_TRANSPORT' : 'FDB_PROTOCOL';
+      const code = controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL';
       throw new ClientError(code, writing ? 'Write was not confirmed; recover the saved request' : 'Database request failed', writing ? 'unknown' : 'read-failed', { ...(status === undefined ? {} : { status }), ...(prepared ? { request: prepared } : {}), cause: error });
     } finally {
       clearTimeout(timer);
@@ -302,9 +360,9 @@ function validatePrepared(prepared) {
 }
 
 function confirmReply(reply, request, reading, prepared) {
-  const invalid = () => new ClientError('FDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
+  const invalid = () => new ClientError('RDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
   if (!plainObject(reply) || reply.requestId !== request.requestId || !sequence(reply.sequence, true) || (reading ? reply.readVersion !== 2 || reply.sequence < request.afterSequence : reply.readVersion !== undefined || reply.sequence <= request.afterSequence || reply.sequence - request.afterSequence > 64)) throw invalid();
-  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
+  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
   if (!Array.isArray(reply.results) || reply.results.length !== request.statements.length || reply.error !== undefined || byteLength(JSON.stringify(reply.results)) > 262_144) throw invalid();
   try {
     const results = reply.results.map(result => {
@@ -339,11 +397,39 @@ async function boundedJson(response, limit) {
   } finally { await reader.cancel().catch(() => {}); }
 }
 
+// Passes the download through and fails it unless exactly `size` bytes arrive.
+function countedBody(body, size, controller, finish) {
+  const reader = body.getReader();
+  let received = 0;
+  const failure = (message, cause) => new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : 'RDB_TRANSPORT', message, 'read-failed', cause === undefined ? {} : { cause });
+  return new ReadableStream({
+    async pull(stream) {
+      let chunk;
+      try { chunk = await reader.read(); }
+      catch (error) { finish(); stream.error(failure('Database file download failed', error)); return; }
+      if (chunk.done) {
+        finish();
+        if (received === size) stream.close();
+        else stream.error(failure('Database file ended before its declared size'));
+        return;
+      }
+      received += chunk.value.byteLength;
+      if (received > size) {
+        finish(); controller.abort();
+        stream.error(new ClientError('RDB_PROTOCOL', 'Database file is larger than its declared size', 'read-failed'));
+        return;
+      }
+      stream.enqueue(chunk.value);
+    },
+    cancel(reason) { finish(); controller.abort(); return reader.cancel(reason).catch(() => {}); },
+  }, { highWaterMark: 0 });
+}
+
 function loopbackHost(hostname) { return ['127.0.0.1', 'localhost', '[::1]'].includes(hostname); }
 
 function capabilities(url, info, local) {
   if (local) {
-    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('FDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
+    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('RDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
     return { ...info.capabilities, provenance: 'negotiated' };
   }
   return { provenance: 'documented', readVersion: 2, atomicWrites: true, replayWindow: 64, exactSequenceCondition: true, negotiatedLimits: false };
@@ -392,7 +478,7 @@ function pause(ms, signal) {
     signal.addEventListener('abort', stop, { once: true });
   });
 }
-function httpCode(status) { return status === 401 ? 'FDB_AUTH' : status === 403 ? 'FDB_FORBIDDEN' : status === 409 ? 'FDB_CONFLICT' : status === 429 || status === 413 ? 'FDB_LIMIT' : 'FDB_REMOTE'; }
+function httpCode(status) { return status === 401 ? 'RDB_AUTH' : status === 403 ? 'RDB_FORBIDDEN' : status === 409 ? 'RDB_CONFLICT' : status === 429 || status === 413 ? 'RDB_LIMIT' : 'RDB_REMOTE'; }
 function redactMessage(message, token) { return (token ? message.replaceAll(token, '[redacted]') : message).slice(0, 2048); }
 function safeMessage(reply, token) { return redactMessage(typeof reply?.error === 'string' ? reply.error : typeof reply?.error?.message === 'string' ? reply.error.message : 'Database request was rejected', token); }