@deckbuilderkit/server-mods 0.0.0-stage → 0.1.0

package/src/records.ts

@@ -0,0 +1,294 @@
+import { join } from 'node:path';
+import { readJsonFile, writeJsonAtomic } from '@deckbuilderkit/platform';
+import { AppError, type ImportResult, invalid, isRecord, notFound, type Routes } from '@deckbuilderkit/server-core';
+import { fromPlatform } from './platform-errors.ts';
+
+/** A stored record: the app's fields plus the ones the store owns. */
+export type Rec<T> = T & { id: string; createdAt: string; updatedAt: string };
+
+/** Where secret field values live instead of the JSON file: `secretStore` from platform, a fake in tests. */
+export interface SecretBackend {
+  set(ref: string, value: string): Promise<void>;
+  get(ref: string): Promise<string | null>;
+  remove(ref: string): Promise<void>;
+}
+
+export interface RecordStoreOptions<T extends object> {
+  /** Folder of `<name>.json`, usually `appHome(APP.id)`. */
+  dir: string;
+  name: string;
+  /**
+   * Builds a fresh `T` from raw client input (never spread the input) and throws `invalid(...)`;
+   * `prev` is set on update, `ctx.imported` when the input comes from a backup file the user
+   * picked in a native dialog (`importItems`) rather than from a form.
+   */
+  validate(input: unknown, prev?: Rec<T>, ctx?: { imported?: true }): T;
+  /** Most records the store holds. */
+  max?: number;
+  /**
+   * Fields kept in `secrets` instead of the file. Input: a non-empty string sets the secret, `''`
+   * removes it, anything else (absent, `{ hasSecret: true }`) keeps it. Every returned record
+   * shows `{ hasSecret: true }` instead; app code reads the value with `secret(id, field)`.
+   */
+  secretFields?: string[];
+  secrets?: SecretBackend;
+}
+
+export interface RecordStore<T extends object> {
+  list(): Promise<Rec<T>[]>;
+  get(id: string): Promise<Rec<T>>;
+  create(input: unknown): Promise<Rec<T>>;
+  update(id: string, input: unknown): Promise<Rec<T>>;
+  remove(id: string): Promise<void>;
+  /** Puts the records named in `ids` first, in that order; unknown ids are ignored and records not named keep their order after them. */
+  reorder(ids: string[]): Promise<void>;
+  /** Server-only: the stored value of a secret field, null when none is set. Never return it from a route. */
+  secret(id: string, field: string): Promise<string | null>;
+  /**
+   * Adds or updates records by id from a backup, in one write. Imports never change secrets: an
+   * updated record keeps its stored ones, an added one has none. `replace` also removes the
+   * records whose id is not in `items`.
+   */
+  importItems(items: unknown[], mode: 'merge' | 'replace'): Promise<ImportResult>;
+  /** Every record without its secret fields (not even the `hasSecret` marker), for a backup. */
+  exportItems(): Promise<Rec<T>[]>;
+}
+
+export type { ImportResult };
+
+interface RecordFile<T> {
+  version: 1;
+  items: Rec<T>[];
+}
+
+/** Longest secret field value, in characters; the secret store is rewritten on every set. */
+const MAX_SECRET_LENGTH = 65_536;
+
+/** What a secret field holds in the file. */
+interface SecretRef {
+  ref: string;
+}
+
+const isRef = (v: unknown): v is SecretRef => typeof v === 'object' && v !== null && typeof (v as SecretRef).ref === 'string';
+
+const IMPORT_ID = /^[\w-]{1,64}$/;
+
+const isValidDate = (v: unknown): v is string => typeof v === 'string' && !Number.isNaN(Date.parse(v));
+
+const isRecordFile = (v: unknown) =>
+  typeof v === 'object' && v !== null && (v as RecordFile<object>).version === 1 && Array.isArray((v as RecordFile<object>).items);
+
+/** A JSON-file store of records with ids and timestamps; calls are serialized so concurrent ones never lose a record. */
+export function recordStore<T extends object>(opts: RecordStoreOptions<T>): RecordStore<T> {
+  const secretFields = opts.secretFields ?? [];
+  const backend = opts.secrets;
+  if (secretFields.length && !backend) throw new Error('recordStore: secretFields need the secrets option');
+  const secrets = backend && {
+    set: (ref: string, value: string) => backend.set(ref, value).catch(fromPlatform),
+    get: (ref: string) => backend.get(ref).catch(fromPlatform),
+    remove: (ref: string) => backend.remove(ref).catch(fromPlatform),
+  };
+  const file = join(opts.dir, `${opts.name}.json`);
+  const max = opts.max ?? 500;
+  let items: Rec<T>[] | null = null;
+  let chain: Promise<unknown> = Promise.resolve();
+
+  const locked = <R>(job: () => Promise<R>): Promise<R> => {
+    const run = chain.then(job);
+    chain = run.catch(() => {});
+    return run;
+  };
+
+  async function load(): Promise<Rec<T>[]> {
+    if (!items) items = ((await readJsonFile(file, isRecordFile)) as RecordFile<T> | undefined)?.items ?? [];
+    return items;
+  }
+
+  async function commit(next: Rec<T>[]): Promise<void> {
+    await writeJsonAtomic(file, { version: 1, items: next } satisfies RecordFile<T>);
+    items = next;
+  }
+
+  const find = (all: Rec<T>[], id: string) => {
+    const rec = all.find((r) => r.id === id);
+    if (!rec) throw notFound('recordNotFound', 'Record not found.');
+    return rec;
+  };
+
+  const fields = (rec: Rec<T>) => rec as unknown as Record<string, unknown>;
+
+  /** A copy of `rec` as routes may show it: each set secret field is `{ hasSecret: true }`. */
+  const masked = (rec: Rec<T>): Rec<T> => {
+    const copy = fields(structuredClone(rec));
+    for (const field of secretFields) {
+      if (isRef(copy[field])) copy[field] = { hasSecret: true };
+      else delete copy[field];
+    }
+    return copy as unknown as Rec<T>;
+  };
+
+  /**
+   * Sets the secret fields of `rec` from raw `input` (see `secretFields`), storing new values at
+   * once; returns the refs to remove once the record is saved.
+   */
+  async function applySecrets(input: unknown, rec: Rec<T>, prev?: Rec<T>): Promise<string[]> {
+    const raw = typeof input === 'object' && input !== null ? (input as Record<string, unknown>) : {};
+    for (const field of secretFields) {
+      const value = raw[field];
+      if (typeof value === 'string' && value.length > MAX_SECRET_LENGTH) throw invalid('secretTooLong', 'The secret is too long.');
+    }
+    const removals: string[] = [];
+    for (const field of secretFields) {
+      const value = raw[field];
+      const old = prev && fields(prev)[field];
+      delete fields(rec)[field];
+      if (typeof value === 'string' && value !== '') {
+        const ref = `${opts.name}:${rec.id}:${field}`;
+        await secrets!.set(ref, value);
+        fields(rec)[field] = { ref } satisfies SecretRef;
+      } else if (value === '') {
+        if (isRef(old)) removals.push(old.ref);
+      } else if (isRef(old)) {
+        fields(rec)[field] = old;
+      }
+    }
+    return removals;
+  }
+
+  const removeSecrets = async (refs: string[]) => {
+    for (const ref of refs) await secrets!.remove(ref);
+  };
+
+  const secretRefs = (rec: Rec<T>) => secretFields.map((field) => fields(rec)[field]).filter(isRef).map((s) => s.ref);
+
+  return {
+    list: () => locked(async () => (await load()).map(masked)),
+    get: (id) => locked(async () => masked(find(await load(), id))),
+    create: (input) =>
+      locked(async () => {
+        const all = await load();
+        if (all.length >= max) throw invalid('tooManyRecords', 'Too many records.');
+        const now = new Date().toISOString();
+        const rec = { ...opts.validate(input), id: crypto.randomUUID(), createdAt: now, updatedAt: now } as Rec<T>;
+        await applySecrets(input, rec);
+        await commit([...all, rec]);
+        return masked(rec);
+      }),
+    update: (id, input) =>
+      locked(async () => {
+        const all = await load();
+        const prev = find(all, id);
+        const rec = { ...opts.validate(input, masked(prev)), id: prev.id, createdAt: prev.createdAt, updatedAt: new Date().toISOString() } as Rec<T>;
+        const removals = await applySecrets(input, rec, prev);
+        await commit(all.map((r) => (r === prev ? rec : r)));
+        await removeSecrets(removals);
+        return masked(rec);
+      }),
+    remove: (id) =>
+      locked(async () => {
+        const all = await load();
+        const prev = find(all, id);
+        await commit(all.filter((r) => r !== prev));
+        await removeSecrets(secretRefs(prev));
+      }),
+    reorder: (ids) =>
+      locked(async () => {
+        const all = await load();
+        const byId = new Map(all.map((r) => [r.id, r]));
+        const first = [...new Set(ids)].flatMap((id) => byId.get(id) ?? []);
+        const named = new Set(first);
+        await commit([...first, ...all.filter((r) => !named.has(r))]);
+      }),
+    secret: (id, field) =>
+      locked(async () => {
+        if (!secretFields.includes(field)) throw new Error(`recordStore: ${field} is not a secret field`);
+        const stored = fields(find(await load(), id))[field];
+        return isRef(stored) ? secrets!.get(stored.ref) : null;
+      }),
+    importItems: (list, mode) =>
+      locked(async () => {
+        const all = await load();
+        const result: ImportResult = { added: 0, updated: 0, removed: 0, skipped: [] };
+        const skip = (id: string | undefined, code: string, message: string) => result.skipped.push({ ...(id && { id }), code, message });
+        const valid: Array<{ id: string; item: Record<string, unknown> }> = [];
+        const ids = new Set<string>();
+        for (const item of list) {
+          const id = typeof item === 'object' && item !== null ? (item as Record<string, unknown>).id : undefined;
+          if (typeof id !== 'string' || !IMPORT_ID.test(id)) skip(undefined, 'badRecord', 'Invalid record.');
+          else if (ids.has(id)) skip(id, 'badRecord', 'Invalid record.');
+          else {
+            ids.add(id);
+            valid.push({ id, item: item as Record<string, unknown> });
+          }
+        }
+        const kept = mode === 'merge' ? all : all.filter((r) => ids.has(r.id));
+        const updates = new Map<string, Rec<T>>();
+        const added: Rec<T>[] = [];
+        const now = new Date().toISOString();
+        for (const { id, item } of valid) {
+          const { id: _id, createdAt, updatedAt: _updatedAt, ...input } = item;
+          for (const field of secretFields) delete input[field];
+          const prev = all.find((r) => r.id === id);
+          if (!prev && kept.length + added.length >= max) {
+            skip(id, 'tooManyRecords', 'Too many records.');
+            continue;
+          }
+          let value: T;
+          try {
+            value = opts.validate(input, prev && masked(prev), { imported: true });
+          } catch (e) {
+            if (!(e instanceof AppError)) throw e;
+            skip(id, e.code, e.message);
+            continue;
+          }
+          if (prev) {
+            const rec = { ...value, id, createdAt: prev.createdAt, updatedAt: now } as Rec<T>;
+            await applySecrets(input, rec, prev);
+            updates.set(id, rec);
+          } else {
+            const rec = { ...value, id, createdAt: isValidDate(createdAt) ? new Date(createdAt).toISOString() : now, updatedAt: now } as Rec<T>;
+            for (const field of secretFields) delete fields(rec)[field];
+            added.push(rec);
+          }
+        }
+        const removed = all.filter((r) => !kept.includes(r));
+        await commit([...kept.map((r) => updates.get(r.id) ?? r), ...added]);
+        await removeSecrets(removed.flatMap(secretRefs));
+        return { ...result, added: added.length, updated: updates.size, removed: removed.length };
+      }),
+    exportItems: () =>
+      locked(async () =>
+        (await load()).map((rec) => {
+          const copy = fields(structuredClone(rec));
+          for (const field of secretFields) delete copy[field];
+          return copy as unknown as Rec<T>;
+        }),
+      ),
+  };
+}
+
+/** `GET <base>`, `GET <base>/item?id=`, `POST <base>`, `PUT <base>?id=`, `DELETE <base>?id=` over a record store. */
+export function recordRoutes<T extends object>(store: RecordStore<T>, base: string): Routes {
+  const idOf = (query: URLSearchParams) => {
+    const id = query.get('id');
+    if (!id) throw invalid('missingId', 'Missing id.');
+    return id;
+  };
+  return {
+    [`GET ${base}`]: () => store.list(),
+    [`GET ${base}/item`]: ({ query }) => store.get(idOf(query)),
+    [`POST ${base}`]: async ({ json }) => store.create(await json()),
+    [`PUT ${base}`]: async ({ query, json }) => store.update(idOf(query), await json()),
+    [`POST ${base}/order`]: async ({ json }) => {
+      const body = await json();
+      const ids = isRecord(body) ? body.ids : undefined;
+      if (!Array.isArray(ids) || ids.some((id) => typeof id !== 'string')) throw invalid('badOrder', 'Invalid order.');
+      await store.reorder(ids as string[]);
+      return { ok: true };
+    },
+    [`DELETE ${base}`]: async ({ query }) => {
+      await store.remove(idOf(query));
+      return { ok: true };
+    },
+  };
+}

