@starci/hfs 4.11.0 → 4.11.11

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.spec.ts

@@ -0,0 +1,96 @@
+import { Test } from "@nestjs/testing"
+import { mockEntityManager } from "@starci/jest-preset"
+import { advisoryXactLock, callDbFunction, notify } from "./database.client"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+const DATABASE_CLIENT = Symbol("database-client")
+
+const setup = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: DATABASE_CLIENT, useFactory: () => ({ advisoryXactLock, callDbFunction, notify }) }],
+    }).compile()
+    return moduleRef.get<{
+        readonly advisoryXactLock: typeof advisoryXactLock
+        readonly callDbFunction: typeof callDbFunction
+        readonly notify: typeof notify
+    }>(DATABASE_CLIENT)
+}
+
+/** What `callDbFunction` throws for `name`, or null when it builds a call. */
+const refusalOf = async (name: string): Promise<unknown> => {
+    const client = await setup()
+    try {
+        await client.callDbFunction(mockEntityManager({ query: ['SELECT * FROM "public"."never"()', []] }), name, [])
+        return null
+    } catch (error) {
+        return error
+    }
+}
+
+describe("callDbFunction", () => {
+    it("calls a schema-qualified function with each part quoted and the arguments as numbered parameters", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "public"."job_claim"($1, $2)', [{ id: "job-1" }]] })
+
+        const rows = await client.callDbFunction<{ id: string }>(manager, "public.job_claim", ["mail", 3])
+
+        expect(rows).toEqual([{ id: "job-1" }])
+        expect(manager.query).toHaveBeenCalledWith('SELECT * FROM "public"."job_claim"($1, $2)', ["mail", 3])
+    })
+
+    it("calls a bare pg built-in of the canon's list in pg_catalog", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "pg_catalog"."to_regproc"($1)', [{ to_regproc: null }]] })
+
+        const rows = await client.callDbFunction<{ to_regproc: string | null }>(manager, "to_regproc", ["public.job_claim"])
+
+        expect(rows).toEqual([{ to_regproc: null }])
+    })
+
+    it("calls a function of another schema with no arguments", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ['SELECT * FROM "be_access"."chat_target_member"()', []] })
+
+        const rows = await client.callDbFunction(manager, "be_access.chat_target_member", [])
+
+        expect(rows).toEqual([])
+    })
+
+    it.each([
+        ["a bare name that is not a listed built-in", "job_claim"],
+        ["a pg_catalog name spelt out", "pg_catalog.pg_terminate_backend"],
+        ["a quote inside a part", 'public."job_claim'],
+        ["a second statement smuggled into the name", "public.job_claim(); SELECT 1; --"],
+        ["an upper-case part", "public.Job_Claim"],
+        ["three parts", "db.public.job_claim"],
+        ["an empty schema", ".job_claim"],
+        ["an empty name", ""],
+    ])("refuses %s before any SQL runs", async (_case, name) => {
+        const refusal = await refusalOf(name)
+
+        expect(refusal).toBeInstanceOf(DatabaseError)
+        expect(refusal).toMatchObject({ code: DatabaseErrorCode.IdentifierRejected, params: { name } })
+    })
+})
+
+describe("advisoryXactLock", () => {
+    it("locks the 64-bit hash of the key for the transaction", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ["SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [{}]] })
+
+        await expect(client.advisoryXactLock(manager, "jobs:mail")).resolves.toBeUndefined()
+
+        expect(manager.query).toHaveBeenCalledWith("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", ["jobs:mail"])
+    })
+})
+
+describe("notify", () => {
+    it("sends the payload on the channel", async () => {
+        const client = await setup()
+        const manager = mockEntityManager({ query: ["SELECT pg_notify($1, $2)", [{}]] })
+
+        await expect(client.notify(manager, "jobs", '{"id":"job-1"}')).resolves.toBeUndefined()
+
+        expect(manager.query).toHaveBeenCalledWith("SELECT pg_notify($1, $2)", ["jobs", '{"id":"job-1"}'])
+    })
+})

package/templates/be/skeleton-lite/src/modules/platform/database/database.client.ts

