feat(lint): refuse a transaction outside UnitOfWork under src/

trek/transactions-through-unit-of-work reads the receiver's type and reports
transactional() on anything but a UnitOfWork (an untyped receiver
included), and begin() or transaction() on an EntityManager, a connection
or Kysely. src/db/engine/ and the two boot-time schema files are left out.
It runs with the rest of the server's ESLint, so lint:warnings fails on a
new one, and its message names UnitOfWork, writeTransaction and the rule in
server/CLAUDE.md.
This commit is contained in:
Maurice
2026-11-17 14:14:49 +01:00
parent af861e5816
commit 2f3dc4ea79
3 changed files with 184 additions and 7 deletions
@@ -0,0 +1,62 @@
/**
* trek/transactions-through-unit-of-work: every transaction under src/ goes
* through `UnitOfWork.transactional` (or `writeTransaction`, which it wraps).
*
* On SQLite one connection writes one transaction at a time, so a check read
* inside a transaction (a `MAX(...) + 1` position, a count under a cap, an
* existence before an insert) still held at the write that followed. On
* Postgres a pool runs transactions side by side, and only the engine's write
* lock (`DatabaseEngine.serializeWrites`), which `UnitOfWork` takes first,
* puts them one after the other again. A transaction opened any other way,
* `em.transactional(...)`, a repository's `getEntityManager().transactional(...)`,
* `em.begin()`, a connection's `transactional(...)` or Kysely's
* `db.transaction()`, does not take that lock, and its check can be raced.
*
* The rule reads the receiver's type: `transactional` is reported on anything
* but a `UnitOfWork` (an untyped receiver included, so it fails closed), and
* `begin`/`transaction` on an EntityManager, a connection or a Kysely
* instance (better-sqlite3's own `transaction()`, the plugin's private SQLite
* file, and unrelated `begin()` methods stay out of it). The engine and the
* boot-time schema files open their own transactions on purpose and are left
* out in eslint.config.mjs, each with its reason.
*/
const OPENERS = new Set(['transactional', 'begin', 'transaction']);
const DATABASE_HANDLE = /EntityManager|Connection|^Kysely\b/;
export default {
meta: {
type: 'problem',
docs: {
description:
'Open transactions only through UnitOfWork.transactional, which takes the engine write lock on Postgres',
},
schema: [],
messages: {
direct:
'`.{{method}}(...)` opens a transaction without the engine write lock. Use `UnitOfWork.transactional` ' +
'(src/nest/database/unit-of-work.ts; outside the Nest container `writeTransaction` from ' +
'src/db/engine/write-transaction.ts), and read every check its write relies on (a count, an existence, ' +
"a MAX + 1) inside it. A repository method runs inside its caller's unit of work instead of opening one. " +
'See server/CLAUDE.md, "Transactions are not optional".',
},
},
create(context) {
const services = context.sourceCode.parserServices;
if (!services?.program) return {};
const checker = services.program.getTypeChecker();
return {
CallExpression(node) {
const callee = node.callee;
if (callee.type !== 'MemberExpression' || callee.computed || callee.property.type !== 'Identifier') return;
const method = callee.property.name;
if (!OPENERS.has(method)) return;
const type = services.getTypeAtLocation(callee.object);
const symbol = (type.getSymbol() ?? type.aliasSymbol)?.getName();
if (symbol === 'UnitOfWork') return;
if (method !== 'transactional' && !DATABASE_HANDLE.test(checker.typeToString(type))) return;
context.report({ node, messageId: 'direct', data: { method } });
},
};
},
};
+45 -7
View File
@@ -1,13 +1,18 @@
import noPromiseAsValue from './eslint-rules/no-promise-as-value.mjs';
import transactionsThroughUnitOfWork from './eslint-rules/transactions-through-unit-of-work.mjs';
import js from '@eslint/js';
import gitignore from 'eslint-config-flat-gitignore';
import eslintConfigPrettier from 'eslint-config-prettier';
import tseslint from 'typescript-eslint';
import noPromiseAsValue from './eslint-rules/no-promise-as-value.mjs';
// Local rules live in eslint-rules/ and are exposed under the `trek/` prefix.
const trek = { rules: { 'no-promise-as-value': noPromiseAsValue } };
const trek = {
rules: {
'no-promise-as-value': noPromiseAsValue,
'transactions-through-unit-of-work': transactionsThroughUnitOfWork,
},
};
// The calls the outbound-timeout selectors below look at: the platform fetch and
// the SSRF-guarded wrappers whose init is passed on to it. safeFetchLlm is not
@@ -126,8 +131,15 @@ const STRING_SQL_SELECTORS = [
const APP_SETTING_MESSAGE =
"Read an app setting through readAppSetting()/resolveAppSetting() from src/nest/common/app-settings.registry.ts, not getValue('<key>'): the register types the key and owns its env override.";
const APP_SETTING_SELECTORS = [
{ selector: "CallExpression[callee.property.name='getValue'] > Literal.arguments:first-child", message: APP_SETTING_MESSAGE },
{ selector: "CallExpression[callee.property.name='getValue'] > TemplateLiteral.arguments:first-child[expressions.length=0]", message: APP_SETTING_MESSAGE },
{
selector: "CallExpression[callee.property.name='getValue'] > Literal.arguments:first-child",
message: APP_SETTING_MESSAGE,
},
{
selector:
"CallExpression[callee.property.name='getValue'] > TemplateLiteral.arguments:first-child[expressions.length=0]",
message: APP_SETTING_MESSAGE,
},
];
// The demo-mode write block runs once, in the MCP registry (trekDemoToolGate in
@@ -136,7 +148,7 @@ const APP_SETTING_SELECTORS = [
const DEMO_GATE_MESSAGE =
'MCP tools do not check demo mode themselves: the registry gate (trekDemoToolGate) refuses every tool not annotated read-only. Annotate the tool instead.';
const MCP_DEMO_SELECTORS = [
{ selector: "CallExpression[callee.property.name=/^isDemoUser(Id)?$/]", message: DEMO_GATE_MESSAGE },
{ selector: 'CallExpression[callee.property.name=/^isDemoUser(Id)?$/]', message: DEMO_GATE_MESSAGE },
{ selector: "CallExpression[callee.name='demoDenied']", message: DEMO_GATE_MESSAGE },
];
@@ -278,13 +290,39 @@ export default tseslint.config(
'no-restricted-syntax': ['error', ...ENV_SELECTORS, ...FETCH_SELECTORS, ...APP_SETTING_SELECTORS],
},
},
{
// Every transaction goes through UnitOfWork.transactional (or writeTransaction,
// which it wraps), the only ones that take the engine's write lock: on
// Postgres a transaction opened any other way runs beside the others, and a
// check read inside it can be raced. See eslint-rules/transactions-through-unit-of-work.mjs.
files: ['src/**/*.ts'],
ignores: [
// The engine: writeTransaction itself, the schema bootstrap, the parity
// diff, the move from SQLite and the plugin data schemas, each on a
// connection or database of its own.
'src/db/engine/**',
// Boot-time schema steps on the raw connection, before the server takes a request.
'src/db/email-case-index.ts',
'src/db/legacy-baseline.ts',
],
plugins: { trek },
rules: {
'trek/transactions-through-unit-of-work': 'error',
},
},
{
// Restates the config-access and app-setting guards above for *.mcp.ts
// (a later block's options replace an earlier one's) and adds the
// demo-gate wall.
files: ['src/**/*.mcp.ts'],
rules: {
'no-restricted-syntax': ['error', ...ENV_SELECTORS, ...FETCH_SELECTORS, ...APP_SETTING_SELECTORS, ...MCP_DEMO_SELECTORS],
'no-restricted-syntax': [
'error',
...ENV_SELECTORS,
...FETCH_SELECTORS,
...APP_SETTING_SELECTORS,
...MCP_DEMO_SELECTORS,
],
},
},
{
@@ -0,0 +1,77 @@
import transactionsThroughUnitOfWork from '../../../eslint-rules/transactions-through-unit-of-work.mjs';
import tsParser from '@typescript-eslint/parser';
import { RuleTester, type Rule } from 'eslint';
import path from 'path';
// TXGATE: the rule reads the receiver's type, so the tester runs against a real
// TypeScript program, the fixture project no-promise-as-value.test.ts uses
// (eslint-rules/fixtures/, outside src/ and tests/). Per-file mode on CI too,
// for the reason given there.
const fixtureRoot = path.resolve(__dirname, '../../../eslint-rules/fixtures');
const filename = path.join(fixtureRoot, 'file.ts');
const ruleTester = new RuleTester({
languageOptions: {
parser: tsParser,
parserOptions: {
project: './tsconfig.json',
tsconfigRootDir: fixtureRoot,
disallowAutomaticSingleRunInference: true,
},
},
});
// Stand-ins named like the real classes: the rule goes by the receiver's type name.
const PRELUDE = `
declare class UnitOfWork { transactional<T>(fn: () => Promise<T>): Promise<T>; }
declare class EntityManager {
transactional<T>(fn: (em: EntityManager) => Promise<T>): Promise<T>;
begin(): Promise<void>;
}
declare class SqlEntityManager extends EntityManager {}
declare class AbstractSqlConnection { transactional<T>(fn: (trx: unknown) => Promise<T>): Promise<T>; begin(): Promise<unknown>; }
declare class Kysely<DB> { transaction(): { execute<T>(fn: (trx: Kysely<DB>) => Promise<T>): Promise<T> }; readonly db?: DB; }
declare class Database { transaction<F extends (...args: unknown[]) => unknown>(fn: F): F; }
declare class RouterState { begin(): void; }
declare function writeTransaction<T>(em: EntityManager, engine: unknown, fn: (em: EntityManager) => Promise<T>): Promise<T>;
declare const uow: UnitOfWork;
declare const em: EntityManager;
declare const sqlEm: SqlEntityManager;
declare const connection: AbstractSqlConnection;
declare const kysely: Kysely<{ trips: { id: number } }>;
declare const pluginDb: Database;
declare const state: RouterState;
declare const repo: { getEntityManager(): EntityManager };
declare const untyped: ReturnType<typeof JSON.parse>;
`;
const withPrelude = (code: string) => `${PRELUDE}${code}\n`;
const valid = [
// The unit of work, injected or held in a field.
`void uow.transactional(async () => 1);`,
`class S { constructor(private readonly uow: UnitOfWork) {} run() { return this.uow.transactional(async () => 1); } }`,
// The engine's own wrapper for code outside the container.
`void writeTransaction(em, null, async () => 1);`,
// better-sqlite3's transaction() on a plugin's private file, and an unrelated begin().
`pluginDb.transaction(() => 1)();`,
`state.begin();`,
];
const invalid = [
`void em.transactional(async () => 1);`,
`void sqlEm.transactional(async () => 1);`,
`void repo.getEntityManager().transactional(async () => 1);`,
`void connection.transactional(async () => 1);`,
`void em.begin();`,
`void connection.begin();`,
`void kysely.transaction().execute(async () => 1);`,
// An untyped receiver is reported too: the rule fails closed.
`void untyped.transactional(async () => 1);`,
];
ruleTester.run('trek/transactions-through-unit-of-work', transactionsThroughUnitOfWork as unknown as Rule.RuleModule, {
valid: valid.map((code) => ({ code: withPrelude(code), filename })),
invalid: invalid.map((code) => ({ code: withPrelude(code), filename, errors: [{ messageId: 'direct' }] })),
});