package/src/rest-env.ts

@@ -0,0 +1,51 @@
+import { invalid } from '@deckbuilderkit/server-core';
+import { REST_VAR_REFERENCE } from '@deckbuilderkit/server-core/protocol';
+
+export interface VariableResolver {
+  /** `text` with every known `{{name}}` replaced; unknown names are collected and left as they are. */
+  resolve(text: string): string;
+  /** Unknown names seen so far, in order of first use. */
+  readonly missing: string[];
+  /** Throws `unknownVariable` (params.names = comma-separated list) when any name was unknown. */
+  check(): void;
+}
+
+/**
+ * Resolves `{{name}}` against `vars` (own keys only) and the built-ins. `$timestamp` and
+ * `$isoTimestamp` are fixed per resolver (one request sees one time); `$uuid` and `$randomInt`
+ * (0..1000) are fresh at each use.
+ */
+export function variableResolver(vars: Record<string, string> = {}, now: () => Date = () => new Date()): VariableResolver {
+  const missing: string[] = [];
+  let at: Date | undefined;
+  const time = () => (at ??= now());
+  const builtin = (name: string): string | undefined => {
+    switch (name) {
+      case '$timestamp':
+        return String(Math.floor(time().getTime() / 1000));
+      case '$isoTimestamp':
+        return time().toISOString();
+      case '$uuid':
+        return crypto.randomUUID();
+      case '$randomInt':
+        return String(Math.floor(Math.random() * 1001));
+      default:
+        return undefined;
+    }
+  };
+  return {
+    resolve: (text) =>
+      text.replace(REST_VAR_REFERENCE, (whole, name: string) => {
+        const value = Object.hasOwn(vars, name) ? vars[name] : builtin(name);
+        if (value !== undefined) return value;
+        if (!missing.includes(name)) missing.push(name);
+        return whole;
+      }),
+    missing,
+    check() {
+      if (missing.length) throw unknownVariables(missing);
+    },
+  };
+}
+
+export const unknownVariables = (names: string[]) => invalid('unknownVariable', `Unknown variables: ${names.join(', ')}.`, { names: names.join(', ') });

