diff --git a/package-lock.json b/package-lock.json index afe0d6a..579cf8b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -25,6 +25,9 @@ "react-redux": "^9.2.0" }, "bin": { + "abode-export": "dist/bin/abode-export.cjs", + "abode-import": "dist/bin/abode-import.cjs", + "abode-inspect": "dist/bin/abode-inspect.cjs", "abode-migrate": "dist/bin/abode-migrate.cjs", "abode-repl": "dist/bin/abode-repl.cjs", "abode-tui": "dist/bin/abode-tui.cjs", diff --git a/package.json b/package.json index 9c234a9..bc19a34 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,10 @@ "abode-migrate": "dist/bin/abode-migrate.cjs", "abode-repl": "dist/bin/abode-repl.cjs", "abode-web": "dist/bin/abode-web.cjs", - "abode-tui": "dist/bin/abode-tui.cjs" + "abode-tui": "dist/bin/abode-tui.cjs", + "abode-export": "dist/bin/abode-export.cjs", + "abode-import": "dist/bin/abode-import.cjs", + "abode-inspect": "dist/bin/abode-inspect.cjs" }, "scripts": { "repl": "tsx --import ./src/meta/dev/register.ts", @@ -18,6 +21,9 @@ "abode-web": "tsx --import ./src/meta/dev/register.ts --import ./src/meta/dev/webhot.ts src/bin/abode-web.ts", "abode-tui": "tsx --import ./src/meta/dev/register.ts --import ./src/meta/dev/silenthot.ts src/bin/abode-tui.ts", "abode-sources": "tsx --import ./src/meta/dev/register.ts src/bin/abode-sources.ts", + "abode-export": "tsx --import ./src/meta/dev/register.ts src/bin/abode-export.ts", + "abode-import": "tsx --import ./src/meta/dev/register.ts src/bin/abode-import.ts", + "abode-inspect": "tsx --import ./src/meta/dev/register.ts src/bin/abode-inspect.ts", "build": "NODE_ENV=production npm run build:impl", "build:impl": "rm -rf dist && tsx node_modules/.bin/webpack && chmod +x dist/bin/* && chmod -x dist/bin/*.*", "test": "node --import tsx/esm --import ./src/meta/dev/register.ts --test $(find test -name '*.test.ts' | sort)", diff --git a/src/bin/abode-export.ts b/src/bin/abode-export.ts new file mode 100644 index 0000000..ba38e4d --- /dev/null +++ b/src/bin/abode-export.ts @@ -0,0 +1,97 @@ +import { createWriteStream } from "node:fs"; +import { pipeline } from "node:stream/promises"; +import { getDbInterface } from "../db/index.js"; +import { isExportable, type ExportFilter } from "../db/types/ExportImport.js"; +import { isExportKind } from "../db/export/filter.js"; + +const args = process.argv.slice(2); + +function printUsage(err: boolean | string = false): never { + const log = (err ? console.error : console.log).bind(console); + if (typeof err === "string") { + log(`Error: ${err}`); + log(""); + } + log("Usage:"); + log("\tabode-export --help"); + log( + "\tabode-export [--kinds=user,abode,...] [--exclude-kinds=...] \\", + ); + log("\t [--abodes=aid,...] [--users=uid,...] [--out=file|-]"); + process.exit(err ? 1 : 0); +} + +if (["-h", "--help", "help"].some((x) => args.includes(x))) printUsage(); + +let url: string | undefined; +const flags = new Map(); +for (const arg of args) { + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + if (eq === -1) printUsage(`invalid flag: ${arg}`); + flags.set(arg.slice(2, eq), arg.slice(eq + 1)); + } else if (url === undefined) { + url = arg; + } else { + printUsage("too many arguments"); + } +} +if (!url) printUsage("missing "); + +const knownFlags = ["kinds", "exclude-kinds", "abodes", "users", "out"]; +for (const key of flags.keys()) { + if (!knownFlags.includes(key)) printUsage(`unknown flag: --${key}`); +} + +function parseList(value: string | undefined): string[] | undefined { + if (value === undefined) return undefined; + return value.split(",").filter(Boolean); +} +function parseKinds(value: string | undefined) { + const list = parseList(value); + if (!list) return undefined; + const bad = list.filter((k) => !isExportKind(k)); + if (bad.length) printUsage(`invalid kind(s): ${bad.join(", ")}`); + return list.filter(isExportKind); +} + +const filter: ExportFilter = {}; +const kinds = parseKinds(flags.get("kinds")); +if (kinds) filter.kinds = kinds; +const excludeKinds = parseKinds(flags.get("exclude-kinds")); +if (excludeKinds) filter.excludeKinds = excludeKinds; +const abodes = parseList(flags.get("abodes")); +if (abodes) filter.abodes = abodes; +const users = parseList(flags.get("users")); +if (users) filter.users = users; + +const db = await getDbInterface(url); +if (!isExportable(db)) { + console.error(`Error: backend '${db.name}' does not support export`); + process.exit(1); +} + +const out = flags.get("out") ?? "-"; +const dest = + out === "-" ? process.stdout : createWriteStream(out, { encoding: "utf8" }); + +const ac = new AbortController(); +const onSignal = () => ac.abort(); +process.on("SIGINT", onSignal); +process.on("SIGTERM", onSignal); + +try { + await pipeline(db.export({ filter, signal: ac.signal }), dest); +} catch (e) { + if (ac.signal.aborted) { + console.error("Export aborted"); + process.exit(130); + } + throw e; +} finally { + process.off("SIGINT", onSignal); + process.off("SIGTERM", onSignal); + await db.close().catch(() => {}); +} + +process.exit(0); diff --git a/src/bin/abode-import.ts b/src/bin/abode-import.ts new file mode 100644 index 0000000..d8e0c2e --- /dev/null +++ b/src/bin/abode-import.ts @@ -0,0 +1,106 @@ +import { createReadStream } from "node:fs"; +import { getWrappedDb } from "../db/sqlite/impl/index.js"; +import { SqliteInterface } from "../db/sqlite/SqliteInterface.js"; +import { parseSqliteUrl } from "../db/sqlite/url.js"; +import { isExportKind } from "../db/export/filter.js"; +import type { ExportFilter } from "../db/types/ExportImport.js"; + +const args = process.argv.slice(2); + +function printUsage(err: boolean | string = false): never { + const log = (err ? console.error : console.log).bind(console); + if (typeof err === "string") { + log(`Error: ${err}`); + log(""); + } + log("Usage:"); + log("\tabode-import --help"); + log("\tabode-import [--kinds=...] \\"); + log( + "\t [--exclude-kinds=...] [--abodes=aid,...] [--users=uid,...]", + ); + log(""); + log( + "The target database must already be migrated (run abode-migrate first).", + ); + process.exit(err ? 1 : 0); +} + +if (["-h", "--help", "help"].some((x) => args.includes(x))) printUsage(); + +const positional: string[] = []; +const flags = new Map(); +for (const arg of args) { + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + if (eq === -1) printUsage(`invalid flag: ${arg}`); + flags.set(arg.slice(2, eq), arg.slice(eq + 1)); + } else { + positional.push(arg); + } +} + +const url = positional[0]; +const input = positional[1]; +if (!url) printUsage("missing "); +if (!input) printUsage("missing "); +if (positional.length > 2) printUsage("too many arguments"); + +const knownFlags = ["kinds", "exclude-kinds", "abodes", "users"]; +for (const key of flags.keys()) { + if (!knownFlags.includes(key)) printUsage(`unknown flag: --${key}`); +} + +function parseList(value: string | undefined): string[] | undefined { + if (value === undefined) return undefined; + return value.split(",").filter(Boolean); +} +function parseKinds(value: string | undefined) { + const list = parseList(value); + if (!list) return undefined; + const bad = list.filter((k) => !isExportKind(k)); + if (bad.length) printUsage(`invalid kind(s): ${bad.join(", ")}`); + return list.filter(isExportKind); +} + +const filter: ExportFilter = {}; +const kinds = parseKinds(flags.get("kinds")); +if (kinds) filter.kinds = kinds; +const excludeKinds = parseKinds(flags.get("exclude-kinds")); +if (excludeKinds) filter.excludeKinds = excludeKinds; +const abodes = parseList(flags.get("abodes")); +if (abodes) filter.abodes = abodes; +const users = parseList(flags.get("users")); +if (users) filter.users = users; + +// Import is sqlite-only: construct the backend directly rather than resolving +// generically, so it can never be pointed at a remote (api) target. +const db = new SqliteInterface(getWrappedDb(...parseSqliteUrl(url))); + +const source = input === "-" ? process.stdin : createReadStream(input); + +const ac = new AbortController(); +const onSignal = () => ac.abort(); +process.on("SIGINT", onSignal); +process.on("SIGTERM", onSignal); + +try { + const result = await db.import(source, { filter, signal: ac.signal }); + const total = Object.values(result.counts).reduce((a, b) => a + b, 0); + console.log(`Imported ${total} record(s):`); + for (const [kind, count] of Object.entries(result.counts)) { + console.log(`- ${kind}: ${count}`); + } +} catch (e) { + if (ac.signal.aborted) { + console.error("Import aborted; no changes committed"); + process.exit(130); + } + throw e; +} finally { + process.off("SIGINT", onSignal); + process.off("SIGTERM", onSignal); + await db.close().catch(() => {}); +} + +process.exit(0); diff --git a/src/bin/abode-inspect.ts b/src/bin/abode-inspect.ts new file mode 100644 index 0000000..cdd5536 --- /dev/null +++ b/src/bin/abode-inspect.ts @@ -0,0 +1,68 @@ +import { createReadStream } from "node:fs"; +import { inspectExportStream } from "../db/export/inspect.js"; +import { isExportKind } from "../db/export/filter.js"; +import type { ExportKind } from "../db/types/ExportImport.js"; + +const args = process.argv.slice(2); + +function printUsage(err: boolean | string = false): never { + const log = (err ? console.error : console.log).bind(console); + if (typeof err === "string") { + log(`Error: ${err}`); + log(""); + } + log("Usage:"); + log("\tabode-inspect --help"); + log("\tabode-inspect [--stop-after=note,...]"); + process.exit(err ? 1 : 0); +} + +if (["-h", "--help", "help"].some((x) => args.includes(x))) printUsage(); + +let input: string | undefined; +const flags = new Map(); +for (const arg of args) { + if (arg.startsWith("--")) { + const eq = arg.indexOf("="); + if (eq === -1) printUsage(`invalid flag: ${arg}`); + flags.set(arg.slice(2, eq), arg.slice(eq + 1)); + } else if (input === undefined) { + input = arg; + } else { + printUsage("too many arguments"); + } +} +if (!input) printUsage("missing "); + +for (const key of flags.keys()) { + if (key !== "stop-after") printUsage(`unknown flag: --${key}`); +} + +let stopAfterKinds: ExportKind[] | undefined; +const rawStop = flags.get("stop-after"); +if (rawStop !== undefined) { + const list = rawStop.split(",").filter(Boolean); + const bad = list.filter((k) => !isExportKind(k)); + if (bad.length) printUsage(`invalid kind(s): ${bad.join(", ")}`); + stopAfterKinds = list.filter(isExportKind); +} + +const source = input === "-" ? process.stdin : createReadStream(input); + +const { counts, meta } = await inspectExportStream(source, { stopAfterKinds }); + +if (meta) { + console.log("Meta:"); + console.log(`- format version: ${meta.v ?? "?"}`); + console.log(`- exported at: ${meta.exportedAt ?? "?"}`); + console.log(`- source backend: ${meta.source ?? "?"}`); + if (meta.filter && Object.keys(meta.filter).length) { + console.log(`- effective filter: ${JSON.stringify(meta.filter)}`); + } +} +console.log("Counts:"); +const entries = Object.entries(counts); +if (!entries.length) console.log("(none)"); +for (const [kind, count] of entries) console.log(`- ${kind}: ${count}`); + +process.exit(0); diff --git a/src/db/api/ApiInterface.ts b/src/db/api/ApiInterface.ts index f376280..3886ddc 100644 --- a/src/db/api/ApiInterface.ts +++ b/src/db/api/ApiInterface.ts @@ -25,8 +25,11 @@ import type { CreateUser, UpdateUser, } from "../types/User.js"; +import { Readable } from "node:stream"; +import type { ReadableStream as WebReadableStream } from "node:stream/web"; +import type { Exportable, ExportOptions } from "../types/ExportImport.js"; -export class ApiInterface implements DbInterface { +export class ApiInterface implements DbInterface, Exportable { #root: string; #headers: Record; #readonly: boolean; @@ -296,4 +299,45 @@ export class ApiInterface implements DbInterface { async listNotesByUserId(uid: string): Promise { return this.#call("GET", "/users/:uid/notes", { params: { uid } }); } + + export(options: ExportOptions = {}): NodeJS.ReadableStream { + // Streaming NDJSON bypasses the JSON-only `#call` helper: the raw + // `fetch` gets the caller's `signal` directly, so aborting cancels the + // underlying HTTP request itself. + const { filter, signal } = options; + const sp = new URLSearchParams(); + if (filter?.kinds) sp.set("kinds", filter.kinds.join(",")); + if (filter?.excludeKinds) + sp.set("excludeKinds", filter.excludeKinds.join(",")); + if (filter?.abodes) sp.set("abodes", filter.abodes.join(",")); + if (filter?.users) sp.set("users", filter.users.join(",")); + const query = sp.toString(); + const url = this.#root + "/export" + (query ? `?${query}` : ""); + const headers = { ...this.#headers }; + + async function* generate(): AsyncGenerator { + const res = await fetch(url, { method: "GET", headers, signal }); + if (!res.ok) { + const text = await res.text(); + switch (res.status) { + case 400: + throw new InvalidAbodeError(); + case 401: + throw new NotAuthorizedAbodeError(); + case 403: + throw new ReadonlyAbodeError(); + case 404: + throw new NotFoundAbodeError(); + case 409: + throw new ConflictAbodeError(); + default: + throw new Error(`${res.status} ${res.statusText} ${text}`); + } + } + if (!res.body) return; + yield* Readable.fromWeb(res.body as WebReadableStream); + } + + return Readable.from(generate()); + } } diff --git a/src/db/export/filter.ts b/src/db/export/filter.ts new file mode 100644 index 0000000..9f78890 --- /dev/null +++ b/src/db/export/filter.ts @@ -0,0 +1,79 @@ +import type { ExportFilter, ExportKind } from "../types/ExportImport.js"; + +const EXPORT_KINDS = new Set([ + "user", + "abode", + "resident", + "apikey", + "note", +]); + +export function isExportKind(x: unknown): x is ExportKind { + return typeof x === "string" && EXPORT_KINDS.has(x as ExportKind); +} + +/** Whether a `kind` survives a filter's `kinds`/`excludeKinds` rules. */ +export function kindAllowed( + filter: ExportFilter | undefined, + kind: ExportKind, +): boolean { + if (!filter) return true; + if (filter.kinds && !filter.kinds.includes(kind)) return false; + if (filter.excludeKinds && filter.excludeKinds.includes(kind)) return false; + return true; +} + +/** + * Whether an individual record passes a filter's `abodes`/`users` allowlists. + * `abodes` scopes abode/resident/note (by aid); `users` scopes user/apikey + * (by uid). An absent allowlist means "unrestricted". + */ +export function recordAllowed( + filter: ExportFilter | undefined, + kind: ExportKind, + record: { uid?: string; aid?: string }, +): boolean { + if (!filter) return true; + switch (kind) { + case "user": + case "apikey": + return !filter.users || filter.users.includes(record.uid as string); + case "abode": + case "resident": + case "note": + return !filter.abodes || filter.abodes.includes(record.aid as string); + } +} + +function intersectList(a?: T[], b?: T[]): T[] | undefined { + if (!a) return b; + if (!b) return a; + const bs = new Set(b); + return a.filter((x) => bs.has(x)); +} + +function unionList(a?: T[], b?: T[]): T[] | undefined { + if (!a) return b; + if (!b) return a; + return [...new Set([...a, ...b])]; +} + +/** + * Combine two filters as a hard intersection: the result can never permit more + * than either input. An absent allowlist is treated as "unrestricted", so + * intersecting it with a present one yields the present one. `excludeKinds` + * are unioned (either exclusion still excludes). + */ +export function intersectExportFilters( + a: ExportFilter | null | undefined, + b: ExportFilter | null | undefined, +): ExportFilter { + if (!a) return b ?? {}; + if (!b) return a; + return { + kinds: intersectList(a.kinds, b.kinds), + excludeKinds: unionList(a.excludeKinds, b.excludeKinds), + abodes: intersectList(a.abodes, b.abodes), + users: intersectList(a.users, b.users), + }; +} diff --git a/src/db/export/inspect.ts b/src/db/export/inspect.ts new file mode 100644 index 0000000..becab57 --- /dev/null +++ b/src/db/export/inspect.ts @@ -0,0 +1,60 @@ +import readline from "node:readline"; +import type { + ExportFilter, + ExportKind, + ExportMeta, +} from "../types/ExportImport.js"; +import { isExportKind } from "./filter.js"; + +export type InspectResult = { + counts: Partial>; + meta?: Partial & { filter?: ExportFilter }; +}; + +/** + * Tally the kinds/counts contained in an NDJSON export stream without ever + * touching a database. Works on any stream — a file, {@link ApiInterface}'s + * export, or a pipe straight from {@link SqliteInterface}'s export. + * + * If `stopAfterKinds` is given, reading stops as soon as at least one record of + * every requested kind has been seen, rather than draining to EOF — useful for + * probing large dumps ("does this contain notes at all?"). + */ +export async function inspectExportStream( + source: NodeJS.ReadableStream, + options: { signal?: AbortSignal; stopAfterKinds?: ExportKind[] } = {}, +): Promise { + const { signal, stopAfterKinds } = options; + const counts: Partial> = {}; + let meta: InspectResult["meta"]; + + const rl = readline.createInterface({ + input: source, + crlfDelay: Infinity, + signal, + }); + try { + for await (const raw of rl) { + signal?.throwIfAborted(); + const line = raw.trim(); + if (!line) continue; + let parsed: { kind?: unknown; data?: unknown }; + try { + parsed = JSON.parse(line); + } catch { + continue; + } + if (parsed.kind === "meta") { + meta = parsed.data as InspectResult["meta"]; + continue; + } + if (!isExportKind(parsed.kind)) continue; + counts[parsed.kind] = (counts[parsed.kind] ?? 0) + 1; + if (stopAfterKinds && stopAfterKinds.every((k) => counts[k])) break; + } + } finally { + rl.close(); + } + + return { counts, meta }; +} diff --git a/src/db/sqlite/SqliteInterface.ts b/src/db/sqlite/SqliteInterface.ts index e5a0102..03c96fa 100644 --- a/src/db/sqlite/SqliteInterface.ts +++ b/src/db/sqlite/SqliteInterface.ts @@ -34,6 +34,7 @@ import { selectClientUser, selectClientUsers, selectNote, + selectNotes, selectPartialNotes, selectResident, selectResidents, @@ -45,8 +46,21 @@ import type { UpdateNote, } from "../types/Note.js"; import type { WrappedDb } from "./impl/types.js"; +import { Readable } from "node:stream"; +import readline from "node:readline"; +import type { + Exportable, + ExportKind, + ExportOptions, + Importable, + ImportOptions, + ImportResult, +} from "../types/ExportImport.js"; +import { isExportKind, kindAllowed, recordAllowed } from "../export/filter.js"; -export class SqliteInterface implements BackendDbInterface { +export class SqliteInterface + implements BackendDbInterface, Exportable, Importable +{ #db: WrappedDb; constructor(db: WrappedDb) { @@ -534,4 +548,219 @@ export class SqliteInterface implements BackendDbInterface { async listNotesByUserId(uid: string): Promise { return selectPartialNotes(this.#db, sql`n."created_by" = ${{ uuid: uid }}`); } + + export(options: ExportOptions = {}): NodeJS.ReadableStream { + const { filter, signal } = options; + const db = this.#db; + const source = this.name; + + // Per-table full materialization + JS-side per-record yielding (each + // `load()` is exactly one `WrappedDb.all()`). Kept lazy so the first query + // only fires once the destination starts pulling, and skipped entirely + // once the signal is aborted — no further reads after the destination + // goes away. + const tables: [ExportKind, () => { uid?: string; aid?: string }[]][] = [ + ["user", () => selectClientUsers(db)], + ["abode", () => selectAbodes(db)], + ["resident", () => selectResidents(db)], + ["apikey", () => selectClientApikeys(db)], + ["note", () => selectNotes(db)], + ]; + + async function* generate(): AsyncGenerator { + if (signal?.aborted) return; + yield JSON.stringify({ + kind: "meta", + data: { + v: 1, + exportedAt: new Date().toISOString(), + source, + filter: filter ?? {}, + }, + }) + "\n"; + try { + for (const [kind, load] of tables) { + if (signal?.aborted) return; + if (!kindAllowed(filter, kind)) continue; + for (const row of load()) { + if (signal?.aborted) return; + if (recordAllowed(filter, kind, row)) { + yield JSON.stringify({ kind, data: row }) + "\n"; + } + } + } + } catch (e) { + // Aborts unwind via early `return`, never here; a genuine mid-stream + // failure is surfaced as a trailing sentinel line (HTTP 200 headers + // are already flushed, so `convertError` can no longer apply). + if (signal?.aborted) return; + yield JSON.stringify({ + kind: "error", + data: { + message: e instanceof Error ? e.message : String(e), + code: e instanceof Error ? e.name : undefined, + }, + }) + "\n"; + } + } + + return Readable.from(generate()); + } + + async import( + source: NodeJS.ReadableStream, + options: ImportOptions = {}, + ): Promise { + this.#checkReadonly(); + const { filter, signal } = options; + const db = this.#db; + const counts: Partial> = {}; + + const rl = readline.createInterface({ + input: source, + crlfDelay: Infinity, + signal, + }); + + // Bulk restore trusts the export's referential integrity, and a filtered + // dump may legitimately reference `created_by`/`updated_by` users outside + // its scope. Suppress FK enforcement for the duration (can only be toggled + // outside a transaction) and restore it in `finally`. + db.run(sql`PRAGMA foreign_keys = OFF`); + db.run(sql`BEGIN`); + try { + for await (const raw of rl) { + signal?.throwIfAborted(); + const line = raw.trim(); + if (!line) continue; + let parsed: { kind?: unknown; data?: unknown }; + try { + parsed = JSON.parse(line); + } catch { + throw new InvalidAbodeError(); + } + if (parsed.kind === "meta") continue; + if (parsed.kind === "error") { + throw new Error( + `export stream reported an error: ${ + (parsed.data as { message?: string })?.message ?? "unknown" + }`, + ); + } + if (!isExportKind(parsed.kind)) continue; + if (!kindAllowed(filter, parsed.kind)) continue; + const data = parsed.data as { uid?: string; aid?: string }; + if (!recordAllowed(filter, parsed.kind, data)) continue; + this.#importRecord(parsed.kind, parsed.data); + counts[parsed.kind] = (counts[parsed.kind] ?? 0) + 1; + } + // An abort while blocked on the source closes readline without throwing, + // so re-check before committing to guarantee no partial commit. + signal?.throwIfAborted(); + db.run(sql`COMMIT`); + } catch (e) { + try { + db.run(sql`ROLLBACK`); + } catch { + /* already rolled back */ + } + throw e; + } finally { + rl.close(); + db.run(sql`PRAGMA foreign_keys = ON`); + } + + return { counts }; + } + + #importRecord(kind: ExportKind, data: unknown): void { + const db = this.#db; + switch (kind) { + case "user": { + const u = data as ClientUser; + // `password` is never exported; imported users land on the schema + // default ('#unset') and must reset before they can log in. + db.run(sql` + INSERT INTO "users"("uid", "email", "name", "flags", "created_at", "updated_at") + VALUES( + ${{ uuid: u.uid }}, + ${{ text: u.email }}, + ${{ text: u.name }}, + ${{ jsonb: u.flags }}, + ${{ date: u.created_at }}, + ${{ date: u.updated_at }} + ) + `); + break; + } + case "abode": { + const a = data as Abode; + db.run(sql` + INSERT INTO "abodes"("aid", "name", "created_at", "created_by", "updated_at", "updated_by") + VALUES( + ${{ uuid: a.aid }}, + ${{ text: a.name }}, + ${{ date: a.created_at }}, + ${a.created_by ? { uuid: a.created_by } : { null: true }}, + ${{ date: a.updated_at }}, + ${a.updated_by ? { uuid: a.updated_by } : { null: true }} + ) + `); + break; + } + case "resident": { + const r = data as Resident; + db.run(sql` + INSERT INTO "residents"("uid", "aid", "flags", "created_at", "created_by", "updated_at", "updated_by") + VALUES( + ${{ uuid: r.uid }}, + ${{ uuid: r.aid }}, + ${{ jsonb: r.flags }}, + ${{ date: r.created_at }}, + ${r.created_by ? { uuid: r.created_by } : { null: true }}, + ${{ date: r.updated_at }}, + ${r.updated_by ? { uuid: r.updated_by } : { null: true }} + ) + `); + break; + } + case "apikey": { + const k = data as ClientApikey; + // `token` is never exported; mint a fresh unique one so the record's + // metadata (kid/permissions/expiry) survives even though the original + // secret cannot. + db.run(sql` + INSERT INTO "apikeys"("uid", "kid", "token", "name", "permissions", "created_at", "expires_at") + VALUES( + ${{ uuid: k.uid }}, + ${{ uuid: k.kid }}, + ${{ text: createApikeyToken() }}, + ${{ text: k.name }}, + ${{ jsonb: k.permissions }}, + ${{ date: k.created_at }}, + ${k.expires_at ? { date: k.expires_at } : { null: true }} + ) + `); + break; + } + case "note": { + const n = data as Note; + db.run(sql` + INSERT INTO "notes"("nid", "aid", "name", "content", "properties", "created_at", "created_by", "updated_at", "updated_by") + VALUES( + ${{ uuid: n.nid }}, + ${{ uuid: n.aid }}, + ${{ text: n.name }}, + ${{ text: n.content ?? "" }}, + ${{ jsonb: n.properties }}, + ${{ date: n.created_at }}, + ${n.created_by ? { uuid: n.created_by } : { null: true }}, + ${{ date: n.updated_at }}, + ${n.updated_by ? { uuid: n.updated_by } : { null: true }} + ) + `); + break; + } + } + } } diff --git a/src/db/sqlite/query.ts b/src/db/sqlite/query.ts index 81b31e9..0c8898f 100644 --- a/src/db/sqlite/query.ts +++ b/src/db/sqlite/query.ts @@ -118,10 +118,10 @@ export function selectClientApikey( } export function selectClientApikeys( db: WrappedDb, - where: SqlCode, + where?: SqlCode, ): ClientApikey[] { const rawApikeys = db.all( - sql`${sqlClientApikey} WHERE ${where}`, + where ? sql`${sqlClientApikey} WHERE ${where}` : sqlClientApikey, ); return rawApikeys.map(sqliteToClientApikey); } diff --git a/src/db/types/ExportImport.ts b/src/db/types/ExportImport.ts new file mode 100644 index 0000000..9c600b2 --- /dev/null +++ b/src/db/types/ExportImport.ts @@ -0,0 +1,68 @@ +import type { DbInterface } from "./DbInterface.js"; + +/** + * The kinds of records that can travel through an export/import stream. + * + * `Session` is intentionally excluded: it has no CRUD/list surface in + * {@link DbInterface} and is ephemeral/non-portable between instances. + */ +export type ExportKind = "user" | "abode" | "resident" | "apikey" | "note"; + +export type ExportFilter = { + /** Include only these kinds; omit = all kinds. */ + kinds?: ExportKind[]; + /** Excluded after `kinds` is applied. */ + excludeKinds?: ExportKind[]; + /** aid allowlist — scopes abode/resident/note. */ + abodes?: string[]; + /** uid allowlist — scopes user/apikey. */ + users?: string[]; +}; + +export interface ExportOptions { + filter?: ExportFilter; + signal?: AbortSignal; +} + +export interface Exportable { + /** Produce a stream of NDJSON lines (one JSON envelope per line). */ + export(options?: ExportOptions): NodeJS.ReadableStream; +} + +export interface ImportOptions { + filter?: ExportFilter; + signal?: AbortSignal; +} + +export interface ImportResult { + counts: Partial>; +} + +export interface Importable { + import( + source: NodeJS.ReadableStream, + options?: ImportOptions, + ): Promise; +} + +/** + * The NDJSON envelope written/read for every line. The leading line is a + * `meta` record; a trailing `error` record may appear if the source failed + * after streaming had already begun. + */ +export type ExportEnvelope = + | { kind: "meta"; data: ExportMeta } + | { kind: ExportKind; data: unknown } + | { kind: "error"; data: { message: string; code?: string } }; + +export type ExportMeta = { + v: number; + exportedAt: string; + source: string; + /** The *effective* filter actually applied (may be narrower than requested). */ + filter: ExportFilter; +}; + +export function isExportable(db: DbInterface): db is DbInterface & Exportable { + return typeof (db as Partial).export === "function"; +} diff --git a/src/webapi/apirouter.ts b/src/webapi/apirouter.ts index 8ff5f0d..ccf55ac 100644 --- a/src/webapi/apirouter.ts +++ b/src/webapi/apirouter.ts @@ -16,6 +16,29 @@ import { } from "../schema/validators.js"; import { authenticate } from "./middleware/authenticate.js"; import { InvalidAbodeError, NotFoundAbodeError } from "../db/types/errors.js"; +import { isExportable } from "../db/types/ExportImport.js"; +import type { ExportFilter, ExportKind } from "../db/types/ExportImport.js"; +import { intersectExportFilters, isExportKind } from "../db/export/filter.js"; +import { computeForcedExportFilter } from "./exportScope.js"; + +function parseExportFilter(query: Record): ExportFilter { + const list = (v: unknown): string[] | undefined => { + if (typeof v !== "string" || !v) return undefined; + return v.split(",").filter(Boolean); + }; + const kinds = (v: unknown): ExportKind[] | undefined => + list(v)?.filter(isExportKind); + const filter: ExportFilter = {}; + const k = kinds(query.kinds); + if (k) filter.kinds = k; + const ek = kinds(query.excludeKinds); + if (ek) filter.excludeKinds = ek; + const abodes = list(query.abodes); + if (abodes) filter.abodes = abodes; + const users = list(query.users); + if (users) filter.users = users; + return filter; +} export function apirouter(db: BackendDbInterface): KoaRouter { const router = new KoaRouter(); @@ -42,6 +65,31 @@ export function apirouter(db: BackendDbInterface): KoaRouter { ctx.status = 204; }); + router.get("/export", authenticate(db), async (ctx) => { + // Everything that can throw a domain error runs *before* any byte is + // written, so `convertError` still applies. Once `ctx.body` is a stream, + // a mid-stream failure surfaces as a trailing `error` NDJSON line instead. + const forced = await computeForcedExportFilter(db, { + user: ctx.user!, + session: ctx.session!, + }); + const effective = intersectExportFilters( + parseExportFilter(ctx.query), + forced, + ); + if (!isExportable(db)) { + ctx.status = 501; + ctx.body = { ok: false, error: "export_unsupported" }; + return; + } + const ac = new AbortController(); + ctx.res.on("close", () => { + if (!ctx.res.writableEnded) ac.abort(); + }); + ctx.type = "application/x-ndjson"; + ctx.body = db.export({ filter: effective, signal: ac.signal }); + }); + router.use("/users", authenticate(db)); router.get("/users", async (ctx) => { ctx.body = await db.listUsers(); diff --git a/src/webapi/exportScope.ts b/src/webapi/exportScope.ts new file mode 100644 index 0000000..aa79bc8 --- /dev/null +++ b/src/webapi/exportScope.ts @@ -0,0 +1,58 @@ +import type { Context } from "koa"; +import type { BackendDbInterface } from "../db/types/DbInterface.js"; +import type { ClientUser } from "../db/types/User.js"; +import type { ExportFilter } from "../db/types/ExportImport.js"; + +/** + * Compute the export scope that must be *forced* on a caller, independent of + * anything they requested. Returns `null` when the caller is unrestricted (a + * global admin whose credential imposes no narrowing) — their own filter, if + * any, is then honored verbatim as a voluntary narrowing. + * + * Otherwise returns `{ abodes, users }`: the abodes the caller resides in, and + * the users needed to keep that data referentially whole (the caller plus every + * co-resident of those abodes). This is the maximum a non-admin may export; the + * route intersects it with any caller-supplied filter (never a union). + */ +export async function computeForcedExportFilter( + db: BackendDbInterface, + ctx: { user: ClientUser; session: NonNullable }, +): Promise { + const { user, session } = ctx; + + if (user.flags.admin) { + if (session.source !== "apikey") return null; + const p = session.key.permissions; + const unrestricted = + !!p.admin && + !!p.all && + !p.restrict_users?.length && + !p.restrict_abodes?.length; + if (unrestricted) return null; + } + + const residencies = await db.listResidentsByUserId(user.uid); + const abodeSet = new Set(residencies.map((r) => r.aid)); + const userSet = new Set([user.uid]); + for (const aid of abodeSet) { + for (const u of await db.listUsersByAbodeId(aid)) userSet.add(u.uid); + } + + let abodes = [...abodeSet]; + let users = [...userSet]; + + // An apikey can only narrow what its owning user could otherwise export. + if (session.source === "apikey") { + const p = session.key.permissions; + if (p.restrict_abodes?.length) { + const allow = new Set(p.restrict_abodes); + abodes = abodes.filter((a) => allow.has(a)); + } + if (p.restrict_users?.length) { + const allow = new Set(p.restrict_users); + users = users.filter((u) => allow.has(u)); + } + } + + return { abodes, users }; +} diff --git a/test/tools/export-import.test.ts b/test/tools/export-import.test.ts new file mode 100644 index 0000000..359c529 --- /dev/null +++ b/test/tools/export-import.test.ts @@ -0,0 +1,715 @@ +import { describe, it, before, after } from "node:test"; +import assert from "node:assert/strict"; +import readline from "node:readline"; +import { Readable } from "node:stream"; +import { createServer } from "node:http"; +import type { AddressInfo } from "node:net"; +import Koa from "koa"; +import { createTestDb, type TestDb } from "../helpers/sqlite.js"; +import { apirouter } from "../../src/webapi/apirouter.js"; +import { computeForcedExportFilter } from "../../src/webapi/exportScope.js"; +import { + intersectExportFilters, + recordAllowed, + kindAllowed, +} from "../../src/db/export/filter.js"; +import { inspectExportStream } from "../../src/db/export/inspect.js"; +import { hashPassword } from "../../src/util/hash.js"; +import type { ClientUser } from "../../src/db/types/User.js"; + +// --------------------------------------------------------------------------- +// helpers +// --------------------------------------------------------------------------- + +async function streamToString(s: NodeJS.ReadableStream): Promise { + let out = ""; + for await (const chunk of s) out += chunk; + return out; +} + +function parseLines(ndjson: string): { kind: string; data: any }[] { + return ndjson + .split("\n") + .filter(Boolean) + .map((l) => JSON.parse(l)); +} + +/** Normalise `*_at` fields to epoch ms so formatting never breaks equality. */ +function norm(obj: Record): Record { + const out: Record = {}; + for (const [k, v] of Object.entries(obj)) { + out[k] = k.endsWith("_at") + ? v == null + ? null + : new Date(v as string).getTime() + : v; + } + return out; +} +function normSorted( + arr: Record[], + key: (x: any) => string, +): Record[] { + return arr.map(norm).sort((a, b) => key(a).localeCompare(key(b))); +} + +interface Seed { + admin: ClientUser; + normal: ClientUser; + co: ClientUser; + aid1: string; + aid2: string; + nid1: string; + nid2: string; +} + +async function seed(db: TestDb["db"]): Promise { + const pw = await hashPassword("password"); + const admin = await db.createUser({ + email: "admin@test.example", + name: "Admin", + password: pw, + flags: { admin: true }, + }); + const normal = await db.createUser({ + email: "normal@test.example", + name: "Normal", + password: pw, + flags: {}, + }); + const co = await db.createUser({ + email: "co@test.example", + name: "Co Resident", + password: pw, + flags: {}, + }); + const abode1 = await db.createAbode( + { name: "Abode One" }, + { uid: admin.uid }, + ); + const abode2 = await db.createAbode( + { name: "Abode Two" }, + { uid: admin.uid }, + ); + await db.createResident( + { uid: normal.uid, aid: abode1.aid, flags: {} }, + { uid: admin.uid }, + ); + await db.createResident( + { uid: co.uid, aid: abode1.aid, flags: {} }, + { uid: admin.uid }, + ); + await db.createResident( + { uid: admin.uid, aid: abode2.aid, flags: { admin: true } }, + { uid: admin.uid }, + ); + await db.createApikey({ + uid: normal.uid, + name: "normal key", + permissions: {}, + expires_at: null, + }); + const note1 = await db.createNote( + { + aid: abode1.aid, + name: "Note One", + content: "hello", + properties: { type: "note" }, + }, + { uid: normal.uid }, + ); + const note2 = await db.createNote( + { + aid: abode2.aid, + name: "Note Two", + content: "world", + properties: { type: "note" }, + }, + { uid: admin.uid }, + ); + return { + admin, + normal, + co, + aid1: abode1.aid, + aid2: abode2.aid, + nid1: note1.nid, + nid2: note2.nid, + }; +} + +// --------------------------------------------------------------------------- +// 1. round-trip +// --------------------------------------------------------------------------- + +describe("export/import: sqlite -> sqlite round-trip", () => { + it("reproduces users, abodes, residents, apikeys, notes", async () => { + const src = await createTestDb(); + const dst = await createTestDb(); + try { + const s = await seed(src.db); + + const result = await dst.db.import(src.db.export()); + assert.ok(result.counts.user && result.counts.user >= 3); + assert.ok(result.counts.note && result.counts.note >= 2); + + assert.deepEqual( + normSorted(await dst.db.listUsers(), (u) => u.uid), + normSorted(await src.db.listUsers(), (u) => u.uid), + ); + assert.deepEqual( + normSorted(await dst.db.listAbodes(), (a) => a.aid), + normSorted(await src.db.listAbodes(), (a) => a.aid), + ); + assert.deepEqual( + normSorted(await dst.db.listResidents(), (r) => r.uid + r.aid), + normSorted(await src.db.listResidents(), (r) => r.uid + r.aid), + ); + // apikeys: token is regenerated on import, so the ClientApikey view + // (which omits token) must still match exactly. + assert.deepEqual( + normSorted(await dst.db.listApikeysByUser(s.normal.uid), (k) => k.kid), + normSorted(await src.db.listApikeysByUser(s.normal.uid), (k) => k.kid), + ); + // notes (full, with content) + const srcNote = await src.db.getNoteById(s.nid1); + const dstNote = await dst.db.getNoteById(s.nid1); + assert.deepEqual(norm(dstNote), norm(srcNote)); + } finally { + src.close(); + dst.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 2. filter narrowing +// --------------------------------------------------------------------------- + +describe("export/import: filter narrowing", () => { + it("scopes abode/resident/note to the requested abodes", async () => { + const src = await createTestDb(); + try { + const s = await seed(src.db); + const ndjson = await streamToString( + src.db.export({ filter: { abodes: [s.aid1] } }), + ); + const lines = parseLines(ndjson); + + const abodeAids = lines + .filter((l) => l.kind === "abode") + .map((l) => l.data.aid); + assert.deepEqual(abodeAids, [s.aid1]); + + const noteAids = new Set( + lines.filter((l) => l.kind === "note").map((l) => l.data.aid), + ); + assert.ok(noteAids.has(s.aid1)); + assert.ok(!noteAids.has(s.aid2)); + + const residentAids = new Set( + lines.filter((l) => l.kind === "resident").map((l) => l.data.aid), + ); + assert.ok(!residentAids.has(s.aid2)); + } finally { + src.close(); + } + }); + + it("imports the narrowed dump into a fresh db with the same scope", async () => { + const src = await createTestDb(); + const dst = await createTestDb(); + try { + const s = await seed(src.db); + await dst.db.import(src.db.export({ filter: { abodes: [s.aid1] } })); + + const abodes = await dst.db.listAbodes(); + assert.deepEqual( + abodes.map((a) => a.aid), + [s.aid1], + ); + const notes = await dst.db.listNotesByAbodeId(s.aid1); + assert.equal(notes.length, 1); + assert.equal((await dst.db.listNotesByAbodeId(s.aid2)).length, 0); + } finally { + src.close(); + dst.close(); + } + }); + + it("kinds filter selects only the requested kinds", async () => { + const src = await createTestDb(); + try { + await seed(src.db); + const ndjson = await streamToString( + src.db.export({ filter: { kinds: ["abode"] } }), + ); + const kinds = new Set(parseLines(ndjson).map((l) => l.kind)); + assert.ok(kinds.has("abode")); + assert.ok(!kinds.has("user")); + assert.ok(!kinds.has("note")); + } finally { + src.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 3. forced-filter enforcement +// --------------------------------------------------------------------------- + +describe("exportScope: computeForcedExportFilter", () => { + it("returns null for a global admin on a basic/session credential", async () => { + const t = await createTestDb(); + try { + const s = await seed(t.db); + const forced = await computeForcedExportFilter(t.db, { + user: s.admin, + session: { source: "basic" }, + }); + assert.equal(forced, null); + } finally { + t.close(); + } + }); + + it("returns null for a global admin with an unrestricted apikey", async () => { + const t = await createTestDb(); + try { + const s = await seed(t.db); + const forced = await computeForcedExportFilter(t.db, { + user: s.admin, + session: { + source: "apikey", + key: { + kid: "k", + uid: s.admin.uid, + name: "k", + permissions: { admin: true, all: true }, + created_at: new Date().toISOString(), + expires_at: null, + }, + }, + }); + assert.equal(forced, null); + } finally { + t.close(); + } + }); + + it("forces a non-admin to their abodes + co-residents", async () => { + const t = await createTestDb(); + try { + const s = await seed(t.db); + const forced = await computeForcedExportFilter(t.db, { + user: s.normal, + session: { source: "basic" }, + }); + assert.ok(forced); + assert.deepEqual(forced!.abodes, [s.aid1]); + assert.deepEqual( + new Set(forced!.users), + new Set([s.normal.uid, s.co.uid]), + ); + assert.ok(!forced!.users!.includes(s.admin.uid)); + + // A caller requesting a wider abode never gets it: intersection, not union. + const effective = intersectExportFilters( + { abodes: [s.aid1, s.aid2] }, + forced, + ); + assert.deepEqual(effective.abodes, [s.aid1]); + assert.ok(!effective.abodes!.includes(s.aid2)); + } finally { + t.close(); + } + }); + + it("intersects a non-admin apikey with restrict_abodes", async () => { + const t = await createTestDb(); + try { + const s = await seed(t.db); + const forced = await computeForcedExportFilter(t.db, { + user: s.normal, + session: { + source: "apikey", + key: { + kid: "k", + uid: s.normal.uid, + name: "k", + permissions: { restrict_abodes: [s.aid2] }, + created_at: new Date().toISOString(), + expires_at: null, + }, + }, + }); + // normal resides only in aid1; restrict to aid2 => empty intersection. + assert.deepEqual(forced!.abodes, []); + } finally { + t.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 4. cancellation, export side +// --------------------------------------------------------------------------- + +describe("export cancellation", () => { + it("stops querying tables after the destination aborts", async () => { + const t = await createTestDb(); + try { + const pw = await hashPassword("password"); + // Enough users that the first table can't be buffered in one go, so the + // generator backpressures mid-`user` and never reaches later tables. + for (let i = 0; i < 400; i++) { + await t.db.createUser({ + email: `bulk-${i}@test.example`, + name: `Bulk ${i}`, + password: pw, + flags: {}, + }); + } + + let allCalls = 0; + const orig = t.wrapped.all.bind(t.wrapped); + (t.wrapped as { all: unknown }).all = (stmt: never) => { + allCalls++; + return orig(stmt); + }; + + const ac = new AbortController(); + const stream = t.db.export({ signal: ac.signal }); + const rl = readline.createInterface({ input: stream }); + + let lines = 0; + let callsAtAbort = -1; + for await (const _ of rl) { + lines++; + if (lines === 3) { + ac.abort(); + callsAtAbort = allCalls; + } + } + + assert.ok(callsAtAbort >= 1, "at least the first table was queried"); + assert.equal(allCalls, callsAtAbort, "no further queries after abort"); + assert.ok(allCalls < 5, "did not materialise all five tables"); + } finally { + t.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 5. cancellation, import side +// --------------------------------------------------------------------------- + +describe("import cancellation", () => { + it("rolls back and leaves no dangling transaction when the source errors", async () => { + const dst = await createTestDb(); + try { + function line(kind: string, data: unknown): string { + return JSON.stringify({ kind, data }) + "\n"; + } + const now = new Date().toISOString(); + const mkUser = (i: number) => ({ + uid: crypto.randomUUID(), + email: `imp-${i}@test.example`, + name: `Imp ${i}`, + flags: {}, + created_at: now, + updated_at: now, + }); + + // Emits a couple of valid user records, then throws mid-stream. + const source = Readable.from( + (async function* () { + yield line("meta", { v: 1 }); + yield line("user", mkUser(1)); + yield line("user", mkUser(2)); + throw new Error("source exploded"); + })(), + ); + + await assert.rejects(() => dst.db.import(source), /source exploded/); + + // ROLLBACK happened: nothing persisted. + assert.equal((await dst.db.listUsers()).length, 0); + + // No lingering open transaction: a follow-up write succeeds immediately. + const pw = await hashPassword("password"); + const created = await dst.db.createUser({ + email: "after@test.example", + name: "After", + password: pw, + flags: {}, + }); + assert.ok(created.uid); + } finally { + dst.close(); + } + }); + + it("aborts cleanly via signal and commits nothing", async () => { + const dst = await createTestDb(); + try { + const ac = new AbortController(); + const now = new Date().toISOString(); + const source = Readable.from( + (async function* () { + yield JSON.stringify({ kind: "meta", data: { v: 1 } }) + "\n"; + yield JSON.stringify({ + kind: "user", + data: { + uid: crypto.randomUUID(), + email: "abort@test.example", + name: "Abort", + flags: {}, + created_at: now, + updated_at: now, + }, + }) + "\n"; + ac.abort(); + // Keep the stream alive so abort — not EOF — ends the import. + await new Promise((r) => setTimeout(r, 1000)); + })(), + ); + + await assert.rejects(() => dst.db.import(source, { signal: ac.signal })); + assert.equal((await dst.db.listUsers()).length, 0); + } finally { + dst.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 6. api export endpoint +// --------------------------------------------------------------------------- + +describe("GET /export endpoint", () => { + let t: TestDb; + let s: Seed; + let url: string; + let close: () => Promise; + + const basic = (email: string) => + "Basic " + Buffer.from(`${email}:password`).toString("base64"); + + before(async () => { + t = await createTestDb(); + s = await seed(t.db); + const app = new Koa(); + const router = apirouter(t.db); + app.use(router.routes()); + app.use(router.allowedMethods()); + const server = createServer(app.callback()); + await new Promise((r) => server.listen(0, "127.0.0.1", r)); + const { port } = server.address() as AddressInfo; + url = `http://127.0.0.1:${port}`; + close = () => + new Promise((resolve, reject) => + server.close((err) => (err ? reject(err) : resolve())), + ); + }); + + after(async () => { + await close(); + t.close(); + }); + + it("global admin exports everything", async () => { + const res = await fetch(`${url}/export`, { + headers: { Authorization: basic(s.admin.email) }, + }); + assert.equal(res.status, 200); + const lines = parseLines(await res.text()); + const abodeAids = new Set( + lines.filter((l) => l.kind === "abode").map((l) => l.data.aid), + ); + assert.ok(abodeAids.has(s.aid1)); + assert.ok(abodeAids.has(s.aid2)); + const userUids = new Set( + lines.filter((l) => l.kind === "user").map((l) => l.data.uid), + ); + assert.ok(userUids.has(s.admin.uid)); + assert.ok(userUids.has(s.normal.uid)); + }); + + it("non-admin is force-scoped even when requesting wider abodes", async () => { + const res = await fetch(`${url}/export?abodes=${s.aid1},${s.aid2}`, { + headers: { Authorization: basic(s.normal.email) }, + }); + assert.equal(res.status, 200); + const lines = parseLines(await res.text()); + + const abodeAids = new Set( + lines.filter((l) => l.kind === "abode").map((l) => l.data.aid), + ); + assert.ok(abodeAids.has(s.aid1)); + assert.ok(!abodeAids.has(s.aid2), "aid2 forced out of scope"); + + const userUids = new Set( + lines.filter((l) => l.kind === "user").map((l) => l.data.uid), + ); + assert.ok(userUids.has(s.normal.uid)); + assert.ok(userUids.has(s.co.uid)); + assert.ok(!userUids.has(s.admin.uid), "admin not a co-resident of aid1"); + + // The meta line records the *effective* (narrowed) filter. + const meta = lines.find((l) => l.kind === "meta"); + assert.ok(meta); + assert.deepEqual(meta!.data.filter.abodes, [s.aid1]); + }); + + it("stops server-side querying shortly after the client aborts", async () => { + // Dedicated db/server. Rows are deliberately large (and inserted in bulk so + // the seed stays fast) so the users table alone can't fit in the socket + // buffer — the export generator backpressures mid-`user` and never reaches + // later tables while the client is still holding the connection open. + const big = await createTestDb(); + let server: ReturnType | undefined; + try { + const pw = await hashPassword("password"); + await big.db.createUser({ + email: "a@test.example", + name: "A", + password: pw, + flags: { admin: true }, + }); + const { sql, db: raw } = big.db._; + // ~32MB of user rows — far more than any socket/kernel buffer can hold, + // so the generator is guaranteed to still be suspended mid-`user` (never + // having queried a later table) when the client aborts. + const bigName = "x".repeat(16000); + raw.multi(() => { + for (let i = 0; i < 2000; i++) { + raw.run(sql` + INSERT INTO "users"("uid", "email", "name", "flags") + VALUES( + ${{ uuid: crypto.randomUUID() }}, + ${{ text: `b-${i}@test.example` }}, + ${{ text: bigName }}, + ${{ jsonb: {} }} + ) + `); + } + }); + + let allCalls = 0; + const orig = big.wrapped.all.bind(big.wrapped); + (big.wrapped as { all: unknown }).all = (stmt: never) => { + allCalls++; + return orig(stmt); + }; + + const app = new Koa(); + app.on("error", () => {}); // swallow the expected ECONNRESET on abort + const router = apirouter(big.db); + app.use(router.routes()); + app.use(router.allowedMethods()); + server = createServer(app.callback()); + await new Promise((r) => server!.listen(0, "127.0.0.1", r)); + const { port } = server.address() as AddressInfo; + + const ac = new AbortController(); + const res = await fetch(`http://127.0.0.1:${port}/export`, { + headers: { Authorization: basic("a@test.example") }, + signal: ac.signal, + }); + const reader = res.body!.getReader(); + await reader.read(); // first chunk — server has begun streaming users + const callsWhileStreaming = allCalls; + assert.ok(callsWhileStreaming >= 1, "server queried the first table"); + ac.abort(); + await reader.cancel().catch(() => {}); + + await new Promise((r) => setTimeout(r, 250)); + const settled = allCalls; + await new Promise((r) => setTimeout(r, 250)); + assert.equal(allCalls, settled, "no further queries after abort"); + assert.ok(allCalls < 5, "did not materialise all five tables"); + } finally { + if (server) await new Promise((r) => server!.close(() => r())); + big.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// 7. inspect utility +// --------------------------------------------------------------------------- + +describe("inspectExportStream", () => { + it("tallies counts and reads meta without a db", async () => { + const src = await createTestDb(); + try { + await seed(src.db); + const ndjson = await streamToString(src.db.export()); + const { counts, meta } = await inspectExportStream( + Readable.from([ndjson]), + ); + assert.equal(meta?.v, 1); + assert.equal(meta?.source, "sqlite"); + assert.ok((counts.user ?? 0) >= 3); + assert.ok((counts.abode ?? 0) >= 2); + assert.ok((counts.note ?? 0) >= 2); + } finally { + src.close(); + } + }); + + it("stopAfterKinds short-circuits once every requested kind is seen", async () => { + const src = await createTestDb(); + try { + await seed(src.db); + const ndjson = await streamToString(src.db.export()); + const { counts } = await inspectExportStream(Readable.from([ndjson]), { + stopAfterKinds: ["user"], + }); + assert.ok((counts.user ?? 0) >= 1); + // stopped as soon as the first user was seen, before later kinds. + assert.equal(counts.note ?? 0, 0); + } finally { + src.close(); + } + }); +}); + +// --------------------------------------------------------------------------- +// filter unit checks +// --------------------------------------------------------------------------- + +describe("filter helpers", () => { + it("kindAllowed respects kinds/excludeKinds", () => { + assert.equal(kindAllowed({ kinds: ["abode"] }, "abode"), true); + assert.equal(kindAllowed({ kinds: ["abode"] }, "user"), false); + assert.equal(kindAllowed({ excludeKinds: ["note"] }, "note"), false); + assert.equal(kindAllowed(undefined, "note"), true); + }); + + it("recordAllowed scopes by aid/uid per kind", () => { + assert.equal( + recordAllowed({ abodes: ["a1"] }, "abode", { aid: "a1" }), + true, + ); + assert.equal( + recordAllowed({ abodes: ["a1"] }, "abode", { aid: "a2" }), + false, + ); + assert.equal( + recordAllowed({ users: ["u1"] }, "apikey", { uid: "u1" }), + true, + ); + assert.equal( + recordAllowed({ users: ["u1"] }, "apikey", { uid: "u2" }), + false, + ); + // abodes allowlist does not constrain user records + assert.equal( + recordAllowed({ abodes: ["a1"] }, "user", { uid: "u9" }), + true, + ); + }); +});