@@ -0,0 +1,93 @@
+import type { EntityManager } from "typeorm"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
+
+declare const functionPartBrand: unique symbol
+declare const parameterListBrand: unique symbol
+
+/** One part of a database function name that passed the identifier check: the only caller text a call statement holds. */
+type DbFunctionPart = string & { readonly [functionPartBrand]: true }
+
+/** The numbered parameters `$1, ..., $n` of one call, built from a count alone. */
+type DbParameterList = string & { readonly [parameterListBrand]: true }
+
+/** A function the call statement names: its schema and its name, each part checked. */
+interface DbFunctionTarget {
+    readonly schema: DbFunctionPart
+    readonly name: DbFunctionPart
+}
+
+/** The pg built-ins the canon lists bare in ruleParams.be.dbFunctions; each is called in pg_catalog. */
+const PG_BUILTINS: ReadonlySet<string> = new Set([
+    "pg_advisory_xact_lock",
+    "hashtextextended",
+    "pg_notify",
+    "to_regproc",
+    "gen_random_uuid",
+])
+
+/** The schema that holds the pg built-ins. */
+const BUILTIN_SCHEMA = "pg_catalog"
+
+/** One unquoted lower-case identifier: a part of this shape needs no escaping inside double quotes. */
+const PART_PATTERN = /^[a-z_][a-z0-9_]*$/
+
+function assertFunctionPart(_value: string): asserts _value is DbFunctionPart {
+    // The brand is compile-time only; `functionPart` is the single caller after checking the part.
+}
+
+function assertParameterList(_value: string): asserts _value is DbParameterList {
+    // The brand is compile-time only; `parameterList` is the single caller.
+}
+
+/** The refusal of a name that is not a callable database function. */
+const rejected = (name: string): DatabaseError =>
+    new DatabaseError({ code: DatabaseErrorCode.IdentifierRejected, params: { name } })
+
+/** Checks one part of a function name against the identifier shape and brands it. */
+const functionPart = (part: string, name: string): DbFunctionPart => {
+    if (!PART_PATTERN.test(part)) throw rejected(name)
+    assertFunctionPart(part)
+    return part
+}
+
+/**
+ * The function a name calls: `schema.name` for a function of a migration (never in pg_catalog), or a bare pg built-in of
+ * the canon's list, called in pg_catalog. Anything else is refused before any SQL is built.
+ */
+const functionTarget = (name: string): DbFunctionTarget => {
+    const parts = name.split(".")
+    if (parts.length === 1 && PG_BUILTINS.has(name)) {
+        return { schema: functionPart(BUILTIN_SCHEMA, name), name: functionPart(name, name) }
+    }
+    const [schema, fn] = parts
+    if (parts.length !== 2 || schema === undefined || fn === undefined || schema === BUILTIN_SCHEMA) throw rejected(name)
+    return { schema: functionPart(schema, name), name: functionPart(fn, name) }
+}
+
+/** The numbered parameter list of a call with `count` arguments. */
+const parameterList = (count: number): DbParameterList => {
+    const list = Array.from({ length: count }, (_, index) => `$${String(index + 1)}`).join(", ")
+    assertParameterList(list)
+    return list
+}
+
+/**
+ * Calls one database function TypeORM cannot express (a pg built-in or a SECURITY DEFINER function of a migration) with
+ * numbered parameters. The name is schema-qualified (`public.job_claim`) or a bare built-in of the canon's list, each part
+ * is checked and double-quoted, and the arguments are values, never text of the statement (R334, R68).
+ */
+export const callDbFunction = <T>(manager: EntityManager, name: string, args: ReadonlyArray<unknown>): Promise<ReadonlyArray<T>> => {
+    const target = functionTarget(name)
+    const parameters = parameterList(args.length)
+    return manager.query<Array<T>>(`SELECT * FROM "${target.schema}"."${target.name}"(${parameters})`, [...args])
+}
+
+/** Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends. */
+export const advisoryXactLock = async (manager: EntityManager, key: string): Promise<void> => {
+    await manager.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key])
+}
+
+/** Sends one NOTIFY on `channel` with `payload`, delivered when the manager's transaction commits. */
+export const notify = async (manager: EntityManager, channel: string, payload: string): Promise<void> => {
+    await manager.query("SELECT pg_notify($1, $2)", [channel, payload])
+}

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -1,5 +1,5 @@
 export { DatabaseModule } from "./database.module"