package/src/rest-history.ts

@@ -0,0 +1,92 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RestHistoryEntry } from '@deckbuilderkit/server-core/protocol';
+import { withoutAuthorization } from './http.ts';
+
+export type { RestHistoryEntry };
+
+export interface RestHistoryOptions {
+  /** Folder of `rest-history.json`. */
+  dir: string;
+  /** Most entries kept; 0 turns recording off. A function is read on every append. */
+  max: number | (() => number);
+}
+
+export interface RestHistory {
+  /** Adds an entry at the top without Authorization headers (no-op while max is 0); gives the stored entry, or null when off. */
+  append(entry: Omit<RestHistoryEntry, 'id'>): Promise<RestHistoryEntry | null>;
+  /** Newest first; `q` matches the method and URL ignoring case. */
+  list(filter?: { q?: string }): Promise<RestHistoryEntry[]>;
+  clear(): Promise<void>;
+  setMax(max: number): void;
+}
+
+const isEntry = (e: unknown): e is RestHistoryEntry => {
+  const r = e as Partial<RestHistoryEntry> | null;
+  return (
+    typeof r === 'object' && r !== null && typeof r.id === 'string' && typeof r.method === 'string' && typeof r.url === 'string' &&
+    typeof r.at === 'number' && typeof r.status === 'number' && typeof r.ms === 'number' && typeof r.draft === 'object' && r.draft !== null &&
+    Array.isArray(r.draft.headers)
+  );
+};
+
+/** The REST request history in `<dir>/rest-history.json`: newest first, capped at `max`, written atomically. */
+export function restHistory({ dir, max }: RestHistoryOptions): RestHistory {
+  const file = join(dir, 'rest-history.json');
+  let limit = max;
+  const maxNow = () => Math.max(0, Math.floor(typeof limit === 'function' ? limit() : limit) || 0);
+  let entries: Promise<RestHistoryEntry[]> | null = null;
+  let queue: Promise<unknown> = Promise.resolve();
+
+  function load(): Promise<RestHistoryEntry[]> {
+    entries ??= readFile(file, 'utf8')
+      .then((text) => {
+        const raw: unknown = JSON.parse(text);
+        return Array.isArray(raw) ? raw.filter(isEntry) : [];
+      })
+      .catch(() => []);
+    return entries;
+  }
+
+  function mutate<T>(change: (list: RestHistoryEntry[]) => { list: RestHistoryEntry[]; result: T; dirty: boolean }): Promise<T> {
+    const run = queue.then(async () => {
+      const { list, result, dirty } = change(await load());
+      entries = Promise.resolve(list);
+      if (dirty) {
+        await mkdir(dir, { recursive: true });
+        const tmp = `${file}.${process.pid}.${crypto.randomUUID().slice(0, 8)}.tmp`;
+        try {
+          await writeFile(tmp, JSON.stringify(list));
+          await rename(tmp, file);
+        } catch (err) {
+          await rm(tmp, { force: true });
+          throw err;
+        }
+      }
+      return result;
+    });
+    queue = run.catch(() => {});
+    return run;
+  }
+
+  return {
+    append(entry) {
+      if (maxNow() === 0) return Promise.resolve(null);
+      return mutate((list) => {
+        const cap = maxNow();
+        if (cap === 0) return { list, result: null, dirty: false };
+        const stored: RestHistoryEntry = { id: crypto.randomUUID(), ...entry, draft: withoutAuthorization(entry.draft) };
+        return { list: [stored, ...list].slice(0, cap), result: stored, dirty: true };
+      });
+    },
+    async list({ q } = {}) {
+      await queue;
+      const needle = q?.trim().toLowerCase();
+      return (await load()).filter((e) => !needle || `${e.method} ${e.url}`.toLowerCase().includes(needle));
+    },
+    clear: () => mutate((list) => ({ list: [], result: undefined, dirty: list.length > 0 })),
+    setMax(n) {
+      limit = n;
+    },
+  };
+}

