marcidb-client 0.15.0 → 0.16.0

package/README.md

@@ -34,12 +34,15 @@ marcidb generate
 marcidb generate schema.marci node_modules/.marcidb/client
 ```
 
-3. Start your MarciDB server and connect:
+3. Start your MarciDB server and connect — the database name is the last segment of the URL:
 
 ```typescript
 import { marcidb } from "marcidb-client";
 
-const db = marcidb("http://localhost:3000");
+const db = marcidb("http://localhost:3000/myapp");
+
+// a server started with --token (or an embedded app's maintenance port opened with one)
+const secured = marcidb("http://localhost:3000/myapp", { token: process.env.MARCI_TOKEN });
 ```
 
 ## Usage
@@ -47,7 +50,7 @@ const db = marcidb("http://localhost:3000");
 ```typescript
 import { marcidb } from "marcidb-client";
 
-const db = marcidb("http://localhost:3000");
+const db = marcidb("http://localhost:3000/myapp");
 
 // Find — a chainable query; no select = id + every scalar
 const users = await db.user.where({ name: { $startsWith: "A" } }).order("id", "desc").limit(20);

package/bin.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
@@ -26,6 +28,9 @@ function binPath(base) {
   return path.join(__dirname, "bin", `${base}-${suffix}`);
 }
 