-export { advisoryXactLock, callDbFunction, notify } from "./database.functions"
+export { advisoryXactLock, callDbFunction, notify } from "./database.client"
 export { DATABASE_PROBE, InjectDatabaseProbe, InjectPrimaryEntityManager, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"

package/templates/be/skeleton-lite/src/tests/fixtures/builders/api.builder.ts

@@ -13,6 +13,7 @@ export const buildWiringProof = () => ({
             rateLimit: { windowMs: 60000, defaultLimit: 100, strictLimit: 10 },
             webhooks: {},
         },
+        http: {},
         database: {
             name: "primary",
             provider: "postgres",

package/runtime/scripts/hfs/rules/database-queue-outbox.mjs

@@ -1,102 +0,0 @@
-// R258: an app whose queue is BullMQ on a declared Redis may keep its own outbox beside the canon `ruleParams.db.queueOutbox` table. The
-// app declares it in hfs.json `sides.be.queueOutbox` ({table, enqueue, queueParameter}), and a pg_cron tick enqueues through the declared
-// `enqueue` function only while that function's active definition does nothing but write the declared table with its queue column bound
-// to the declared parameter. The checker reads the declaration and the function body; it names no app table or function.
-import pg from 'libpg-query';
-import { sqlStringParts as strings, walkSqlAst as walk, sqlParser } from '../../lib/sql-ast.mjs';
-
-await pg.loadModule();
-
-const sqlTree = sqlParser(pg);
-const STATEMENTS = new Set(['PLpgSQL_stmt_block', 'PLpgSQL_stmt_execsql', 'PLpgSQL_stmt_if', 'PLpgSQL_stmt_assign', 'PLpgSQL_stmt_return']);
-const OTHER_DML = ['UpdateStmt', 'DeleteStmt', 'MergeStmt'];
-const qualified = (name) => name.includes('.') ? name : `public.${name}`;
-
-/** The outbox an app declares, or null: it counts only while the back end declares the redis backing the relay hands rows to. */
-export function queueOutboxDeclaration(declaration) {
-  const be = declaration?.sides?.be;
-  const declared = be?.queueOutbox;
-  if (!declared || !(be.backing ?? []).includes('redis')) return null;
-  return { table: qualified(declared.table), enqueue: qualified(declared.enqueue), parameter: declared.queueParameter };
-}
-
-function plpgsqlStatements(fn, body) {
-  const parameters = (fn.parameters ?? []).map((item) => item.FunctionParameter?.name).filter(Boolean).map((name) => `"${name.replaceAll('"', '""')}" text`).join(',');
-  let tag = '$hfs_outbox$';
-  while (body.includes(tag)) tag = `${tag.slice(0, -1)}_$`;
-  let tree;
-  try { tree = pg.parsePlPgSQLSync(`create function hfs_probe(${parameters}) returns text language plpgsql as ${tag}${body}${tag};`); } catch { return null; }
-  const trees = [];
-  let safe = true;
-  walk(tree, (node) => {
-    for (const key of Object.keys(node)) if (key.startsWith('PLpgSQL_stmt_') && !STATEMENTS.has(key)) safe = false;
-    const expr = node.PLpgSQL_expr;
-    if (expr) trees.push(sqlTree(expr.parseMode === 0 ? expr.query : `select ${expr.query}`));
-  });
-  return safe ? trees : null;
-}
-
-function bodyStatements(fn) {
-  const option = (name) => (fn.options ?? []).find((item) => item.DefElem?.defname === name)?.DefElem?.arg;
-  const language = option('language')?.String?.sval ?? 'sql';
-  const body = strings(option('as')?.List?.items).join('');
-  if (language === 'plpgsql') return plpgsqlStatements(fn, body);
-  if (language !== 'sql') return null;
-  if (fn.sql_body) return (fn.sql_body.List ? fn.sql_body.List.items : [fn.sql_body]).map((stmt) => ({ stmts: [{ stmt }] }));
-  return sqlTree(body)?.stmts?.map((entry) => ({ stmts: [entry] })) ?? null;
-}
-
-/** True when the nodes hold no sub-select or other statement and call only functions `pureCall` admits. */
-function pureNodes(nodes, pureCall) {
-  let ok = true;
-  walk(nodes, (node) => {
-    if (node.SubLink || node.SelectStmt || node.InsertStmt || OTHER_DML.some((key) => node[key])) ok = false;
-    if (node.FuncCall && !pureCall(node.FuncCall)) ok = false;
-  });
-  return ok;
-}
-
-/** `insert into <table> (..., queue, ...) values (..., <parameter>, ...) [on conflict .. do nothing] [returning ..]` with pure other values. */
-function insertOk(declared, insert, pureCall) {
-  if (insert.withClause || `${insert.relation?.schemaname || 'public'}.${insert.relation?.relname}` !== declared.table) return false;
-  if (insert.onConflictClause && insert.onConflictClause.action !== 'ONCONFLICT_NOTHING') return false;
-  const columns = (insert.cols ?? []).map((item) => item.ResTarget?.name);
-  const rows = insert.selectStmt?.SelectStmt?.valuesLists ?? [];
-  const values = rows.length === 1 ? rows[0].List?.items ?? [] : [];
-  const at = columns.indexOf('queue');
-  if (at < 0 || new Set(columns).size !== columns.length || values.length !== columns.length) return false;
-  const bound = values[at].ColumnRef?.fields;
-  if (!bound || strings(bound).join('.') !== declared.parameter || bound.length !== 1) return false;
-  return pureNodes(values.filter((_, index) => index !== at), pureCall);
-}
-
-/** A read of the declared table with pure expressions, or an expression over variables alone. */
-function readOk(declared, tree, pureCall) {
-  let ok = true;
-  walk(tree, (node) => {
-    if (OTHER_DML.some((key) => node[key]) || node.InsertStmt || node.SelectStmt?.intoClause) ok = false;
-    if (node.FuncCall && !pureCall(node.FuncCall)) ok = false;
-    if (node.RangeVar && `${node.RangeVar.schemaname || 'public'}.${node.RangeVar.relname}` !== declared.table) ok = false;
-  });
-  return ok;
-}
-
-function statementOk(declared, tree, pureCall) {
-  const stmt = tree?.stmts?.length === 1 ? tree.stmts[0].stmt : null;
-  if (stmt?.InsertStmt) return insertOk(declared, stmt.InsertStmt, pureCall);
-  return Boolean(stmt?.SelectStmt) && readOk(declared, tree, pureCall);
-}
-
-/**
- * The position of the queue parameter when the active definition of the declared enqueue function only writes the declared outbox
- * (inserts, reads of that table and pure expressions), or -1. `pureCall` admits a function call that does no work.
- */
-export function outboxEnqueueQueueIndex(declared, entry, pureCall) {
-  const fn = entry?.node;
-  if (!fn) return -1;
-  const index = (fn.parameters ?? []).findIndex((item) => item.FunctionParameter?.name === declared.parameter);
-  const trees = bodyStatements(fn);
-  if (index < 0 || !trees?.length || !trees.every((tree) => statementOk(declared, tree, pureCall))) return -1;
-  const inserts = trees.filter((tree) => tree?.stmts?.[0]?.stmt?.InsertStmt).length;
-  return inserts === 1 ? index : -1;
-}

package/templates/app/db-image/db/Dockerfile

@@ -1,8 +0,0 @@
-# Managed by starci app sync (slot app.db.image); do not edit: run "npx starci app sync --write".
-# The image of the db service of a lite app (ruling lite-official-postgres-image): the Docker Official postgres image, pinned by
-# digest, plus pgvector from the PGDG repository the image already configures. The contrib extensions (pgcrypto, pg_trgm, unaccent,
-# uuid-ossp, btree_gist) ship in the image. The stack's db service, `npm run db:create` and `starci app db drift` all build this file.
-FROM {{dbBaseImage}}
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends {{pgvectorPackage}} \
-    && rm -rf /var/lib/apt/lists/*

package/templates/be/skeleton-lite/src/modules/platform/database/database.functions.ts

@@ -1,24 +0,0 @@
-import type { EntityManager } from "typeorm"
-
-/** The database functions this app may call, each listed with its reason in ruleParams.be.dbFunctions or hfs.json sides.be.dbFunctions. */
-const IDENTIFIER = /^[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)?$/
-
-/**
- * Calls one database function TypeORM cannot express (a pg built-in or a SECURITY DEFINER function of a migration) with numbered
- * parameters; the function name is an identifier the canon lint holds to the listed set, never a value.
- */
-export const callDbFunction = async <T>(manager: EntityManager, name: string, args: ReadonlyArray<unknown>): Promise<ReadonlyArray<T>> => {
-    if (!IDENTIFIER.test(name)) throw new TypeError(`${name} is not a database function name`)
-    const placeholders = args.map((_, index) => `$${String(index + 1)}`).join(", ")
-    return manager.query<Array<T>>(`SELECT * FROM ${name}(${placeholders})`, [...args])
-}
-
-/** Takes a transaction-scoped advisory lock on the 64-bit hash of `key`; it is released when the manager's transaction ends. */
-export const advisoryXactLock = async (manager: EntityManager, key: string): Promise<void> => {
-    await manager.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key])
-}
-
-/** Sends one NOTIFY on `channel` with `payload`, delivered when the manager's transaction commits. */
-export const notify = async (manager: EntityManager, channel: string, payload: string): Promise<void> => {
-    await manager.query("SELECT pg_notify($1, $2)", [channel, payload])
-}