package/src/rest-tabs.ts

@@ -0,0 +1,83 @@
+import { join } from 'node:path';
+import { readJsonFile, writeJsonAtomic } from '@deckbuilderkit/platform';
+import { invalid, isRecord, type Routes } from '@deckbuilderkit/server-core';
+import type { HttpRequestDraft } from '@deckbuilderkit/server-core/protocol';
+import { validateDraft, withoutAuthorization } from './http.ts';
+
+export const REST_TABS_MAX = 30;
+const ID = /^[\w-]{1,64}$/;
+const MAX_TITLE = 200;
+
+export interface RestTab {
+  id: string;
+  draft: HttpRequestDraft;
+  savedId?: string;
+  title?: string;
+}
+
+export interface RestTabsFile {
+  version: 1;
+  tabs: RestTab[];
+  active?: string;
+}
+
+const badTabs = () => invalid('badRestTabs', 'The open requests are not valid.');
+
+/** The open REST tabs as a fresh object; Authorization headers are dropped, anything out of range throws `badRestTabs`. */
+export function validateRestTabs(raw: unknown): RestTabsFile {
+  if (!isRecord(raw) || raw.version !== 1 || !Array.isArray(raw.tabs) || raw.tabs.length > REST_TABS_MAX) throw badTabs();
+  const seen = new Set<string>();
+  const tabs = raw.tabs.map((tab): RestTab => {
+    if (!isRecord(tab) || typeof tab.id !== 'string' || !ID.test(tab.id) || seen.has(tab.id)) throw badTabs();
+    seen.add(tab.id);
+    let draft: HttpRequestDraft;
+    try {
+      draft = withoutAuthorization(validateDraft(tab.draft));
+    } catch {
+      throw badTabs();
+    }
+    const out: RestTab = { id: tab.id, draft };
+    if (tab.savedId !== undefined) {
+      if (typeof tab.savedId !== 'string' || !ID.test(tab.savedId)) throw badTabs();
+      out.savedId = tab.savedId;
+    }
+    if (tab.title !== undefined) {
+      if (typeof tab.title !== 'string' || tab.title.length > MAX_TITLE) throw badTabs();
+      out.title = tab.title;
+    }
+    return out;
+  });
+  const file: RestTabsFile = { version: 1, tabs };
+  if (raw.active !== undefined) {
+    if (typeof raw.active !== 'string' || !seen.has(raw.active)) throw badTabs();
+    file.active = raw.active;
+  }
+  return file;
+}
+
+const isTabsFile = (v: unknown) => isRecord(v) && v.version === 1 && Array.isArray(v.tabs);
+
+/** GET/PUT `path`: the REST screen's open tabs in `<dir>/restTabs.json` (never the Authorization value). */
+export function restTabsRoutes(opts: { dir: string; path?: string }): Routes {
+  const file = join(opts.dir, 'restTabs.json');
+  const path = opts.path ?? '/api/rest-tabs';
+  let chain: Promise<unknown> = Promise.resolve();
+  return {
+    [`GET ${path}`]: async () => {
+      const stored = await readJsonFile(file, isTabsFile);
+      if (!stored) return { version: 1, tabs: [] } satisfies RestTabsFile;
+      try {
+        return validateRestTabs(stored);
+      } catch {
+        return { version: 1, tabs: [] } satisfies RestTabsFile;
+      }
+    },
+    [`PUT ${path}`]: async ({ json }) => {
+      const next = validateRestTabs(await json());
+      const run = chain.then(() => writeJsonAtomic(file, next));
+      chain = run.catch(() => {});
+      await run;
+      return { ok: true };
+    },
+  };
+}