From b144781e9f499882120fa35787bd7d227cb08cd2 Mon Sep 17 00:00:00 2001 From: Maurice Date: Tue, 17 Nov 2026 13:00:39 +0100 Subject: [PATCH] feat(db): keep a plugin's own data in a Postgres schema of its own A plugin with db:own got a SQLite WAL file in the data volume whatever the engine, so a Postgres install still needed a local disk (discussion #386). This adds the plugin data port (db/engine/plugin-data.ts) and its Postgres side: one schema per plugin, trek_plugin_, reached through TREK's pool. Every call runs in a transaction that creates the schema if missing, puts only it on the search_path and sets statement_timeout to the call's budget. Reads stream through a cursor and stop at the row cap, a write that grows the schema past the quota rolls back, and the calls of one plugin run one at a time on at most half of the pool. TREK's role may read every table, and a role per plugin would need CREATEROLE, so plugin-sql-guard.ts checks each statement first: it lexes the SQL as Postgres does and refuses another schema as a qualifier, the pg_ catalogs and functions, functions that run SQL from a string or reach an object by a name in one, temporary tables, and every statement but DML and DDL on tables, indexes, views, sequences and types. --- server/src/db/engine/index.ts | 15 +- server/src/db/engine/plugin-data.ts | 59 +++ .../db/engine/postgres/plugin-data-store.ts | 378 +++++++++++++++++ .../src/db/engine/postgres/plugin-schema.ts | 51 +++ .../db/engine/postgres/plugin-sql-guard.ts | 400 ++++++++++++++++++ .../db/engine/postgres/plugin-schema.test.ts | 92 ++++ .../engine/postgres/plugin-sql-guard.test.ts | 176 ++++++++ 7 files changed, 1165 insertions(+), 6 deletions(-) create mode 100644 server/src/db/engine/plugin-data.ts create mode 100644 server/src/db/engine/postgres/plugin-data-store.ts create mode 100644 server/src/db/engine/postgres/plugin-schema.ts create mode 100644 server/src/db/engine/postgres/plugin-sql-guard.ts create mode 100644 server/tests/unit/db/engine/postgres/plugin-schema.test.ts create mode 100644 server/tests/unit/db/engine/postgres/plugin-sql-guard.test.ts diff --git a/server/src/db/engine/index.ts b/server/src/db/engine/index.ts index fb80cf17e..cf06b3a80 100644 --- a/server/src/db/engine/index.ts +++ b/server/src/db/engine/index.ts @@ -23,14 +23,17 @@ export function resolveEngine(db: DbEngineSettings = readEnv().db): DatabaseEngi } /** - * The Postgres URL and the directory of its client tools, when the settings - * name a Postgres database; null on SQLite. For the code that drives pg_dump - * and pg_restore, which needs both and must not read them from the environment - * again. + * The Postgres URL, the directory of its client tools and the pool's size, + * when the settings name a Postgres database; null on SQLite. For the code + * that drives pg_dump and pg_restore, which needs the first two, and the + * plugin data stores, which share the pool, and must not read them from the + * environment again. */ -export function postgresTarget(db: DbSettings): { url: string; binDir: string | undefined } | null { +export function postgresTarget( + db: DbSettings, +): { url: string; binDir: string | undefined; poolMax: number } | null { if (db.engine !== 'postgres') return null; - return { url: db.url, binDir: db.pgBinDir }; + return { url: db.url, binDir: db.pgBinDir, poolMax: db.poolMax }; } /** diff --git a/server/src/db/engine/plugin-data.ts b/server/src/db/engine/plugin-data.ts new file mode 100644 index 000000000..edcca30a2 --- /dev/null +++ b/server/src/db/engine/plugin-data.ts @@ -0,0 +1,59 @@ +import type { EngineId } from '../../app-config/db-settings'; + +/** + * A plugin's own database (`db:own`), as the host's RPC handlers reach it. + * One implementation per engine: on SQLite a file of the plugin's own + * (`nest/plugins/host/plugin-data.service.ts`), on Postgres a schema of the + * plugin's own (`postgres/plugin-data-store.ts`). The plugin's SQL is its + * own, written for the engine `engine` names; neither implementation + * translates it. + * + * The SQLite handle answers synchronously, the Postgres one with a promise, + * so every method may return either. The caller awaits the result. + */ +export interface PluginDataStore { + readonly pluginId: string; + /** The engine the plugin's SQL runs on, which decides the SQL dialect it has to be written in. */ + readonly engine: EngineId; + /** One read statement: its rows, up to the row cap and within the time budget. */ + query(sql: string, args?: unknown[]): MaybePromise; + /** One statement with bound args, or a script of statements without. */ + exec(sql: string, args?: unknown[]): MaybePromise<{ changes: number }>; + /** Statements that commit or roll back together. */ + tx(ops: PluginTxOp[]): MaybePromise; + /** Runs `sql` once per `id`; a second call with the same id is a no-op. */ + migrate(id: string, sql: string): MaybePromise<{ applied: boolean }>; + /** False once `close` ran: the host then opens a new store instead of reusing this one. */ + isOpen(): boolean; + close(): void; +} + +type MaybePromise = T | Promise; + +/** One statement of a `tx` batch. */ +export interface PluginTxOp { + sql: string; + args?: unknown[]; +} + +/** A `tx` batch's results, one per op: the rows of a statement that returns rows, the change count of any other. */ +export interface PluginTxResult { + results: Array<{ changes?: number; rows?: unknown[] }>; +} + +/** + * The limits every plugin database is held to, whatever the engine. The + * plugin-sdk README's "Runtime limits" table documents them. + */ +export const PLUGIN_DATA_CAPS = { + /** The longest SQL text one call may carry. */ + maxSqlLength: 100_000, + /** The most rows a query, or a whole tx batch, returns. */ + maxRows: 100_000, + /** The most statements one tx batch holds. */ + maxTxOps: 100, + /** Wall-clock time for one query, one tx batch or one exec script. */ + timeBudgetMs: 2_000, + /** The most a plugin's data may take on disk. */ + quotaBytes: 256 * 1024 * 1024, +} as const; diff --git a/server/src/db/engine/postgres/plugin-data-store.ts b/server/src/db/engine/postgres/plugin-data-store.ts new file mode 100644 index 000000000..307ca9e64 --- /dev/null +++ b/server/src/db/engine/postgres/plugin-data-store.ts @@ -0,0 +1,378 @@ +import { PLUGIN_DATA_CAPS, type PluginDataStore, type PluginTxOp, type PluginTxResult } from '../plugin-data'; +import { isPluginId, pluginSchemaName, quotePluginSchema } from './plugin-schema'; +import { checkPlaceholders, checkQualifiers, parsePluginSql, type PluginStatement } from './plugin-sql-guard'; + +import { CompiledQuery, type Kysely, type Transaction } from 'kysely'; + +/** + * A plugin's own data on Postgres (`db:own`): a schema of its own in TREK's + * database (`plugin-schema.ts`), reached through TREK's pool. + * + * Every call runs in one transaction that first makes sure the schema and its + * migration table exist, then puts only that schema on the `search_path` and + * sets `statement_timeout` to the call's time budget. The plugin's SQL is + * checked by `plugin-sql-guard.ts` before it runs, so it cannot name another + * schema. Reads stream through a cursor and stop at the row cap. A call that + * may write measures the schema's size before and after, and rolls back one + * that leaves it past the quota and larger than it found it, so a plugin at + * its quota can still delete. + * + * The calls of one plugin run one at a time, as they do on its SQLite file, + * and all plugins together hold at most half of TREK's pool + * (`pluginDataSlots`), so a busy plugin never takes the connections TREK's + * own requests need. + * + * The SQLite store's semantics carry over: `query` and `tx` are held to the + * row cap, `query`, a `tx` batch and an `exec` script to the time budget, a + * script's statements each commit on their own, and `migrate` runs once per + * id with no time budget. What Postgres adds is that the budget also stops a + * single statement (`statement_timeout`), which SQLite cannot, and that an + * `exec` with bound args is held to it as well. + */ + +/** The limits one store enforces. Overridable for tests; production uses `PLUGIN_DATA_CAPS`. */ +interface PostgresPluginDataLimits { + maxRows: number; + timeBudgetMs: number; + quotaBytes: number; + /** The clock the time budget reads. */ + now: () => number; +} + +const DEFAULT_LIMITS: PostgresPluginDataLimits = { + maxRows: PLUGIN_DATA_CAPS.maxRows, + timeBudgetMs: PLUGIN_DATA_CAPS.timeBudgetMs, + quotaBytes: PLUGIN_DATA_CAPS.quotaBytes, + now: () => Date.now(), +}; + +/** Postgres's SQLSTATE for a statement cancelled by `statement_timeout`. */ +const QUERY_CANCELED = '57014'; +/** Rows a cursor fetches at once. */ +const CHUNK_ROWS = 500; +/** What better-sqlite3 says about a closed handle, which the host recognizes. */ +const CLOSED = 'The database connection is not open'; + +/** How many plugin transactions may hold a pool connection at once: half of TREK's pool, at least one. */ +export function pluginDataSlots(poolMax: number): number { + return Math.max(1, Math.floor(poolMax / 2)); +} + +/** A counting semaphore: at most `size` pieces of work at once, the rest wait in order. */ +export class PluginDataSlots { + private active = 0; + private readonly waiting: Array<() => void> = []; + + constructor(readonly size: number) {} + + async run(work: () => Promise): Promise { + if (this.active < this.size) this.active++; + else await new Promise((resolve) => this.waiting.push(resolve)); + try { + return await work(); + } finally { + // A waiting call takes the slot over, so the count stays where it is. + const next = this.waiting.shift(); + if (next) next(); + else this.active--; + } + } +} + +type Trx = Transaction; + +/** The rows one call has returned so far, against the cap they share. */ +interface RowBudget { + count: number; + readonly max: number; + readonly message: string; +} + +/** Drops the plugin `id`'s schema and everything in it. An id no schema can be made from has none. */ +export async function dropPluginSchema(db: Kysely, id: string): Promise { + if (!isPluginId(id)) return; + const schema = quotePluginSchema(pluginSchemaName(id)); + await db.executeQuery(CompiledQuery.raw(`drop schema if exists ${schema} cascade`)); +} + +export class PostgresPluginDataStore implements PluginDataStore { + readonly engine = 'postgres' as const; + private readonly schema: string; + private readonly quoted: string; + private readonly limits: PostgresPluginDataLimits; + private open = true; + private queue: Promise = Promise.resolve(); + + constructor( + readonly pluginId: string, + private readonly db: Kysely, + private readonly slots: PluginDataSlots, + limits: Partial = {}, + ) { + this.schema = pluginSchemaName(pluginId); + this.quoted = quotePluginSchema(this.schema); + this.limits = { ...DEFAULT_LIMITS, ...limits }; + } + + isOpen(): boolean { + return this.open; + } + + /** Stops new calls. One already running finishes: it holds a pool connection of its own, not this store. */ + close(): void { + this.open = false; + } + + async query(sql: string, args: unknown[] = []): Promise { + const statement = this.single(sql, args); + const { maxRows } = this.limits; + return this.call('query', (budget) => + this.transaction(budget.ms, [statement], (trx) => { + const rows = { count: 0, max: maxRows, message: `query returned more than ${maxRows} rows` }; + return this.stream(trx, statement, args, rows, budget.check); + }), + ); + } + + async exec(sql: string, args: unknown[] = []): Promise<{ changes: number }> { + if (args.length > 0) { + const statement = this.single(sql, args); + return this.call('exec', (budget) => + this.transaction(budget.ms, [statement], async (trx) => ({ changes: await this.run(trx, statement, args) })), + ); + } + const statements = this.parse(sql); + return this.call('exec', async (budget) => { + // A script runs as SQLite runs one: each statement commits on its own, and + // the clock is read before every statement but the first. + await inOrder(statements, (statement, index) => { + if (index > 0) budget.check(); + return this.transaction(budget.remaining(), [statement], (trx) => this.run(trx, statement, [])); + }); + return { changes: 0 }; + }); + } + + async tx(ops: PluginTxOp[]): Promise { + if (!Array.isArray(ops)) throw new Error('tx requires an array of { sql, args }'); + if (ops.length === 0) return { results: [] }; + if (ops.length > PLUGIN_DATA_CAPS.maxTxOps) { + throw new Error(`tx allows at most ${PLUGIN_DATA_CAPS.maxTxOps} statements`); + } + const statements = ops.map((op) => this.single(op?.sql, op?.args ?? [])); + const { maxRows } = this.limits; + return this.call('tx', (budget) => + this.transaction(budget.ms, statements, async (trx) => { + const rows = { count: 0, max: maxRows, message: `tx returned more than ${maxRows} rows in total` }; + const results = await inOrder(statements, async (statement, index) => { + const args = ops[index].args ?? []; + // One budget for the whole batch: each statement after the first gets what is left of it. + if (index > 0) await this.setTimeout(trx, budget.remaining()); + const result = statement.returnsRows + ? { rows: await this.stream(trx, statement, args, rows, budget.check) } + : { changes: await this.run(trx, statement, args) }; + budget.check(); + return result; + }); + return { results }; + }), + ); + } + + /** No time budget, as on SQLite: a migration stopped part of the way would fail the same way on every start. */ + async migrate(id: string, sql: string): Promise<{ applied: boolean }> { + const statements = this.parse(sql); + return this.enqueue(() => + this.transaction(null, statements, async (trx) => { + const seen = await trx.executeQuery( + CompiledQuery.raw(`select 1 from ${this.quoted}._plugin_migrations where id = $1`, [id]), + ); + if (seen.rows.length > 0) return { applied: false }; + await inOrder(statements, (statement) => this.run(trx, statement, [])); + await trx.executeQuery( + CompiledQuery.raw(`insert into ${this.quoted}._plugin_migrations (id, applied_at) values ($1, $2)`, [ + id, + Date.now(), + ]), + ); + return { applied: true }; + }), + ); + } + + /** `sql` as exactly one statement, checked against `args`. */ + private single(sql: unknown, args: readonly unknown[]): PluginStatement { + const statements = this.parse(sql); + if (statements.length !== 1) throw new Error('sql must hold exactly one statement here; use exec() for a script'); + checkPlaceholders(statements[0], args); + return statements[0]; + } + + /** The statements of `sql`, refused when the guard does not allow one or none is there. */ + private parse(sql: unknown): PluginStatement[] { + if (!this.open) throw new Error(CLOSED); + if (typeof sql !== 'string') throw new Error('sql must be a string'); + if (sql.length > PLUGIN_DATA_CAPS.maxSqlLength) throw new Error('sql too long'); + const statements = parsePluginSql(sql); + if (statements.length === 0) throw new Error('The supplied SQL string contains no statements'); + return statements; + } + + /** + * Runs `work` in this plugin's turn with a time budget that starts when its + * turn comes, and reports a statement Postgres cancelled at + * `statement_timeout` as the budget running out. + */ + private call(what: string, work: (budget: Budget) => Promise): Promise { + const { now, timeBudgetMs } = this.limits; + return this.enqueue(async () => { + const startedAt = now(); + const budget: Budget = { + ms: timeBudgetMs, + remaining: () => Math.max(1, timeBudgetMs - (now() - startedAt)), + check: () => { + if (now() - startedAt > timeBudgetMs) throw new Error(`${what} exceeded its ${timeBudgetMs} ms time budget`); + }, + }; + try { + return await work(budget); + } catch (err) { + if (sqlState(err) === QUERY_CANCELED) { + throw new Error(`${what} exceeded its ${timeBudgetMs} ms time budget`, { cause: err }); + } + throw err; + } + }); + } + + /** Queues `work` behind this plugin's earlier calls, then waits for a pool slot. */ + private enqueue(work: () => Promise): Promise { + const turn = this.queue.then(() => this.slots.run(work)); + this.queue = turn.catch(() => undefined); + return turn; + } + + /** + * One transaction on this plugin's schema: created if missing, alone on the + * `search_path`, with `statement_timeout` at `timeoutMs` (none for null). + * The statements' qualified names are checked against the database's + * schemas first, and a call that may write is held to the quota. + */ + private transaction( + timeoutMs: number | null, + statements: readonly PluginStatement[], + work: (trx: Trx) => Promise, + ): Promise { + return this.db.transaction().execute(async (trx) => { + const setup = [ + `create schema if not exists ${this.quoted}`, + `create table if not exists ${this.quoted}._plugin_migrations (id text primary key, applied_at bigint)`, + `set local search_path to ${this.quoted}`, + 'set local standard_conforming_strings to on', + ]; + if (timeoutMs !== null) setup.push(`set local statement_timeout to ${Math.max(1, Math.floor(timeoutMs))}`); + await trx.executeQuery(CompiledQuery.raw(setup.join(';\n'))); + if (statements.some((s) => s.qualifies)) { + const schemas = await this.schemaNames(trx); + for (const statement of statements) checkQualifiers(statement, this.schema, schemas); + } + const writes = statements.some((s) => s.mayWrite); + const before = writes ? await this.sizeBytes(trx) : 0; + const result = await work(trx); + if (writes) { + const after = await this.sizeBytes(trx); + if (after > this.limits.quotaBytes && after > before) { + throw new Error(`the plugin database is past its ${this.limits.quotaBytes / 1024 / 1024} MB quota`); + } + } + return result; + }); + } + + private async setTimeout(trx: Trx, ms: number): Promise { + await trx.executeQuery( + CompiledQuery.raw("select set_config('statement_timeout', $1, true)", [String(Math.max(1, Math.floor(ms)))]), + ); + } + + /** Every schema name of the database, which a qualified name in plugin SQL may not use. */ + private async schemaNames(trx: Trx): Promise> { + const result = await trx.executeQuery<{ nspname: string }>(CompiledQuery.raw('select nspname from pg_namespace')); + return new Set(result.rows.map((row) => row.nspname)); + } + + /** What this plugin's tables, indexes and materialized views take on disk. */ + private async sizeBytes(trx: Trx): Promise { + const result = await trx.executeQuery<{ bytes: number | string }>( + CompiledQuery.raw( + 'select coalesce(sum(pg_total_relation_size(c.oid)), 0) as bytes from pg_class c ' + + "join pg_namespace n on n.oid = c.relnamespace where n.nspname = $1 and c.relkind in ('r', 'm')", + [this.schema], + ), + ); + return Number(result.rows[0]?.bytes ?? 0); + } + + /** Runs a statement for its effect: the rows it changed, or 0 for a read, whose rows are streamed past and dropped. */ + private async run(trx: Trx, statement: PluginStatement, args: readonly unknown[]): Promise { + if (!statement.mayWrite) { + const chunks = trx.getExecutor().stream(CompiledQuery.raw(statement.text, [...args]), CHUNK_ROWS); + for await (const _chunk of chunks) { + // Read to the end so the statement runs whole; its rows are not wanted. + } + return 0; + } + const result = await trx.executeQuery(CompiledQuery.raw(statement.text, [...args])); + return Number(result.numAffectedRows ?? 0); + } + + /** + * The rows of a statement, read through a cursor a chunk at a time: past the + * row cap the read stops and throws, and the clock is read between chunks. + */ + private async stream( + trx: Trx, + statement: PluginStatement, + args: readonly unknown[], + budget: RowBudget, + checkTime: () => void, + ): Promise { + const rows: unknown[] = []; + const chunks = trx.getExecutor().stream(CompiledQuery.raw(statement.text, [...args]), CHUNK_ROWS); + for await (const chunk of chunks) { + if (rows.length > 0) checkTime(); + for (const row of chunk.rows) { + rows.push(row); + budget.count++; + if (budget.count > budget.max) throw new Error(budget.message); + } + } + return rows; + } +} + +/** `work` for each item, one after the other, each started once the one before it has finished. */ +async function inOrder(items: readonly T[], work: (item: T, index: number) => Promise): Promise { + const results: R[] = []; + await items.reduce>( + (previous, item, index) => + previous.then(async () => { + results.push(await work(item, index)); + }), + Promise.resolve(), + ); + return results; +} + +/** A call's time budget: its whole length, what is left of it, and a check that throws once it is spent. */ +interface Budget { + readonly ms: number; + remaining(): number; + check(): void; +} + +/** The SQLSTATE of a `pg` error, or null. */ +function sqlState(err: unknown): string | null { + if (typeof err !== 'object' || err === null || !('code' in err)) return null; + return typeof err.code === 'string' ? err.code : null; +} diff --git a/server/src/db/engine/postgres/plugin-schema.ts b/server/src/db/engine/postgres/plugin-schema.ts new file mode 100644 index 000000000..68946f8e8 --- /dev/null +++ b/server/src/db/engine/postgres/plugin-schema.ts @@ -0,0 +1,51 @@ +/** + * The schema a plugin's own data lives in on Postgres (`db:own`): one per + * plugin, named from its id, beside TREK's schema in the same database. + * + * A plugin id is what the manifest allows (`PLUGIN_ID_RE` in + * `nest/plugins/protocol/manifest-rules.ts`): a lowercase letter, then 2 to 39 + * lowercase letters, digits or dashes. The schema name is the prefix plus the + * id with each dash spelled as an underscore. An id never holds an underscore, + * so two ids never share a name, and the longest name (52 characters) stays + * under Postgres's 63. The pattern is repeated here rather than imported, + * because `src/db` does not import `src/nest`; a unit test holds the two equal. + * + * Every name TREK gives a plugin schema starts with the prefix, so a backup, + * a restore and the plugin SQL guard can tell them from every other schema of + * the database. Two TREK instances on one database would share these names, + * so each instance needs a database of its own (the wiki says so). + */ + +/** What every plugin schema's name starts with. */ +export const PLUGIN_SCHEMA_PREFIX = 'trek_plugin_'; + +/** The plugin ids a schema name can be made from: the manifest's rule. */ +const PLUGIN_ID = /^[a-z][a-z0-9-]{2,39}$/; + +/** A plugin schema's name, as `pluginSchemaName` makes it. */ +const PLUGIN_SCHEMA = /^trek_plugin_[a-z][a-z0-9_]{2,39}$/; + +/** Whether `id` is a plugin id a schema name can be made from. */ +export function isPluginId(id: string): boolean { + return PLUGIN_ID.test(id); +} + +/** The schema of the plugin `id`. Throws for anything the manifest would not accept as an id. */ +export function pluginSchemaName(id: string): string { + if (!isPluginId(id)) throw new Error(`"${id}" is not a plugin id, so it has no data schema.`); + return PLUGIN_SCHEMA_PREFIX + id.replaceAll('-', '_'); +} + +/** Whether `name` is a schema name `pluginSchemaName` makes. */ +export function isPluginSchemaName(name: string): boolean { + return PLUGIN_SCHEMA.test(name); +} + +/** + * `name` as a quoted SQL identifier. Only plugin schema names reach it, which + * hold no quote, so the quoting cannot be escaped; it is checked all the same. + */ +export function quotePluginSchema(name: string): string { + if (!isPluginSchemaName(name)) throw new Error(`"${name}" is not a plugin schema name.`); + return `"${name}"`; +} diff --git a/server/src/db/engine/postgres/plugin-sql-guard.ts b/server/src/db/engine/postgres/plugin-sql-guard.ts new file mode 100644 index 000000000..3077f368a --- /dev/null +++ b/server/src/db/engine/postgres/plugin-sql-guard.ts @@ -0,0 +1,400 @@ +import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema'; + +/** + * What keeps a plugin's own SQL on Postgres inside its own schema. + * + * On SQLite a plugin's database is a file of its own, so it cannot name + * TREK's tables at all. On Postgres its schema sits in TREK's database and + * its statements run as TREK's role, which may read every table TREK has: a + * role per plugin would need CREATEROLE, which TREK's role is not given. So + * the statement itself is held to what cannot leave the schema, before it + * runs, and the transaction it runs in names only that schema on its + * `search_path`, so an unqualified name finds nothing else. + * + * The SQL is split into tokens the way Postgres's own lexer splits it (string + * and identifier quoting, comments, dollar signs), and refused when it holds: + * + * - a statement other than SELECT, INSERT, UPDATE, DELETE, MERGE, WITH, + * VALUES, TABLE, TRUNCATE, REFRESH, or a CREATE, ALTER or DROP of a table, + * index, view, materialized view, sequence or type. No function, schema, + * role, setting, transaction control, COPY, LOCK, prepared statement or + * notification. Several statements are split at their semicolons and each + * is checked; + * - a qualified name whose qualifier is another schema of the database + * (`public.users`, another plugin's schema), or any name starting with + * `pg_` or naming `information_schema`: the catalogs, the server functions + * and the temporary schema; + * - a function that runs SQL handed to it as text (`query_to_xml`, `ts_stat`, + * `ts_rewrite`), reads or changes settings (`set_config`, + * `current_setting`), reaches objects by a name in a string (`nextval`, + * `setval`, the `reg*` casts), large objects (`lo_*`) or `dblink`; + * - a temporary table (`CREATE TEMP`, `SELECT ... INTO`), which would outlive + * the call on a pooled connection another plugin uses next, and + * `WITH RECURSIVE`, refused on SQLite too; + * - in an ALTER, a change of a table's schema, owner or tablespace; + * - escape strings (`E'...'`), Unicode escapes (`U&'...'`), dollar-quoted + * strings and a number running straight into a name, whose reading + * differs between Postgres versions and settings. + * + * An alias that happens to share a schema's name (`auth.id` on a database + * that has an `auth` schema) is refused too; the plugin renames the alias. + */ + +/** Why a plugin's SQL is refused. The message is the plugin's to read, so it says what to change. */ +export class PluginSqlRefused extends Error { + constructor(reason: string) { + super(`statement type not allowed for plugin databases: ${reason}`); + this.name = 'PluginSqlRefused'; + } +} + +/** One token of plugin SQL. A word is a name or a keyword: `value` is folded to lower case unless it was quoted. */ +type Token = ( + | { kind: 'word'; value: string; quoted: boolean } + | { kind: 'string' } + | { kind: 'number' } + | { kind: 'param' } + | { kind: 'punct'; value: string } +) & { + /** Where the token starts in the SQL text. */ + at: number; +}; + +/** One statement of plugin SQL: its tokens, without the semicolon that ended it. */ +export interface PluginStatement { + /** The statement's own text, as Postgres is handed it. */ + readonly text: string; + readonly tokens: readonly Token[]; + /** Whether it returns rows: a SELECT, VALUES or TABLE, or anything with a RETURNING clause. */ + readonly returnsRows: boolean; + /** Whether it may change data or schema, which is what the disk quota is checked after. */ + readonly mayWrite: boolean; + /** Whether it names a qualified object (`x.y`), which needs the database's schema names to check. */ + readonly qualifies: boolean; + /** How many `$n` placeholders it holds. */ + readonly params: number; +} + +/** Postgres keeps the first 63 bytes of a name (NAMEDATALEN - 1) and drops the rest. */ +const MAX_NAME_BYTES = 63; + +/** The first word of each statement a plugin may run. */ +const STATEMENTS = new Set([ + 'select', + 'insert', + 'update', + 'delete', + 'merge', + 'with', + 'values', + 'table', + 'truncate', + 'refresh', + 'create', + 'alter', + 'drop', +]); + +/** Transaction control: every call already runs in a transaction of the host's. */ +const TRANSACTION_CONTROL = new Set(['begin', 'start', 'commit', 'end', 'rollback', 'abort', 'savepoint', 'release']); + +/** What a CREATE, ALTER or DROP may act on. */ +const OBJECTS = new Set(['table', 'index', 'view', 'materialized', 'sequence', 'type']); + +/** The words that make up a statement's main verb, after a WITH clause. */ +const VERBS = new Set(['select', 'insert', 'update', 'delete', 'merge', 'values', 'table']); + +/** The verbs of a statement that only reads. */ +const READ_VERBS = new Set(['select', 'values', 'table']); + +/** Functions and types refused under any spelling, quoted or not. */ +const REFUSED_NAMES = new Set([ + 'set_config', + 'current_setting', + 'ts_stat', + 'ts_rewrite', + 'nextval', + 'setval', + 'currval', + 'lastval', + 'loread', + 'lowrite', + 'regclass', + 'regproc', + 'regprocedure', + 'regoper', + 'regoperator', + 'regnamespace', + 'regrole', + 'regcollation', + 'information_schema', +]); + +/** Name prefixes refused under any spelling. */ +const REFUSED_PREFIXES = ['pg_', 'lo_', 'dblink', 'to_reg', 'binary_upgrade_']; + +/** A name refused wherever it appears: the XML exports of a query, a table, a schema or the database. */ +const XML_EXPORT = /_to_xml/; + +/** Starts a name: a letter, an underscore or any character past ASCII, as Postgres reads it. */ +const NAME_START = /[A-Za-z_\u0080-￿]/; +/** Continues a name; a dollar sign is part of one. */ +const NAME_PART = /[A-Za-z0-9_$\u0080-￿]/; +/** The single-character punctuation and operator characters. */ +const PUNCT = new Set([...'.,()[];+-*/<>=~!@#%^&|?']); + +/** `name` lower-cased the way Postgres folds an unquoted name: ASCII letters only. */ +function fold(name: string): string { + return name.replace(/[A-Z]/g, (c) => c.toLowerCase()); +} + +/** `name` cut to the bytes Postgres keeps of it, never in the middle of a character. */ +function truncateName(name: string): string { + if (Buffer.byteLength(name, 'utf8') <= MAX_NAME_BYTES) return name; + let out = ''; + for (const ch of name) { + if (Buffer.byteLength(out + ch, 'utf8') > MAX_NAME_BYTES) break; + out += ch; + } + return out; +} + +/** Splits `sql` into tokens, or refuses what this guard does not read the way Postgres would. */ +export function tokenize(sql: string): Token[] { + const tokens: Token[] = []; + let i = 0; + const n = sql.length; + while (i < n) { + const at = i; + const c = sql[i]; + const next = sql[i + 1]; + if (/\s/.test(c)) { + i++; + } else if (c === '-' && next === '-') { + while (i < n && sql[i] !== '\n') i++; + } else if (c === '/' && next === '*') { + i = skipBlockComment(sql, i); + } else if (c === "'") { + i = skipQuoted(sql, i, "'", 'a string'); + tokens.push({ kind: 'string', at }); + } else if (c === '"') { + const end = skipQuoted(sql, i, '"', 'a quoted name'); + const value = sql.slice(i + 1, end - 1).replaceAll('""', '"'); + if (value === '') throw new PluginSqlRefused('a quoted name may not be empty'); + tokens.push({ kind: 'word', value: truncateName(value), quoted: true, at }); + i = end; + } else if (c === '$') { + if (!/[0-9]/.test(next ?? '')) { + throw new PluginSqlRefused('dollar-quoted strings are not accepted; write the string in single quotes'); + } + i++; + while (i < n && /[0-9]/.test(sql[i])) i++; + tokens.push({ kind: 'param', at }); + } else if (/[0-9]/.test(c) || (c === '.' && /[0-9]/.test(next ?? ''))) { + i = skipNumber(sql, i); + if (i < n && NAME_PART.test(sql[i])) { + throw new PluginSqlRefused('a number may not run straight into a name; put a space between them'); + } + tokens.push({ kind: 'number', at }); + } else if (NAME_START.test(c)) { + if ((c === 'e' || c === 'E') && next === "'") { + throw new PluginSqlRefused("escape strings (E'...') are not accepted; write the string in single quotes"); + } + if ((c === 'u' || c === 'U') && next === '&' && (sql[i + 2] === "'" || sql[i + 2] === '"')) { + throw new PluginSqlRefused('Unicode escapes (U&) are not accepted'); + } + while (i < n && NAME_PART.test(sql[i])) i++; + tokens.push({ kind: 'word', value: truncateName(fold(sql.slice(at, i))), quoted: false, at }); + } else if (c === ':' && next === ':') { + tokens.push({ kind: 'punct', value: '::', at }); + i += 2; + } else if (c === ':' || PUNCT.has(c)) { + tokens.push({ kind: 'punct', value: c, at }); + i++; + } else { + throw new PluginSqlRefused(`unexpected character ${JSON.stringify(c)}`); + } + } + return tokens; +} + +/** The index past a block comment starting at `start`; Postgres nests them. */ +function skipBlockComment(sql: string, start: number): number { + let depth = 0; + let i = start; + while (i < sql.length) { + if (sql[i] === '/' && sql[i + 1] === '*') { + depth++; + i += 2; + } else if (sql[i] === '*' && sql[i + 1] === '/') { + depth--; + i += 2; + if (depth === 0) return i; + } else { + i++; + } + } + throw new PluginSqlRefused('a comment is not closed'); +} + +/** The index past a quoted string or name starting at `start`; a doubled quote stands for one. */ +function skipQuoted(sql: string, start: number, quote: string, what: string): number { + let i = start + 1; + while (i < sql.length) { + if (sql[i] === quote) { + if (sql[i + 1] === quote) { + i += 2; + continue; + } + return i + 1; + } + i++; + } + throw new PluginSqlRefused(`${what} is not closed`); +} + +/** The index past a numeric constant starting at `start`: decimal, with a fraction and an exponent, or 0x/0o/0b. */ +function skipNumber(sql: string, start: number): number { + const rest = sql.slice(start); + const match = + /^0[xX][0-9a-fA-F_]+|^0[oO][0-7_]+|^0[bB][01_]+|^(?:[0-9][0-9_]*(?:\.[0-9_]*)?|\.[0-9][0-9_]*)(?:[eE][+-]?[0-9]+)?/.exec( + rest, + ); + return start + (match ? match[0].length : 1); +} + +/** Splits `sql` into its statements, each checked on its own; empty ones (`;;`, a comment) are dropped. */ +export function parsePluginSql(sql: string): PluginStatement[] { + const statements: PluginStatement[] = []; + let current: Token[] = []; + const flush = (end: number) => { + if (current.length > 0) statements.push(describe(sql.slice(current[0].at, end).trimEnd(), current)); + current = []; + }; + for (const token of tokenize(sql)) { + if (token.kind === 'punct' && token.value === ';') flush(token.at); + else current.push(token); + } + flush(sql.length); + return statements; +} + +/** The unquoted keyword at `token`, or null for anything else. */ +function keyword(token: Token | undefined): string | null { + return token?.kind === 'word' && !token.quoted ? token.value : null; +} + +/** Reads what a statement's caller needs to know about it, and refuses one this guard does not allow. */ +function describe(text: string, tokens: Token[]): PluginStatement { + const first = tokens[0]; + const opensWithParen = first.kind === 'punct' && first.value === '('; + const verb = opensWithParen ? 'select' : keyword(first); + if (verb !== null && TRANSACTION_CONTROL.has(verb)) { + throw new PluginSqlRefused( + 'transaction-control statements are not allowed: each call runs in its own transaction, and tx() makes a batch atomic', + ); + } + if (verb === null || !STATEMENTS.has(verb)) { + throw new PluginSqlRefused(`a statement may not start with ${describeToken(first)}`); + } + if (verb === 'create' || verb === 'alter' || verb === 'drop' || verb === 'refresh') checkObject(verb, tokens); + + let depth = 0; + let main: string | null = verb === 'with' ? null : verb; + let returning = false; + let selectInto = false; + let params = 0; + let qualifies = false; + for (const [index, token] of tokens.entries()) { + if (token.kind === 'param') params++; + if (token.kind === 'punct' && token.value === '(') depth++; + if (token.kind === 'punct' && token.value === ')') depth--; + if (token.kind !== 'word') continue; + checkName(token.value); + const after = tokens[index + 1]; + if (after?.kind === 'punct' && after.value === '.') qualifies = true; + if (token.quoted) continue; + if (token.value === 'recursive') throw new PluginSqlRefused('WITH RECURSIVE is not allowed'); + if (token.value === 'tablespace') throw new PluginSqlRefused('a tablespace may not be named'); + if (verb === 'alter' && (token.value === 'schema' || token.value === 'owner')) { + throw new PluginSqlRefused(`an ALTER may not change the ${token.value}`); + } + if (depth !== 0) continue; + if (main === null && VERBS.has(token.value)) main = token.value; + if (token.value === 'returning') returning = true; + if (token.value === 'into' && main === 'select') selectInto = true; + } + if (selectInto) throw new PluginSqlRefused('SELECT ... INTO is not allowed; use CREATE TABLE ... AS'); + + const reads = main !== null && READ_VERBS.has(main); + const writesInside = tokens.some((t) => { + const word = keyword(t); + return word !== null && ['insert', 'update', 'delete', 'merge'].includes(word); + }); + return { + text, + tokens, + returnsRows: reads || returning, + mayWrite: !reads || writesInside, + qualifies, + params, + }; +} + +/** Refuses a CREATE, ALTER, DROP or REFRESH of anything but the objects a plugin keeps in its schema. */ +function checkObject(verb: string, tokens: readonly Token[]): void { + let at = 1; + if (verb === 'create') { + if (keyword(tokens[at]) === 'or' && keyword(tokens[at + 1]) === 'replace') at += 2; + while (keyword(tokens[at]) === 'unique' || keyword(tokens[at]) === 'unlogged') at++; + } + const object = keyword(tokens[at]); + const allowed = verb === 'refresh' ? object === 'materialized' : object !== null && OBJECTS.has(object); + if (!allowed) { + throw new PluginSqlRefused(`${verb.toUpperCase()} ${describeToken(tokens[at])} is not allowed`); + } +} + +/** Refuses a name that reaches past the plugin's schema whatever qualifies it. */ +function checkName(name: string): void { + if (REFUSED_NAMES.has(name) || REFUSED_PREFIXES.some((p) => name.startsWith(p)) || XML_EXPORT.test(name)) { + throw new PluginSqlRefused(`"${name}" may not be named in a plugin's SQL`); + } +} + +/** A token as an error message shows it. */ +function describeToken(token: Token | undefined): string { + if (token === undefined) return 'nothing'; + if (token.kind === 'word') return token.quoted ? `"${token.value}"` : token.value.toUpperCase(); + if (token.kind === 'punct') return `"${token.value}"`; + return `a ${token.kind}`; +} + +/** + * Refuses a qualified name in `statement` whose qualifier is a schema other + * than `ownSchema`: one of `schemas` (every schema of the database), or one + * named like a plugin schema even before it exists. + */ +export function checkQualifiers(statement: PluginStatement, ownSchema: string, schemas: ReadonlySet): void { + const { tokens } = statement; + for (const [index, token] of tokens.entries()) { + const after = tokens[index + 1]; + if (token.kind !== 'word' || after?.kind !== 'punct' || after.value !== '.') continue; + if (token.value === ownSchema) continue; + if (schemas.has(token.value) || token.value.startsWith(PLUGIN_SCHEMA_PREFIX) || token.value === 'public') { + throw new PluginSqlRefused(`"${token.value}" is another schema; a plugin reaches its own tables only`); + } + } +} + +/** + * Refuses `?` placeholders where bound args were given: Postgres numbers its + * placeholders `$1`, `$2`, ..., and reads a `?` as an operator. + */ +export function checkPlaceholders(statement: PluginStatement, args: readonly unknown[]): void { + if (args.length === 0 || statement.params > 0) return; + const questionMark = statement.tokens.some((t) => t.kind === 'punct' && t.value === '?'); + if (questionMark) { + throw new PluginSqlRefused('this TREK runs on Postgres, which numbers its placeholders $1, $2, ... instead of ?'); + } +} diff --git a/server/tests/unit/db/engine/postgres/plugin-schema.test.ts b/server/tests/unit/db/engine/postgres/plugin-schema.test.ts new file mode 100644 index 000000000..fbb494ce5 --- /dev/null +++ b/server/tests/unit/db/engine/postgres/plugin-schema.test.ts @@ -0,0 +1,92 @@ +/** + * The schema a plugin's own data lives in on Postgres + * (src/db/engine/postgres/plugin-schema.ts), the restore's statements for the + * plugin schemas (clear-schema.ts) and the pool slots the plugin stores share + * (plugin-data-store.ts), without a database. + */ +import { pluginSchemasSql } from '../../../../../src/db/engine/postgres/clear-schema'; +import { PluginDataSlots, pluginDataSlots } from '../../../../../src/db/engine/postgres/plugin-data-store'; +import { + isPluginId, + isPluginSchemaName, + PLUGIN_SCHEMA_PREFIX, + pluginSchemaName, + quotePluginSchema, +} from '../../../../../src/db/engine/postgres/plugin-schema'; +import { PLUGIN_ID_RE } from '../../../../../src/nest/plugins/protocol/manifest-rules'; + +import { describe, expect, it } from 'vitest'; + +describe('plugin schema names', () => { + it('PGSCHEMA-001: a name is the prefix plus the id, each dash an underscore', () => { + expect(pluginSchemaName('notes')).toBe('trek_plugin_notes'); + expect(pluginSchemaName('trip-weather-2')).toBe('trek_plugin_trip_weather_2'); + expect(quotePluginSchema(pluginSchemaName('trip-weather-2'))).toBe('"trek_plugin_trip_weather_2"'); + }); + + it('PGSCHEMA-002: accepts exactly the ids the manifest accepts', () => { + const samples = ['abc', 'a-b', 'a--b', 'z9', 'notes', 'Notes', '9abc', '-abc', 'a_b', 'a.b', '', 'a'.repeat(40)]; + samples.push('a'.repeat(41), '../x', 'abc ', 'ab"c', 'abc;drop'); + for (const id of samples) expect(isPluginId(id), id).toBe(PLUGIN_ID_RE.test(id)); + expect(String(PLUGIN_ID_RE)).toBe('/^[a-z][a-z0-9-]{2,39}$/'); + }); + + it('PGSCHEMA-003: refuses anything that is not an id, before any SQL is written', () => { + for (const id of ['Notes', '../x', 'a"b', 'ab', 'a b', 'a'.repeat(41)]) { + expect(() => pluginSchemaName(id), id).toThrow(/is not a plugin id/); + } + expect(() => quotePluginSchema('public')).toThrow(/is not a plugin schema name/); + expect(() => quotePluginSchema('trek_plugin_x"; drop')).toThrow(/is not a plugin schema name/); + }); + + it('PGSCHEMA-004: two ids never share a name, and every name fits in a Postgres identifier', () => { + expect(pluginSchemaName('a-b-c')).not.toBe(pluginSchemaName('a--bc')); + const longest = pluginSchemaName(`a${'-'.repeat(39)}`); + expect(longest.length).toBeLessThanOrEqual(63); + expect(isPluginSchemaName(longest)).toBe(true); + expect(isPluginSchemaName('trek_plugin_ab')).toBe(false); + expect(isPluginSchemaName('public')).toBe(false); + expect(isPluginSchemaName(`${PLUGIN_SCHEMA_PREFIX}Notes`)).toBe(false); + }); + + it("PGSCHEMA-005: a restore drops only the role's own plugin schemas, then creates the dump's", () => { + const sql = pluginSchemasSql(['trek_plugin_a', 'trek_plugin_b']); + expect(sql).toContain("starts_with(nspname, 'trek_plugin_')"); + expect(sql).toContain('pg_get_userbyid(nspowner) = current_user'); + expect(sql).toContain("EXECUTE format('DROP SCHEMA %I CASCADE', r.nspname);"); + expect(sql.endsWith('CREATE SCHEMA "trek_plugin_a";\nCREATE SCHEMA "trek_plugin_b";\n')).toBe(true); + expect(pluginSchemasSql([])).not.toContain('CREATE SCHEMA'); + expect(() => pluginSchemasSql(['auth'])).toThrow(/is not a plugin schema name/); + }); +}); + +describe('plugin data pool slots', () => { + it('PGSCHEMA-006: plugins hold at most half of the pool, at least one connection', () => { + expect(pluginDataSlots(10)).toBe(5); + expect(pluginDataSlots(3)).toBe(1); + expect(pluginDataSlots(1)).toBe(1); + }); + + it('PGSCHEMA-007: no more than `size` pieces of work run at once, and the rest run in order', async () => { + const slots = new PluginDataSlots(2); + let running = 0; + let most = 0; + const order: number[] = []; + const work = (n: number) => + slots.run(async () => { + running++; + most = Math.max(most, running); + await new Promise((resolve) => setTimeout(resolve, 5)); + order.push(n); + running--; + if (n === 2) throw new Error('fails'); + return n; + }); + const results = await Promise.allSettled([1, 2, 3, 4, 5].map(work)); + expect(most).toBe(2); + expect(order.slice(2)).toEqual([3, 4, 5]); + expect(results.map((r) => r.status)).toEqual(['fulfilled', 'rejected', 'fulfilled', 'fulfilled', 'fulfilled']); + // A failure gives its slot back like a success does. + await expect(slots.run(async () => 'next')).resolves.toBe('next'); + }); +}); diff --git a/server/tests/unit/db/engine/postgres/plugin-sql-guard.test.ts b/server/tests/unit/db/engine/postgres/plugin-sql-guard.test.ts new file mode 100644 index 000000000..80950aaa4 --- /dev/null +++ b/server/tests/unit/db/engine/postgres/plugin-sql-guard.test.ts @@ -0,0 +1,176 @@ +/** + * The guard that keeps a plugin's own SQL inside its schema on Postgres + * (src/db/engine/postgres/plugin-sql-guard.ts), without a database: what it + * lets through, what it refuses and why, how it reads quoting and comments + * the way Postgres does, and what it tells the store about a statement. The + * same rules against a real database are PGPLUG-003/004 in the Postgres lane. + */ +import { + checkPlaceholders, + checkQualifiers, + parsePluginSql, + PluginSqlRefused, + tokenize, +} from '../../../../../src/db/engine/postgres/plugin-sql-guard'; + +import { describe, expect, it } from 'vitest'; + +const OWN = 'trek_plugin_notes'; +const SCHEMAS = new Set(['public', 'auth', 'pg_catalog', 'information_schema', OWN, 'trek_plugin_other']); + +/** Parses `sql` and checks its qualified names as the store does. */ +function check(sql: string): void { + for (const statement of parsePluginSql(sql)) checkQualifiers(statement, OWN, SCHEMAS); +} + +describe('plugin SQL guard', () => { + it.each([ + 'SELECT * FROM notes WHERE id = $1', + 'select n.body, t.name from notes n join tags t on t.note_id = n.id', + 'INSERT INTO notes (body) VALUES ($1) RETURNING id', + "UPDATE notes SET body = 'it''s' WHERE id = 1", + 'DELETE FROM notes WHERE id IN (SELECT note_id FROM trash)', + 'WITH recent AS (SELECT * FROM notes ORDER BY id DESC LIMIT 5) SELECT count(*) FROM recent', + 'VALUES (1), (2)', + 'TABLE notes', + '(SELECT 1) UNION (SELECT 2)', + 'CREATE TABLE notes (id bigserial PRIMARY KEY, body text, temp real, schema text)', + 'CREATE UNIQUE INDEX notes_body ON notes (body)', + 'CREATE UNLOGGED TABLE cache (k text)', + 'CREATE OR REPLACE VIEW v AS SELECT body FROM notes', + 'CREATE MATERIALIZED VIEW mv AS SELECT 1', + 'CREATE SEQUENCE s', + "CREATE TYPE mood AS ENUM ('ok', 'sad')", + 'ALTER TABLE notes ADD COLUMN tag text', + 'DROP TABLE IF EXISTS notes CASCADE', + 'TRUNCATE notes', + 'REFRESH MATERIALIZED VIEW mv', + 'SELECT body FROM trek_plugin_notes.notes', + 'SELECT "notes"."body" FROM "notes"', + "SELECT 'public.users -- not code' AS text", + 'SELECT 1 -- public.users\n', + 'SELECT /* public.users */ 1', + 'SELECT 1.5e3, .5, 0x1F', + 'INSERT INTO kv VALUES ($1, $2) ON CONFLICT (k) DO NOTHING', + ])('lets through %s', (sql) => { + expect(() => check(sql)).not.toThrow(); + }); + + it.each([ + ['SELECT * FROM public.users', /another schema/], + ['SELECT * FROM "public"."users"', /another schema/], + ['SELECT * FROM PUBLIC . users', /another schema/], + ['SELECT * FROM public/**/.users', /another schema/], + ['SELECT * FROM auth.secret', /another schema/], + ['SELECT * FROM trek_plugin_other.notes', /another schema/], + ['SELECT * FROM trek_plugin_not_yet.notes', /another schema/], + ['SELECT * FROM trek.public.users', /another schema/], + ['SELECT * FROM pg_stats', /"pg_stats" may not be named/], + ['SELECT * FROM "pg_catalog".pg_authid', /"pg_catalog" may not be named/], + ['SELECT * FROM information_schema.tables', /"information_schema" may not be named/], + ["SELECT query_to_xml('select 1', true, true, '')", /"query_to_xml" may not be named/], + ["SELECT database_to_xml(true, true, '')", /"database_to_xml" may not be named/], + ["SELECT ts_stat('select 1')", /"ts_stat" may not be named/], + ["SELECT \"set_config\"('search_path', 'public', true)", /"set_config" may not be named/], + ["SELECT current_setting('search_path')", /"current_setting" may not be named/], + ["SELECT nextval('users_id_seq')", /"nextval" may not be named/], + ["SELECT 'users'::regclass", /"regclass" may not be named/], + ["SELECT to_regclass('users')", /"to_regclass" may not be named/], + ['SELECT lo_get(1)', /"lo_get" may not be named/], + ["SELECT dblink('x', 'y')", /"dblink" may not be named/], + ['WITH RECURSIVE r(x) AS (SELECT 1 UNION ALL SELECT x + 1 FROM r) SELECT * FROM r', /RECURSIVE/], + ['SELECT 1 AS x INTO copy_of', /SELECT \.\.\. INTO/], + ['CREATE TEMP TABLE t (x int)', /CREATE TEMP is not allowed/], + ['CREATE TEMPORARY TABLE t (x int)', /CREATE TEMPORARY is not allowed/], + ["CREATE FUNCTION f() RETURNS int LANGUAGE sql AS 'select 1'", /CREATE FUNCTION is not allowed/], + ['CREATE OR REPLACE FUNCTION f() RETURNS int', /CREATE FUNCTION is not allowed/], + ['CREATE SCHEMA mine', /CREATE SCHEMA is not allowed/], + ['CREATE EXTENSION dblink', /CREATE EXTENSION is not allowed/], + ['DROP SCHEMA trek_plugin_notes', /DROP SCHEMA is not allowed/], + ['DROP OWNED BY current_user', /DROP OWNED is not allowed/], + ['ALTER TABLE notes SET SCHEMA x', /may not change the schema/], + ['ALTER TABLE notes OWNER TO someone', /may not change the owner/], + ['ALTER ROLE trek SUPERUSER', /ALTER ROLE is not allowed/], + ['CREATE TABLE t (x int) TABLESPACE pg_default', /tablespace/], + ['SET search_path TO public', /may not start with SET/], + ['RESET ROLE', /may not start with RESET/], + ['COPY notes TO STDOUT', /may not start with COPY/], + ['GRANT SELECT ON notes TO PUBLIC', /may not start with GRANT/], + ['DO $$ BEGIN END $$', /dollar-quoted/], + ['LISTEN x', /may not start with LISTEN/], + ['PREPARE p AS SELECT 1', /may not start with PREPARE/], + ['EXPLAIN ANALYZE SELECT 1', /may not start with EXPLAIN/], + ['BEGIN', /transaction-control/], + ['COMMIT', /transaction-control/], + ['SAVEPOINT a', /transaction-control/], + ["SELECT E'\\x'", /escape strings/], + ["SELECT U&'\\0041'", /Unicode escapes/], + ['SELECT * FROM U&"\\0070ublic".users', /Unicode escapes/], + ['SELECT $tag$x$tag$', /dollar-quoted/], + ['SELECT 1.public', /a number may not run straight into a name/], + ["SELECT 'open", /a string is not closed/], + ['SELECT "open', /a quoted name is not closed/], + ['SELECT /* open', /a comment is not closed/], + ['SELECT ""', /a quoted name may not be empty/], + ['SELECT `x`', /unexpected character/], + ['SELECT 1; SELECT * FROM public.users', /another schema/], + ])('refuses %s', (sql, reason) => { + expect(() => check(sql)).toThrow(PluginSqlRefused); + expect(() => check(sql)).toThrow(reason); + }); + + it('reads nested block comments as Postgres does, so code after the inner close is still a comment', () => { + expect(() => check('SELECT 1 /* outer /* inner */ public.users */')).not.toThrow(); + expect(() => check('SELECT 1 /* one */ FROM public.users')).toThrow(/another schema/); + }); + + it('compares a long name the way Postgres keeps it: cut to 63 bytes', () => { + const own = `trek_plugin_${'a'.repeat(51)}`; + expect(own).toHaveLength(63); + const statement = parsePluginSql(`SELECT * FROM ${own}zzzz.notes`)[0]; + expect(() => checkQualifiers(statement, own, new Set([own]))).not.toThrow(); + const other = `public${'x'.repeat(70)}`; + const cut = other.slice(0, 63); + expect(() => checkQualifiers(parsePluginSql(`SELECT * FROM ${other}.t`)[0], own, new Set([cut]))).toThrow( + /another schema/, + ); + }); + + it('splits a script at its semicolons, keeps each statement text and drops empty ones', () => { + const statements = parsePluginSql("CREATE TABLE a (x text);;\n-- note\nINSERT INTO a VALUES ('a;b');"); + expect(statements.map((s) => s.text)).toEqual(['CREATE TABLE a (x text)', "INSERT INTO a VALUES ('a;b')"]); + expect(parsePluginSql('-- nothing\n;')).toEqual([]); + }); + + it('says whether a statement returns rows, may write, qualifies a name and how many placeholders it has', () => { + const [select] = parsePluginSql('SELECT * FROM notes WHERE id = $1 AND tag = $2'); + expect(select).toMatchObject({ returnsRows: true, mayWrite: false, qualifies: false, params: 2 }); + const [returning] = parsePluginSql('UPDATE notes SET body = $1 RETURNING id'); + expect(returning).toMatchObject({ returnsRows: true, mayWrite: true }); + const [insert] = parsePluginSql('INSERT INTO notes (body) VALUES ($1)'); + expect(insert).toMatchObject({ returnsRows: false, mayWrite: true }); + const [cte] = parsePluginSql('WITH gone AS (DELETE FROM notes RETURNING id) SELECT count(*) FROM gone'); + expect(cte).toMatchObject({ returnsRows: true, mayWrite: true }); + const [ddl] = parsePluginSql('CREATE TABLE t (x int)'); + expect(ddl).toMatchObject({ returnsRows: false, mayWrite: true }); + const [qualified] = parsePluginSql('SELECT n.body FROM notes n'); + expect(qualified.qualifies).toBe(true); + }); + + it('turns a SQLite ? placeholder into a message about $1 when args are bound', () => { + const [sqliteStyle] = parsePluginSql('SELECT * FROM notes WHERE id = ?'); + expect(() => checkPlaceholders(sqliteStyle, [1])).toThrow(/\$1, \$2/); + expect(() => checkPlaceholders(sqliteStyle, [])).not.toThrow(); + const [pgStyle] = parsePluginSql('SELECT * FROM notes WHERE id = $1'); + expect(() => checkPlaceholders(pgStyle, [1])).not.toThrow(); + }); + + it('folds unquoted names to lower case and keeps quoted ones as written', () => { + expect(tokenize('Select "MiXed", Plain')).toEqual([ + { kind: 'word', value: 'select', quoted: false, at: 0 }, + { kind: 'word', value: 'MiXed', quoted: true, at: 7 }, + { kind: 'punct', value: ',', at: 14 }, + { kind: 'word', value: 'plain', quoted: false, at: 16 }, + ]); + }); +});