+// Flags that never take a value (so `--yes backup.marcibin` keeps the file as a positional argument)
+const BOOLEAN_FLAGS = new Set(["yes", "no-migrations"]);
+
 // Parses positional arguments and flags (--flag value | --flag)
 function parseArgs(args) {
   const positional = [];
@@ -35,7 +40,7 @@ function parseArgs(args) {
     if (a.startsWith("--")) {
       const key = a.slice(2);
       const next = args[i + 1];
-      if (next === undefined || next.startsWith("--")) {
+      if (BOOLEAN_FLAGS.has(key) || next === undefined || next.startsWith("--")) {
         flags[key] = true;
       } else {
         flags[key] = next;
@@ -66,14 +71,45 @@ Commands:
     --url <url>                   server url (default: http://localhost:3000)
     --migrations <dir>            migrations directory (default: migrations)
 
+  backup <db> [options]           Download a consistent backup of a database (.marcibin)
+    --url <url>                   server url (default: http://localhost:3000)
+    --out <file|dir>              where to write it (default: <db>-<YYYYMMDD-HHMMSS>.marcibin in cwd)
+
+  restore <db> <file> [options]   Upload a backup; replaces the live database <db>
+    --url <url>                   server url (default: http://localhost:3000)
+    --into <name>                 restore under another name instead (created if missing)
+    --yes                         confirm replacing a database that exists
+
+  inspect <file|dir> [options]    Read a backup, or a database directory no process has open
+    --tree <name>                 list one tree's entries (rows decoded through the schema)
+    --limit <n>                   entries to show (default: 20)
+    --id <json>                   one row of a model tree, by id
+    --raw                         hex keys/values; row headers annotated
+
+Every command talking to a server sends --token <token> (or $MARCI_TOKEN) as a bearer token.
+
 Examples:
   marcidb generate
   marcidb generate schema.marci --name add_users
   marcidb migrate push myapp --url http://localhost:3000
   marcidb migrate check myapp
+  marcidb backup myapp --out backups/
+  marcidb restore myapp backups/myapp-20261012-030000.marcibin --into myapp_check
+  marcidb inspect backups/myapp-20261012-030000.marcibin --tree User --limit 5
 `);
 }
 
+// The server url (--url, default local) without a trailing slash
+function serverUrl(flags) {
+  return (flags.url ?? "http://localhost:3000").replace(/\/+$/, "");
+}
+
+// `Authorization: Bearer` for a server started with --token / MARCI_TOKEN
+function authHeaders(flags) {
+  const token = typeof flags.token === "string" ? flags.token : process.env.MARCI_TOKEN;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
 function cmdGenerate(args) {
   const { positional, flags } = parseArgs(args);
   const schema = positional[0] ?? "schema.marci";
@@ -112,8 +148,8 @@ async function cmdMigrate(args) {
 }
 
 // The server's current snapshot ("" if the DB doesn't exist yet)
-async function fetchServerSnapshot(url, db) {
-  const res = await fetch(`${url}/${db}/$snapshot`);
+async function fetchServerSnapshot(url, db, flags) {
+  const res = await fetch(`${url}/${db}/$snapshot`, { headers: authHeaders(flags) });
   if (res.ok) return await res.text();
   if (res.status === 404) return "";
   console.error(`Cannot read server snapshot [${res.status}]: ${await res.text()}`);
@@ -135,21 +171,21 @@ async function migratePush(rest) {
   const db = positional[0];
   if (!db) { console.error("marcidb migrate push: <db> name required"); process.exit(1); }
 
-  const url = (flags.url ?? "http://localhost:3000").replace(/\/+$/, "");
+  const url = serverUrl(flags);
   const dir = flags.migrations ?? "migrations";
   if (!fs.existsSync(dir)) {
     console.error(`marcidb migrate push: migrations directory "${dir}" not found — run "marcidb generate" first`);
     process.exit(1);
   }
 
-  const serverSnap = await fetchServerSnapshot(url, db);
+  const serverSnap = await fetchServerSnapshot(url, db, flags);
   const plan = planActions(dir, serverSnap);
   if (plan.error !== undefined) { console.error(`Migration planning failed: ${plan.error}`); process.exit(1); }
   if (!plan.out.trim()) { console.log(`'${db}' is up to date — nothing to push`); return; }
 
   const res = await fetch(`${url}/${db}/$migrate`, {
     method: "POST",
-    headers: { "Content-Type": "text/plain" },
+    headers: { "Content-Type": "text/plain", ...authHeaders(flags) },
     body: plan.out,
   });
   if (!res.ok) { console.error(`Migration failed [${res.status}]: ${await res.text()}`); process.exit(1); }
@@ -162,10 +198,10 @@ async function migrateCheck(rest) {
   const db = positional[0];
   if (!db) { console.error("marcidb migrate check: <db> name required"); process.exit(1); }
 
-  const url = (flags.url ?? "http://localhost:3000").replace(/\/+$/, "");
+  const url = serverUrl(flags);
   const dir = flags.migrations ?? "migrations";
 
-  const serverSnap = await fetchServerSnapshot(url, db);
+  const serverSnap = await fetchServerSnapshot(url, db, flags);
   const plan = planActions(dir, serverSnap);
   if (plan.error !== undefined) {
     console.error(`'${db}' has DIVERGED — the server schema isn't a point in your migration history.`);
@@ -179,9 +215,89 @@ async function migrateCheck(rest) {
   }
 }
 
+// `20261012-120000` for a local timestamp (the server's file name carries the snapshot time instead)
+function stamp() {
+  return new Date().toISOString().replace(/\.\d+Z$/, "").replace(/[-:]/g, "").replace("T", "-");
+}
+
+// Backup: GET /:db/$backup streamed to <out>.tmp, renamed when complete. A download that breaks off
+// (the server aborts the response when its copy fails) leaves nothing behind.
+async function cmdBackup(args) {
+  const { positional, flags } = parseArgs(args);
+  const db = positional[0];
+  if (!db) { console.error("marcidb backup: <db> name required"); process.exit(1); }
+
+  const url = serverUrl(flags);
+  const res = await fetch(`${url}/${db}/$backup`, { headers: authHeaders(flags) });
+  if (!res.ok) { console.error(`Backup failed [${res.status}]: ${await res.text()}`); process.exit(1); }
+
+  const offered = /filename="([^"]+)"/.exec(res.headers.get("content-disposition") ?? "")?.[1];
+  const name = path.basename(offered ?? `${db}-${stamp()}.marcibin`);
+  const outFlag = typeof flags.out === "string" ? flags.out : undefined;
+  const out = outFlag === undefined ? name
+    : fs.existsSync(outFlag) && fs.statSync(outFlag).isDirectory() ? path.join(outFlag, name)
+    : outFlag;
+
+  const tmp = `${out}.tmp`;
+  try {
+    await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(tmp));
+    fs.renameSync(tmp, out);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    console.error(`Backup failed: the download broke off (${e.message ?? e}) — nothing was written`);
+    process.exit(1);
+  }
+  console.log(`Backed up '${db}' to ${out} (${fs.statSync(out).size} bytes)`);
+}
+
+// Restore: POST the file to /:db/$restore[?into=]. Replacing a database that exists needs --yes.
+async function cmdRestore(args) {
+  const { positional, flags } = parseArgs(args);
+  const [db, file] = positional;
+  if (!db || !file) { console.error("marcidb restore: usage: marcidb restore <db> <file.marcibin> [--into <name>] [--yes]"); process.exit(1); }
+  if (!fs.existsSync(file)) { console.error(`marcidb restore: "${file}" not found`); process.exit(1); }
+
+  const url = serverUrl(flags);
+  const into = typeof flags.into === "string" ? flags.into : undefined;
+  const target = into ?? db;
+  if (!flags.yes) {
+    // Without --into the live database is replaced; with it, only when that name already exists.
+    const exists = into === undefined || (await fetch(`${url}/${into}/$snapshot`, { headers: authHeaders(flags) })).status !== 404;
+    if (exists) {
+      console.error(
+        `This replaces the database '${target}' on ${url} with the contents of ${file}:\n` +
+        `everything written to '${target}' after that backup was taken is lost.\n` +
+        `Run again with --yes to proceed${into === undefined ? ", or restore under another name with --into <name>" : ""}.`,
+      );
+      process.exit(1);
+    }
+  }
+
+  const query = into === undefined ? "" : `?into=${encodeURIComponent(into)}`;
+  const body = typeof fs.openAsBlob === "function" ? await fs.openAsBlob(file) : fs.readFileSync(file);
+  const res = await fetch(`${url}/${db}/$restore${query}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-marcidb-backup", ...authHeaders(flags) },
+    body,
+  });
+  if (!res.ok) { console.error(`Restore failed [${res.status}]: ${await res.text()}`); process.exit(1); }
+  const info = await res.json();
+  console.log(`Restored ${file} into '${info.restored}' (${info.trees} trees, ${info.entries} entries, schema version ${info.schemaVersion}, taken ${info.createdAt})`);
+}
+
+// Inspect runs locally (no server): marci-migrate reads the file or the closed directory.
+function cmdInspect(args) {
+  const r = spawnSync(binPath("marci-migrate"), ["inspect", ...args], { stdio: "inherit" });
+  if (r.error) { console.error(`marcidb inspect: ${r.error.message}`); process.exit(1); }
+  process.exit(r.status ?? 1);
+}
+
 const COMMANDS = {
   generate: cmdGenerate,
   migrate: cmdMigrate,
+  backup: cmdBackup,
+  restore: cmdRestore,
+  inspect: cmdInspect,
 };
 
 // --- main ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "marcidb-client",
   "type": "module",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "license": "MIT",
   "author": {
     "name": "den59k"

package/runtime/index.d.ts

@@ -423,7 +423,13 @@ declare class MarciError extends Error {
 	readonly field?: string;
 	constructor(status: number, message: string, kind: MarciErrorKind, field?: string);
 }
-declare function request(method: string, url: string, body?: any): Promise<any>;
+/** Options of the HTTP transport — the second argument of `marcidb(url, options)`. */
+interface HttpOptions {
+	/** Sent as `Authorization: Bearer <token>` on every request: for a server started with `--token`, or an
+	*  embedded app's maintenance port opened with one (`db.listen({ token })`). */
+	token?: string;
+}
+declare function request(method: string, url: string, body?: any, options?: HttpOptions): Promise<any>;
 /**
 * A binary-eligible read over HTTP. Advertises `Accept: <binary>, json` plus the client's schema
 * fingerprint (`X-Marci-Schema`) and inspects the *response* content-type:
@@ -432,7 +438,7 @@ declare function request(method: string, url: string, body?: any): Promise<any>;
 *     schema/shape mismatch — so it sent the normal JSON body; no second round-trip needed).
 * A single request handles both outcomes; `run()` in the generated client branches on the return shape.
 */
-declare function requestBinary(url: string, body: any, schemaHash: string): Promise<Uint8Array | {
+declare function requestBinary(url: string, body: any, schemaHash: string, options?: HttpOptions): Promise<Uint8Array | {
 	json: any;
 }>;
 /**
@@ -445,4 +451,4 @@ declare function createDecoderRegistry(MODELS: Record<string, FieldDesc[]>): {
 	decodeBuffer(decoder: (reader: any) => any, bytes: Uint8Array, many: boolean): any;
 };
 declare function encodeId(id: any): string;
-export { AggregateKeys, AggregateResult, BareId, Collection, CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearch, CustomSearchValue, Effective, FieldDesc, FieldOps, FullTextSearch, GetResult, IdArg, Journal, JournalArgs, JournalEntry, JournalOp, JournalOptions, JsonCondition, JsonPathWhere, JsonType, JsonValue, MarciError, MarciErrorKind, MarciOp, MarciTransport, ModelTypes, ModelsMeta, Never, NumOps, Only, Op, PrimitiveListUpdate, Query, QueryLayerOptions, RefListUpdate, RefListUpdateOrdered, RefListUpdateStruct, RefUpdate, RefUpdateStruct, Resolve, Rows, ServiceKeys, StrOps, Sub, UpdateNumValue, ValueOps, VectorSearch, WhereValue, createDecoderRegistry, createQueryLayer, encodeId, request, requestBinary };
+export { AggregateKeys, AggregateResult, BareId, Collection, CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearch, CustomSearchValue, Effective, FieldDesc, FieldOps, FullTextSearch, GetResult, HttpOptions, IdArg, Journal, JournalArgs, JournalEntry, JournalOp, JournalOptions, JsonCondition, JsonPathWhere, JsonType, JsonValue, MarciError, MarciErrorKind, MarciOp, MarciTransport, ModelTypes, ModelsMeta, Never, NumOps, Only, Op, PrimitiveListUpdate, Query, QueryLayerOptions, RefListUpdate, RefListUpdateOrdered, RefListUpdateStruct, RefUpdate, RefUpdateStruct, Resolve, Rows, ServiceKeys, StrOps, Sub, UpdateNumValue, ValueOps, VectorSearch, WhereValue, createDecoderRegistry, createQueryLayer, encodeId, request, requestBinary };

package/runtime/index.js

@@ -189,10 +189,13 @@ async function failure(res) {
   } catch {}
   return new MarciError(res.status, text || `HTTP ${res.status}`, kindOfStatus(res.status));
 }
-async function request(method, url, body) {
+function optionHeaders(options) {
+  return options?.token ? { Authorization: `Bearer ${options.token}` } : {};
+}
+async function request(method, url, body, options) {
   const res = await fetch(url, {
     method,
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...optionHeaders(options) },
     body: body !== undefined ? JSON.stringify(body) : undefined
   });
   if (!res.ok)
@@ -200,13 +203,14 @@ async function request(method, url, body) {
   return res.json();
 }
 var BINARY_MEDIA_TYPE = "application/x-marcidb-rows";
-async function requestBinary(url, body, schemaHash) {
+async function requestBinary(url, body, schemaHash, options) {
   const res = await fetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Accept: `${BINARY_MEDIA_TYPE}, application/json`,
-      "X-Marci-Schema": schemaHash
+      "X-Marci-Schema": schemaHash,
+      ...optionHeaders(options)
     },
     body: JSON.stringify(body ?? {})
   });